@bricks-soft/capacitor-location-tracking 8.0.0 → 8.1.0

package/android/src/main/java/com/brickssoft/locationtracking/config/SharedPrefsConfigStore.kt

@@ -1,10 +1,13 @@
 package com.brickssoft.locationtracking.config
 
+import android.annotation.SuppressLint
 import android.content.Context
 import android.content.SharedPreferences
 import com.brickssoft.locationtracking.core.Clock
 import com.brickssoft.locationtracking.core.Constants
 import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.http.ConfigChecks
+import com.brickssoft.locationtracking.service.BootCountStore
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
@@ -16,24 +19,58 @@ import org.json.JSONObject
  * Config and runtime state are loaded synchronously in the constructor. An unreadable stored value falls back to
  * its default; unreadable JSON text falls back to all defaults.
  *
- * Every write runs under one lock: it computes the new value, persists it with `apply()` and publishes it on the
- * matching [StateFlow] before returning. Config writes go through [ConfigJson.parse] and [ConfigValidator].
- * Only the `cfg_` keys of the shared prefs file are touched.
+ * Every write runs under one lock: it computes the new value, persists it and publishes it on the matching
+ * [StateFlow] before returning. Writes use `apply()`, except a change of `runtime.enabled`, which uses `commit()`, so a
+ * process killed a few milliseconds after `stop()` cannot bring tracking back (recommendation 16). Config writes go
+ * through [ConfigJson.parse] and [ConfigValidator]. Only the `cfg_` keys of the shared prefs file are touched.
+ *
+ * **Tokens** (recommendation 8). `accessToken`, `refreshToken`, `refreshPayload` and `refreshHeaders` of
+ * `http.authorization` are never written to the prefs file: they go to [secrets] (AES-GCM with an Android Keystore key,
+ * under `noBackupFilesDir`), and the prefs file keeps the rest of the config. Plain-text tokens stored by an older
+ * version are moved there on the first load. If the stored tokens cannot be decrypted (the key is gone, the file is
+ * damaged, or the Keystore throws), they read as unset and [secretsUnavailable] is true: the uploader then sends
+ * nothing that needs them and emits an `authorization` event with an error, until the app sets new tokens. If they
+ * cannot be encrypted, they are kept in memory only (logged as an error).
+ *
+ * **Restored onto another installation** (recommendation 7). The app's `firstInstallTime` is stored; when it differs
+ * from the stored one, the prefs file came from another installation (Auto Backup restore or device-to-device
+ * transfer). Tracking is then never turned on by itself: `enabled` is cleared, the tokens are removed and the boot
+ * counts are cleared.
  */
 class SharedPrefsConfigStore(
     context: Context,
     @Suppress("unused") private val clock: Clock,
+    private val secrets: SecretStore = FileSecretStore.forContext(context),
 ) : ConfigStore {
-    private val prefs: SharedPreferences =
-        (context.applicationContext ?: context).getSharedPreferences(Constants.PREFS_NAME, Context.MODE_PRIVATE)
+    private val appContext: Context = context.applicationContext ?: context
+    private val prefs: SharedPreferences = appContext.getSharedPreferences(Constants.PREFS_NAME, Context.MODE_PRIVATE)
     private val lock = Any()
 
+    /** The secrets [secrets] holds now (null: none). Guarded by [lock] after construction. */
+    private var storedSecrets: AuthorizationSecrets? = null
+
+    @Volatile
+    private var secretsLost = false
+
+    /** The plain-text tokens of an older version were moved to [secrets]: the prefs file must be rewritten. */
+    private var migratedSecrets = false
+
+    private val restored: Boolean = detectRestore()
+
     private val configFlow = MutableStateFlow(loadConfig())
     private val runtimeFlow = MutableStateFlow(loadRuntime())
 
     override val config: StateFlow<Config> = configFlow.asStateFlow()
     override val runtime: StateFlow<RuntimeState> = runtimeFlow.asStateFlow()
 
+    override val secretsUnavailable: Boolean get() = secretsLost
+
+    init {
+        if (restored || migratedSecrets) {
+            persist(configFlow.value, runtimeFlow.value.takeIf { restored }, sync = true)
+        }
+    }
+
     override fun ready(json: JSONObject?, reset: Boolean): Config = synchronized(lock) {
         val current = configFlow.value
         val next = when {
@@ -63,7 +100,7 @@ class SharedPrefsConfigStore(
         val current = runtimeFlow.value
         val next = transform(current)
         if (next != current) {
-            persist(null, next)
+            persist(null, next, sync = next.enabled != current.enabled)
             runtimeFlow.value = next
         }
         next
@@ -79,21 +116,105 @@ class SharedPrefsConfigStore(
         next
     }
 
-    /** Defaults-or-[base] plus [json], clamped. Throws INVALID_ARGUMENT (before anything changes) on bad input. */
-    private fun build(json: JSONObject?, base: Config): Config =
-        ConfigValidator.validate(if (json == null) base else ConfigJson.parse(json, base))
+    /**
+     * Defaults-or-[base] plus [json], clamped, then checked ([ConfigChecks]). Throws INVALID_ARGUMENT (before anything
+     * changes) on bad input; logs the warnings.
+     */
+    private fun build(json: JSONObject?, base: Config): Config {
+        val config = ConfigValidator.validate(if (json == null) base else ConfigJson.parse(json, base))
+        ConfigChecks.check(config).forEach { Logger.w(TAG, it) }
+        return config
+    }
 
-    /** Writes the non-null values in one `apply()`. A value that cannot be serialized is logged and skipped. */
-    private fun persist(config: Config?, runtime: RuntimeState?) {
+    /**
+     * Writes the non-null values in one `apply()` (`commit()` when [sync]). A value that cannot be serialized is logged
+     * and skipped. The config's tokens go to [secrets] (see the class docs), never to the prefs file.
+     */
+    @SuppressLint("ApplySharedPref") // commit() only for `enabled` changes, which must be on disk at once
+    private fun persist(config: Config?, runtime: RuntimeState?, sync: Boolean = false) {
         if (config == null && runtime == null) return
         val editor = prefs.edit()
         if (config != null) {
-            serialize("config") { ConfigJson.toJson(config) }?.let { editor.putString(KEY_CONFIG, it) }
+            storeSecrets(config, editor)
+            serialize("config") { ConfigJson.toJson(withoutSecrets(config)) }?.let { editor.putString(KEY_CONFIG, it) }
         }
         if (runtime != null) {
             serialize("runtime state") { RuntimeStateJson.toJson(runtime) }?.let { editor.putString(KEY_RUNTIME, it) }
         }
-        editor.apply()
+        if (sync) editor.commit() else editor.apply()
+    }
+
+    /** Writes [config]'s tokens to [secrets] if they changed. */
+    private fun storeSecrets(config: Config, editor: SharedPreferences.Editor) {
+        val auth = config.http.authorization
+        val wanted = auth?.let { AuthorizationSecrets.of(it) }?.takeUnless { it == AuthorizationSecrets.EMPTY }
+        if (wanted == storedSecrets) return
+        try {
+            if (wanted == null) secrets.clear() else secrets.write(wanted)
+            storedSecrets = wanted
+            editor.putBoolean(KEY_SECRETS, wanted != null)
+            // New tokens from the app (or no authorization at all) end the "cannot be decrypted" state.
+            if (auth == null || wanted?.accessToken != null || wanted?.refreshToken != null) secretsLost = false
+        } catch (e: Exception) {
+            // GeneralSecurityException, and the RuntimeException (ProviderException) some Keystores throw. The old
+            // tokens are removed so they cannot come back after a restart (for example after a user switch).
+            Logger.e(TAG, "cannot store the authorization tokens encrypted; they are kept in memory only", e)
+            secrets.runCatching { clear() }
+            storedSecrets = null
+            editor.putBoolean(KEY_SECRETS, false)
+        }
+    }
+
+    private fun withoutSecrets(config: Config): Config {
+        val auth = config.http.authorization ?: return config
+        val stripped = auth.copy(
+            accessToken = null,
+            refreshToken = null,
+            refreshPayload = AuthorizationSecrets.EMPTY.refreshPayload,
+            refreshHeaders = emptyMap(),
+        )
+        return config.copy(http = config.http.copy(authorization = stripped))
+    }
+
+    private fun withSecrets(config: Config, values: AuthorizationSecrets): Config {
+        val auth = config.http.authorization ?: return config
+        val merged = auth.copy(
+            accessToken = values.accessToken,
+            refreshToken = values.refreshToken,
+            refreshPayload = values.refreshPayload,
+            refreshHeaders = values.refreshHeaders,
+        )
+        return config.copy(http = config.http.copy(authorization = merged))
+    }
+
+    /**
+     * True when the prefs file came from another installation (see the class docs); stores the current
+     * `firstInstallTime` either way. A missing stored value (first run, or an update from a version that did not store
+     * it) is not a restore.
+     */
+    @SuppressLint("ApplySharedPref")
+    private fun detectRestore(): Boolean {
+        val installed = try {
+            appContext.packageManager.getPackageInfo(appContext.packageName, 0).firstInstallTime
+        } catch (e: Exception) {
+            Logger.w(TAG, "firstInstallTime unavailable; restores from another installation are not detected", e)
+            return false
+        }
+        val stored = prefs.getLong(KEY_FIRST_INSTALL, NO_INSTALL_TIME)
+        if (stored == installed) return false
+        prefs.edit().putLong(KEY_FIRST_INSTALL, installed).commit()
+        if (stored == NO_INSTALL_TIME) return false
+        Logger.w(
+            TAG,
+            "the stored state comes from another installation (backup restore or device transfer): tracking is not " +
+                "turned on by itself; tokens and boot counts are cleared",
+        )
+        try {
+            BootCountStore.clear(appContext)
+        } catch (e: Exception) {
+            Logger.w(TAG, "cannot clear the boot counts", e)
+        }
+        return true
     }
 
     private inline fun serialize(what: String, toJson: () -> JSONObject): String? = try {
@@ -105,22 +226,65 @@ class SharedPrefsConfigStore(
 
     private fun loadConfig(): Config {
         val text = prefs.getString(KEY_CONFIG, null) ?: return Config()
-        return try {
+        val stored = try {
             ConfigValidator.validate(ConfigJson.parseStored(JSONObject(text)))
         } catch (e: Exception) {
             Logger.e(TAG, "persisted config is unreadable; using defaults", e)
-            Config()
+            return Config()
+        }
+        if (restored) {
+            secrets.runCatching { clear() }
+            prefs.edit().remove(KEY_SECRETS).apply()
+            return withoutSecrets(stored)
+        }
+        return withStoredSecrets(stored)
+    }
+
+    /** [stored] with the tokens from [secrets], or with the plain-text tokens of an older version moved there. */
+    private fun withStoredSecrets(stored: Config): Config {
+        val auth = stored.http.authorization ?: return stored
+        val plain = AuthorizationSecrets.of(auth).takeUnless { it == AuthorizationSecrets.EMPTY }
+        val values = try {
+            secrets.read()
+        } catch (e: Exception) {
+            // GeneralSecurityException, a damaged file, or a Keystore ProviderException (a RuntimeException).
+            Logger.e(TAG, "the stored tokens cannot be decrypted; uploads that need them wait for new tokens", e)
+            secretsLost = true
+            return withoutSecrets(stored)
         }
+        if (values != null) {
+            storedSecrets = values
+            return withSecrets(stored, values)
+        }
+        if (plain != null) {
+            // Written in plain text by an older version: move them now.
+            try {
+                secrets.write(plain)
+                storedSecrets = plain
+                migratedSecrets = true
+                prefs.edit().putBoolean(KEY_SECRETS, true).apply()
+                Logger.i(TAG, "authorization tokens moved to encrypted storage")
+            } catch (e: Exception) {
+                Logger.w(TAG, "cannot encrypt the stored tokens yet; they stay in the old place until the next start", e)
+            }
+            return stored
+        }
+        if (prefs.getBoolean(KEY_SECRETS, false)) {
+            Logger.e(TAG, "the encrypted tokens are missing; uploads that need them wait for new tokens")
+            secretsLost = true
+        }
+        return stored
     }
 
     private fun loadRuntime(): RuntimeState {
         val text = prefs.getString(KEY_RUNTIME, null) ?: return RuntimeState()
-        return try {
+        val stored = try {
             RuntimeStateJson.fromJson(JSONObject(text))
         } catch (e: Exception) {
             Logger.e(TAG, "persisted runtime state is unreadable; using defaults", e)
-            RuntimeState()
+            return RuntimeState()
         }
+        return if (restored) stored.copy(enabled = false, isMoving = false) else stored
     }
 
     internal companion object {
@@ -131,5 +295,12 @@ class SharedPrefsConfigStore(
 
         /** Runtime state JSON (`RuntimeStateJson`). */
         const val KEY_RUNTIME = "cfg_runtime"
+
+        /** True while the encrypted tokens file holds tokens. */
+        const val KEY_SECRETS = "cfg_secrets"
+
+        /** `PackageInfo.firstInstallTime` of the installation that wrote this file. */
+        const val KEY_FIRST_INSTALL = "cfg_first_install_time"
+        private const val NO_INSTALL_TIME = -1L
     }
 }

package/android/src/main/java/com/brickssoft/locationtracking/config/State.kt

@@ -24,6 +24,12 @@ enum class TrackingMode(val wire: String) {
  * @property lastRecordBootCount boot count when the last record was persisted.
  * @property providerState last provider state seen, used to detect `providerchange` across process restarts.
  * @property didReady true once `ready()` has ever completed (drives `ReadyOptions.reset=false`).
+ * @property trackingStartedElapsed elapsed-realtime ms when the session started (`stopAfterElapsedMinutes`), valid
+ *   while the boot count is [trackingStartedBootCount].
+ * @property lastStopReason the reason of the last `tracking_stop` record, and [lastStopAt] when tracking stopped
+ *   (epoch ms).
+ * @property userStopRecordedFor the time of the user stop (Task Manager Stop or force stop) whose `tracking_stop`
+ *   record was written, so a later process does not write it again.
  */
 data class RuntimeState(
     val enabled: Boolean = false,
@@ -39,6 +45,11 @@ data class RuntimeState(
     val trackingStartedAt: Long? = null,
     val providerState: ProviderState? = null,
     val didReady: Boolean = false,
+    val trackingStartedElapsed: Long? = null,
+    val trackingStartedBootCount: Int? = null,
+    val lastStopReason: String? = null,
+    val lastStopAt: Long? = null,
+    val userStopRecordedFor: Long? = null,
 )
 
 /** Snapshot returned to JS as `State` (see `ConfigJson.stateToJson`). */

package/android/src/main/java/com/brickssoft/locationtracking/core/Components.kt

@@ -2,6 +2,7 @@ package com.brickssoft.locationtracking.core
 
 import android.annotation.SuppressLint
 import android.content.Context
+import android.os.StatFs
 import androidx.annotation.VisibleForTesting
 import com.brickssoft.locationtracking.api.NativeListeners
 import com.brickssoft.locationtracking.config.ConfigStore
@@ -11,6 +12,7 @@ import com.brickssoft.locationtracking.data.LocationStore
 import com.brickssoft.locationtracking.data.SqliteGeofenceStore
 import com.brickssoft.locationtracking.data.SqliteLocationStore
 import com.brickssoft.locationtracking.data.TrackingDatabase
+import com.brickssoft.locationtracking.device.DefaultDeviceDetails
 import com.brickssoft.locationtracking.device.DefaultDeviceInfoProvider
 import com.brickssoft.locationtracking.device.DefaultDeviceMonitor
 import com.brickssoft.locationtracking.device.DeviceInfoProvider
@@ -21,8 +23,12 @@ import com.brickssoft.locationtracking.geofence.DefaultGeofenceManager
 import com.brickssoft.locationtracking.geofence.GeofenceManager
 import com.brickssoft.locationtracking.heartbeat.DefaultHeartbeatScheduler
 import com.brickssoft.locationtracking.heartbeat.HeartbeatScheduler
+import com.brickssoft.locationtracking.http.HttpSupport
 import com.brickssoft.locationtracking.http.HttpSyncer
+import com.brickssoft.locationtracking.http.JobUploadScheduler
 import com.brickssoft.locationtracking.http.OkHttpSyncer
+import com.brickssoft.locationtracking.http.PrefsNextTryStore
+import com.brickssoft.locationtracking.http.UploadScheduler
 import com.brickssoft.locationtracking.logging.FileLogger
 import com.brickssoft.locationtracking.logging.LogStore
 import com.brickssoft.locationtracking.permission.DefaultPermissionManager
@@ -72,7 +78,7 @@ class Components private constructor(context: Context) {
 
     /** Round 2: every queued record (sink and insertLocation) for the companion native API (unit 5). */
     val recordHooks: RecordHooks = RecordHooks()
-    val http: OkHttpClient by lazy { OkHttpClient() }
+    val http: OkHttpClient by lazy { HttpSupport.sharedClient() }
 
     // U17
     val logStore: LogStore by lazy { FileLogger(this.context, clock, dispatchers, lazy { http }) }
@@ -97,30 +103,40 @@ class Components private constructor(context: Context) {
     val deviceInfo: DeviceInfoProvider by lazy { DefaultDeviceInfoProvider(this.context, lazy { providers }) }
 
     // U10
-    private val database by lazy { TrackingDatabase(this.context) }
+    private val database by lazy { TrackingDatabase(this.context, TrackingDatabase.location(this.context)) }
     val locationStore: LocationStore by lazy { SqliteLocationStore(database, configStore, clock, dispatchers) }
     val geofenceStore: GeofenceStore by lazy { SqliteGeofenceStore(database, dispatchers) }
 
     // U9
     val processor: LocationProcessor by lazy { DefaultLocationProcessor(configStore) }
     val odometer: Odometer by lazy { DefaultOdometer(configStore) }
-    val recordFactory: RecordFactory by lazy { DefaultRecordFactory(configStore, device, providers, clock) }
+    val recordFactory: RecordFactory by lazy {
+        DefaultRecordFactory(configStore, device, providers, clock, DefaultDeviceDetails(this.context))
+    }
 
     // U11
+    /** Schedules the upload job that sends queued records when no tracking session runs (recommendation 10). */
+    val uploadScheduler: UploadScheduler by lazy { JobUploadScheduler(this.context) }
     val syncer: HttpSyncer by lazy {
-        OkHttpSyncer(configStore, locationStore, device, events, clock, http, dispatchers, scope)
+        OkHttpSyncer(
+            configStore, locationStore, device, events, clock, http, dispatchers, scope,
+            PrefsNextTryStore(this.context), uploadScheduler,
+        )
     }
 
     // U12
     val heartbeat: HeartbeatScheduler by lazy {
         DefaultHeartbeatScheduler(
             this.context, configStore, device, providers, locationStore, recordFactory, lazy { recordSink }, clock, scope,
+            uploads = lazy { syncer },
         )
     }
 
     // SCAFFOLD
     val recordSink: RecordSink by lazy {
-        DefaultRecordSink(locationStore, configStore, heartbeat, syncer, events, recordHooks)
+        DefaultRecordSink(locationStore, configStore, heartbeat, syncer, events, recordHooks) {
+            StatFs(this.context.noBackupFilesDir.path).availableBytes
+        }
     }
 
     // U13 (round 2: STATIONARY_REGION_ID transitions go to the engine)

package/android/src/main/java/com/brickssoft/locationtracking/core/ForceStopProbe.kt

@@ -11,12 +11,18 @@ import android.os.Build
  * Android cancels the app's alarms and does not restart its services after a force stop, so tracking stays off until
  * the user opens the app again. A broadcast that was already on its way can still start the process (on the CI
  * emulator a Play services activity update arrived 0.5 s after `am force-stop`, scenario P-L04). The engine asks this
- * probe before a background trigger (activity update, stationary region EXIT) restores tracking.
+ * probe before a background trigger (activity update, stationary region EXIT, heartbeat alarm, the service's sticky or
+ * earlier-process restart) restores tracking. A user stop means both the Settings force stop and the Stop button of
+ * the Android 13+ Task Manager; unlike a force stop, the Task Manager leaves the app's alarms in place, so the heartbeat
+ * alarm can start the process again (recommendation 6).
  */
 fun interface ForceStopProbe {
     /** True when the previous process of this app ended with a user force stop. */
     fun startedAfterForceStop(): Boolean
 
+    /** When the previous process was stopped by the user (the exit record's time, epoch ms), or null. */
+    fun forceStopTime(): Long? = null
+
     companion object {
         private const val TAG = "LT.ForceStop"
 
@@ -35,28 +41,33 @@ fun interface ForceStopProbe {
          */
         fun system(context: Context): ForceStopProbe {
             val app = context.applicationContext ?: context
-            val result by lazy(LazyThreadSafetyMode.SYNCHRONIZED) { lastExitWasForceStop(app) }
-            return ForceStopProbe { result }
+            val result by lazy(LazyThreadSafetyMode.SYNCHRONIZED) { lastExitForceStopTime(app) }
+            return object : ForceStopProbe {
+                override fun startedAfterForceStop(): Boolean = result != null
+
+                override fun forceStopTime(): Long? = result
+            }
         }
 
-        private fun lastExitWasForceStop(context: Context): Boolean {
-            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) return false
+        /** The time of the previous main process's exit if it was a user stop, else null. */
+        private fun lastExitForceStopTime(context: Context): Long? {
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) return null
             return try {
-                val manager = context.getSystemService(ActivityManager::class.java) ?: return false
+                val manager = context.getSystemService(ActivityManager::class.java) ?: return null
                 val mainProcess = context.applicationInfo?.processName ?: context.packageName
                 val previous = manager.getHistoricalProcessExitReasons(context.packageName, 0, EXIT_RECORDS)
                     .firstOrNull { it.processName == mainProcess }
-                    ?: return false
+                    ?: return null
                 val forceStopped = previous.reason == ApplicationExitInfo.REASON_USER_REQUESTED
                 Logger.i(
                     TAG,
                     "previous process ${previous.pid} exited with reason ${previous.reason} " +
                         "(${previous.description ?: "no description"}); force stop: $forceStopped",
                 )
-                forceStopped
+                if (forceStopped) previous.timestamp else null
             } catch (e: Exception) {
                 Logger.w(TAG, "the previous process's exit reason is unknown", e)
-                false
+                null
             }
         }
     }

package/android/src/main/java/com/brickssoft/locationtracking/core/TrackingEvent.kt

@@ -5,8 +5,10 @@ import com.brickssoft.locationtracking.model.Connectivity
 import com.brickssoft.locationtracking.model.GeofenceAction
 import com.brickssoft.locationtracking.model.GeofenceSpec
 import com.brickssoft.locationtracking.model.HttpResult
+import com.brickssoft.locationtracking.model.ProviderKind
 import com.brickssoft.locationtracking.model.ProviderState
 import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordEvent
 
 /**
  * Events forwarded to JS. The JS event name and payload are built by
@@ -48,12 +50,32 @@ sealed interface TrackingEvent {
     /** "powersavechange" */
     data class PowerSaveChange(val isPowerSaveMode: Boolean) : TrackingEvent
 
-    /** "enabledchange" */
-    data class EnabledChange(val enabled: Boolean) : TrackingEvent
+    /**
+     * "enabledchange". [reason] is the `tracking_start` reason when tracking was switched on, the `tracking_stop` reason
+     * when it was switched off (the same values as the audit records), or null.
+     */
+    data class EnabledChange(val enabled: Boolean, val reason: String? = null) : TrackingEvent
 
     /** "notificationaction" */
     data class NotificationAction(val id: String) : TrackingEvent
 
+    /**
+     * "locationerror": the location request on [backend] failed (recommendation 3). The engine retries it after
+     * [retryInMs] ms (null: no retry is scheduled, for example tracking stopped).
+     */
+    data class LocationError(
+        val code: ErrorCode,
+        val message: String,
+        val backend: ProviderKind,
+        val retryInMs: Long?,
+    ) : TrackingEvent
+
+    /**
+     * "storagefull": the record [uuid] ([event]) could not be stored because the device storage is full
+     * (recommendation 16); [diskFreeBytes] is the free space of the app's storage, or null if unknown.
+     */
+    data class StorageFull(val uuid: String, val event: RecordEvent, val diskFreeBytes: Long?) : TrackingEvent
+
     /** "authorization"; [responseJson] is JSON object text. */
     data class Authorization(
         val success: Boolean,

package/android/src/main/java/com/brickssoft/locationtracking/data/TrackingDatabase.kt

@@ -5,6 +5,7 @@ import android.database.sqlite.SQLiteDatabase
 import android.database.sqlite.SQLiteOpenHelper
 import com.brickssoft.locationtracking.core.Constants
 import com.brickssoft.locationtracking.core.Logger
+import java.io.File
 
 /**
  * SQLiteOpenHelper for [Constants.DATABASE_NAME] (schema [VERSION]), shared by [SqliteLocationStore] and
@@ -17,7 +18,11 @@ import com.brickssoft.locationtracking.core.Logger
  * - `geofences`: `json` is `GeofenceJson.toJson(spec)`; `runtime_json` is `{insideCircle, insidePolygon, enteredAt}`
  *   or null.
  *
- * @param name database file name; `null` creates an in-memory database.
+ * The plugin opens it at [location]: `noBackupFilesDir/location_tracking.db`, so the queue is not copied by Android
+ * Auto Backup or device-to-device transfer (recommendation 7). A database left in the default databases folder by an
+ * older version is moved there once, without losing records.
+ *
+ * @param name database file name or absolute path; `null` creates an in-memory database.
  */
 class TrackingDatabase(
     context: Context,
@@ -86,6 +91,43 @@ class TrackingDatabase(
         const val VERSION = 1
 
         private const val TAG = "LT.Database"
+
+        /** Files SQLite may keep next to a database. */
+        private val SIDE_FILES = listOf("-wal", "-shm", "-journal")
+
+        /**
+         * The absolute path of the plugin's database under `noBackupFilesDir`. A database still in the default
+         * databases folder (an older version) is moved there first: its write-ahead log is folded into the main file
+         * (`PRAGMA wal_checkpoint(TRUNCATE)` and close), then the file is renamed (same file system), then the old side
+         * files are deleted. If anything fails, the old path is returned and nothing is lost. If both exist (a
+         * downgrade and upgrade), the one under `noBackupFilesDir` is used and the old one is left in place.
+         */
+        fun location(context: Context): String {
+            val app = context.applicationContext ?: context
+            val target = File(app.noBackupFilesDir, Constants.DATABASE_NAME)
+            val legacy = app.getDatabasePath(Constants.DATABASE_NAME)
+            if (!legacy.exists()) return target.path
+            if (target.exists()) {
+                Logger.w(TAG, "databases/${Constants.DATABASE_NAME} and its no_backup copy both exist; using the no_backup one")
+                return target.path
+            }
+            return try {
+                SQLiteDatabase.openDatabase(legacy.path, null, SQLiteDatabase.OPEN_READWRITE).use { db ->
+                    db.rawQuery("PRAGMA wal_checkpoint(TRUNCATE)", null).use { it.moveToFirst() }
+                }
+                target.parentFile?.mkdirs()
+                if (!legacy.renameTo(target)) {
+                    Logger.w(TAG, "could not move the database to no_backup; keeping it in databases/")
+                    return legacy.path
+                }
+                for (suffix in SIDE_FILES) File(legacy.path + suffix).delete()
+                Logger.i(TAG, "database moved to no_backup (kept out of Auto Backup and device transfer)")
+                target.path
+            } catch (e: Exception) {
+                Logger.e(TAG, "could not move the database to no_backup; keeping it in databases/", e)
+                legacy.path
+            }
+        }
     }
 }
 

package/android/src/main/java/com/brickssoft/locationtracking/device/DefaultDeviceInfoProvider.kt

@@ -44,6 +44,12 @@ class DefaultDeviceInfoProvider(
             Logger.e(TAG, "provider kind unavailable", e)
             null
         }
+        val selection = try {
+            factory?.selectionInfo()
+        } catch (e: Exception) {
+            Logger.w(TAG, "provider selection info unavailable", e)
+            null
+        }
         return DeviceInfo(
             platform = "android",
             manufacturer = Build.MANUFACTURER.orEmpty(),
@@ -56,6 +62,17 @@ class DefaultDeviceInfoProvider(
             hmsAvailable = factory != null && isAvailable(factory, ProviderKind.HMS),
             backend = backend ?: ProviderKind.ANDROID,
             packagedProviders = packagedProviders(),
+            backendFallbackReason = selection?.fallbackReason,
+            gmsStatus = selection?.gmsStatus,
+            hmsStatus = selection?.hmsStatus,
+            hmsCoreOutdated = selection?.hmsCoreOutdated,
+            locationAvailableHint = try {
+                factory?.location()?.availabilityHint
+            } catch (e: Exception) {
+                null
+            },
+            cpuCores = Runtime.getRuntime().availableProcessors(),
+            supportedAbis = Build.SUPPORTED_ABIS?.toList().orEmpty(),
         )
     }