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

package/android/build.gradle

@@ -39,7 +39,8 @@ android {
         minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
         targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
         consumerProguardFiles 'consumer-rules.pro'
-        buildConfigField 'String', 'PLUGIN_VERSION', '"8.0.0"'
+        // package.json ships next to android/ in the npm package, so it is the one place the version is set.
+        buildConfigField 'String', 'PLUGIN_VERSION', "\"${new groovy.json.JsonSlurper().parse(file('../package.json')).version}\""
     }
     buildFeatures {
         buildConfig = true

package/android/src/main/AndroidManifest.xml

@@ -29,6 +29,8 @@
   <application>
     <service android:name="com.brickssoft.locationtracking.service.LocationTrackingService"
         android:exported="false" android:foregroundServiceType="location" android:stopWithTask="false"/>
+    <service android:name="com.brickssoft.locationtracking.http.UploadJobService"
+        android:exported="false" android:permission="android.permission.BIND_JOB_SERVICE"/>
     <receiver android:name="com.brickssoft.locationtracking.service.BootReceiver" android:exported="true">
       <intent-filter>
         <action android:name="android.intent.action.BOOT_COMPLETED"/>

package/android/src/main/java/com/brickssoft/locationtracking/bridge/OptionParsers.kt

@@ -117,8 +117,11 @@ internal object OptionParsers {
         requireNumber(coords, "longitude", "location.coords.longitude").also {
             checkRange(it, LONGITUDE, "location.coords.longitude")
         }
+        requireNumber(coords, "accuracy", "location.coords.accuracy").also {
+            if (it <= 0) invalid("location.coords.accuracy must be > 0")
+        }
         optNumber(coords, "altitude", "location.coords.altitude")
-        for (key in listOf("accuracy", "altitude_accuracy", "speed", "speed_accuracy", "heading_accuracy")) {
+        for (key in listOf("altitude_accuracy", "speed", "speed_accuracy", "heading_accuracy")) {
             val value = optNumber(coords, key, "location.coords.$key")
             if (value != null && value < 0) invalid("location.coords.$key must be >= 0")
         }

package/android/src/main/java/com/brickssoft/locationtracking/bridge/PluginHandlers.kt

@@ -11,6 +11,8 @@ import com.brickssoft.locationtracking.core.Logger
 import com.brickssoft.locationtracking.core.Subscription
 import com.brickssoft.locationtracking.core.TrackingException
 import com.brickssoft.locationtracking.model.BatteryOptimizationStatus
+import com.brickssoft.locationtracking.http.ConfigChecks
+import com.brickssoft.locationtracking.logging.LogRedaction
 import com.brickssoft.locationtracking.model.BatteryOptimizationStatusJson
 import com.brickssoft.locationtracking.model.DeviceInfoJson
 import com.brickssoft.locationtracking.model.EventJson
@@ -71,21 +73,25 @@ internal class PluginHandlers(
         val reset = OptionParsers.optBoolean(options, "reset") ?: true
         val state = services.engine.ready(config, reset)
         readyFlag.set(true)
-        return stateJson(state)
+        return configResultJson(state)
     }
 
     /** `setConfig({config})` -> State. */
     suspend fun setConfig(options: JSONObject): JSONObject {
         gate("setConfig")
-        return stateJson(services.engine.setConfig(OptionParsers.requireObject(options, "config")))
+        return configResultJson(services.engine.setConfig(OptionParsers.requireObject(options, "config")))
     }
 
     /** `reset({config?})` -> State. */
     suspend fun reset(options: JSONObject): JSONObject {
         gate("reset")
-        return stateJson(services.engine.reset(OptionParsers.optObject(options, "config")))
+        return configResultJson(services.engine.reset(OptionParsers.optObject(options, "config")))
     }
 
+    /** The State of a call that applied a config, with `warnings`: what was accepted but probably wrong (rec. 14). */
+    private fun configResultJson(state: State): JSONObject =
+        stateJson(state).put("warnings", JSONArray(ConfigChecks.warnings(state.config)))
+
     fun getState(): JSONObject {
         gate("getState")
         return stateJson(services.engine.state())
@@ -419,12 +425,15 @@ internal class PluginHandlers(
 
     // ---- log
 
-    /** `log({level, message})` -> void; written through [Logger] (logcat and the log file). */
+    /**
+     * `log({level, message})` -> void; written through [Logger] (logcat and the log file), with bearer tokens, JWTs,
+     * credential fields and URLs removed ([LogRedaction]).
+     */
     fun log(options: JSONObject): JSONObject? {
         gate("log")
         val level = OptionParsers.logLevel(options)
         val message = OptionParsers.optString(options, "message") ?: OptionParsers.invalid("'message' is required")
-        Logger.log(level, JS_TAG, message)
+        Logger.log(level, JS_TAG, LogRedaction.redact(message))
         return null
     }
 

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

@@ -97,6 +97,12 @@ data class HeartbeatConfig(
     val minInterval: Int = 180,
     /** seconds, >= minInterval */
     val maxInterval: Int = 300,
+    /**
+     * Seconds, 0..60. After a heartbeat record is queued, the phone is kept awake until its upload has finished, or
+     * at most this long, so the heartbeat reaches the server on time while tracking is on. 0 = the wake lock ends when
+     * the heartbeat is queued.
+     */
+    val uploadKeepAwake: Int = 10,
 )
 
 data class AuthorizationConfig(
@@ -138,6 +144,10 @@ data class HttpConfig(
     val geofenceTemplate: String? = null,
     /** ms */
     val timeout: Long = 60_000,
+    /**
+     * Seconds, >= 0. The longest wait a `Retry-After` header of a 429 or 503 answer can impose on automatic uploads.
+     */
+    val maxRetryAfter: Int = 3600,
     val authorization: AuthorizationConfig? = null,
 )
 

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

@@ -69,12 +69,16 @@ object ConfigJson {
         return result
     }
 
-    /** The full TS `Config`: every key present, defaults filled, unset optional values as JSON null. */
-    fun toJson(c: Config): JSONObject = JSONObject()
+    /**
+     * The full TS `Config`: every key present, defaults filled, unset optional values as JSON null. With [maskSecrets],
+     * the authorization secrets are masked ([maskSecret]): results returned to the app (`getState()`, `setConfig()`,
+     * `ready()`, …) never carry the tokens (recommendation 16); the `authorization` event still does.
+     */
+    fun toJson(c: Config, maskSecrets: Boolean = false): JSONObject = JSONObject()
         .put("geolocation", geolocationToJson(c.geolocation))
         .put("activity", activityToJson(c.activity))
         .put("heartbeat", heartbeatToJson(c.heartbeat))
-        .put("http", httpToJson(c.http))
+        .put("http", httpToJson(c.http, maskSecrets))
         .put("persistence", persistenceToJson(c.persistence))
         .put("app", JSONObject().put("stopOnTerminate", c.app.stopOnTerminate).put("startOnBoot", c.app.startOnBoot))
         .put("notification", notificationToJson(c.notification))
@@ -91,7 +95,9 @@ object ConfigJson {
         .put("odometer", finiteOr(s.runtime.odometer, 0.0))
         .put("backend", s.backend.wire)
         .put("lastRecordAt", JsonUtil.orNull(Iso8601.formatOrNull(s.runtime.lastRecordAt)))
-        .put("config", toJson(s.config))
+        .put("lastStopReason", JsonUtil.orNull(s.runtime.lastStopReason))
+        .put("lastStopAt", JsonUtil.orNull(Iso8601.formatOrNull(s.runtime.lastStopAt)))
+        .put("config", toJson(s.config, maskSecrets = true))
 
     // ---- parse
 
@@ -184,6 +190,7 @@ object ConfigJson {
             enabled = r.boolean("enabled", c.enabled, d.enabled),
             minInterval = r.int("minInterval", c.minInterval, d.minInterval),
             maxInterval = r.int("maxInterval", c.maxInterval, d.maxInterval),
+            uploadKeepAwake = r.int("uploadKeepAwake", c.uploadKeepAwake, d.uploadKeepAwake),
         )
     }
 
@@ -214,6 +221,7 @@ object ConfigJson {
             locationTemplate = r.nullableString("locationTemplate", c.locationTemplate, d.locationTemplate),
             geofenceTemplate = r.nullableString("geofenceTemplate", c.geofenceTemplate, d.geofenceTemplate),
             timeout = r.long("timeout", c.timeout, d.timeout),
+            maxRetryAfter = r.int("maxRetryAfter", c.maxRetryAfter, d.maxRetryAfter),
             authorization = r.group<AuthorizationConfig?>("authorization", c.authorization, d.authorization) { ar, a ->
                 parseAuthorization(ar, a ?: AuthorizationConfig())
             },
@@ -226,11 +234,11 @@ object ConfigJson {
             strategy = r.enumValue("strategy", c.strategy, d.strategy, listOf(d.strategy)) { value ->
                 d.strategy.takeIf { it.equals(value, ignoreCase = true) }
             },
-            accessToken = r.nullableString("accessToken", c.accessToken, d.accessToken),
-            refreshToken = r.nullableString("refreshToken", c.refreshToken, d.refreshToken),
+            accessToken = unmasked(r.nullableString("accessToken", c.accessToken, d.accessToken), c.accessToken),
+            refreshToken = unmasked(r.nullableString("refreshToken", c.refreshToken, d.refreshToken), c.refreshToken),
             refreshUrl = r.nullableString("refreshUrl", c.refreshUrl, d.refreshUrl),
-            refreshPayload = r.objectText("refreshPayload", c.refreshPayload, d.refreshPayload),
-            refreshHeaders = r.stringMap("refreshHeaders", c.refreshHeaders, d.refreshHeaders),
+            refreshPayload = unmaskedPayload(r.objectText("refreshPayload", c.refreshPayload, d.refreshPayload), c.refreshPayload),
+            refreshHeaders = unmaskedHeaders(r.stringMap("refreshHeaders", c.refreshHeaders, d.refreshHeaders), c.refreshHeaders),
             refreshPayloadEncoding = r.enumValue(
                 "refreshPayloadEncoding",
                 c.refreshPayloadEncoding,
@@ -371,8 +379,9 @@ object ConfigJson {
         .put("enabled", h.enabled)
         .put("minInterval", h.minInterval)
         .put("maxInterval", h.maxInterval)
+        .put("uploadKeepAwake", h.uploadKeepAwake)
 
-    private fun httpToJson(h: HttpConfig): JSONObject = JSONObject()
+    private fun httpToJson(h: HttpConfig, maskSecrets: Boolean): JSONObject = JSONObject()
         .put("url", JsonUtil.orNull(h.url))
         .put("method", h.method.wire)
         .put("headers", JsonUtil.fromStringMap(h.headers))
@@ -387,15 +396,19 @@ object ConfigJson {
         .put("locationTemplate", JsonUtil.orNull(h.locationTemplate))
         .put("geofenceTemplate", JsonUtil.orNull(h.geofenceTemplate))
         .put("timeout", h.timeout)
-        .put("authorization", h.authorization?.let { authorizationToJson(it) } ?: JSONObject.NULL)
+        .put("maxRetryAfter", h.maxRetryAfter)
+        .put("authorization", h.authorization?.let { authorizationToJson(it, maskSecrets) } ?: JSONObject.NULL)
 
-    private fun authorizationToJson(a: AuthorizationConfig): JSONObject = JSONObject()
+    private fun authorizationToJson(a: AuthorizationConfig, mask: Boolean): JSONObject = JSONObject()
         .put("strategy", a.strategy)
-        .put("accessToken", JsonUtil.orNull(a.accessToken))
-        .put("refreshToken", JsonUtil.orNull(a.refreshToken))
+        .put("accessToken", JsonUtil.orNull(if (mask) a.accessToken?.let(::maskSecret) else a.accessToken))
+        .put("refreshToken", JsonUtil.orNull(if (mask) a.refreshToken?.let(::maskSecret) else a.refreshToken))
         .put("refreshUrl", JsonUtil.orNull(a.refreshUrl))
-        .put("refreshPayload", objectOrEmpty(a.refreshPayload, "http.authorization.refreshPayload"))
-        .put("refreshHeaders", JsonUtil.fromStringMap(a.refreshHeaders))
+        .put(
+            "refreshPayload",
+            objectOrEmpty(if (mask) maskedPayload(a.refreshPayload) else a.refreshPayload, "http.authorization.refreshPayload"),
+        )
+        .put("refreshHeaders", JsonUtil.fromStringMap(if (mask) a.refreshHeaders.mapValues { maskSecret(it.value) } else a.refreshHeaders))
         .put("refreshPayloadEncoding", a.refreshPayloadEncoding.wire)
         .put("expires", a.expires)
 
@@ -433,6 +446,48 @@ object ConfigJson {
         .put("positiveAction", JsonUtil.orNull(b.positiveAction))
         .put("negativeAction", JsonUtil.orNull(b.negativeAction))
 
+    /** Prefix of a masked secret in results: `***` and the last 4 characters (all hidden when 8 or fewer). */
+    const val MASK_PREFIX = "***"
+
+    /** [value] masked for results (see [toJson]). */
+    fun maskSecret(value: String): String =
+        if (value.length <= MASK_VISIBLE * 2) MASK_PREFIX else MASK_PREFIX + value.takeLast(MASK_VISIBLE)
+
+    private const val MASK_VISIBLE = 4
+
+    /**
+     * `refreshPayload` with every string value masked, except values that only use the `{refreshToken}` placeholder
+     * (they hold no secret themselves).
+     */
+    private fun maskedPayload(text: String): String {
+        val payload = JsonUtil.parseObject(text) ?: return text
+        val masked = JSONObject()
+        val keys = payload.keys()
+        while (keys.hasNext()) {
+            val key = keys.next()
+            val value = payload.get(key)
+            masked.put(key, if (value is String && !value.contains("{refreshToken}")) maskSecret(value) else value)
+        }
+        return masked.toString()
+    }
+
+    /**
+     * A secret given back unchanged from a result (`setConfig({config: (await getState()).config})`) keeps the stored
+     * value instead of replacing it with the masked text.
+     */
+    private fun unmasked(given: String?, current: String?): String? =
+        if (given != null && current != null && given.startsWith(MASK_PREFIX) && given == maskSecret(current)) current else given
+
+    private fun unmaskedPayload(given: String, current: String): String =
+        if (given != current && JsonUtil.parseObject(given)?.toString() == JsonUtil.parseObject(maskedPayload(current))?.toString()) {
+            current
+        } else {
+            given
+        }
+
+    private fun unmaskedHeaders(given: Map<String, String>, current: Map<String, String>): Map<String, String> =
+        if (given != current && given == current.mapValues { maskSecret(it.value) }) current else given
+
     /** Parses stored JSON object text; invalid text (only possible through `update{}`) becomes `{}`. */
     private fun objectOrEmpty(text: String, path: String): JSONObject {
         JsonUtil.parseObject(text)?.let { return it }

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

@@ -28,4 +28,10 @@ interface ConfigStore {
     fun update(transform: (Config) -> Config): Config
 
     fun updateRuntime(transform: (RuntimeState) -> RuntimeState): RuntimeState
+
+    /**
+     * True when the stored tokens (`accessToken`, `refreshToken`, `refreshPayload`, `refreshHeaders`) could not be
+     * decrypted at load: they read as unset, and uploads that need them are not sent until the app sets new ones.
+     */
+    val secretsUnavailable: Boolean get() = false
 }

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

@@ -6,11 +6,11 @@ import com.brickssoft.locationtracking.core.Logger
 /**
  * Clamps config values to their allowed ranges and logs a warning for each value it changes. Never throws.
  *
- * - `heartbeat.minInterval` >= 60 s and `heartbeat.maxInterval` >= `minInterval`;
+ * - `heartbeat.minInterval` >= 60 s and `heartbeat.maxInterval` >= `minInterval`; `heartbeat.uploadKeepAwake` in 0..60;
  * - `activity.minimumActivityRecognitionConfidence` in 0..100;
  * - `geolocation.stationaryRadius` >= 1; distances, intervals, delays and filter thresholds >= 0;
  * - `geolocation.locationTimeout` and `http.timeout` > 0 (otherwise their defaults);
- * - `http.maxBatchSize` >= 1, `http.autoSyncThreshold` >= 0, `http.syncInterval` >= 0;
+ * - `http.maxBatchSize` >= 1, `http.autoSyncThreshold` >= 0, `http.syncInterval` >= 0, `http.maxRetryAfter` >= 0;
  * - `persistence.maxDaysToPersist` >= 1, `persistence.maxRecordsToPersist` >= -1 (-1 = unlimited);
  * - `logger.logMaxDays` >= 1;
  * - at most [Constants.MAX_NOTIFICATION_ACTIONS] notification actions (the first ones are kept);
@@ -24,6 +24,9 @@ object ConfigValidator {
 
     const val MIN_STATIONARY_RADIUS_M = 1.0
 
+    /** Largest allowed `heartbeat.uploadKeepAwake`, seconds. */
+    const val MAX_UPLOAD_KEEP_AWAKE_S = 60
+
     /** Returns [config] with every out-of-range value clamped (equal to [config] when all values are valid). */
     fun validate(config: Config): Config {
         val validated = config.copy(
@@ -104,12 +107,14 @@ object ConfigValidator {
     private fun heartbeat(h: HeartbeatConfig): HeartbeatConfig {
         val min = atLeast("heartbeat.minInterval", h.minInterval, MIN_HEARTBEAT_INTERVAL_S)
         val max = atLeast("heartbeat.maxInterval", h.maxInterval, min)
-        return h.copy(minInterval = min, maxInterval = max)
+        val keepAwake = inRange("heartbeat.uploadKeepAwake", h.uploadKeepAwake, 0, MAX_UPLOAD_KEEP_AWAKE_S)
+        return h.copy(minInterval = min, maxInterval = max, uploadKeepAwake = keepAwake)
     }
 
     private fun http(h: HttpConfig): HttpConfig = h.copy(
         autoSyncThreshold = atLeast("http.autoSyncThreshold", h.autoSyncThreshold, 0),
         syncInterval = atLeast("http.syncInterval", h.syncInterval, 0),
+        maxRetryAfter = atLeast("http.maxRetryAfter", h.maxRetryAfter, 0),
         maxBatchSize = atLeast("http.maxBatchSize", h.maxBatchSize, 1),
         timeout = positive("http.timeout", h.timeout, HttpConfig().timeout),
     )

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

@@ -30,6 +30,11 @@ internal object RuntimeStateJson {
         .put("trackingStartedAt", JsonUtil.orNull(r.trackingStartedAt))
         .put("providerState", r.providerState?.let { ProviderStateJson.toJson(it) } ?: JSONObject.NULL)
         .put("didReady", r.didReady)
+        .put("trackingStartedElapsed", JsonUtil.orNull(r.trackingStartedElapsed))
+        .put("trackingStartedBootCount", JsonUtil.orNull(r.trackingStartedBootCount))
+        .put("lastStopReason", JsonUtil.orNull(r.lastStopReason))
+        .put("lastStopAt", JsonUtil.orNull(r.lastStopAt))
+        .put("userStopRecordedFor", JsonUtil.orNull(r.userStopRecordedFor))
 
     fun fromJson(json: JSONObject): RuntimeState {
         val d = RuntimeState()
@@ -59,6 +64,11 @@ internal object RuntimeStateJson {
             trackingStartedAt = JsonUtil.optLong(json, "trackingStartedAt"),
             providerState = json.optJSONObject("providerState")?.let { ProviderStateJson.fromJson(it) },
             didReady = JsonUtil.optBoolean(json, "didReady") ?: d.didReady,
+            trackingStartedElapsed = JsonUtil.optLong(json, "trackingStartedElapsed"),
+            trackingStartedBootCount = JsonUtil.optInt(json, "trackingStartedBootCount"),
+            lastStopReason = JsonUtil.optString(json, "lastStopReason"),
+            lastStopAt = JsonUtil.optLong(json, "lastStopAt"),
+            userStopRecordedFor = JsonUtil.optLong(json, "userStopRecordedFor"),
         )
     }
 

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

@@ -0,0 +1,188 @@
+package com.brickssoft.locationtracking.config
+
+import android.content.Context
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import androidx.annotation.VisibleForTesting
+import com.brickssoft.locationtracking.core.Logger
+import org.json.JSONObject
+import java.io.File
+import java.io.IOException
+import java.nio.ByteBuffer
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+
+/**
+ * The secret fields of `http.authorization` (recommendation 8): `accessToken`, `refreshToken`, `refreshPayload` (it can
+ * hold a client secret) and `refreshHeaders`. They are kept out of the SharedPreferences file and stored by a
+ * [SecretStore] instead.
+ */
+data class AuthorizationSecrets(
+    val accessToken: String?,
+    val refreshToken: String?,
+    val refreshPayload: String,
+    val refreshHeaders: Map<String, String>,
+) {
+    override fun toString(): String = "AuthorizationSecrets(redacted)"
+
+    fun toJson(): JSONObject = JSONObject()
+        .put("accessToken", accessToken ?: JSONObject.NULL)
+        .put("refreshToken", refreshToken ?: JSONObject.NULL)
+        .put("refreshPayload", refreshPayload)
+        .put("refreshHeaders", JSONObject(refreshHeaders))
+
+    companion object {
+        val EMPTY = AuthorizationSecrets(null, null, AuthorizationConfig().refreshPayload, emptyMap())
+
+        fun of(auth: AuthorizationConfig): AuthorizationSecrets =
+            AuthorizationSecrets(auth.accessToken, auth.refreshToken, auth.refreshPayload, auth.refreshHeaders)
+
+        fun fromJson(json: JSONObject): AuthorizationSecrets {
+            val headers = LinkedHashMap<String, String>()
+            json.optJSONObject("refreshHeaders")?.let { h -> h.keys().forEach { k -> headers[k] = h.optString(k) } }
+            return AuthorizationSecrets(
+                accessToken = if (json.isNull("accessToken")) null else json.optString("accessToken"),
+                refreshToken = if (json.isNull("refreshToken")) null else json.optString("refreshToken"),
+                refreshPayload = json.optString("refreshPayload", AuthorizationConfig().refreshPayload),
+                refreshHeaders = headers,
+            )
+        }
+    }
+}
+
+/** Stores [AuthorizationSecrets]. Every method may throw; the config store decides what a failure means. */
+interface SecretStore {
+    /** The stored secrets, or null if none are stored. @throws Exception if they are stored but cannot be read. */
+    fun read(): AuthorizationSecrets?
+
+    fun write(secrets: AuthorizationSecrets)
+
+    fun clear()
+
+    companion object {
+        /** In memory only (tests). */
+        fun inMemory(): SecretStore = object : SecretStore {
+            @Volatile
+            private var value: AuthorizationSecrets? = null
+
+            override fun read(): AuthorizationSecrets? = value
+
+            override fun write(secrets: AuthorizationSecrets) {
+                value = secrets
+            }
+
+            override fun clear() {
+                value = null
+            }
+        }
+    }
+}
+
+/** Encrypts and decrypts the secrets file. */
+interface SecretCipher {
+    fun encrypt(plaintext: ByteArray): ByteArray
+
+    fun decrypt(ciphertext: ByteArray): ByteArray
+}
+
+/**
+ * AES-256-GCM with a key that never leaves the Android Keystore (alias [KEY_ALIAS], created on first use). The output
+ * is `[IV length (4 bytes)][IV][ciphertext and tag]`, with [AAD] as associated data.
+ *
+ * This protects copies of the file (a backup, a forensic image, `adb backup`); code running inside the app process on
+ * a rooted phone can still use the key.
+ */
+class KeystoreSecretCipher : SecretCipher {
+    override fun encrypt(plaintext: ByteArray): ByteArray {
+        val cipher = Cipher.getInstance(TRANSFORMATION)
+        cipher.init(Cipher.ENCRYPT_MODE, key())
+        cipher.updateAAD(AAD)
+        val encrypted = cipher.doFinal(plaintext)
+        val iv = cipher.iv
+        return ByteBuffer.allocate(Int.SIZE_BYTES + iv.size + encrypted.size).putInt(iv.size).put(iv).put(encrypted).array()
+    }
+
+    override fun decrypt(ciphertext: ByteArray): ByteArray {
+        val buffer = ByteBuffer.wrap(ciphertext)
+        val ivSize = buffer.int
+        require(ivSize in 12..32 && buffer.remaining() > ivSize) { "damaged secrets file" }
+        val iv = ByteArray(ivSize).also { buffer.get(it) }
+        val encrypted = ByteArray(buffer.remaining()).also { buffer.get(it) }
+        val cipher = Cipher.getInstance(TRANSFORMATION)
+        cipher.init(Cipher.DECRYPT_MODE, key(), GCMParameterSpec(TAG_BITS, iv))
+        cipher.updateAAD(AAD)
+        return cipher.doFinal(encrypted)
+    }
+
+    private fun key(): SecretKey = synchronized(lock) {
+        val store = KeyStore.getInstance(KEYSTORE).apply { load(null) }
+        (store.getKey(KEY_ALIAS, null) as? SecretKey) ?: KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, KEYSTORE)
+            .apply {
+                init(
+                    KeyGenParameterSpec.Builder(KEY_ALIAS, KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
+                        .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+                        .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+                        .setKeySize(KEY_BITS)
+                        .build(),
+                )
+            }
+            .generateKey()
+    }
+
+    private companion object {
+        const val KEYSTORE = "AndroidKeyStore"
+        const val KEY_ALIAS = "com.brickssoft.locationtracking.secrets.v1"
+        const val TRANSFORMATION = "AES/GCM/NoPadding"
+        const val KEY_BITS = 256
+        const val TAG_BITS = 128
+        val AAD = "location_tracking_secrets_v1".toByteArray(Charsets.UTF_8)
+        val lock = Any()
+    }
+}
+
+/**
+ * [SecretStore] in the file `noBackupFilesDir/`[FILE_NAME] (never in Auto Backup or device-to-device transfer),
+ * encrypted by [cipher]. Writes go to a temporary file that is renamed over the old one.
+ */
+class FileSecretStore(private val file: File, private val cipher: SecretCipher) : SecretStore {
+    override fun read(): AuthorizationSecrets? {
+        if (!file.isFile) return null
+        val plaintext = cipher.decrypt(file.readBytes())
+        return AuthorizationSecrets.fromJson(JSONObject(String(plaintext, Charsets.UTF_8)))
+    }
+
+    override fun write(secrets: AuthorizationSecrets) {
+        val encrypted = cipher.encrypt(secrets.toJson().toString().toByteArray(Charsets.UTF_8))
+        file.parentFile?.mkdirs()
+        val temp = File(file.path + ".tmp")
+        temp.writeBytes(encrypted)
+        if (!temp.renameTo(file)) {
+            temp.delete()
+            throw IOException("could not replace $file")
+        }
+    }
+
+    override fun clear() {
+        if (file.exists() && !file.delete()) Logger.w(TAG, "could not delete $file")
+    }
+
+    companion object {
+        private const val TAG = "LT.Secrets"
+        const val FILE_NAME = "location_tracking_secrets.bin"
+
+        /** The store the plugin uses: [FILE_NAME] under `noBackupFilesDir`, Android Keystore encryption. */
+        fun forContext(context: Context): SecretStore {
+            testOverride?.let { return it }
+            val app = context.applicationContext ?: context
+            return FileSecretStore(File(app.noBackupFilesDir, FILE_NAME), KeystoreSecretCipher())
+        }
+
+        /** Test hook: the store [forContext] returns (Robolectric has no Android Keystore). */
+        @VisibleForTesting
+        @Volatile
+        var testOverride: SecretStore? = null
+    }
+}