@cero-base/core 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/core",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "cero p2p primitives — identity, storage, network, database, blobs, rpc, pairing.",
   "type": "module",
   "sideEffects": false,

package/src/network/bluetooth.js

@@ -1,15 +1,77 @@
 import ReadyResource from 'ready-resource'
 import b4a from 'b4a'
-import { hash } from 'hypercore-crypto'
+import { hash, randomBytes } 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'
+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
@@ -46,14 +108,15 @@ const uuidEq = (a, b) =>
 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
+ * 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 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.
+ * 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.
@@ -71,6 +134,7 @@ export class BluetoothTransport extends ReadyResource {
    * @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,
@@ -80,11 +144,13 @@ export class BluetoothTransport extends ReadyResource {
     tag = 'cero-ble',
     cap = DEFAULT_CAP,
     scanOptions,
-    keepLinks = false
+    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)
@@ -95,12 +161,31 @@ export class BluetoothTransport extends ReadyResource {
     this.state = 'off'
     this.central = null
     this.server = null
-    this.psm = 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()
   }
@@ -133,18 +218,15 @@ export class BluetoothTransport extends ReadyResource {
       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('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()
@@ -165,22 +247,173 @@ export class BluetoothTransport extends ReadyResource {
   _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]))
+      this._dataChar = new Characteristic(DATA_UUID, { write: true, notify: true })
+      this.server.addService(new Service(this.serviceUUID, [this._dataChar]))
     }
