Presence Bridge

Logo

Local iPhone Bluetooth presence and estimated rooms for Home Assistant. Install with HACS, enroll with Presence Pair, and keep presence data in your home.

View the Project on GitHub ravhello/presence-bridge

Presence Pair protocol v2

Goals

The protocol lets an authenticated Home Assistant administrator associate a person with the Bluetooth identity created when that person’s iPhone bonds to a specific Windows or Linux receiver. It deliberately does not give the app a Home Assistant access token, MQTT credentials, or an IRK.

Transport

Home Assistant and the observer communicate through the local MQTT broker under presence_bridge/v1/observers/<observer_id>. After scanning a code, the iPhone temporarily advertises a Bluetooth LE GATT service. Current apps derive a fresh service UUID from the one-time QR secret and session id, which prevents Windows from reusing a stale GATT catalogue after a previous bond. Receivers also accept the original static service UUID so older app builds remain pairable. The Windows observer scans for either service and initiates the connection and bond.

Characteristic UUID Access
Service Per-session UUID; legacy 61dd168c-4ec1-40de-a78c-ccdce5774bba Temporary iPhone advertisement
Session ef70387a-ba9d-4e83-9171-fea99252b57a Plain read by observer
Claim 700dbb64-64ed-4f51-adae-b106a00e908a HMAC-authenticated read by observer
Result fb5312b1-c24c-42b5-8d21-5263874c258f HMAC-authenticated write by observer

Invitation

The authenticated HA panel creates a 32-byte random secret and a 2048-bit ephemeral RSA key. The app receives this short-lived URI through a QR code or a custom URL:

presencepair://pair?v=2&sid=<session>&oid=<observer>&exp=<unix>&secret=<base64url>

The invitation is valid for at most ten minutes to start. Scanning starts one five-minute app attempt, including proximity, retries and HA verification. The receiver starts its bounded attempt on the first exact QR-scoped advertisement. The completion phase inherits that deadline; it never renews it. Seeing a generic Presence Pair advertisement cannot consume or extend another invitation.

The Windows receiver keeps the same QR-scoped proximity beacon available after the initial proximity write, through service discovery, Bluetooth bonding, and the protected acknowledgement. The iPhone samples that beacon during the active exchange. If the signal is continuously too weak or disappears beyond the bounded gap, the app terminates the attempt with PP-PROX-02; it does not reuse the interrupted exchange and asks the user to start a fresh QR attempt. This is a proximity safety guard, not a calibrated distance measurement.

After a matching live address is verified and its identity persisted, HA sends the receiver a non-retained MQTT complete command for the same active session. Only then does the receiver advertise a completion receipt for at most 20 seconds, within the remaining attempt budget. A failed protected GATT acknowledgement must never produce a completion receipt, including reused bonds. The UUID is HMAC-SHA256(secret, UTF-8 of presence-bridge-complete:v2\nsid\noid\nexp), truncated to 16 bytes with the same UUID version/variant bits as the other services. The app scans only that UUID and accepts it only within its active attempt. It contains no identity or key. The encrypted GATT result means bond exchange accepted, not final HA completion.

Claim and acknowledgement

The observer first reads the public session characteristic and requires an exact match with its active invitation. It then reads and verifies this claim before requesting a Windows bond:

HMAC-SHA256(secret, "presence-bridge:v2\n<sid>\n<oid>\n<exp>")

The claim proves that the nearby app owns the one-time invitation. The QR secret itself is never transmitted over Bluetooth. Verifying the claim before the bond also avoids a Windows/iOS interoperability failure where WinRT hides the temporary iPhone GATT service immediately after committing the bond.

After verification, the observer writes an encrypted acknowledgement carrying:

HMAC-SHA256(secret, "presence-bridge-result:v2\n<sid>\n<oid>\n<exp>\naccepted")

The acknowledgement is mandatory and means the secure exchange succeeded, not that HA has saved the association. The app must wait for the QR-authenticated HA completion receipt. A lost GATT channel may be retried within the original deadline, but cannot downgrade the protected acknowledgement to best effort.

Linux uses the same contract locally in-process or over MQTT. It reads only the verified peer’s BlueZ bond file, requires an authenticated 128-bit LongTermKey, then performs the protected result write. Because BlueZ can resolve RPAs in the kernel, its encrypted result may also contain identity_address and secure_exchange_complete: true. HA accepts fresh observations of that address only from the enrolling observer. It never accepts another observer’s arbitrary MAC as equivalent to resolving the IRK. Raw identity addresses stay out of UI payloads and diagnostics.

The cross-language test vectors are:

sid             = abcdefghijklmnopQRSTUVWX
oid             = living_room_pc
exp             = 1800000180
secret          = bytes 00 through 1f
claim proof     = -q6gU_keDbd_kcgOXTfnolM0m3ke96HzM_b-z1uuXPk
acceptance proof = u1KQY_RD_yBH9VIx0CrrOe2nZ0zrkbuoa3iOBhH6QE4

Identity transfer

The SYSTEM observer selects the IRK created by the bond. For an existing bond, it matches the connected identity address or resolvable private address against the retained Windows IRKs. It encrypts the result with RSA-OAEP SHA-256 and publishes the ciphertext to HA. HA accepts the result only for the active session, decrypts it in memory, and checks that the IRK resolves a currently observed private address before storing it.

IRKs and raw addresses are omitted from entities, WebSocket UI payloads, logs, and diagnostics.

Threat model

Saved-bond repair

Following verified receiver-side removal, invitations can include the optional reset=forget_receiver query hint. This is phone-side preparation guidance only, not deletion authority. It does not alter the canonical claim, secret or derived GATT UUIDs. HA persists it by person/receiver across retries and restarts and clears it only with a verified identity commit. Supporting apps wait for explicit phone-side preparation before starting the radio transport; older apps retain the same protocol and see the guidance in the HA panel.

An unreadable service does not authenticate a peer. Windows may offer a repair only after a session-scoped advertisement uniquely resolves to a stored IRK. An opaque, one-shot offer is bound to the failed session, observer, identity fingerprint and a ten-minute deadline. Only HA’s administrator WebSocket command can confirm it; radio discovery alone never triggers an unpair. HA rejects identities assigned to another person or receiver. Windows rejects stale offers and cancels only that same failed attempt before using its existing interactive removal helper. SYSTEM verifies bond and key absence. HA then clears only that identity and creates a new invitation for the same person and receiver. The raw key never enters the repair command, UI, diagnostics or recovery journal. Offers are deliberately not persisted: after a restart a fresh attempt is needed.

Enrollment boundaries