@bricks-soft/capacitor-location-tracking 0.0.0-stage → 8.0.0

package/android/src/main/java/com/brickssoft/locationtracking/heartbeat/HeartbeatAlarmReceiver.kt

@@ -0,0 +1,69 @@
+package com.brickssoft.locationtracking.heartbeat
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.engine.TrackingEngine
+import com.brickssoft.locationtracking.service.ServiceController
+import kotlinx.coroutines.launch
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * Receives the heartbeat PendingIntent alarms (exact and backup). Runs [HeartbeatScheduler.onAlarm] and, if
+ * tracking is enabled but the foreground service is gone (the process was killed), restores tracking with
+ * `engine.restore("restore")`: together with `START_STICKY` this is how tracking comes back after task killers.
+ */
+class HeartbeatAlarmReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        if (intent.action != Constants.ACTION_HEARTBEAT) return
+        val trigger = HeartbeatIntents.triggerOf(intent)
+        val pending = goAsync()
+        try {
+            val c = Components.get(context)
+            // invokeOnCompletion also finishes the broadcast if the coroutine is cancelled before it starts.
+            c.scope.launch {
+                deliver(trigger, c.heartbeat, c.configStore, lazy { c.serviceController }, lazy { c.engine })
+            }.invokeOnCompletion { pending.finish() }
+        } catch (e: Exception) {
+            Logger.e(TAG, "heartbeat alarm delivery failed", e)
+            pending.finish()
+        }
+    }
+
+    internal companion object {
+        private const val TAG = DefaultHeartbeatScheduler.TAG
+
+        /**
+         * The post-alarm decision: run the heartbeat, then restore tracking if it is enabled while the foreground
+         * service is not running. Failures are logged; the restore check runs even if the heartbeat failed.
+         */
+        suspend fun deliver(
+            trigger: HeartbeatTrigger,
+            heartbeat: HeartbeatScheduler,
+            configStore: ConfigStore,
+            serviceController: Lazy<ServiceController>,
+            engine: Lazy<TrackingEngine>,
+        ) {
+            try {
+                heartbeat.onAlarm(trigger)
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                Logger.e(TAG, "heartbeat alarm ($trigger) failed", e)
+            }
+            if (!configStore.runtime.value.enabled || serviceController.value.isRunning) return
+            Logger.i(TAG, "tracking is enabled but the service is not running; restoring")
+            try {
+                engine.value.restore("restore")
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                Logger.e(TAG, "restore after heartbeat alarm failed", e)
+            }
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/heartbeat/HeartbeatAlarms.kt

@@ -0,0 +1,100 @@
+package com.brickssoft.locationtracking.heartbeat
+
+import android.annotation.SuppressLint
+import android.app.AlarmManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.os.Handler
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Logger
+
+/** The subset of [AlarmManager] the heartbeat uses. Injectable so tests can simulate a refusing AlarmManager. */
+interface HeartbeatAlarms {
+    /** @throws SecurityException if exact alarms are not allowed. */
+    fun setExactAndAllowWhileIdle(type: Int, triggerAtMillis: Long, operation: PendingIntent)
+
+    fun setExact(type: Int, triggerAtMillis: Long, tag: String, listener: AlarmManager.OnAlarmListener, handler: Handler)
+
+    fun setAndAllowWhileIdle(type: Int, triggerAtMillis: Long, operation: PendingIntent)
+
+    fun cancel(operation: PendingIntent)
+
+    fun cancel(listener: AlarmManager.OnAlarmListener)
+}
+
+/**
+ * [HeartbeatAlarms] backed by the system [AlarmManager]. The plugin declares no exact-alarm permission: the
+ * scheduler calls [setExactAndAllowWhileIdle] only when `canScheduleExactAlarms()` (battery-exempt apps) and
+ * catches the [SecurityException] otherwise; listener-based [setExact] needs no permission.
+ */
+class SystemHeartbeatAlarms(context: Context) : HeartbeatAlarms {
+    private val appContext: Context = context.applicationContext ?: context
+    private val alarmManager: AlarmManager? by lazy {
+        (appContext.getSystemService(Context.ALARM_SERVICE) as? AlarmManager).also {
+            if (it == null) Logger.e(TAG, "AlarmManager unavailable; heartbeat alarms are disabled")
+        }
+    }
+
+    @SuppressLint("ScheduleExactAlarm", "MissingPermission")
+    override fun setExactAndAllowWhileIdle(type: Int, triggerAtMillis: Long, operation: PendingIntent) {
+        alarmManager?.setExactAndAllowWhileIdle(type, triggerAtMillis, operation)
+    }
+
+    @SuppressLint("ScheduleExactAlarm", "MissingPermission")
+    override fun setExact(
+        type: Int,
+        triggerAtMillis: Long,
+        tag: String,
+        listener: AlarmManager.OnAlarmListener,
+        handler: Handler,
+    ) {
+        alarmManager?.setExact(type, triggerAtMillis, tag, listener, handler)
+    }
+
+    override fun setAndAllowWhileIdle(type: Int, triggerAtMillis: Long, operation: PendingIntent) {
+        alarmManager?.setAndAllowWhileIdle(type, triggerAtMillis, operation)
+    }
+
+    override fun cancel(operation: PendingIntent) {
+        alarmManager?.cancel(operation)
+    }
+
+    override fun cancel(listener: AlarmManager.OnAlarmListener) {
+        alarmManager?.cancel(listener)
+    }
+
+    private companion object {
+        const val TAG = DefaultHeartbeatScheduler.TAG
+    }
+}
+
+/** The explicit, immutable heartbeat broadcast (request code [Constants.RC_HEARTBEAT], [Constants.ACTION_HEARTBEAT]). */
+internal object HeartbeatIntents {
+    /** [HeartbeatTrigger] name of the alarm that fired. */
+    const val EXTRA_TRIGGER = "com.brickssoft.locationtracking.EXTRA_HEARTBEAT_TRIGGER"
+
+    fun intent(context: Context, trigger: HeartbeatTrigger): Intent =
+        Intent(context, HeartbeatAlarmReceiver::class.java)
+            .setAction(Constants.ACTION_HEARTBEAT)
+            .putExtra(EXTRA_TRIGGER, trigger.name)
+
+    /** The heartbeat PendingIntent; [trigger] is updated in place (one PendingIntent, so one alarm, at a time). */
+    fun pendingIntent(context: Context, trigger: HeartbeatTrigger): PendingIntent =
+        PendingIntent.getBroadcast(context, Constants.RC_HEARTBEAT, intent(context, trigger), Constants.piImmutable())
+
+    /** The heartbeat PendingIntent if it exists (for example armed by a previous process), without creating it. */
+    fun existing(context: Context): PendingIntent? =
+        PendingIntent.getBroadcast(
+            context,
+            Constants.RC_HEARTBEAT,
+            Intent(context, HeartbeatAlarmReceiver::class.java).setAction(Constants.ACTION_HEARTBEAT),
+            PendingIntent.FLAG_NO_CREATE or PendingIntent.FLAG_IMMUTABLE,
+        )
+
+    /** The trigger carried by [intent]; [HeartbeatTrigger.BACKUP_ALARM] if missing or unknown. */
+    fun triggerOf(intent: Intent?): HeartbeatTrigger {
+        val name = intent?.getStringExtra(EXTRA_TRIGGER) ?: return HeartbeatTrigger.BACKUP_ALARM
+        return HeartbeatTrigger.entries.firstOrNull { it.name == name } ?: HeartbeatTrigger.BACKUP_ALARM
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/heartbeat/HeartbeatScheduler.kt

@@ -0,0 +1,25 @@
+package com.brickssoft.locationtracking.heartbeat
+
+import com.brickssoft.locationtracking.model.HeartbeatStatus
+import com.brickssoft.locationtracking.model.Record
+
+enum class HeartbeatTrigger {
+    EXACT_ALARM,
+    LISTENER_ALARM,
+    BACKUP_ALARM,
+}
+
+/** Creates a `heartbeat` record when no record was created for `heartbeat.minInterval` while tracking. */
+interface HeartbeatScheduler {
+    /** Starts the window from runtime.lastRecord* (or now); observes config itself. */
+    fun start()
+
+    fun stop()
+
+    /** Every persisted record restarts the window. */
+    fun onRecordRecorded(record: Record)
+
+    suspend fun onAlarm(trigger: HeartbeatTrigger)
+
+    suspend fun status(): HeartbeatStatus
+}

package/android/src/main/java/com/brickssoft/locationtracking/heartbeat/HeartbeatWindow.kt

@@ -0,0 +1,179 @@
+package com.brickssoft.locationtracking.heartbeat
+
+import com.brickssoft.locationtracking.model.HeartbeatStrategy
+
+/**
+ * One heartbeat window: when the next heartbeat is due and how it is scheduled (architecture §3).
+ *
+ * Pure Kotlin, no Android types. Every `*Elapsed` value is in the current boot's elapsed-realtime timebase
+ * (ms), which is what `AlarmManager.ELAPSED_REALTIME_WAKEUP` uses.
+ *
+ * @property baseElapsed start of the window: the last record (or the no-record anchor), never before the session start.
+ * @property dueElapsed `base + minInterval` (never before the last attempt + minInterval): when the heartbeat is due.
+ * @property deadlineElapsed `base + maxInterval`: the heartbeat should exist by then.
+ * @property backupAtElapsed trigger of the allow-while-idle backup alarm (`due`, or paced 9 min apart while idle).
+ * @property strategy how the window is armed; [HeartbeatStrategy.DISABLED] if heartbeat or tracking is off.
+ * @property nextHeartbeatAt wall-clock estimate of the next heartbeat (epoch ms), or null when disabled.
+ * @property minIntervalMs the effective min interval (floored at [MIN_INTERVAL_FLOOR_S]).
+ */
+internal data class HeartbeatWindow(
+    val baseElapsed: Long,
+    val dueElapsed: Long,
+    val deadlineElapsed: Long,
+    val backupAtElapsed: Long,
+    val strategy: HeartbeatStrategy,
+    val nextHeartbeatAt: Long?,
+    val minIntervalMs: Long,
+) {
+    /**
+     * Elapsed time at which the heartbeat is expected: the backup alarm while idle-paced (the listener alarm is
+     * deferred in deep idle), otherwise [dueElapsed]. This is the heartbeat metadata's `next_at` and
+     * `getHeartbeatStatus().nextHeartbeatAt`, converted to wall-clock time.
+     */
+    val expectedFireElapsed: Long
+        get() = if (strategy == HeartbeatStrategy.IDLE_PACED) backupAtElapsed else dueElapsed
+
+    /**
+     * True if a heartbeat must be created now: `now - base >= minInterval - 1 s` (and the previous attempt is at
+     * least `minInterval - 1 s` ago).
+     */
+    fun shouldFire(nowElapsed: Long): Boolean = nowElapsed >= dueElapsed - FIRE_TOLERANCE_MS
+
+    /**
+     * True if the alarms armed for [armed] must be set again for this window (null [armed]: nothing is armed).
+     *
+     * Every record moves the window later, and a moving phone records every few seconds. Setting the alarms for each
+     * record costs AlarmManager calls, so a due time that moved later by less than [REARM_THRESHOLD_MS] keeps the
+     * armed alarms. Such an alarm fires up to [REARM_THRESHOLD_MS] before the real due time; the alarm handler then
+     * finds the window not due, creates no heartbeat and arms the real due time.
+     *
+     * The alarms are always set again when:
+     * - the strategy differs;
+     * - a trigger time moved earlier (the armed alarm would fire after the heartbeat is due);
+     * - the strategy is [HeartbeatStrategy.IDLE_PACED] and the backup time moved at all. An early backup alarm uses
+     *   one of the few allow-while-idle alarms Android grants per hour and would move the next backup about
+     *   9 minutes later ([IDLE_BACKUP_SPACING_MS]). Records are rare in deep idle, so this costs little.
+     */
+    fun needsRearm(armed: HeartbeatWindow?): Boolean {
+        if (armed == null || armed.strategy != strategy) return true
+        val dueMove = dueElapsed - armed.dueElapsed
+        val backupMove = backupAtElapsed - armed.backupAtElapsed
+        if (dueMove < 0L || backupMove < 0L) return true
+        if (strategy == HeartbeatStrategy.IDLE_PACED && backupMove != 0L) return true
+        // Outside idle pacing the backup time equals the due time, so the due time decides.
+        return dueMove >= REARM_THRESHOLD_MS
+    }
+
+    companion object {
+        /** Tolerance of [shouldFire], so an alarm delivered a little early still counts. */
+        const val FIRE_TOLERANCE_MS = 1_000L
+
+        /**
+         * A due time that moved later by less than this keeps the armed alarms (see [needsRearm]). With a record every
+         * 5 s, the alarms are set once per 30 s of records instead of once per record.
+         */
+        const val REARM_THRESHOLD_MS = 30_000L
+
+        /** Minimum spacing of allow-while-idle backup alarms while idle and not battery-exempt. */
+        const val IDLE_BACKUP_SPACING_MS = 9 * 60_000L
+
+        /** Floor of `heartbeat.minInterval` (the documented minimum). */
+        const val MIN_INTERVAL_FLOOR_S = 60
+
+        /**
+         * Computes the window.
+         *
+         * Base: the last record's elapsed time if it was recorded in this boot; otherwise it is derived from the
+         * wall clock (`nowElapsed - (now - lastRecordAt)`); if there is no record, [noRecordBaseElapsed] (or
+         * [nowElapsed]). A last record older than [trackingStartedAt] belongs to an earlier tracking session, so
+         * the base is then the session start instead (otherwise every `start()` after a pause would find the window
+         * overdue). The base never lies in the future. When the boot count is unknown (-1) on either side, the
+         * record counts as "this boot" as long as its elapsed time is not ahead of [nowElapsed].
+         *
+         * @param lastRecordAt wall time of the last record (epoch ms), or null if there is none.
+         * @param lastRecordElapsed elapsed time of the last record.
+         * @param lastRecordBootCount boot count of the last record.
+         * @param minIntervalSec `heartbeat.minInterval` (floored at [MIN_INTERVAL_FLOOR_S]).
+         * @param maxIntervalSec `heartbeat.maxInterval` (at least the min interval).
+         * @param isIdle device is in deep idle (Doze).
+         * @param canExact `canScheduleExactAlarms()`: battery-exempt, alarms are not rate-limited.
+         * @param lastBackupFireElapsed when a backup alarm last fired in this boot, or null.
+         * @param enabled tracking and heartbeat are both enabled; false yields [HeartbeatStrategy.DISABLED].
+         * @param noRecordBaseElapsed base to use when there is no record (a stable anchor), default [nowElapsed].
+         * @param lastAttemptElapsed elapsed time of the last heartbeat attempt: the next one is due no earlier than
+         *   one min interval later, even if that attempt failed to produce a record.
+         * @param trackingStartedAt wall time the current tracking session started (`runtime.trackingStartedAt`).
+         */
+        fun compute(
+            lastRecordAt: Long?,
+            lastRecordElapsed: Long?,
+            lastRecordBootCount: Int?,
+            now: Long,
+            nowElapsed: Long,
+            bootCount: Int,
+            minIntervalSec: Int,
+            maxIntervalSec: Int,
+            isIdle: Boolean,
+            canExact: Boolean,
+            lastBackupFireElapsed: Long?,
+            enabled: Boolean = true,
+            noRecordBaseElapsed: Long? = null,
+            lastAttemptElapsed: Long? = null,
+            trackingStartedAt: Long? = null,
+        ): HeartbeatWindow {
+            val minMs = minIntervalSec.coerceAtLeast(MIN_INTERVAL_FLOOR_S) * 1_000L
+            val maxMs = (maxIntervalSec * 1_000L).coerceAtLeast(minMs)
+
+            val base = when {
+                lastRecordAt == null -> noRecordBaseElapsed ?: nowElapsed
+                lastRecordElapsed != null && sameBoot(lastRecordElapsed, lastRecordBootCount, nowElapsed, bootCount) ->
+                    lastRecordElapsed
+                else -> nowElapsed - (now - lastRecordAt)
+            }.coerceAtLeast(sessionStartElapsed(lastRecordAt, trackingStartedAt, now, nowElapsed) ?: Long.MIN_VALUE)
+                .coerceAtMost(nowElapsed)
+            val due = maxOf(base + minMs, lastAttemptElapsed?.plus(minMs) ?: Long.MIN_VALUE)
+
+            // A backup fire from a previous boot (ahead of now) says nothing about the current idle quota.
+            val lastBackup = lastBackupFireElapsed?.takeIf { it <= nowElapsed }
+            val backupAt = if (isIdle && !canExact && lastBackup != null) {
+                maxOf(due, lastBackup + IDLE_BACKUP_SPACING_MS)
+            } else {
+                due
+            }
+
+            val strategy = when {
+                !enabled -> HeartbeatStrategy.DISABLED
+                canExact -> HeartbeatStrategy.EXACT
+                isIdle -> HeartbeatStrategy.IDLE_PACED
+                else -> HeartbeatStrategy.LISTENER_WITH_BACKUP
+            }
+            val window = HeartbeatWindow(
+                baseElapsed = base,
+                dueElapsed = due,
+                deadlineElapsed = base + maxMs,
+                backupAtElapsed = backupAt,
+                strategy = strategy,
+                nextHeartbeatAt = null,
+                minIntervalMs = minMs,
+            )
+            if (strategy == HeartbeatStrategy.DISABLED) return window
+            // An overdue window fires as soon as it is armed.
+            val next = now + (maxOf(window.expectedFireElapsed, nowElapsed) - nowElapsed)
+            return window.copy(nextHeartbeatAt = next)
+        }
+
+        /** Elapsed time of the session start, if the last record predates it (and the start is not in the future). */
+        private fun sessionStartElapsed(lastRecordAt: Long?, trackingStartedAt: Long?, now: Long, nowElapsed: Long): Long? {
+            if (lastRecordAt == null || trackingStartedAt == null) return null
+            if (lastRecordAt >= trackingStartedAt || trackingStartedAt > now) return null
+            return nowElapsed - (now - trackingStartedAt)
+        }
+
+        private fun sameBoot(recordElapsed: Long, recordBootCount: Int?, nowElapsed: Long, bootCount: Int): Boolean =
+            if (recordBootCount != null && recordBootCount >= 0 && bootCount >= 0) {
+                recordBootCount == bootCount
+            } else {
+                recordElapsed <= nowElapsed
+            }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/http/AuthorizationManager.kt

@@ -0,0 +1,213 @@
+package com.brickssoft.locationtracking.http
+
+import com.brickssoft.locationtracking.config.AuthorizationConfig
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.config.HttpConfig
+import com.brickssoft.locationtracking.config.RefreshPayloadEncoding
+import com.brickssoft.locationtracking.core.AppDispatchers
+import com.brickssoft.locationtracking.core.Clock
+import com.brickssoft.locationtracking.core.EventBus
+import com.brickssoft.locationtracking.core.Iso8601
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingEvent
+import com.brickssoft.locationtracking.model.JsonUtil
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.ensureActive
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import okhttp3.FormBody
+import okhttp3.OkHttpClient
+import org.json.JSONObject
+import java.io.IOException
+
+/**
+ * JWT access-token handling for `http.authorization` (architecture §2).
+ *
+ * - The token is refreshed before a request when it is missing or `expires > 0 && now >= expires - 60 s`, and after
+ *   a 401 (at most once per upload; the caller enforces that).
+ * - A refresh POSTs `refreshPayload` (string values with `{refreshToken}` substituted, JSON or form encoded) with
+ *   `refreshHeaders` to `refreshUrl`, reads `accessToken|access_token`, `refreshToken|refresh_token` and
+ *   `expires|expires_at` (epoch; seconds if < 1e12) or `expires_in` (relative seconds), persists the new tokens with
+ *   `configStore.update` and emits an `Authorization` event (also on failure).
+ * - Refreshes are single-flight: callers that waited while another caller replaced their stale token reuse it.
+ *
+ * Token values are never logged.
+ */
+internal class AuthorizationManager(
+    private val configStore: ConfigStore,
+    private val events: EventBus,
+    private val clock: Clock,
+    private val dispatchers: AppDispatchers,
+) {
+    private val mutex = Mutex()
+
+    /**
+     * A refreshed token whose whole lifetime already fell inside the refresh margin. It is not refreshed again before
+     * it really expires; otherwise every upload would first refresh it.
+     */
+    @Volatile
+    private var shortLivedToken: String? = null
+
+    /** The access token to send ([value] null = no Authorization header) and whether a refresh was attempted. */
+    data class Token(val value: String?, val refreshAttempted: Boolean)
+
+    /** Tokens read from a refresh response; [expires] is epoch ms or -1 if unknown. */
+    data class Tokens(val accessToken: String, val refreshToken: String?, val expires: Long)
+
+    /** True if requests configured by [http] carry the bearer token (authorization set, no explicit header). */
+    fun appliesTo(http: HttpConfig): Boolean =
+        http.authorization != null && !HttpSupport.hasHeader(http.headers, HttpSupport.AUTHORIZATION)
+
+    /**
+     * The token for the next request, refreshing first if it is missing or about to expire (and refreshable), unless
+     * [mayRefresh] is false.
+     */
+    suspend fun tokenForRequest(client: OkHttpClient, mayRefresh: Boolean = true): Token {
+        val auth = configStore.config.value.http.authorization ?: return Token(null, false)
+        val current = auth.accessToken.nonBlank()
+        if (!mayRefresh || !needsRefresh(auth) || !canRefresh(auth)) return Token(current, false)
+        return Token(refresh(client, current) ?: current, true)
+    }
+
+    /**
+     * Refreshes the token (single-flight) unless another caller already replaced [staleToken] with a token that
+     * does not need a refresh. Returns the token to use, or null if there is none (refresh failed or impossible).
+     */
+    suspend fun refresh(client: OkHttpClient, staleToken: String?): String? = mutex.withLock {
+        val auth = configStore.config.value.http.authorization ?: return@withLock null
+        val current = auth.accessToken.nonBlank()
+        if (current != null && current != staleToken && !needsRefresh(auth)) return@withLock current
+        if (!canRefresh(auth)) return@withLock null
+        performRefresh(client, auth)
+    }
+
+    private fun canRefresh(auth: AuthorizationConfig): Boolean = !auth.refreshUrl.isNullOrBlank()
+
+    private fun needsRefresh(auth: AuthorizationConfig): Boolean {
+        val token = auth.accessToken
+        if (token.isNullOrBlank()) return true
+        if (auth.expires <= 0) return false
+        val now = clock.now()
+        return now >= auth.expires || (now >= auth.expires - EXPIRY_MARGIN_MS && token != shortLivedToken)
+    }
+
+    private suspend fun performRefresh(client: OkHttpClient, auth: AuthorizationConfig): String? {
+        val url = HttpSupport.parseUrl(auth.refreshUrl)
+        if (url == null) {
+            Logger.e(TAG, "authorization.refreshUrl is not a valid http(s) URL")
+            emit(false, 0, "authorization.refreshUrl is not a valid http(s) URL", null)
+            return null
+        }
+        val (contentType, body) = refreshBody(auth)
+        val headers = HttpSupport.headers(contentType, auth.refreshHeaders, bearerToken = null)
+        val request = HttpSupport.request(url, "POST", headers, body)
+        val response = try {
+            HttpSupport.execute(client, request, dispatchers.io)
+        } catch (e: IOException) {
+            currentCoroutineContext().ensureActive()
+            Logger.w(TAG, "token refresh failed: ${e.message}")
+            emit(false, 0, e.message ?: e.javaClass.simpleName, null)
+            return null
+        }
+        val json = JsonUtil.parseObject(response.body)
+        if (!response.isSuccessful) {
+            Logger.w(TAG, "token refresh failed: HTTP ${response.status}")
+            emit(false, response.status, "HTTP ${response.status}", json?.toString())
+            return null
+        }
+        val tokens = parseTokens(json, clock.now())
+        if (tokens == null) {
+            Logger.w(TAG, "token refresh response (HTTP ${response.status}) has no accessToken")
+            emit(false, response.status, "refresh response has no accessToken", json?.toString())
+            return null
+        }
+        configStore.update { config ->
+            // Do not resurrect an authorization config removed while the refresh was in flight.
+            val current = config.http.authorization ?: return@update config
+            val updated = current.copy(
+                accessToken = tokens.accessToken,
+                refreshToken = tokens.refreshToken ?: current.refreshToken,
+                expires = tokens.expires,
+            )
+            config.copy(http = config.http.copy(authorization = updated))
+        }
+        val shortLived = tokens.expires > 0 && tokens.expires - clock.now() <= EXPIRY_MARGIN_MS
+        shortLivedToken = if (shortLived) tokens.accessToken else null
+        if (shortLived) Logger.w(TAG, "refreshed access token expires within ${EXPIRY_MARGIN_MS / 1000} s")
+        Logger.i(TAG, "access token refreshed (HTTP ${response.status})")
+        emit(true, response.status, null, json?.toString())
+        return tokens.accessToken
+    }
+
+    private fun emit(success: Boolean, status: Int, error: String?, responseJson: String?) {
+        events.emit(TrackingEvent.Authorization(success, status, error, responseJson))
+    }
+
+    companion object {
+        private const val TAG = "LT.Auth"
+
+        /** Refresh this long before `expires`. */
+        const val EXPIRY_MARGIN_MS = 60_000L
+
+        private const val REFRESH_TOKEN_PLACEHOLDER = "{refreshToken}"
+
+        /** Epoch values below this are seconds, not milliseconds. */
+        private const val EPOCH_SECONDS_LIMIT = 1e12
+
+        /** Content type and body text of the refresh request. */
+        fun refreshBody(auth: AuthorizationConfig): Pair<String, String> {
+            val payload = JsonUtil.parseObject(auth.refreshPayload) ?: JSONObject().also {
+                if (auth.refreshPayload.isNotBlank()) Logger.w(TAG, "authorization.refreshPayload is not a JSON object")
+            }
+            val refreshToken = auth.refreshToken.orEmpty()
+            val substituted = JSONObject()
+            val keys = payload.keys()
+            while (keys.hasNext()) {
+                val key = keys.next()
+                val value = payload.get(key)
+                val resolved = if (value is String) value.replace(REFRESH_TOKEN_PLACEHOLDER, refreshToken) else value
+                substituted.put(key, resolved)
+            }
+            return when (auth.refreshPayloadEncoding) {
+                RefreshPayloadEncoding.JSON -> HttpSupport.JSON_CONTENT_TYPE to substituted.toString()
+                RefreshPayloadEncoding.FORM -> HttpSupport.FORM_CONTENT_TYPE to formEncode(substituted)
+            }
+        }
+
+        /** Reads the tokens of a refresh response; null if it has no access token. */
+        fun parseTokens(json: JSONObject?, now: Long): Tokens? {
+            if (json == null) return null
+            val access = firstString(json, "accessToken", "access_token") ?: return null
+            val expires = epochMs(json, "expires")
+                ?: epochMs(json, "expires_at")
+                ?: JsonUtil.optDouble(json, "expires_in")?.takeIf { it > 0 }?.let { now + (it * 1000).toLong() }
+                ?: -1L
+            return Tokens(access, firstString(json, "refreshToken", "refresh_token"), expires)
+        }
+
+        private fun firstString(json: JSONObject, vararg keys: String): String? =
+            keys.firstNotNullOfOrNull { JsonUtil.optString(json, it).nonBlank() }
+
+        /** An absolute expiry: epoch seconds (< 1e12), epoch ms, or an ISO-8601 string; null if absent/invalid. */
+        private fun epochMs(json: JSONObject, key: String): Long? {
+            val number = JsonUtil.optDouble(json, key)
+                ?: return JsonUtil.optString(json, key)?.let { Iso8601.parse(it) }
+            if (number <= 0) return null
+            return if (number < EPOCH_SECONDS_LIMIT) (number * 1000).toLong() else number.toLong()
+        }
+
+        /** `application/x-www-form-urlencoded` text of [json]'s non-null values. */
+        private fun formEncode(json: JSONObject): String {
+            val form = FormBody.Builder()
+            val keys = json.keys()
+            while (keys.hasNext()) {
+                val key = keys.next()
+                if (!json.isNull(key)) form.add(key, json.get(key).toString())
+            }
+            val body = form.build()
+            return (0 until body.size).joinToString("&") { "${body.encodedName(it)}=${body.encodedValue(it)}" }
+        }
+
+        private fun String?.nonBlank(): String? = this?.takeIf { it.isNotBlank() }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/http/BodyBuilder.kt

@@ -0,0 +1,73 @@
+package com.brickssoft.locationtracking.http
+
+import com.brickssoft.locationtracking.config.HttpConfig
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.JsonUtil
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordJson
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Builds request bodies (architecture §2). Every record carries `sent_at`; a template, when configured, replaces
+ * the default record shape.
+ *
+ * - Single record (`batchSync:false`): `{"<rootProperty>": {...}, ...params}`.
+ * - Batch (`batchSync:true`): `{"<rootProperty>": [{...}, ...], ...params}`, records in the given order.
+ * - `rootProperty` "." (or blank): a single record's fields are merged into the root together with params; a batch
+ *   is a bare JSON array and params are ignored.
+ *
+ * Params never overwrite a key the body already has (the record data wins).
+ */
+internal object BodyBuilder {
+    private const val TAG = "LT.Http"
+
+    /** The `rootProperty` value meaning "no wrapping". */
+    const val MERGE_ROOT = "."
+
+    /** Body for [records]: a batch if `http.batchSync`, otherwise [records] must hold exactly one record. */
+    fun build(records: List<Record>, http: HttpConfig, sentAt: Long): String =
+        if (http.batchSync) {
+            batch(records, http, sentAt)
+        } else {
+            require(records.size == 1) { "a non-batch body holds exactly one record, got ${records.size}" }
+            single(records[0], http, sentAt)
+        }
+
+    fun single(record: Record, http: HttpConfig, sentAt: Long): String {
+        val value = recordValue(record, http, sentAt)
+        if (!isMerge(http)) return withParams(JSONObject().put(http.rootProperty, value), http).toString()
+        // A template may render an array, which cannot be merged: send it bare.
+        return if (value is JSONObject) withParams(value, http).toString() else value.toString()
+    }
+
+    fun batch(records: List<Record>, http: HttpConfig, sentAt: Long): String {
+        val array = JSONArray()
+        for (record in records) array.put(recordValue(record, http, sentAt))
+        if (isMerge(http)) return array.toString()
+        return withParams(JSONObject().put(http.rootProperty, array), http).toString()
+    }
+
+    /** The rendered template for [record] if one applies and renders valid JSON, else `RecordJson.toJson`. */
+    fun recordValue(record: Record, http: HttpConfig, sentAt: Long): Any {
+        val template = TemplateRenderer.templateFor(record, http)
+        if (template != null) TemplateRenderer.render(template, record, sentAt)?.let { return it }
+        return RecordJson.toJson(record, sentAt)
+    }
+
+    private fun isMerge(http: HttpConfig): Boolean = http.rootProperty.isBlank() || http.rootProperty == MERGE_ROOT
+
+    private fun withParams(body: JSONObject, http: HttpConfig): JSONObject {
+        val params = JsonUtil.parseObject(http.params)
+        if (params == null) {
+            if (http.params.isNotBlank()) Logger.w(TAG, "http.params is not a JSON object; ignored")
+            return body
+        }
+        val keys = params.keys()
+        while (keys.hasNext()) {
+            val key = keys.next()
+            if (!body.has(key)) body.put(key, params.get(key))
+        }
+        return body
+    }
+}