@cero-base/core 1.1.1 → 1.3.0

package/src/network/bluetooth.js

@@ -0,0 +1,804 @@
+import ReadyResource from 'ready-resource'
+import b4a from 'b4a'
+import { hash, randomBytes } from 'hypercore-crypto'
+import safetyCatch from 'safety-catch'
+
+import { GattStream } from './gatt-stream.js'
+
+// One data characteristic (write + notify) carries a framed byte stream both
+// ways. iOS never answers an L2CAP channel opened by a Mac central and gives no
+// L2CAP disconnect signal; GATT with app-level framing is the proven transport
+// (the bitchat mesh app uses exactly this on iOS and Android).
+const DATA_UUID = 'ce1a0004-0000-1000-8000-00805f9b34fb'
+
+// Wire frame on the characteristic (both directions): [type:1][sessionId:8][payload].
+const TYPE_OPEN = 1
+const TYPE_DATA = 2
+const TYPE_CLOSE = 3
+const TYPE_HELLO = 4
+const SID_LEN = 8
+const HEADER = 1 + SID_LEN
+
+const DEFAULT_CAP = 4
+const CONNECT_TIMEOUT = 15000
+// per-peer dial backoff bases (bitchat model): eager while unlinked, patient once
+// we have a link. The actual cooldown grows exponentially per consecutive failure.
+const DIAL_COOLDOWN_BASE = 8000
+const DIAL_COOLDOWN_BASE_LONELY = 2000
+const DIAL_COOLDOWN_MAX = 30000
+// no two dials globally closer than this — one radio can't usefully dial faster
+const DIAL_MIN_INTERVAL = 500
+// Lonely: scan continuously, cycling every SCAN_RESTART_LONELY so a re-advertised
+// peer is re-reported (iOS suppresses duplicate discoveries within a scan session).
+const SCAN_RESTART_LONELY = 5000
+// Linked: continuous scanning is the dominant BLE battery cost, so duty-cycle it
+// (bitchat model) — scan for SCAN_DUTY_ON, then stay dark for SCAN_DUTY_OFF.
+const SCAN_DUTY_ON = 5000
+const SCAN_DUTY_OFF = 25000
+// suspend() drain window: how long to let goodbye frames flush before hanging up.
+const DRAIN_MS = 300
+
+const EMPTY = b4a.alloc(0)
+
+/**
+ * Build a wire frame [type][sessionId][payload].
+ *
+ * @param {number} type
+ * @param {Uint8Array} sid  8-byte session id.
+ * @param {Uint8Array} [payload]
+ * @returns {Buffer}
+ */
+function frame(type, sid, payload = EMPTY) {
+  const out = b4a.allocUnsafe(HEADER + payload.byteLength)
+  out[0] = type
+  b4a.copy(sid, out, 1)
+  if (payload.byteLength) b4a.copy(payload, out, HEADER)
+  return out
+}
+
+/**
+ * Parse a wire frame. Short/empty buffers → null (the caller logs + drops).
+ *
+ * @param {Uint8Array} buf
+ * @returns {{ type: number, sid: Uint8Array, sidHex: string, payload: Uint8Array } | null}
+ */
+function parseFrame(buf) {
+  if (!buf || buf.byteLength < HEADER) return null
+  const sid = buf.subarray(1, HEADER)
+  return {
+    type: buf[0],
+    sid,
+    sidHex: b4a.toString(sid, 'hex'),
+    payload: buf.subarray(HEADER)
+  }
+}
+
+/**
+ * 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 a GATT
+ * byte-stream to each discovered peer, and feeds it into `network.inject`. From
+ * there replication and pairing are transport-agnostic (see Network.inject).
+ *
+ * Choreography: the server adds one data characteristic (write + notify) and
+ * advertises. The central connects, discovers the characteristic, subscribes,
+ * then framed bytes flow both ways — central→server as GATT writes, server→
+ * central as notifications — each tagged with an 8-byte session id (bitchat
+ * model). `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).
+   * @param {string} [opts.name]          Local app-user display name, sent to peers over a hello frame.
+   */
+  constructor({
+    backend,
+    network,
+    uuid,
+    nodeId,
+    tag = 'cero-ble',
+    cap = DEFAULT_CAP,
+    scanOptions,
+    keepLinks = false,
+    name
+  }) {
+    super()
+    this.backend = backend
+    this.network = network
+    this.name = name || ''
+    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._dataChar = null
+    /** sessionId hex → { stream, sid } for server-side (peripheral) sessions */
+    this._sessions = new Map()
+    /** serialized server notify queue: { frame, resolve, reject } */
+    this._notifyQueue = []
+    this._scanning = false
+    this._advertising = false
+    this._serviceAdded = false
+    /** peripheral id being dialed → its connect-timeout timer */
+    this._dialing = new Map()
+    /** peripheral ids that carry a live channel — never re-dialed (a second
+     * dial's failure would disconnect the peripheral and kill the good link) */
+    this._linked = new Set()
+    /** peripheral id → retry-after timestamp; failed dials back off */
+    this._coolUntil = new Map()
+    /** peripheral id → consecutive failure count; drives exponential backoff */
+    this._failures = new Map()
+    /** peripheral id → remote peer key, learned at handshake — dial guard */
+    this._peerByPeripheral = new Map()
+    /** live central-side peripheral wrappers — for goodbye + physical hang-up on suspend */
+    this._connectedPeripherals = new Set()
+    /** last central.connect timestamp — global inter-dial rate limit */
+    this._lastDial = 0
+    this._scanTimer = null
+    this._suspended = false
+    /** 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('writeRequest', (reqs) => this._onWriteRequests(reqs))
+    // Notify queue drain signal: the last updateValue was refused (queue full);
+    // retry the head frame now that the peripheral can accept more.
+    this.server.on('readyToUpdate', () => this._drainNotify())
+    // WriteRequests carry no central identifier (see peripheral-manager
+    // _onwriterequests), so sessions can't be mapped to the unsubscribing
+    // central; teardown is left to the per-link keepalive/timeout liveness in
+    // _onChannel (15s).
+    this.server.on('unsubscribe', () => {})
+    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) {
+      this._dataChar = new Characteristic(DATA_UUID, { write: true, notify: true })
+      this.server.addService(new Service(this.serviceUUID, [this._dataChar]))
+    }
+  }
+
+  _maybeAdvertise() {
+    if (this._advertising || !this._serviceAdded) return
+    this._advertising = true
+    this.server.startAdvertising({ serviceUUIDs: [this.serviceUUID] })
+  }
+
+  // ─── server (peripheral) side ─────────────────────────────────────────────
+
+  _onWriteRequests(requests) {
+    const ok = this.server.constructor.ATT_SUCCESS ?? 0
+    for (const req of requests) {
+      // respond within ms or the central times out — before any parsing
+      if (req.responseNeeded !== false) this.server.respondToRequest(req, ok)
+      if (this._suspended) continue // off means off: acknowledge but drop
+      this._onServerFrame(req.data)
+    }
+  }
+
+  _onServerFrame(data) {
+    const f = parseFrame(data)
+    if (!f) {
+      return
+    }
+    if (f.type === TYPE_OPEN) {
+      if (this._sessions.has(f.sidHex)) return // duplicate open
+      const sid = b4a.from(f.sid) // copy: f.sid views the transient request buffer
+      const stream = new GattStream({
+        send: (payload) => this._enqueueNotify(frame(TYPE_DATA, sid, payload)),
+        onclose: () => this._closeServerSession(f.sidHex, sid)
+      })
+      const session = { stream, sid, conn: null, name: null }
+      this._sessions.set(f.sidHex, session)
+      session.conn = this._onChannel(stream, false, null)
+      // greet the peer with our app-user name so it can label this link
+      this._enqueueNotify(frame(TYPE_HELLO, sid, this._helloPayload())).catch(safetyCatch)
+    } else if (f.type === TYPE_DATA) {
+      const s = this._sessions.get(f.sidHex)
+      if (s) s.stream.receive(b4a.from(f.payload))
+    } else if (f.type === TYPE_HELLO) {
+      const s = this._sessions.get(f.sidHex)
+      if (s) this._applyPeerName(s, f.payload)
+    } else if (f.type === TYPE_CLOSE) {
+      const s = this._sessions.get(f.sidHex)
+      if (s) {
+        this._sessions.delete(f.sidHex)
+        s.stream.remoteEnd()
+      }
+    } else {
+    }
+  }
+
+  _closeServerSession(sidHex, sid) {
+    if (!this._sessions.has(sidHex)) return // already torn down (peer sent close)
+    this._sessions.delete(sidHex)
+    this._enqueueNotify(frame(TYPE_CLOSE, sid)).catch(safetyCatch) // best effort
+  }
+
+  // ─── peer display name (hello frame) ──────────────────────────────────────
+
+  /** Our hello payload: the local app-user name the peer labels this link with. */
+  _helloPayload() {
+    return b4a.from(JSON.stringify({ n: this.name || '' }))
+  }
+
+  /**
+   * Parse a hello payload. Malformed → null (the caller ignores it).
+   *
+   * @param {Uint8Array} payload
+   * @returns {string | null}
+   */
+  _parseHello(payload) {
+    try {
+      const { n } = JSON.parse(b4a.toString(payload))
+      return typeof n === 'string' ? n : ''
+    } catch {
+      return null
+    }
+  }
+
+  /** Stash a peer's name onto a server session + its conn, then refresh mirrors. */
+  _applyPeerName(session, payload) {
+    const name = this._parseHello(payload)
+    if (name === null) return // malformed hello — ignore
+    session.name = name
+    if (session.conn) session.conn._peerName = name
+    this.emit('update')
+  }
+
+  // Serialize notifications through the single characteristic: updateValue
+  // returns false when the peripheral's queue is full — hold the frame and retry
+  // on the next 'readyToUpdate', preserving order.
+  _enqueueNotify(f) {
+    return new Promise((resolve, reject) => {
+      this._notifyQueue.push({ frame: f, resolve, reject })
+      this._drainNotify()
+    })
+  }
+
+  _drainNotify() {
+    while (this._notifyQueue.length) {
+      const item = this._notifyQueue[0]
+      let ok
+      try {
+        ok = this.server.updateValue(this._dataChar, item.frame)
+      } catch (err) {
+        this._notifyQueue.shift()
+        item.reject(err)
+        continue
+      }
+      if (!ok) return // queue full — wait for 'readyToUpdate', retry same frame
+      this._notifyQueue.shift()
+      item.resolve()
+    }
+  }
+
+  _startScan() {
+    if (this._scanning || this.central.state !== 'poweredOn') return
+    this._scanning = true
+    this.central.startScan([this.serviceUUID], this.scanOptions)
+    this._armScanRestart()
+  }
+
+  // Scan scheduler (bitchat model). Lonely: cycle the scan every
+  // SCAN_RESTART_LONELY so a re-advertised peer is re-reported (iOS suppresses
+  // duplicate discoveries within a scan session). Linked: duty-cycle to save the
+  // battery — scan SCAN_DUTY_ON, then go dark SCAN_DUTY_OFF, repeat. The next
+  // delay is derived from the current phase, so one timer drives the whole cycle.
+  _armScanRestart() {
+    if (this._scanTimer) clearTimeout(this._scanTimer)
+    const delay =
+      this.linkCount > 0 ? (this._scanning ? SCAN_DUTY_ON : SCAN_DUTY_OFF) : SCAN_RESTART_LONELY
+    this._scanTimer = setTimeout(() => {
+      this._scanTimer = null
+      if (this.closing || this.closed || this._suspended) return
+      // never toggle the scan mid-dial (would kill the connect) — defer a phase
+      if (this._dialing.size > 0) {
+        this._armScanRestart()
+        return
+      }
+      if (this.linkCount > 0) {
+        if (this._scanning) {
+          this._stopScan() // enter the dark half of the duty cycle
+          this._armScanRestart()
+        } else {
+          this._startScan() // wake up and re-arm for the next dark window
+        }
+      } else {
+        this._stopScan() // lonely: cycle so re-advertised peers re-report
+        this._startScan()
+      }
+    }, delay)
+    if (this._scanTimer.unref) this._scanTimer.unref()
+  }
+
+  _stopScan() {
+    if (!this._scanning) return
+    this._scanning = false
+    try {
+      this.central.stopScan()
+    } catch (err) {
+      safetyCatch(err)
+    }
+  }
+
+  _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._suspended) return
+    if (this._linked.has(peripheral.id)) return // already linked
+    const knownPeer = this._peerByPeripheral.get(peripheral.id)
+    if (knownPeer && this.peers.has(knownPeer)) return // device already linked via another channel
+    const cool = this._coolUntil.get(peripheral.id)
+    if (cool && cool > Date.now()) return // failed recently — back off
+    if (this._dialing.has(peripheral.id)) return // already connecting to this one
+    if (this.linkCount >= this.cap) return // gossip covers the rest
+    // global rate limit: one radio can't usefully dial faster than this, and
+    // back-to-back connects thrash CoreBluetooth (bitchat connect hygiene)
+    if (Date.now() - this._lastDial < DIAL_MIN_INTERVAL) return
+    // no tie-break: dial every discovery and open a session (bitchat model);
+    // a redundant link to the same peer is dropped by _track's dedup
+    this._lastDial = Date.now()
+    const timer = setTimeout(() => this._abortDial(peripheral, 'timeout'), CONNECT_TIMEOUT)
+    this._dialing.set(peripheral.id, timer)
+    try {
+      this._stopScan()
+      this.central.connect(peripheral)
+    } catch (err) {
+      this._abortDial(peripheral, err)
+    }
+  }
+
+  _onConnect(peripheral) {
+    this._connectedPeripherals.add(peripheral)
+    peripheral.on('error', () => this._abortDial(peripheral, 'peripheral-error'))
+    peripheral.once('servicesDiscover', (services) => {
+      const svc = findByUUID(services, this.serviceUUID)
+      if (svc) peripheral.discoverCharacteristics(svc, [DATA_UUID])
+      else this._abortDial(peripheral, 'no-service')
+    })
+    peripheral.once('characteristicsDiscover', (_svc, chars) => {
+      const dataChar = findByUUID(chars, DATA_UUID)
+      if (dataChar) peripheral.subscribe(dataChar)
+      else this._abortDial(peripheral, 'no-data-char')
+    })
+    peripheral.once('notifyState', (char, isNotifying) => {
+      if (!isNotifying) {
+        this._abortDial(peripheral, 'subscribe-failed')
+        return
+      }
+      this._startCentralSession(peripheral, char)
+    })
+    // No tie-break: both sides open a session (bitchat model). On iOS the peer
+    // id isn't known until after connect, so a tie-break can only yield
+    // post-handshake — which deadlocks when the other side never dials back.
+    // Redundant links are tolerated; _track keeps the first and drops the dup.
+    peripheral.discoverServices([this.serviceUUID])
+  }
+
+  // ─── central side ─────────────────────────────────────────────────────────
+
+  _startCentralSession(peripheral, char) {
+    const sid = randomBytes(SID_LEN)
+    const sidHex = b4a.toString(sid, 'hex')
+    peripheral._session = { sidHex, sid }
+    peripheral._char = char // suspend's goodbye writes reuse it
+    peripheral.on('notify', (_char, data) => this._onCentralNotify(peripheral, data))
+    const stream = new GattStream({
+      send: (payload) => this._centralSend(peripheral, char, frame(TYPE_DATA, sid, payload)),
+      onclose: () => {
+        this._centralSend(peripheral, char, frame(TYPE_CLOSE, sid)).catch(safetyCatch)
+        this._connectedPeripherals.delete(peripheral)
+        try {
+          this.central.disconnect(peripheral)
+        } catch (err) {
+          safetyCatch(err)
+        }
+      }
+    })
+    peripheral._stream = stream
+    // open frame first: it registers the session on the server before any data
+    this._centralSend(peripheral, char, frame(TYPE_OPEN, sid)).catch(safetyCatch)
+    // greet the peer with our app-user name so it can label this link
+    this._centralSend(peripheral, char, frame(TYPE_HELLO, sid, this._helloPayload())).catch(
+      safetyCatch
+    )
+    this._clearDial(peripheral.id)
+    peripheral._conn = this._onChannel(stream, true, peripheral.id)
+  }
+
+  _onCentralNotify(peripheral, data) {
+    const sess = peripheral._session
+    if (!sess || !peripheral._stream) return
+    const f = parseFrame(data)
+    if (!f) {
+      return
+    }
+    if (f.sidHex !== sess.sidHex) return // not our session (broadcast to others)
+    if (f.type === TYPE_DATA) peripheral._stream.receive(b4a.from(f.payload))
+    else if (f.type === TYPE_HELLO) {
+      const name = this._parseHello(f.payload)
+      if (name === null) return // malformed hello — ignore
+      peripheral._peerName = name
+      if (peripheral._conn) peripheral._conn._peerName = name
+      this.emit('update')
+    } else if (f.type === TYPE_CLOSE) {
+      peripheral._session = null
+      peripheral._stream.remoteEnd()
+    }
+  }
+
+  // One write in flight per peripheral: chain each write behind the previous,
+  // resolving on the 'write' completion event before the next is issued.
+  _centralSend(peripheral, char, f) {
+    const prev = peripheral._writeChain || Promise.resolve()
+    const next = prev.then(() => this._writeOnce(peripheral, char, f))
+    peripheral._writeChain = next.catch(safetyCatch) // keep the chain alive
+    return next
+  }
+
+  _writeOnce(peripheral, char, f) {
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        peripheral.removeListener('write', onWrite)
+        peripheral.removeListener('error', onErr)
+      }
+      const onWrite = () => {
+        cleanup()
+        resolve()
+      }
+      const onErr = (err) => {
+        cleanup()
+        reject(err)
+      }
+      peripheral.once('write', onWrite)
+      peripheral.once('error', onErr)
+      try {
+        peripheral.write(char, f, true)
+      } catch (err) {
+        cleanup()
+        reject(err)
+      }
+    })
+  }
+
+  _abortDial(peripheral, _reason) {
+    const id = peripheral?.id
+    // eager when unlinked, patient once linked; per-peer exponential backoff so a
+    // peer that keeps failing is retried ever less often (bitchat connect hygiene)
+    if (id != null) {
+      const count = (this._failures.get(id) || 0) + 1
+      this._failures.set(id, count)
+      const base = this.linkCount === 0 ? DIAL_COOLDOWN_BASE_LONELY : DIAL_COOLDOWN_BASE
+      const cooldown = Math.min(DIAL_COOLDOWN_MAX, base * 2 ** Math.min(4, count - 1))
+      this._coolUntil.set(id, Date.now() + cooldown)
+    }
+    this._clearDial(id)
+    this._connectedPeripherals.delete(peripheral)
+    try {
+      this.central.disconnect(peripheral)
+    } catch (err) {
+      safetyCatch(err)
+    }
+    this._startScan()
+  }
+
+  _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 || this._suspended) {
+      l2cap.destroy()
+      return
+    }
+    const conn = this.network.inject(l2cap, { isInitiator })
+    // Liveness: iOS never signals an L2CAP disconnect, so ping the peer and
+    // drop the link if we stop hearing back (keepalive refreshes the timeout).
+    conn.setKeepAlive(5000)
+    conn.setTimeout(15000)
+    l2cap.on('error', safetyCatch)
+    // marked at channel-open (not handshake-open): rediscovery must not dial a
+    // peripheral whose channel is still handshaking
+    if (peripheralId != null) {
+      this._linked.add(peripheralId)
+      this._coolUntil.delete(peripheralId)
+      this._failures.delete(peripheralId) // reached a live session — reset backoff
+      conn.once('close', () => this._linked.delete(peripheralId))
+    }
+    conn.on('open', () => this._track(conn, peripheralId, isInitiator))
+    conn.on('close', () => this._untrack(conn, peripheralId))
+    this._startScan()
+    return conn
+  }
+
+  _track(conn, peripheralId, isInitiator) {
+    if (peripheralId != null && conn.remotePublicKey) {
+      this._peerByPeripheral.set(peripheralId, b4a.toString(conn.remotePublicKey, 'hex'))
+    }
+    if (this.closing || this.closed) return
+    const key = b4a.toString(conn.remotePublicKey, 'hex')
+    const existing = this.peers.get(key)
+    if (existing && existing !== conn) {
+      // Both sides dial (bitchat model) so a pair links twice — two separate
+      // channels, each with an initiator end on one device and a responder end
+      // on the other. Dropping a channel closes it for BOTH devices, so the two
+      // devices MUST retire the same channel or one tears down the peer's kept
+      // link. Deterministic winner: keep the channel whose initiator has the
+      // smaller static key. Both peers compute it identically (initiator end:
+      // our key smaller; responder end: remote key smaller), so the loser
+      // channel is dropped on both ends and never cascades onto the survivor.
+      const initiatorIsUsSmaller = b4a.compare(conn.publicKey, conn.remotePublicKey) < 0
+      const preferred = isInitiator === initiatorIsUsSmaller
+      if (!preferred) {
+        conn.destroy()
+        return
+      }
+    }
+    conn._peripheralId = peripheralId
+    conn._peerKey = key
+    this.peers.set(key, conn)
+    if (existing && existing !== conn) existing.destroy() // retire the loser channel
+    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) {
+      // last link gone → hunt immediately instead of waiting out a dark window
+      if (this.linkCount === 0 && !this._suspended) this._startScan()
+      this.emit('update')
+    }
+  }
+
+  /**
+   * Best-effort TYPE_CLOSE to every live session — server sessions over the
+   * notify path, central sessions over the write path — reusing the same helpers
+   * a normal stream close uses. Waits up to DRAIN_MS for the frames to flush,
+   * then resolves regardless: suspend must never hang on a wedged radio.
+   *
+   * @returns {Promise<void>}
+   */
+  async _sayGoodbye() {
+    const sent = []
+    for (const { sid } of this._sessions.values()) {
+      sent.push(this._enqueueNotify(frame(TYPE_CLOSE, sid)).catch(safetyCatch))
+    }
+    for (const peripheral of this._connectedPeripherals) {
+      const sess = peripheral._session
+      if (!sess || !peripheral._char) continue
+      const f = frame(TYPE_CLOSE, sess.sid)
+      sent.push(this._centralSend(peripheral, peripheral._char, f).catch(safetyCatch))
+    }
+    if (!sent.length) return
+    await Promise.race([Promise.all(sent), new Promise((r) => setTimeout(r, DRAIN_MS))])
+  }
+
+  /**
+   * Pause radio activity but KEEP the Server/Central instances and the
+   * registered GATT service alive — the toggle-friendly counterpart to _close.
+   * iOS CoreBluetooth managers can't be destroy()ed (native double-free), so a
+   * fresh transport per toggle leaks a manager whose stale peripheral-manager
+   * keeps a duplicate GATT service registered; remote centrals then subscribe to
+   * the dead service and hear silence. Reuse one instance instead. Idempotent.
+   */
+  async suspend() {
+    this._suspended = true
+    if (this._scanTimer) clearTimeout(this._scanTimer)
+    this._scanTimer = null
+    for (const timer of this._dialing.values()) clearTimeout(timer)
+    this._dialing.clear()
+    // Say goodbye BEFORE teardown so the remote reacts in <1s instead of waiting
+    // out the 15s keepalive: close frames, a short drain, then drop the physical
+    // links (an ACL disconnect is an instant OS-level signal on both roles).
+    await this._sayGoodbye()
+    for (const peripheral of this._connectedPeripherals) {
+      try {
+        this.central.disconnect(peripheral)
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+    this._connectedPeripherals.clear()
+    try {
+      this._stopScan()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    try {
+      this.server?.stopAdvertising()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    this._advertising = false
+    for (const conn of this.peers.values()) {
+      try {
+        conn.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+    this.peers.clear()
+    for (const { stream } of this._sessions.values()) {
+      try {
+        stream.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+    this._sessions.clear()
+    for (const item of this._notifyQueue) item.reject(new Error('suspended'))
+    this._notifyQueue = []
+    this._linked.clear()
+    this._coolUntil.clear()
+    this._failures.clear()
+    this.state = 'off'
+    this.emit('update')
+  }
+
+  /**
+   * Restart advertising + scanning on the SAME Server/Central. `_serviceAdded`
+   * is still true (the service was never removed) so advertising resumes
+   * immediately. Safe to call repeatedly; no-op once closing/closed.
+   */
+  resume() {
+    this._suspended = false
+    if (this.closing || this.closed) return
+    this._advertising = false
+    this._maybeAdvertise()
+    this._startScan()
+    const raw = this.central?.state ?? this.server?.state
+    this.state = STATE[raw] ?? 'waiting'
+    this.emit('update')
+  }
+
+  async _close() {
+    if (this._scanTimer) clearTimeout(this._scanTimer)
+    this._scanTimer = null
+    // 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)
+        }
+      }
+      // kept links keep carrying frames through their sessions/notify queue; only
+      // tear this down when we're actually dropping the links
+      for (const item of this._notifyQueue) item.reject(new Error('closed'))
+      this._notifyQueue = []
+      this._sessions.clear()
+    }
+    this.peers.clear()
+    this.state = 'off'
+  }
+}