07 — Bluetooth followers
Esta página aún no está disponible en tu idioma.
2026-10-16 · investigation report · builds on 06 — Sharing and keys · spec: PROTOCOL-v2, treatments: libreview SPEC §5
- BLE as a second transport for the same signed + encrypted v2 events (owner = GATT server, follower =
central). Security from the events (signatures, roster, NIP-44 to
G_n), not from BLE pairing. A follower with no internet must keep receiving. - Nearby pairing over BLE: no QR, no internet — the follower lists nearby owners, sends its access request over BLE, the owner sees the usual Allow dialog with the match code, the key delivery comes back over BLE.
- Followers as writers: owner toggle “Can add entries” → follower key in roster
writers→ follower can add a treatment that the owner accepts only if the signer is a writer.
Result
Section titled “Result”All three work, on real radio (Pixel owner ↔ Mac) and app↔app (two emulators via netsim), with the follower
emulator’s Wi-Fi and mobile data off for the whole app↔app run. Transport code is ~400 lines on top of 06’s
Transport seam; the engines’ acceptance rules are unchanged — BLE events go into the same onEvent(json, via).
| # | Claim | Devices | Result | Evidence (poc/spikes/nostr/android-app/evidence/) |
|---|---|---|---|---|
| 1 | Owner advertises, follower discovers it by service UUID | Pixel → Mac; emu → emu | ✅ Mac finds it in 0.2–5 s; emulator lists it with RSSI | 07-mac-ble-pairing.log, 07-follower-nearby-list.png |
| 2 | Same v2 events over BLE, verified/decrypted by an independent implementation | Pixel (Juggluco) → Mac (cgm2.py) |
✅ roster + 25 chunks + live, 27/27 accepted, 0 rejected | 07-mac-ble-treatment-rejected.log (first lines) |
| 3 | Live readings pushed over BLE as they happen | Pixel → Mac | ✅ every minute, ≈ 1 s after Juggluco’s reading | 07-mac-ble-writer-treatment-live.log |
| 4 | Follower with no internet keeps receiving (BLE only) | emu → emu (follower offline) | ✅ 24 h of chunks + live every minute, all via ble: while every relay fails with UnknownHostException |
07-emu-follower-offline.log, 07-follower-home-ble-offline.png |
| 5 | Nearby pairing: request over BLE, Allow + match code, key delivery back over BLE | Pixel ↔ Mac; emu ↔ emu (follower offline) | ✅ code 1841 on both sides (Mac); emulator: request → Allow → KEY accepted … via ble: → backlog readable |
07-mac-ble-pairing.log, 07-phone-owner.log, 07-owner-allow-dialog-ble.png, 07-follower-waiting-code-ble.png, 07-emu-follower-nearby-pairing.log |
| 6 | Non-writer’s treatment is rejected | Mac (approved follower, not a writer) → Pixel | ✅ treatment REJECTED: author Mac BLE … is not in roster writers |
07-phone-owner.log |
| 7 | Owner toggle → roster writers → follower learns it may write |
Pixel → Mac; emu → emu | ✅ roster over BLE shows writers [325d…] / follower UI shows “Add entry” |
07-mac-ble-writer-treatment-live.log, 07-emu-owner.log |
| 8 | Writer’s treatment accepted and stored by the owner | Mac → Pixel; offline emu → emu | ✅ TREATMENT accepted from Mac BLE via ble:… rapid 1.5; emulator: rapid 2.5 shown under “Entries from followers” |
07-phone-owner.log, 07-emu-owner.log, 07-follower-add-entry.png, 07-owner-writer-and-entry.png |
| 9 | Follower reconnects by itself after the owner restarts (new private address) | emu → emu | ✅ after the fix below (re-scan by service UUID) | 07-emu-follower-nearby-pairing.log |
Numbers (real radio: Pixel owner ↔ MacBook, same room)
Section titled “Numbers (real radio: Pixel owner ↔ MacBook, same room)”| Discovery (scan → found) | 0.2–5 s |
| Connect + service discovery | 4.6–4.9 s (one outlier 31.7 s) |
| ATT MTU | 517 requested by Android / 515 seen by bleak on macOS → 512-byte attribute limit applies (506 B payload per frame) |
HELLO → INFO |
63–121 ms |
| Backlog on connect (roster + 24–25 hour chunks + live, ~1.8–1.9 KB per chunk) | 47–52 KB in 2.2–2.4 s ≈ 19–22 KiB/s; once 48 KB in 4.2 s (11 KiB/s) while a second central (the Mac menubar agent) was also connected |
| Live push latency | phone clock was 1.85 s ahead of the Mac; corrected, ≈ 0.9 s from the phone’s created_at to receipt on the Mac (second-resolution timestamps → ±1 s) |
| Treatment write → owner accepted | ≈ 0.1 s (skew-corrected) |
| Emulator ↔ emulator (netsim) | live readings +0 s when the owner app is in front; +11…+18 s later while the owner emulator sat in the background (owner-side source timing, not BLE) |
Design
Section titled “Design” follower (central) owner phone (GATT server, advertises service UUID) ─ scan for service UUID ─────────────────────────► ─ connect, MTU 517, notify on TX, write HELLO {nonce} ► ◄──────────── INFO {nonce, m, (i, relays, pair)} ─ m proves sid; i/relays/pair only while "Pair nearby" is open ◄── EVENT roster, EVENT chunk ×24, EVENT live, EVENT recent gift wraps (backlog cache) ── EVENT gift wrap "request" (to I) ─────────────► onEvent(json, "ble:<addr>") → same rules → Allow dialog ◄──────────────── EVENT gift wrap "key" (to F) ─── every publish() also goes to BLE peers ── HELLO (again, now the backlog is readable) ───► ◄── EVENT live … every minute ── EVENT treatment (kind 30078, signed by F) ────► accepted only if F ∈ roster writers- One
Transportper medium.BleOwnerandBleFollowerimplement 06’sTransport; the engines callpublish()on every attached transport and receive throughonEvent(json, via)withvia = "ble:<addr>". Nothing BLE-specific is trusted: the owner’s backup event is never sent over BLE; everything else is the same bytes as on the relays (the Mac verified signatures and decrypted with its ownG_n). - Relays stay on. A BLE follower still subscribes to the relays; whichever copy arrives first wins (
viais stored per reading). With no internet the relay connections just fail and BLE carries everything. - Backlog cache on the owner (in memory): last roster, last ~38 hour chunks (by
d), latest live, last 10 gift wraps. Sent on everyHELLO(at most one backlog per central every 5 s; events whose expiration has passed are dropped from the cache, never re-sent). Caching wraps means a follower that drops out during approval still gets its key when it reconnects. A follower re-sendsHELLOafter accepting a new key, so chunks received before approval become readable. - Nearby pairing token: “Pair nearby (10 min)” creates a normal invite token (stored with the QR ones, single
use, burnt on Allow/Deny) and exposes it in
INFO. Anyone in range during those 10 minutes can ask; the owner still decides with the match code, exactly like the QR flow. - Writers:
OwnerState.writers(in the owner backup too) →writersarray of the roster (only active followers; removed on revoke). Owner accepts a treatment if: valid signature, author ∈ writers and an active follower,gkknown, decrypts with that epoch’sG,dtag matchesH("cgm2:tr:"+sid+":"+id); stored inowner.dbtabletreatmentswith LWW onu. Accepted BLE treatments are forwarded to the other BLE peers; the owner also subscribes on the relays to#ctreatments from writers, so a writer far away works over relays too (code path in place; only the BLE path was tested).
GATT framing
Section titled “GATT framing”Owner phone = peripheral / GATT server (advertises the service UUID in the advertising packet and no scan
response: the phone’s Bluetooth name, often its owner’s name, isn’t broadcast — investigation 24, P12). Follower =
central. No BLE pairing/bonding: anyone nearby may connect; trust comes only from the v2 events themselves
(signatures, roster, NIP-44 to G_n, gift-wrap seal signer), exactly as for relays. (Android’s own GAP service still
answers a connected central’s Device Name read; an app can’t turn that off.)
| what | UUID | properties |
|---|---|---|
| service | 7c6a0001-5c3e-4f0a-9a57-c95e0b1e0007 |
primary |
| RX (follower → owner) | 7c6a0002-5c3e-4f0a-9a57-c95e0b1e0007 |
write (with response) |
| TX (owner → follower) | 7c6a0003-5c3e-4f0a-9a57-c95e0b1e0007 |
notify (CCCD 0x2902) |
Frame (each GATT write or notification): 6-byte header, big endian, then payload bytes
[msgId u16][idx u16][count u16][payload: up to min(ATT_MTU - 3, 512) - 6 bytes]The link rules (every frame within one ATT write, long writes on the wearer, which phone is the wearer’s, how long a
phone is left alone) are specified once, in PROTOCOL-v2 “Bluetooth link”,
and pinned by contracts/protocol/ble/link-rules.json; this section is the background.
msgIdincrements per message per sender (wraps at 65535);idx= 0..count-1; frames are sent in order.- Receiver keeps one buffer per
msgId; a frame withidx == 0restarts that buffer. When allcountparts are present, concatenate payloads → UTF-8 → one JSON array (the message). - Limits (P13, Android and Mac): a buffer idle for 30 s is dropped; a message over 256 KiB is dropped (its later frames ignored); at most 16 buffers are open (the oldest goes).
- Owner limits (P13): at most 8 centrals at once; a write is checked before the GATT response, and a frame
shorter than the header, with
idx ≥ countorcount = 0, or over the central’s byte budget (256 KiB a minute) getsGATT_WRITE_NOT_PERMITTEDand the central is disconnected; at most 30 messages a minute per central (more are dropped). - Central requests MTU 517 (Android) / takes the ATT MTU from
maximumWriteValueLength(for: .withoutResponse)+ 3 (CoreBluetooth; the.withResponselength is always 512 and would make every frame a long write); the owner uses each central’s negotiated MTU for its notifications (23 if never negotiated → 14 payload bytes per frame). The owner still accepts a long (Prepare / Execute) write on RX: parts in offset order, ≤ 512 bytes, one queue per central, dropped 30 s after its last part without an Execute Write. - Owner sends one notification at a time per central (next one after
onNotificationSent); central writes one frame at a time (next one after the write response).
Messages (Nostr-wire style JSON arrays):
| message | direction | meaning |
|---|---|---|
["HELLO", {"v":2,"nonce":"<16 random bytes, hex>"}] |
follower → owner | sent right after enabling notifications: “send INFO + what you have”; a fresh nonce every time |
["INFO", {"v":2,"nonce":"<the HELLO's>","m":"<H(\"cgm2:ble:\"+sid+\":\"+nonce)>"}] |
owner → follower | reply to HELLO. m proves the phone holds the stream’s sid without naming the stream (P12). Only while the owner has “Pair nearby” open (10 min) it also carries "i":"<I pubkey hex>","relays":[…],"pair":{"t":"<token>","x":<expiry>,"profile":{"name","avatar"}}: an invite token like the QR one plus the wearer’s profile (owner still has to Allow and type the match code) |
["EVENT", <signed nostr event>] |
both | any v2 event: live (21078), hour chunks / roster / treatments (30078), gift wraps (1059: access requests, key deliveries, rekey, revoked) |
After HELLO the owner sends INFO, then its cached events, none expired: the roster first, then the other cached
events in the order they were last published (in practice the hour chunks newest hour first, up to ~38, then the
sensor update and the newest alert), then the treatments of the last 30 days (newest 200), the latest live event and
the last 10 gift wraps. After that every event the owner publishes (live, chunks, roster,
key deliveries…) is also pushed to every subscribed central. The owner backup event is never sent over BLE.
Followers send access requests (gift wrap to I), rekey requests and treatments (kind 30078, see below) as
EVENTs on RX; the owner feeds them into the same onEvent(json, "ble:<addr>") as relay events.
Which owner (P12, Android and Mac; the rule: PROTOCOL-v2 “Bluetooth link”):
a follower writes nothing but HELLO until the phone’s INFO proves it’s its wearer’s. Once the follower knows the
sid, m is checked first: only m = H("cgm2:ble:"+sid+":"+nonce) for one of its last 4 HELLO nonces proves it (a
recorded INFO can’t be replayed; a pairing i is public, so it never does), and an i naming another identity still
makes it another wearer’s. Before the sid (request pending), i = its stream’s I while pairing says ours. Another
wearer’s phone is left and avoided for 10 minutes, and the scan goes on. While a request is still pending and the
phone isn’t pairing, the follower receives (events are verified anyway) but writes nothing.
Treatments (libreview SPEC §5): kind 30078, signed by the writer W (the follower key F), tags
d = H("cgm2:tr:"+sid+":"+id), c = H("cgm2:treatments:"+sid), gk, expiration (+30 d); content =
NIP-44(W → G_n.pub) of the §1 treatment JSON (id,k,a,t,n,u,del,o). The owner accepts it only if W is in the
roster writers (which it controls with the per-follower “Can add entries” switch) and is an active follower.
Implementation
Section titled “Implementation”CGM Share (poc/spikes/nostr/android-app, Kotlin), same app, both roles:
| file | what |
|---|---|
core/Ble.kt |
UUIDs, frame split / reassembly, INFO builder |
core/BleOwner.kt |
GATT server + advertiser, per-central notify queue (one in flight, onNotificationSent), backlog cache, forward() |
core/BleFollower.kt |
scan, connect, MTU, CCCD, HELLO, write queue, auto-reconnect with re-scan |
core/Proto.kt |
treatmentEvent, treatmentsC/D, roster writers |
owner/OwnerEngine.kt |
BLE start, “Pair nearby”, setWriter, onTreatment, treatments relay subscription |
owner/OwnerState.kt, owner/OwnerDb.kt |
writers (persisted + backup), treatments table (DB v2) |
follower/FollowerEngine.kt, FollowerState.kt |
joinNearby, addTreatment, roster writers, stored owner BLE address |
ui/* |
owner: “Nearby (Bluetooth)” card, per-follower “Can add entries” switch, “Entries from followers”; follower: “Find phones nearby” list, “Add entry” (insulin / carbs / note) |
App.kt |
debug-only dev.spike.cgmshare.CMD broadcast (owner, pair, approve, writer, fg) to drive a locked phone over adb |
AndroidManifest.xml |
BLUETOOTH_CONNECT, BLUETOOTH_ADVERTISE, BLUETOOTH_SCAN (neverForLocation) — runtime-requested at launch |
Mac test client: poc/spikes/nostr/ble/ble_follower.py (bleak, uses v2/cgm2.py for every check). Follower secret in
poc/spikes/nostr/secrets/ble-follower.json (gitignored, never printed).
Release APK built: poc/spikes/nostr/android-app/app/build/outputs/apk/release/app-release.apk (14 MB; only the debug
build was run on devices).
Bugs found (and fixed)
Section titled “Bugs found (and fixed)”- 512-byte attribute limit. With MTU 517, frames of
MTU − 3 = 514bytes madenotifyCharacteristicChangedfail; frames are now capped at 512 bytes (506 payload) whatever the MTU. - Roster missing from the BLE backlog after a restart (it is re-published to relays only weekly) → a fresh
BLE-only follower had no
writers/devices update. The owner now re-publishes the roster when BLE starts. - Rotating private addresses. Android advertises from a resolvable private address that changes when the app
restarts; reconnecting to the stored address failed with status 147 forever. The follower now re-scans by service
UUID and falls back to the stored address.
For several owners in range it should check— done (investigation 24, P12): the INFO must prove the stream’sINFO.ibefore trusting the link for writessidbefore any write, and another wearer’s phone is skipped. - Re-
HELLOloop in the Mac client: the backlog contains cached key wraps, so “new key → HELLO” looped. Only a key with an unknowngktriggersHELLOnow (the Android engine already ignores repeated keys). - CoreBluetooth stale identifiers: the Mac sometimes got a peripheral id that never connected (30 s timeout) while another Mac process (the menubar agent) held a link to the phone; the client retries with a fresh scan.
- Test-harness note: the phone’s
mainlog buffer is 256 KiB and rotates within minutes — capture withadb logcat -T 1 -s CgmShare.owner:I > filefrom the start.
Not done / open
Section titled “Not done / open”- Forged-key treatment over BLE from the Mac (random key, not a follower) did not complete: three connect
timeouts (bug 5). The equivalent rejection path is covered by the real non-writer follower (row 6), which is the
stricter case (valid follower, valid epoch, only
writersmembership missing). - Writer treatments over relays (follower away from the owner) — code path present, not tested.
Followers don’t show treatments— done in Sukrara (docs/10, polish round 2). No edits/deletes UI, no LibreView upload (showcase app wires investigation 04’s uploader).No GATT-level abuse limits— done (investigation 24, P13): reassembly timeout and size cap, per-central message and byte budgets, malformed frames refused before the response, at most 8 centrals, one backlog per 5 s.- Privacy:
— done (P12:INFOreveals the owner’s identity pubkey to anyone nearbyIonly while pairing, a blindedmotherwise; no name in the scan response). Still open: the encrypted events reveal activity timing, the phone advertises whenever sharing is on (not only while followers exist), and a connected central can read the phone’s name from Android’s GAP service. - Battery cost of advertising + GATT server with a follower connected all day: not measured (see investigation 11).
- Screen-off/Doze behaviour of the follower’s background re-scan (Android limits background scans) and the owner’s advertising over hours: not tested; only ~30 min runs.
- Two followers on one owner over BLE at once: worked incidentally (Mac test client + menubar agent), not measured.
- Release APK not run on a device.
Mac follower (GlucoseBar, now Sukrara for Mac) — same pairing as Android
Section titled “Mac follower (GlucoseBar, now Sukrara for Mac) — same pairing as Android”
GlucoseBar now follows a wearer exactly like the Android follower — over Nostr v2 (“Follow someone…” with the
invite link or a QR image, match code, Allow) and over Bluetooth v2 (nearby pairing with the same match code,
the GATT framing above). Keys live in the macOS Keychain. Notes and numbers: poc/spikes/menubar/FOLLOWER.md.
| Test | Result |
|---|---|
| Nostr, against the Python v2 owner | approved < 1 s, same code on both sides; 183/183 readings equal; rotation → rekey in ~4 s; revoke → “Access removed”; denied → 0 data; state survives restart (Keychain) |
| Bluetooth only, against the Pixel owner | code 0936 on both; key + 26 hour-chunks + live over BLE; 180/180 readings equal the phone’s DB; live < 1 s; with both transports the BLE copy wins, relay copies deduplicated |
| Writer | a Mac note accepted by the phone over BLE in 2 s |
Forgery self-test (-v2selftest) |
13/13 forged inputs rejected (forged key delivery, non-roster author, tampered content, fake roster, forged revoke, unknown epoch, …) |
Not done: rotation/revoke over BLE with the phone, opening a cgmshare: link live, Mac alarms and a local DB. Ad-hoc
signing means macOS asks once for Keychain access after each rebuild.
For the showcase app (bundling all features)
Section titled “For the showcase app (bundling all features)”- Copy
core/Ble.kt,core/BleOwner.kt,core/BleFollower.kt; attach them as extraTransports exactly as here. Keep the GATT framing above — the Mac menubar implements the same (another agent,poc/spikes/menubar). - Frames ≤ 512 bytes; one notification in flight per central; one write in flight on the central.
- Re-publish the roster when BLE starts; cache recent gift wraps; re-
HELLOafter a new key. - Reconnect by re-scanning the service UUID, not by stored MAC address.
- Manifest needs the three BLUETOOTH_* permissions (runtime) and the FGS type
connectedDeviceit already has. - Drop the debug
CMDreceiver (it’sBuildConfig.DEBUG-gated here, but exported).
Device state left behind
Section titled “Device state left behind”- Pixel
62240DLCH0005W: CGM Share debug build installed for the first time (Juggluco and GlucoBridge untouched; Bluetooth/Wi-Fi not toggled). Role owner, new identitynpub1ugv8n…jq9h(epoch 1), source Juggluco (127.0.0.1:17580), foreground service running, BLE advertising on, publishing to the 4 relays. Followers: two “Mac BLE” entries (9fc0…— an abandoned first test key, approved by the test harness — and325d…, the Mac test client, writer = on). One treatment stored (“rapid 1.5 mac writer test”). Phone screen is locked: drive it withadb shell am broadcast -a dev.spike.cgmshare.CMD -p dev.spike.cgmshare --es c pair|approve|writer …. - Emulators
emulator-5554(owner, synthetic) andemulator-5556(follower, joined over BLE) still running; follower network re-enabled at the end.