@mentra/bluetooth-sdk 3.4.0-dev.993 → 3.4.0-dev.998

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/MentraLiveOwnerLossPolicy.kt

@@ -0,0 +1,227 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import android.bluetooth.BluetoothDevice
+
+/**
+ * Pure predicates behind Mentra Live pairing-mode pauses and rejection detection (pairing spec
+ * "Ownership transfer v4"). [MentraLivePairingStateMachine] owns the state; this object holds
+ * the per-signal rules both use. Mirrors iOS `MentraLiveConnectionAttemptPolicy`.
+ *
+ * Outside a pairing window the glasses reject a phone they no longer bond with at connect time
+ * (HCI Authentication Failure). A single rejection is only a hint: a glasses reboot, a stale
+ * bond, or a radio hiccup can produce one. Only secure-pairing firmware rejects on purpose, and
+ * only a rejection that repeats across automatic reconnects ([OwnerRejectionStreak]) counts.
+ */
+internal object MentraLiveOwnerLossPolicy {
+    /** `entering_pairing_mode.window_ms` when the glasses omit it. */
+    const val DEFAULT_PAIRING_WINDOW_MS = 120_000L
+
+    /** Covers the glasses' bounded close deferral (30 s) after the window timer. */
+    const val PAIRING_RESUME_MARGIN_MS = 30_000L
+
+    /** A bond the glasses dropped surfaces within a few seconds of the reconnect link. */
+    const val BOND_REMOVED_AFTER_RECONNECT_MS = 15_000L
+
+    /** Consecutive automatic-reconnect rejections before this phone stands down. */
+    const val REJECTIONS_TO_STAND_DOWN = 3
+
+    /** The rejections must keep arriving for about this long, so a glasses reboot is not owner loss. */
+    const val MIN_REJECTION_SPAN_MS = 45_000L
+
+    /** A gap this long between rejections means they are unrelated, not one streak. */
+    const val REJECTION_STREAK_GAP_MS = 90_000L
+
+    /** One failed attempt can report twice (bond removed, then GATT disconnect). Count it once. */
+    const val SAME_ATTEMPT_MS = 2_000L
+
+    /**
+     * HCI 0x05 Authentication Failure / 0x0F Unacceptable BD_ADDR from a connect-time rejection.
+     * The glasses refuse the previous owner during a window with 0x14, which never counts.
+     */
+    fun isOwnerRejectionStatus(status: Int): Boolean = status == 0x05 || status == 0x0F
+
+    /**
+     * A connect-time rejection of saved secure glasses. Legacy firmware never rejects a
+     * non-owner on purpose, and during an explicit pairing attempt the user is pairing anew.
+     * This is one observation; [MentraLivePairingStateMachine.onAuthRejection] decides what it adds up to.
+     */
+    fun isOwnerRejectionOnGattError(
+            status: Int,
+            manualPairing: Boolean,
+            secureFirmware: Boolean,
+    ): Boolean = secureFirmware && !manualPairing && isOwnerRejectionStatus(status)
+
+    /**
+     * Android deletes its BLE keys when the glasses answer an encryption request without them.
+     * Right after an automatic reconnect that can mean the glasses forgot this phone. Like
+     * [isOwnerRejectionOnGattError] this is one observation, not yet owner loss.
+     */
+    fun isOwnerRejectionOnBondRemoved(
+            previousBondState: Int,
+            bondState: Int,
+            killed: Boolean,
+            unpairInProgress: Boolean,
+            manualPairing: Boolean,
+            msSinceAutoReconnectLink: Long?,
+            secureFirmware: Boolean,
+    ): Boolean {
+        if (!secureFirmware || killed || unpairInProgress || manualPairing) return false
+        if (previousBondState != BluetoothDevice.BOND_BONDED ||
+                        bondState != BluetoothDevice.BOND_NONE
+        ) {
+            return false
+        }
+        val since = msSinceAutoReconnectLink ?: return false
+        return since in 0..BOND_REMOVED_AFTER_RECONNECT_MS
+    }
+
+    /**
+     * Tracks rejections across automatic reconnects. Owner loss needs [REJECTIONS_TO_STAND_DOWN]
+     * attempts in a row that span at least [MIN_REJECTION_SPAN_MS]. Any successful ready session
+     * calls [reset].
+     */
+    class OwnerRejectionStreak {
+        private var count = 0
+        private var firstAtMs = 0L
+        private var lastAtMs = 0L
+
+        /** Records one rejection and returns true once the streak means owner loss. */
+        @Synchronized
+        fun record(nowMs: Long): Boolean {
+            if (count > 0 && nowMs - lastAtMs <= SAME_ATTEMPT_MS) {
+                return reached(nowMs)
+            }
+            if (count > 0 && nowMs - lastAtMs > REJECTION_STREAK_GAP_MS) {
+                count = 0
+            }
+            if (count == 0) firstAtMs = nowMs
+            count++
+            lastAtMs = nowMs
+            return reached(nowMs)
+        }
+
+        @Synchronized
+        fun reset() {
+            count = 0
+            firstAtMs = 0L
+            lastAtMs = 0L
+        }
+
+        private fun reached(nowMs: Long): Boolean =
+                count >= REJECTIONS_TO_STAND_DOWN && nowMs - firstAtMs >= MIN_REJECTION_SPAN_MS
+    }
+
+    /**
+     * How long automatic reconnect pauses for a window: the window plus the close-deferral
+     * margin. No floor beyond a missing value and no upper clamp; the glasses own the window.
+     */
+    fun yieldMs(windowMs: Long): Long =
+            (if (windowMs > 0L) windowMs else DEFAULT_PAIRING_WINDOW_MS) + PAIRING_RESUME_MARGIN_MS
+
+    /**
+     * Remaining pause after a process restart. A missing, expired, or implausible deadline (more
+     * than the pause that was persisted with it) returns 0 so the phone reconnects. Mirrors iOS
+     * `MentraLiveConnectionAttemptPolicy.persistedYieldRemainingMs`.
+     */
+    fun persistedYieldRemainingMs(untilWallMs: Long, nowWallMs: Long, pauseMs: Long): Long {
+        if (untilWallMs <= 0L || pauseMs <= 0L) return 0L
+        val remaining = untilWallMs - nowWallMs
+        if (remaining <= 0L || remaining > pauseMs) return 0L
+        return remaining
+    }
+
+    /**
+     * Automatic reconnect must not take the single BLE slot while the saved glasses advertise
+     * pairing mode. An explicit pairing attempt (the new phone, or Pair Again) still connects.
+     * Mirrors iOS `MentraLiveConnectionAttemptPolicy.shouldStandDownInsteadOfReconnect`.
+     */
+    fun shouldStandDownInsteadOfReconnect(
+            pairingMode: Boolean,
+            savedGlasses: Boolean,
+            explicitPairing: Boolean,
+    ): Boolean = pairingMode && savedGlasses && !explicitPairing
+
+    /**
+     * A discovery scan lists other secure glasses that are not in pairing mode as non-pairable
+     * and does not connect to them. The saved glasses are the exception: the pause watch scan
+     * has to read their trailer, so a cleared pairing flag ends the pause and reconnects.
+     * Mirrors iOS, which skips this return when the advertisement is the saved device.
+     */
+    fun shouldExposeAsNonPairable(
+            savedGlasses: Boolean,
+            reconnectScan: Boolean,
+            secureTrailer: Boolean,
+            pairingDiscoverable: Boolean,
+    ): Boolean = !savedGlasses && !reconnectScan && secureTrailer && !pairingDiscoverable
+
+    /**
+     * `secure_pairing_capable` only means the firmware can do secure pairing. Ownership is the
+     * separate `owner_committed` bit the glasses set after the BLE bond. Mirrors iOS
+     * `MentraLiveConnectionAttemptPolicy.pairingInfoConfirmsOwner`.
+     */
+    fun pairingInfoConfirmsOwner(ownerCommitted: Boolean): Boolean = ownerCommitted
+
+    /**
+     * Secure glasses commit an owner only on a BLE bond, and announce it with `pairing_info`
+     * `owner_committed`. A stale BOND_BONDED (or a Classic-only bond on the same public address)
+     * does not prove the glasses committed this phone, so readiness inside the open window needs
+     * both the bond and the owner commit. Callers apply this only to explicit pairing attempts;
+     * non-secure (legacy) targets are never gated.
+     */
+    fun shouldDeferReadyForBond(
+            securePairingTarget: Boolean,
+            bondState: Int?,
+            ownerCommitted: Boolean,
+    ): Boolean =
+            securePairingTarget &&
+                    (bondState != BluetoothDevice.BOND_BONDED ||
+                            !pairingInfoConfirmsOwner(ownerCommitted))
+
+    /** How long an explicit secure pair may wait for a bond result before the attempt fails. */
+    const val SECURE_BOND_WAIT_MS = 40_000L
+
+    /**
+     * Readiness parked by [shouldDeferReadyForBond] always has a deadline: an explicit secure
+     * attempt arms the bond wait, so a missing bond broadcast or owner commit fails the pair
+     * instead of leaving it loading. Mirrors iOS `shouldRunSecurePairingWait`.
+     */
+    fun shouldRunSecureBondWait(explicitPairing: Boolean, securePairingTarget: Boolean): Boolean =
+            explicitPairing && securePairingTarget
+
+    /**
+     * An explicit secure pair must not call `createBond` before `pairing_info` arrives: the
+     * glasses ask for security themselves once they know the link, and an early SMP races it.
+     */
+    fun shouldDeferCtkdBond(
+            explicitPairing: Boolean,
+            secureTarget: Boolean,
+            bondState: Int,
+            pairingInfoSeen: Boolean,
+    ): Boolean =
+            explicitPairing &&
+                    secureTarget &&
+                    bondState != BluetoothDevice.BOND_BONDED &&
+                    !pairingInfoSeen
+
+    /**
+     * `pair_select` tells the glasses this link is the user's explicit choice (pairing spec V4).
+     * It goes out once per GATT session, only on an explicit attempt to secure glasses, never on
+     * an automatic reconnect. Legacy firmware has no use for it.
+     */
+    fun shouldSendPairSelect(explicitPairing: Boolean, securePairingTarget: Boolean): Boolean =
+            explicitPairing && securePairingTarget
+
+    /**
+     * Classic audio can come up before the BLE bond or the owner commit. During an explicit
+     * secure pair that must not save this phone. A reconnect of an already-paired phone can still
+     * mark ready.
+     */
+    fun shouldMarkReadyFromAudio(
+            explicitPairing: Boolean,
+            securePairingTarget: Boolean,
+            bondState: Int?,
+            ownerCommitted: Boolean,
+    ): Boolean =
+            !explicitPairing ||
+                    !shouldDeferReadyForBond(securePairingTarget, bondState, ownerCommitted)
+}

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/MentraLivePairingAdvertisement.kt