-    if (this.psm == null) this.server.publishChannel({})
   }
 
   _maybeAdvertise() {
-    if (this._advertising || !this._serviceAdded || this.psm == null) return
+    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) {
@@ -192,13 +425,24 @@ export class BluetoothTransport extends ReadyResource {
 
   _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
-    // tie-break is decided post-read (we can't trust advertisement payloads);
-    // dial now, learn the peer id from the PSM characteristic, decide there.
+    // 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)
@@ -206,44 +450,137 @@ export class BluetoothTransport extends ReadyResource {
   }
 
   _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, [PSM_UUID])
+      if (svc) peripheral.discoverCharacteristics(svc, [DATA_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')
+      const dataChar = findByUUID(chars, DATA_UUID)
+      if (dataChar) peripheral.subscribe(dataChar)
+      else this._abortDial(peripheral, 'no-data-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')
+    peripheral.once('notifyState', (char, isNotifying) => {
+      if (!isNotifying) {
+        this._abortDial(peripheral, 'subscribe-failed')
         return
       }
-      peripheral.once('channelOpen', (l2cap) => {
-        this._clearDial(peripheral.id)
-        this._onChannel(l2cap, true, peripheral.id)
-      })
-      peripheral.openL2CAPChannel(psm)
+      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) {
@@ -264,36 +601,174 @@ export class BluetoothTransport extends ReadyResource {
   }
 
   _onChannel(l2cap, isInitiator, peripheralId) {
-    if (this.closing || this.closed) {
+    if (this.closing || this.closed || this._suspended) {
       l2cap.destroy()
       return
     }
     const conn = this.network.inject(l2cap, { isInitiator })
-    conn.on('open', () => this._track(conn, peripheralId))
+    // 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) {
+  _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) {
-      conn.destroy() // duplicate link to the same peer — keep the first
-      return
+      // 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) this.emit('update')
+    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)
@@ -317,6 +792,11 @@ export class BluetoothTransport extends ReadyResource {
           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'

package/src/network/gatt-stream.js

@@ -0,0 +1,59 @@
+import { Duplex } from 'streamx'
+
+// iOS caps a single GATT write (and a notify payload) at ATT_MTU − 3 ≈ 182
+// bytes. 150 stays safely under that without negotiating an MTU. Raise later
+// via the peripheral's maximumWriteValueLength + write-without-response.
+const PAYLOAD = 150
+
+/**
+ * A dumb byte-carrying duplex for the GATT transport. Framing and session logic
+ * live in BluetoothTransport; this only fragments outbound writes to fit a GATT
+ * write and pushes inbound payload bytes. NoiseSecretStream wraps it as a raw
+ * duplex, exactly like the old L2CAP channel.
+ *
+ * @extends Duplex
+ */
+export class GattStream extends Duplex {
+  /**
+   * @param {object} opts
+   * @param {(buffer: Uint8Array) => Promise<void>} opts.send  Transmit one payload piece (transport frames it).
+   * @param {() => void} [opts.onclose]  Called once on teardown (send a close frame, disconnect).
+   */
+  constructor({ send, onclose } = {}) {
+    super()
+    this._send = send
+    this._onclose = onclose || null
+  }
+
+  async _write(chunk, cb) {
+    try {
+      for (let offset = 0; offset < chunk.byteLength; offset += PAYLOAD) {
+        await this._send(chunk.subarray(offset, offset + PAYLOAD))
+      }
+      cb(null)
+    } catch (err) {
+      cb(err)
+    }
+  }
+
+  receive(buffer) {
+    this.push(buffer)
+  }
+
+  remoteEnd() {
+    this.push(null)
+  }
+
+  _destroy(cb) {
+    const onclose = this._onclose
+    this._onclose = null
+    if (onclose) {
+      try {
+        onclose()
+      } catch {
+        // teardown is best-effort
+      }
+    }
+    cb(null)
+  }
+}

package/src/network/index.js

@@ -60,8 +60,16 @@ export class Network extends ReadyResource {
   inject(stream, { isInitiator } = {}) {
     if (this.closing || this.closed) throw CeroError.CLOSED('Network')
     if (!stream) throw CeroError.REQUIRED('stream')
+    // Injected links authenticate with the same long-lived identity as the
+    // swarm — an ephemeral key per link would defeat duplicate-peer detection
+    // (two radios between one pair would look like two different peers).
+    const keyPair = this.identity
+      ? { publicKey: this.identity.publicKey, secretKey: this.identity.secretKey }
+      : (this.swarm?.keyPair ?? undefined)
     const conn =
-      stream.noiseStream === stream ? stream : new NoiseSecretStream(isInitiator === true, stream)
+      stream.noiseStream === stream
+        ? stream
+        : new NoiseSecretStream(isInitiator === true, stream, keyPair ? { keyPair } : undefined)
 
     // 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,

package/types/network/bluetooth.d.ts

@@ -8,14 +8,15 @@
  */
 export function toServiceUUID(topic: Uint8Array, tag?: string): string;
 /**
- * Dual-role BLE transport: advertises + scans one service UUID, opens an L2CAP
- * channel to each discovered peer, and feeds it into `network.inject`. From
+ * 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 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.
+ * 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.
@@ -33,8 +34,9 @@ export class BluetoothTransport extends ReadyResource {
      * @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, cap, scanOptions, keepLinks }: {
+    constructor({ backend, network, uuid, nodeId, tag, cap, scanOptions, keepLinks, name }: {
         backend: any;
         network: import("./index.js").Network;
         uuid: Uint8Array;
@@ -45,9 +47,11 @@ export class BluetoothTransport extends ReadyResource {
             scanMode?: any;
         };
         keepLinks?: boolean;
+        name?: string;
     });
     backend: any;
     network: import("./index.js").Network;
+    name: string;
     nodeId: Uint8Array<ArrayBufferLike>;
     nodeHex: any;
     serviceUUID: string;
@@ -59,12 +63,31 @@ export class BluetoothTransport extends ReadyResource {
     state: string;
     central: any;
     server: any;
-    psm: any;
+    _dataChar: any;
+    /** sessionId hex → { stream, sid } for server-side (peripheral) sessions */
+    _sessions: Map<any, any>;
+    /** serialized server notify queue: { frame, resolve, reject } */
+    _notifyQueue: any[];
     _scanning: boolean;
     _advertising: boolean;
     _serviceAdded: boolean;
     /** peripheral id being dialed → its connect-timeout timer */
     _dialing: Map<any, any>;
+    /** peripheral ids that carry a live channel — never re-dialed (a second
+     * dial's failure would disconnect the peripheral and kill the good link) */
+    _linked: Set<any>;
+    /** peripheral id → retry-after timestamp; failed dials back off */
+    _coolUntil: Map<any, any>;
+    /** peripheral id → consecutive failure count; drives exponential backoff */
+    _failures: Map<any, any>;
+    /** peripheral id → remote peer key, learned at handshake — dial guard */
+    _peerByPeripheral: Map<any, any>;
+    /** live central-side peripheral wrappers — for goodbye + physical hang-up on suspend */
+    _connectedPeripherals: Set<any>;
+    /** last central.connect timestamp — global inter-dial rate limit */
+    _lastDial: number;
+    _scanTimer: any;
+    _suspended: boolean;
     /** live injected links keyed by remote node id hex */
     peers: Map<any, any>;
     /**
@@ -79,15 +102,61 @@ export class BluetoothTransport extends ReadyResource {
     get linkCount(): number;
     _startServer(Service: any, Characteristic: any): void;
     _maybeAdvertise(): void;
+    _onWriteRequests(requests: any): void;
+    _onServerFrame(data: any): void;
+    _closeServerSession(sidHex: any, sid: any): void;
+    /** Our hello payload: the local app-user name the peer labels this link with. */
+    _helloPayload(): any;
+    /**
+     * Parse a hello payload. Malformed → null (the caller ignores it).
+     *
+     * @param {Uint8Array} payload
+     * @returns {string | null}
+     */
+    _parseHello(payload: Uint8Array): string | null;
+    /** Stash a peer's name onto a server session + its conn, then refresh mirrors. */
+    _applyPeerName(session: any, payload: any): void;
+    _enqueueNotify(f: any): Promise<any>;
+    _drainNotify(): void;
     _startScan(): void;
+    _armScanRestart(): void;
+    _stopScan(): void;
     _onState(raw: any): void;
     _onDiscover(peripheral: any): void;
     _onConnect(peripheral: any): void;
+    _startCentralSession(peripheral: any, char: any): void;
+    _onCentralNotify(peripheral: any, data: any): void;
+    _centralSend(peripheral: any, char: any, f: any): any;
+    _writeOnce(peripheral: any, char: any, f: any): Promise<any>;
     _abortDial(peripheral: any, _reason: any): void;
     _clearDial(id: any): void;
     _onCentralError(err: any): void;
-    _onChannel(l2cap: any, isInitiator: any, peripheralId: any): void;
-    _track(conn: any, peripheralId: any): void;
+    _onChannel(l2cap: any, isInitiator: any, peripheralId: any): any;
+    _track(conn: any, peripheralId: any, isInitiator: any): void;
     _untrack(conn: any): void;
+    /**
+     * 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>}
+     */
+    _sayGoodbye(): Promise<void>;
+    /**
+     * 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.
+     */
+    suspend(): Promise<void>;
+    /**
+     * 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(): void;
 }
 import ReadyResource from 'ready-resource';

package/types/network/gatt-stream.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A dumb byte-carrying duplex for the GATT transport. Framing and session logic
+ * live in BluetoothTransport; this only fragments outbound writes to fit a GATT
+ * write and pushes inbound payload bytes. NoiseSecretStream wraps it as a raw
+ * duplex, exactly like the old L2CAP channel.
+ *
+ * @extends Duplex
+ */
+export class GattStream extends Duplex<import("streamx").DuplexEvents> {
+    /**
+     * @param {object} opts
+     * @param {(buffer: Uint8Array) => Promise<void>} opts.send  Transmit one payload piece (transport frames it).
+     * @param {() => void} [opts.onclose]  Called once on teardown (send a close frame, disconnect).
+     */
+    constructor({ send, onclose }?: {
+        send: (buffer: Uint8Array) => Promise<void>;
+        onclose?: () => void;
+    });
+    _send: (buffer: Uint8Array) => Promise<void>;
+    _onclose: () => void;
+    _write(chunk: any, cb: any): Promise<void>;
+    receive(buffer: any): void;
+    remoteEnd(): void;
+    _destroy(cb: any): void;
+}
+import { Duplex } from 'streamx';