@cero-base/core 1.1.0 → 1.2.0

package/src/lib/utils.js

@@ -1,7 +1,8 @@
 import crypto from 'crypto'
+import b4a from 'b4a'
 import { Readable } from 'streamx'
 import z32 from 'z32'
-import { encode, decode, isValid } from 'hypercore-id-encoding'
+import { encode, decode } from 'hypercore-id-encoding'
 
 import { ROLE_PERMS, RANK } from './constants.js'
 
@@ -28,12 +29,18 @@ export const toId = encode
  */
 export const toKey = decode
 
-/**
- * Test whether a string is a well-formed canonical id.
- *
- * @type {(id: string) => boolean}
- */
-export const isKeyId = isValid
+// Domain-separated payloads for writer-admission signatures. Binding the db
+// key makes an admission unreplayable across rooms; the tag pins the format.
+// v2 — pre-1.2 signatures (writer‖appender / bare writer) no longer verify.
+const ADD_WRITER_TAG = b4a.from('cero/add-writer/v2')
+const CLAIM_WRITER_TAG = b4a.from('cero/claim-writer/v2')
+
+/** @type {(dbKey: Uint8Array, writer: Uint8Array, appender: Uint8Array) => Uint8Array} */
+export const addWriterPayload = (dbKey, writer, appender) =>
+  b4a.concat([ADD_WRITER_TAG, dbKey, writer, appender])
+
+/** @type {(dbKey: Uint8Array, writer: Uint8Array) => Uint8Array} */
+export const claimWriterPayload = (dbKey, writer) => b4a.concat([CLAIM_WRITER_TAG, dbKey, writer])
 
 /**
  * Whether `role` is granted `perm` under the default policy.
@@ -63,7 +70,6 @@ export const outranks = (a, b) => RANK[a] != null && RANK[b] != null && RANK[a]
  */
 export function subscribe({ get, watch }) {
   let stop = null
-  let version = 0
   let last
   const stream = new Readable({
     destroy(cb) {
@@ -78,15 +84,30 @@ export function subscribe({ get, watch }) {
     stream.push(data)
   }
 
+  // Coalesce: one get() in flight at a time. Ticks that land mid-read mark
+  // dirty and fold into a single trailing re-read — a write burst costs one
+  // extra snapshot instead of one concurrent scan per tick, and only the
+  // latest state is emitted.
+  let running = false
+  let dirty = false
   const push = async () => {
     if (stream.destroyed) return
-    const v = ++version
+    if (running) {
+      dirty = true
+      return
+    }
+    running = true
     try {
-      const data = await get()
-      if (v !== version || stream.destroyed) return
-      emit(data)
+      do {
+        dirty = false
+        const data = await get()
+        if (stream.destroyed) return
+        emit(data)
+      } while (dirty)
     } catch (e) {
       stream.destroy(e)
+    } finally {
+      running = false
     }
   }
 

package/src/network/bluetooth.js

@@ -0,0 +1,324 @@
+import ReadyResource from 'ready-resource'
+import b4a from 'b4a'
+import { hash } from 'hypercore-crypto'
+import safetyCatch from 'safety-catch'
+
+// Readable characteristic carrying "<psm>:<nodeId-hex>" — the L2CAP PSM to
+// connect on plus the advertiser's stable id for the initiate tie-break. Read
+// over GATT after connecting (bare-mobile-doctor reads the PSM the same way);
+// advertisement service-data is not a portable channel for this.
+const PSM_UUID = 'ce1a0003-0000-1000-8000-00805f9b34fb'
+const DEFAULT_CAP = 4
+const CONNECT_TIMEOUT = 15000
+
+/**
+ * Derive a stable 128-bit BLE service UUID from a topic. Only devices that
+ * compute the same UUID (same channel / same invite) ever discover each other.
+ *
+ * @param {Uint8Array} topic
+ * @param {string} [tag]  Namespace so channel and invite meshes never collide.
+ * @returns {string}
+ */
+export function toServiceUUID(topic, tag = 'cero-ble') {
+  const h = hash([b4a.from(tag), topic])
+  const hex = b4a.toString(h.subarray(0, 16), 'hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
+// Backend adapter state → the app-facing state the facade exposes.
+const STATE = {
+  poweredOn: 'on',
+  poweredOff: 'waiting',
+  unauthorized: 'unauthorized',
+  unsupported: 'unsupported',
+  resetting: 'waiting',
+  unknown: 'waiting'
+}
+
+const uuidEq = (a, b) =>
+  String(a || '')
+    .toLowerCase()
+    .replace(/-/g, '') ===
+  String(b || '')
+    .toLowerCase()
+    .replace(/-/g, '')
+
+const findByUUID = (items, uuid) => (items || []).find((i) => uuidEq(i.uuid, uuid)) || null
+
+/**
+ * Dual-role BLE transport: advertises + scans one service UUID, opens an L2CAP
+ * channel to each discovered peer, and feeds it into `network.inject`. From
+ * there replication and pairing are transport-agnostic (see Network.inject).
+ *
+ * Choreography mirrors the proven bare-mobile-doctor worklet: server adds a
+ * readable PSM characteristic at startup and answers reads dynamically; the
+ * central connects, reads "<psm>:<nodeId>", tie-breaks, then opens the channel.
+ * `backend` is bare-bluetooth in production and a mock in tests.
+ *
+ * ponytail: capability-handshake DoS link-scoring is deferred — it needs a
+ * replication-progress signal (design §4b). v1 caps links + times out dials.
+ *
+ * @extends ReadyResource
+ */
+export class BluetoothTransport extends ReadyResource {
+  /**
+   * @param {object} opts
+   * @param {any} opts.backend            bare-bluetooth-shaped module (Central, Server, Service, Characteristic).
+   * @param {import('./index.js').Network} opts.network
+   * @param {Uint8Array} opts.uuid        The 32-byte topic the service UUID derives from.
+   * @param {Uint8Array} opts.nodeId      Stable local id (identity/device key) for the initiate tie-break.
+   * @param {string} [opts.tag]           UUID namespace (channel mesh vs invite mesh).
+   * @param {number} [opts.cap]           Max concurrent links; gossip covers the rest.
+   * @param {{ scanMode?: any }} [opts.scanOptions]  Platform scan options (e.g. Android low-power).
+   * @param {boolean} [opts.keepLinks]    On close, stop the radio but leave established links alive (invite rendezvous: the link outlives the QR and carries the initial replication).
+   */
+  constructor({
+    backend,
+    network,
+    uuid,
+    nodeId,
+    tag = 'cero-ble',
+    cap = DEFAULT_CAP,
+    scanOptions,
+    keepLinks = false
+  }) {
+    super()
+    this.backend = backend
+    this.network = network
+    this.nodeId = nodeId
+    this.nodeHex = b4a.toString(nodeId, 'hex')
+    this.serviceUUID = toServiceUUID(uuid, tag)
+    this.cap = cap
+    this.scanOptions = scanOptions
+    this.keepLinks = keepLinks
+
+    this.state = 'off'
+    this.central = null
+    this.server = null
+    this.psm = null
+    this._scanning = false
+    this._advertising = false
+    this._serviceAdded = false
+    /** peripheral id being dialed → its connect-timeout timer */
+    this._dialing = new Map()
+    /** live injected links keyed by remote node id hex */
+    this.peers = new Map()
+  }
+
+  /**
+   * Whether we should be the one to open the connection to `peerNodeId`. The
+   * lexicographically smaller id initiates; the larger waits — so a pair
+   * connects once, not twice. Equal (our own reflection) → false.
+   *
+   * @param {Uint8Array} peerNodeId
+   * @returns {boolean}
+   */
+  shouldInitiate(peerNodeId) {
+    return b4a.compare(this.nodeId, peerNodeId) < 0
+  }
+
+  get linkCount() {
+    return this.peers.size
+  }
+
+  async _open() {
+    const { Central, Server, Service, Characteristic } = this.backend
+
+    this.server = new Server()
+    this.server.on('stateChange', (s) => {
+      this._onState(s)
+      if (s === 'poweredOn') this._startServer(Service, Characteristic)
+    })
+    this.server.on('serviceAdd', () => {
+      this._serviceAdded = true
+      this._maybeAdvertise()
+    })
+    this.server.on('channelPublish', (psm) => {
+      this.psm = psm
+      this._maybeAdvertise()
+    })
+    // A central reads this to learn the PSM (+ our id) before opening the
+    // channel. Answer dynamically: the PSM isn't known when the service is added.
+    this.server.on('readRequest', (req) => {
+      const ok = this.server.constructor.ATT_SUCCESS ?? 0
+      const val = this.psm == null ? b4a.alloc(0) : b4a.from(`${this.psm}:${this.nodeHex}`)
+      this.server.respondToRequest(req, ok, val)
+    })
+    this.server.on('channelOpen', (l2cap) => this._onChannel(l2cap, false, null))
+    this.server.on('error', safetyCatch)
+
+    this.central = new Central()
+    this.central.on('stateChange', (s) => {
+      this._onState(s)
+      if (s === 'poweredOn') this._startScan()
+    })
+    this.central.on('discover', (peripheral) => this._onDiscover(peripheral))
+    this.central.on('connect', (peripheral) => this._onConnect(peripheral))
+    this.central.on('disconnect', () => {})
+    this.central.on('error', (err) => this._onCentralError(err))
+
+    this._startServer(Service, Characteristic)
+    this._startScan()
+    this.state = 'starting'
+  }
+
+  _startServer(Service, Characteristic) {
+    if (this.server.state !== 'poweredOn') return // wait for the adapter (stateChange)
+    if (!this._serviceAdded) {
+      const char = new Characteristic(PSM_UUID, { read: true })
+      this.server.addService(new Service(this.serviceUUID, [char]))
+    }
+    if (this.psm == null) this.server.publishChannel({})
+  }
+
+  _maybeAdvertise() {
+    if (this._advertising || !this._serviceAdded || this.psm == null) return
+    this._advertising = true
+    this.server.startAdvertising({ serviceUUIDs: [this.serviceUUID] })
+  }
+
+  _startScan() {
+    if (this._scanning || this.central.state !== 'poweredOn') return
+    this._scanning = true
+    this.central.startScan([this.serviceUUID], this.scanOptions)
+  }
+
+  _onState(raw) {
+    const next = STATE[raw] ?? 'waiting'
+    if (next === this.state) return
+    this.state = next
+    this.emit('update')
+  }
+
+  _onDiscover(peripheral) {
+    if (this.closing || this.closed) return
+    if (this._dialing.has(peripheral.id)) return // already connecting to this one
+    if (this.linkCount >= this.cap) return // gossip covers the rest
+    // tie-break is decided post-read (we can't trust advertisement payloads);
+    // dial now, learn the peer id from the PSM characteristic, decide there.
+    const timer = setTimeout(() => this._abortDial(peripheral, 'timeout'), CONNECT_TIMEOUT)
+    this._dialing.set(peripheral.id, timer)
+    try {
+      this.central.connect(peripheral)
+    } catch (err) {
+      this._abortDial(peripheral, err)
+    }
+  }
+
+  _onConnect(peripheral) {
+    peripheral.on('error', () => this._abortDial(peripheral, 'peripheral-error'))
+    peripheral.once('servicesDiscover', (services) => {
+      const svc = findByUUID(services, this.serviceUUID)
+      if (svc) peripheral.discoverCharacteristics(svc, [PSM_UUID])
+      else this._abortDial(peripheral, 'no-service')
+    })
+    peripheral.once('characteristicsDiscover', (_svc, chars) => {
+      const psmChar = findByUUID(chars, PSM_UUID)
+      if (psmChar) peripheral.read(psmChar)
+      else this._abortDial(peripheral, 'no-psm-char')
+    })
+    peripheral.once('read', (_char, data) => {
+      const [psmStr, peerHex] = b4a.toString(data).split(':')
+      const psm = Number(psmStr)
+      const peerId = peerHex ? b4a.from(peerHex, 'hex') : null
+      // the smaller id opens the channel; the larger disconnects and waits for
+      // the peer to dial back — a pair links once, not twice
+      if (!psm || !peerId || !this.shouldInitiate(peerId)) {
+        this._abortDial(peripheral, 'yield')
+        return
+      }
+      peripheral.once('channelOpen', (l2cap) => {
+        this._clearDial(peripheral.id)
+        this._onChannel(l2cap, true, peripheral.id)
+      })
+      peripheral.openL2CAPChannel(psm)
+    })
+    peripheral.discoverServices([this.serviceUUID])
+  }
+
+  _abortDial(peripheral, _reason) {
+    const id = peripheral?.id
+    this._clearDial(id)
+    try {
+      this.central.disconnect(peripheral)
+    } catch (err) {
+      safetyCatch(err)
+    }
+  }
+
+  _clearDial(id) {
+    if (id == null) return
+    const timer = this._dialing.get(id)
+    if (timer) clearTimeout(timer)
+    this._dialing.delete(id) // free the slot — rediscovery can re-dial
+  }
+
+  // iOS & Android report errored connects as 'error' with a code, not
+  // 'disconnect' — without this a failed dial pins the peripheral forever.
+  _onCentralError(err) {
+    safetyCatch(err)
+    const code = err && err.code
+    if (code === 'CONNECTION_FAILED' || code === 'DISCONNECT') {
+      for (const id of [...this._dialing.keys()]) this._clearDial(id)
+    }
+  }
+
+  _onChannel(l2cap, isInitiator, peripheralId) {
+    if (this.closing || this.closed) {
+      l2cap.destroy()
+      return
+    }
+    const conn = this.network.inject(l2cap, { isInitiator })
+    conn.on('open', () => this._track(conn, peripheralId))
+    conn.on('close', () => this._untrack(conn, peripheralId))
+  }
+
+  _track(conn, peripheralId) {
+    if (this.closing || this.closed) return
+    const key = b4a.toString(conn.remotePublicKey, 'hex')
+    const existing = this.peers.get(key)
+    if (existing && existing !== conn) {
+      conn.destroy() // duplicate link to the same peer — keep the first
+      return
+    }
+    conn._peripheralId = peripheralId
+    conn._peerKey = key
+    this.peers.set(key, conn)
+    this.emit('update')
+  }
+
+  _untrack(conn) {
+    const key = conn._peerKey
+    if (key && this.peers.get(key) === conn) this.peers.delete(key)
+    if (!this.closing && !this.closed) this.emit('update')
+  }
+
+  async _close() {
+    // doctor-app rule: never call central/server.destroy() — it double-frees in
+    // the native teardown; stop advertising/scanning and let the runtime reclaim.
+    for (const timer of this._dialing.values()) clearTimeout(timer)
+    this._dialing.clear()
+    try {
+      this.central?.stopScan()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    try {
+      this.server?.stopAdvertising()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    if (!this.keepLinks) {
+      // channel mesh: toggling nearby off means stop syncing nearby
+      for (const conn of this.peers.values()) {
+        try {
+          conn.destroy()
+        } catch (err) {
+          safetyCatch(err)
+        }
+      }
+    }
+    this.peers.clear()
+    this.state = 'off'
+  }
+}

package/src/network/index.js

@@ -1,4 +1,6 @@
 import Hyperswarm from 'hyperswarm'
+import NoiseSecretStream from '@hyperswarm/secret-stream'
+import BlindPairing from 'blind-pairing'
 import ProtomuxWakeup from 'protomux-wakeup'
 import ReadyResource from 'ready-resource'
 import safetyCatch from 'safety-catch'
@@ -39,6 +41,81 @@ export class Network extends ReadyResource {
 
     this._replicateables = new Set()
     this._discoveries = new Set()
+    this._injected = new Set()
+    this._blind = null
+  }
+
+  /**
+   * Feed an externally-established connection — a Bluetooth L2CAP channel, a
+   * serial link, an in-process pair, any duplex — into the network. A raw
+   * duplex is wrapped in NoiseSecretStream (pass `isInitiator`); a stream
+   * that already IS one is used as-is. From here it gets the exact same
+   * treatment as a swarm connection: wakeup, replication of every attached
+   * core, pairing, and the 'connection' event.
+   *
+   * @param {any} stream  Duplex transport, or a ready NoiseSecretStream.
+   * @param {{ isInitiator?: boolean }} [opts]  Which side initiates the noise handshake (raw duplexes only).
+   * @returns {any} The encrypted connection stream.
+   */
+  inject(stream, { isInitiator } = {}) {
+    if (this.closing || this.closed) throw CeroError.CLOSED('Network')
+    if (!stream) throw CeroError.REQUIRED('stream')
+    const conn =
+      stream.noiseStream === stream ? stream : new NoiseSecretStream(isInitiator === true, stream)
+
+    // blind-pairing picks the lowest-`rtt` unvisited channel to send on; that
+    // field only exists on real udx sockets. A raw injected duplex has none,
+    // so `rtt < Infinity` is always false and pairing never sends a request.
+    // Zero is also the semantically correct RTT for a direct injected link.
+    if (conn.rawStream && conn.rawStream.rtt === undefined) conn.rawStream.rtt = 0
+
+    this._injected.add(conn)
+    conn.on('close', () => this._injected.delete(conn))
+    conn.on('error', safetyCatch) // a dropped radio link must not crash the host
+
+    this.wakeup.addStream(conn)
+    for (const r of this._replicateables) replicateInto(r, conn)
+    this.emit('connection', conn, { injected: true })
+    return conn
+  }
+
+  /**
+   * Lazily create the network-shared BlindPairing. One instance serves every
+   * handle's pairing member — per-handle instances each added their own swarm
+   * and DHT listeners plus a protomux channel per connection.
+   *
+   * @returns {Promise<any>}
+   */
+  async blind() {
+    if (!this._blind) {
+      const blind = new BlindPairing(this.swarm)
+      this._blind = blind.ready().then(() => {
+        // blind-pairing only watches the swarm — injected connections must
+        // reach it too, or offline (e.g. Bluetooth) pairing never completes.
+        // _onconnection is upstream-private; the offline-pairing test pins it.
+        this.on('connection', (conn, info) => {
+          if (info?.injected) blind._onconnection(conn)
+        })
+        for (const conn of this._injected) blind._onconnection(conn)
+        return blind
+      })
+    }
+    return this._blind
+  }
+
+  /**
+   * Re-attach pairing channels on injected connections. blind-pairing only
+   * auto-attaches refs that existed when a connection arrived — swarm peers
+   * meet again over topic joins, injected links (Bluetooth, pipes) don't, so
+   * a member/candidate added later must re-run the attach. Idempotent:
+   * protomux refuses duplicate channels.
+   *
+   * @returns {Promise<void>}
+   */
+  async refreshInjected() {
+    if (!this._blind || !this._injected.size) return
+    const blind = await this._blind
+    for (const conn of this._injected) blind._onconnection(conn)
   }
 
   /** @returns {Map<string, any>} Known peers keyed by public-key string. */
@@ -46,9 +123,10 @@ export class Network extends ReadyResource {
     return this.swarm ? this.swarm.peers : new Map()
   }
 
-  /** @returns {Set<any>} Live connection streams. */
+  /** @returns {Set<any>} Live connection streams — swarm and injected. */
   get connections() {
-    return this.swarm ? this.swarm.connections : new Set()
+    if (!this._injected.size) return this.swarm ? this.swarm.connections : new Set()
+    return new Set([...(this.swarm ? this.swarm.connections : []), ...this._injected])
   }
 
   /** @returns {boolean} */
@@ -129,6 +207,15 @@ export class Network extends ReadyResource {
   }
 
   async _close() {
+    for (const conn of [...this._injected]) {
+      try {
+        conn.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+    this._injected.clear()
+
     for (const d of [...this._discoveries]) {
       try {
         await d.destroy()
@@ -137,6 +224,15 @@ export class Network extends ReadyResource {
       }
     }
 
+    if (this._blind) {
+      try {
+        await (await this._blind).close()
+      } catch (err) {
+        safetyCatch(err)
+      }
+      this._blind = null
+    }
+
     if (this.swarm) {
       try {
         await this.flush()
@@ -195,9 +291,7 @@ export class Network extends ReadyResource {
   attach(core) {
     if (!core) throw CeroError.REQUIRED('core')
     this._replicateables.add(core)
-    if (this.swarm) {
-      for (const stream of this.swarm.connections) replicateInto(core, stream)
-    }
+    for (const stream of this.connections) replicateInto(core, stream)
   }
 
   /**
@@ -223,13 +317,24 @@ export class Network extends ReadyResource {
     if (!target || typeof target.replicate !== 'function') {
       throw CeroError.INVALID('target must be an object with a replicate(stream) method')
     }
-    if (this.swarm) {
-      for (const stream of this.swarm.connections) replicateInto(target, stream)
-    }
+    for (const stream of this.connections) replicateInto(target, stream)
   }
 }
 
+// Corestore replication is store-wide: N attached bees on one store would
+// re-attach every core AND add N duplicate StreamTracker records per
+// connection. Replicate each root store once per stream; wakeup streams are
+// added at the network level, so skipped bees lose nothing.
+const replicatedRoots = new WeakMap()
+
 function replicateInto(core, stream) {
+  const root = core.store ? core.store.root || core.store : null
+  if (root) {
+    let seen = replicatedRoots.get(stream)
+    if (!seen) replicatedRoots.set(stream, (seen = new WeakSet()))
+    if (seen.has(root)) return
+    seen.add(root)
+  }
   try {
     core.replicate(stream)
   } catch (err) {

package/src/pairing/index.js

@@ -88,13 +88,14 @@ export class Pairing extends ReadyResource {
 
   async _open() {
     await this.network.ready()
-    this._blind = new BlindPairing(this.network.swarm)
-    await this._blind.ready()
+    // shared instance — one set of swarm/DHT listeners for every handle
+    this._blind = await this.network.blind()
 
     this._member = this._blind.addMember({
       discoveryKey: discoveryKey(this.topic),
       onadd: (req) => this._onCandidate(req).catch(this._onerror)
     })
+    await this.network.refreshInjected()
   }
 
   async _close() {
@@ -105,10 +106,8 @@ export class Pairing extends ReadyResource {
       await this._member.close()
       this._member = null
     }
-    if (this._blind) {
-      await this._blind.close()
-      this._blind = null
-    }
+    // the BlindPairing is network-owned and shared — never close it here
+    this._blind = null
     this._invites.clear()
   }
 
@@ -415,6 +414,7 @@ class Candidate {
           onadd: (result) => this._done(result)
         })
         this._candidate.request.on('rejected', (err) => this._fail(fromBlindError(err)))
+        this.pairing.network.refreshInjected().catch(this._onerror ?? (() => {}))
       } catch (err) {
         this._fail(err instanceof CeroError ? err : CeroError.NETWORK_ERROR(err.message))
       }

package/src/rpc/index.js

@@ -108,13 +108,13 @@ export function bindCodec(spec) {
     },
     encodeAction(handle, op, data) {
       const ref = handle?.[op]
-      if (!ref || !ref.schema) throw new Error(`unknown action: ${op}`)
+      if (!ref || !ref.schema) throw CeroError.UNKNOWN('action', op)
       if (data == null) return EMPTY
       return schema.encode(ref.schema, data)
     },
     decodeAction(handle, op, buf) {
       const ref = handle?.[op]
-      if (!ref || !ref.schema) throw new Error(`unknown action: ${op}`)
+      if (!ref || !ref.schema) throw CeroError.UNKNOWN('action', op)
       if (!buf || buf.length === 0) return undefined
       return schema.decode(ref.schema, buf)
     }