@@ -3,6 +3,15 @@ package com.mentra.bluetoothsdk.sgcs
 internal data class MentraLivePairingAdvertisement(
     val pairingMode: Boolean,
     val pairingCode: String,
+    /**
+     * The glasses' `window_id`: moves on each pairing-mode entry. Null when the byte is absent.
+     */
+    val pairingGeneration: Int? = null,
+    /**
+     * Trailer flag `OWNER_CHANGED`: the window [pairingGeneration] committed a different phone.
+     * Unauthenticated, so it only triggers one verification reconnect.
+     */
+    val ownerChanged: Boolean = false,
 )
 
 internal object MentraLivePairingAdvertisementParser {
@@ -14,9 +23,11 @@ internal object MentraLivePairingAdvertisementParser {
     private const val CODE_HIGH_OFFSET = CODE_LOW_OFFSET + 1
     private const val MAGIC_FIRST_OFFSET = CODE_HIGH_OFFSET + 1
     private const val MAGIC_SECOND_OFFSET = MAGIC_FIRST_OFFSET + 1
+    private const val PAIRING_GENERATION_OFFSET = MAGIC_SECOND_OFFSET + 1
     private const val PROTOCOL_VERSION_MIN = 2
     private const val PROTOCOL_VERSION_MAX = 15
     private const val SECURE_PAIRING_CAPABILITY = 0x01
+    private const val OWNER_CHANGED_FLAG = 0x04
     private const val MAGIC_FIRST = 0x4D // M
     private const val MAGIC_SECOND = 0x50 // P
 
@@ -46,9 +57,17 @@ internal object MentraLivePairingAdvertisementParser {
 
         val codeLow = manufacturerData[CODE_LOW_OFFSET].toInt() and 0xFF
         val codeHigh = manufacturerData[CODE_HIGH_OFFSET].toInt() and 0xFF
+        val pairingGeneration =
+                if (manufacturerData.size > PAIRING_GENERATION_OFFSET) {
+                    manufacturerData[PAIRING_GENERATION_OFFSET].toInt() and 0xFF
+                } else {
+                    null
+                }
         return MentraLivePairingAdvertisement(
             pairingMode = manufacturerData[PAIRING_FLAG_OFFSET] == PAIRING_DISCOVERABLE,
             pairingCode = String.format("%02X%02X", codeHigh, codeLow),
+            pairingGeneration = pairingGeneration,
+            ownerChanged = (capability and OWNER_CHANGED_FLAG) != 0,
         )
     }
 }

package/android/src/main/java/com/mentra/bluetoothsdk/sgcs/MentraLivePairingReadinessPolicy.kt

@@ -0,0 +1,94 @@
+package com.mentra.bluetoothsdk.sgcs
+
+/**
+ * Pure rules for when an explicit Mentra Live pair reports ready, and for the saved secure
+ * firmware memory. [MentraLive] feeds them the selected scan row, this GATT session's
+ * `pairing_info` and the bond state. Readiness never waits without a deadline: the owner-commit
+ * wait has [MentraLiveOwnerLossPolicy.SECURE_BOND_WAIT_MS], the unknown-capability wait has
+ * [UNKNOWN_CAPABILITY_PAIRING_INFO_WAIT_MS].
+ */
+internal object MentraLivePairingReadinessPolicy {
+    /**
+     * How long an explicit pair to glasses of unknown secure capability waits after
+     * `glasses_ready` for `pairing_info` before treating them as legacy firmware.
+     */
+    const val UNKNOWN_CAPABILITY_PAIRING_INFO_WAIT_MS = 5_000L
+
+    /** A ready session without `pairing_info` within this time means the glasses are not secure firmware. */
+    const val SECURE_FIRMWARE_REFRESH_MS = 15_000L
+
+    enum class Readiness {
+        /** Report the glasses ready now. */
+        READY,
+        /** The selected glasses' capability is unknown and no `pairing_info` has arrived yet. */
+        AWAIT_PAIRING_INFO,
+        /** Secure target: wait for the BLE bond and `pairing_info.owner_committed`. */
+        AWAIT_OWNER_COMMIT,
+    }
+
+    /**
+     * Whether an explicit pair targets secure-pairing firmware. The selected scan row's
+     * capability decides, never an address or name seen earlier; when the row did not know it,
+     * this session's `pairing_info` does.
+     *
+     * @param selectedCapability `pending_device_secure_pairing_capable`, null when unknown
+     * @param sessionPairingInfoSecure `secure_pairing_capable` from this session's `pairing_info`,
+     *   null before one arrives
+     */
+    fun isSecurePairingTarget(selectedCapability: Boolean?, sessionPairingInfoSecure: Boolean?): Boolean =
+            selectedCapability ?: (sessionPairingInfoSecure == true)
+
+    /**
+     * Readiness after `glasses_ready`. Automatic reconnects are never gated. An explicit pair to
+     * glasses of unknown capability waits for `pairing_info` until [unknownCapabilityWaitExpired];
+     * a secure one then follows the owner-commit rule, a legacy one (or none) is ready.
+     */
+    fun readiness(
+            explicitPairing: Boolean,
+            selectedCapability: Boolean?,
+            sessionPairingInfoSecure: Boolean?,
+            unknownCapabilityWaitExpired: Boolean,
+            bondState: Int?,
+            ownerCommitted: Boolean,
+    ): Readiness {
+        if (!explicitPairing) return Readiness.READY
+        if (selectedCapability == null &&
+                        sessionPairingInfoSecure == null &&
+                        !unknownCapabilityWaitExpired
+        ) {
+            return Readiness.AWAIT_PAIRING_INFO
+        }
+        val secure = isSecurePairingTarget(selectedCapability, sessionPairingInfoSecure)
+        return if (MentraLiveOwnerLossPolicy.shouldDeferReadyForBond(secure, bondState, ownerCommitted)) {
+            Readiness.AWAIT_OWNER_COMMIT
+        } else {
+            Readiness.READY
+        }
+    }
+
+    /**
+     * `mentra_live_secure_firmware` once a ready session's [SECURE_FIRMWARE_REFRESH_MS] has
+     * passed: false when no `pairing_info` arrived, so glasses rolled back to old firmware stop
+     * counting as secure. Null leaves the value a `pairing_info` already wrote.
+     */
+    fun secureFirmwareAfterReadySession(pairingInfoSeen: Boolean): Boolean? =
+            if (pairingInfoSeen) null else false
+}
+
+/**
+ * Addresses advertising the secure-pairing trailer in the current scan. It starts empty with each
+ * scan, so glasses rolled back to old firmware stop counting as secure on the next scan. It is a
+ * hint for automatic sessions only; an explicit pair uses the selected row's capability
+ * ([MentraLivePairingReadinessPolicy.isSecurePairingTarget]).
+ */
+internal class MentraLiveSecureTrailerScanMemory {
+    private val addresses: MutableSet<String> = java.util.Collections.synchronizedSet(mutableSetOf())
+
+    fun onScanStart() = addresses.clear()
+
+    fun noteSecureTrailer(address: String) {
+        addresses.add(address)
+    }
+
+    fun contains(address: String?): Boolean = address != null && addresses.contains(address)
+}