@bglocation/capacitor 1.1.0

package/android/src/main/kotlin/dev/bglocation/core/license/BGLLicenseEnforcer.kt

@@ -0,0 +1,137 @@
+package dev.bglocation.core.license
+
+import android.content.SharedPreferences
+import android.util.Log
+import dev.bglocation.core.BGLLicenseMode
+import dev.bglocation.core.BGLLicenseResult
+import dev.bglocation.core.BGLLocationConfig
+import org.json.JSONObject
+
+/**
+ * Manages license validation, trial timer lifecycle, and cooldown enforcement.
+ */
+class BGLLicenseEnforcer(
+    private val licensePrefs: SharedPreferences,
+    private val licenseValidator: BGLLicenseValidator
+) {
+
+    companion object {
+        private const val TAG = "BGLocation"
+    }
+
+    var licenseMode = BGLLicenseMode.TRIAL
+        private set
+    var trialTimer: BGLTrialTimer? = null
+        private set
+
+    /**
+     * Validate license key and populate configure result.
+     * Returns the updated config (may force debug in trial mode).
+     */
+    fun validateLicense(
+        licenseKey: String?,
+        bundleId: String,
+        config: BGLLocationConfig,
+        configureResult: JSONObject,
+        onTrialExpired: () -> Unit
+    ): BGLLocationConfig {
+        val result = licenseValidator.validate(licenseKey, bundleId, BGLBuildConfig.buildEpoch)
+        var updatedConfig = config
+
+        when (result) {
+            is BGLLicenseResult.Valid -> {
+                licenseMode = BGLLicenseMode.FULL
+                trialTimer?.stop()
+                trialTimer = null
+                configureResult.put("licenseMode", "full")
+                if (result.updatesUntil != null) {
+                    val updatesUntil = java.time.Instant.ofEpochSecond(result.updatesUntil).toString()
+                    configureResult.put("licenseUpdatesUntil", updatesUntil)
+                    Log.d(TAG, "License valid — full mode, updates until $updatesUntil")
+                } else {
+                    Log.d(TAG, "License valid — full mode, no update expiry")
+                }
+            }
+            is BGLLicenseResult.UpdatesExpired -> {
+                licenseMode = BGLLicenseMode.TRIAL
+                updatedConfig = config.copy(debug = true)
+                val updatesUntil = java.time.Instant.ofEpochSecond(result.updatesUntil).toString()
+                configureResult.put("licenseMode", "trial")
+                configureResult.put("licenseUpdateExpired", true)
+                configureResult.put("licenseUpdatesUntil", updatesUntil)
+                configureResult.put("licenseError", "Updates expired. This plugin version requires a license with updates valid until ${java.time.Instant.ofEpochSecond(BGLBuildConfig.buildEpoch)}. Please renew at bglocation.dev/portal")
+
+                if (trialTimer == null) {
+                    trialTimer = BGLTrialTimer(licensePrefs, onTrialExpired)
+                }
+
+                Log.w(TAG, "License updates expired (until $updatesUntil). Running in TRIAL mode.")
+            }
+            is BGLLicenseResult.Invalid -> {
+                licenseMode = BGLLicenseMode.TRIAL
+                updatedConfig = config.copy(debug = true)
+                configureResult.put("licenseMode", "trial")
+                configureResult.put("licenseError", result.reason)
+
+                if (trialTimer == null) {
+                    trialTimer = BGLTrialTimer(licensePrefs, onTrialExpired)
+                }
+
+                Log.w(TAG, "License: ${result.reason}. Running in TRIAL mode (30 min limit, 1h cooldown).")
+            }
+        }
+
+        return updatedConfig
+    }
+
+    /**
+     * Check if trial cooldown is active. Returns a rejection JSObject if cooldown
+     * is active, or null if the operation can proceed.
+     */
+    fun checkCooldown(): BGLCooldownResult? {
+        if (licenseMode != BGLLicenseMode.TRIAL) return null
+        val timer = trialTimer ?: return null
+        if (!timer.isInCooldown()) return null
+
+        val remaining = timer.remainingCooldownSeconds()
+        return BGLCooldownResult(
+            remainingSeconds = remaining,
+            message = "Trial cooldown active. Please wait $remaining seconds or provide a license key."
+        )
+    }
+
+    /**
+     * Start trial timer if in trial mode.
+     */
+    fun startTrialIfNeeded() {
+        if (licenseMode == BGLLicenseMode.TRIAL) {
+            trialTimer?.start()
+        }
+    }
+
+    /**
+     * Stop trial timer if no geofences are active and tracking is stopped.
+     */
+    fun stopTrialIfIdle(hasGeofences: Boolean, isTracking: Boolean) {
+        if (licenseMode == BGLLicenseMode.TRIAL && !hasGeofences && !isTracking) {
+            trialTimer?.stop()
+        }
+    }
+
+    /**
+     * Stop trial timer if no geofences are active (used by stop()).
+     */
+    fun stopTrialIfNoGeofences(hasGeofences: Boolean) {
+        if (!hasGeofences) {
+            trialTimer?.stop()
+        }
+    }
+}
+
+/**
+ * Result of a cooldown check.
+ */
+data class BGLCooldownResult(
+    val remainingSeconds: Int,
+    val message: String
+)

package/android/src/main/kotlin/dev/bglocation/core/license/BGLLicenseValidator.kt

@@ -0,0 +1,134 @@
+package dev.bglocation.core.license
+
+import dev.bglocation.core.BGLLicenseResult
+import android.content.SharedPreferences
+import java.security.KeyFactory
+import java.security.Signature
+import java.security.spec.X509EncodedKeySpec
+import java.util.Base64
+import org.json.JSONObject
+
+/**
+ * Offline RSA-SHA256 license key validator.
+ *
+ * Key format: BGL1-{base64url(payload)}.{base64url(signature)}
+ * Payload: { bid: String, iat: Long, exp?: Long }
+ *
+ * Public key is embedded at compile time — private key never leaves the publisher.
+ */
+class BGLLicenseValidator(private val prefs: SharedPreferences) {
+
+    companion object {
+        private const val KEY_MAX_OBSERVED_TIME = "bgl_max_observed_time"
+        private const val KEY_PREFIX = "BGL1-"
+
+        // RSA-2048 public key (SPKI / X.509 DER, base64-encoded)
+        private const val PUBLIC_KEY_BASE64 =
+            "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAygeAaJHcA3s1DOsu4QWP" +
+            "NBNrK7gu6w+FhHMh5cVmy3YRkUrXblHnRCM1EZdfZb8/jX24rtyrrblF6sUDFDa/" +
+            "G/r1DeQUapmcVlbbJbQQbbRziVYQ3wA3N+/uZSJ08ac5CPw09yuIU2ytFkbnx27T" +
+            "nrRQ5Z8u9hSbW9e5YE9c5pG0yngD0IbW2Kz1ZVEH4TkLdNuhjaPr9wyA5Y3paOW3" +
+            "P0Fz9cpHj1eDVEYRZNlzvFuRMvxo2lVSX/FqNuRi4orlyGfHugLjqHihIymz6rVJ" +
+            "k+5lLyjgX6KLbKusn5OzblyedBwyJ6TcPWf7BBxZik6hWuqcv24reeCUMXO5t8eC" +
+            "+wIDAQAB"
+    }
+
+    /**
+     * Validate a license key against the given bundle ID.
+     *
+     * @param licenseKey  The GT1 license key string, or null/empty for trial.
+     * @param bundleId    The app's package name / bundle identifier.
+     * @param buildEpoch  Unix epoch seconds when the plugin was built. Used for update gating.
+     * @return [BGLLicenseResult.Valid] with optional updatesUntil timestamp, or [BGLLicenseResult.Invalid] with reason.
+     */
+    fun validate(licenseKey: String?, bundleId: String, buildEpoch: Long = 0): BGLLicenseResult {
+        if (licenseKey.isNullOrBlank()) {
+            return BGLLicenseResult.Invalid("No license key provided")
+        }
+
+        if (!licenseKey.startsWith(KEY_PREFIX)) {
+            return BGLLicenseResult.Invalid("Unsupported key format")
+        }
+
+        val body = licenseKey.removePrefix(KEY_PREFIX)
+        val parts = body.split(".")
+        if (parts.size != 2) {
+            return BGLLicenseResult.Invalid("Malformed key structure")
+        }
+
+        val payloadB64 = parts[0]
+        val signatureB64 = parts[1]
+
+        // Decode payload
+        val payloadBytes: ByteArray
+        try {
+            payloadBytes = Base64.getUrlDecoder().decode(payloadB64)
+        } catch (_: IllegalArgumentException) {
+            return BGLLicenseResult.Invalid("Invalid payload encoding")
+        }
+
+        // Decode signature
+        val signatureBytes: ByteArray
+        try {
+            signatureBytes = Base64.getUrlDecoder().decode(signatureB64)
+        } catch (_: IllegalArgumentException) {
+            return BGLLicenseResult.Invalid("Invalid signature encoding")
+        }
+
+        // Verify RSA-SHA256 signature
+        if (!verifySignature(payloadBytes, signatureBytes)) {
+            return BGLLicenseResult.Invalid("Invalid signature")
+        }
+
+        // Parse payload JSON
+        val json: JSONObject
+        try {
+            json = JSONObject(String(payloadBytes, Charsets.UTF_8))
+        } catch (_: Exception) {
+            return BGLLicenseResult.Invalid("Invalid payload JSON")
+        }
+
+        val bid = json.optString("bid", "")
+        // exp is optional — informational only ("updates available until")
+        val exp = if (json.has("exp")) json.optLong("exp", 0).takeIf { it != 0L } else null
+
+        // Check bundle ID
+        if (bid != bundleId) {
+            return BGLLicenseResult.Invalid("Bundle ID mismatch")
+        }
+
+        // Update gating: if exp is set and build epoch is after exp, updates have expired
+        if (exp != null && buildEpoch > 0 && exp < buildEpoch) {
+            return BGLLicenseResult.UpdatesExpired(updatesUntil = exp)
+        }
+
+        return BGLLicenseResult.Valid(updatesUntil = exp)
+    }
+
+    /**
+     * High-water-mark: track the maximum observed time to prevent clock rollback attacks.
+     * Once a time is observed, it never "goes back".
+     */
+    internal fun maxObservedTime(nowSeconds: Long): Long {
+        val stored = prefs.getLong(KEY_MAX_OBSERVED_TIME, 0)
+        val maxTime = maxOf(nowSeconds, stored)
+        if (maxTime != stored) {
+            prefs.edit().putLong(KEY_MAX_OBSERVED_TIME, maxTime).apply()
+        }
+        return maxTime
+    }
+
+    private fun verifySignature(data: ByteArray, signature: ByteArray): Boolean {
+        return try {
+            val keyBytes = Base64.getDecoder().decode(PUBLIC_KEY_BASE64)
+            val keySpec = X509EncodedKeySpec(keyBytes)
+            val publicKey = KeyFactory.getInstance("RSA").generatePublic(keySpec)
+            val sig = Signature.getInstance("SHA256withRSA")
+            sig.initVerify(publicKey)
+            sig.update(data)
+            sig.verify(signature)
+        } catch (_: Exception) {
+            false
+        }
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/license/BGLTrialTimer.kt

@@ -0,0 +1,176 @@
+package dev.bglocation.core.license
+
+import android.content.SharedPreferences
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+
+/**
+ * 30-minute trial timer with 1-hour cooldown.
+ *
+ * After the trial expires, a cooldown is persisted so that restarting the app
+ * does not bypass the restriction. Clock manipulation is mitigated using
+ * [SystemClock.elapsedRealtime] (monotonic) as the primary source and an
+ * anti-rollback guard on wall clock as fallback.
+ */
+class BGLTrialTimer(
+    private val prefs: SharedPreferences,
+    private val onExpired: () -> Unit
+) {
+
+    companion object {
+        const val TRIAL_DURATION_SECONDS = 30 * 60          // 30 min
+        const val COOLDOWN_DURATION_SECONDS = 60 * 60       // 1 hour
+
+        internal const val KEY_COOLDOWN_ENDS = "bgl_trial_cooldown_ends_at"
+        internal const val KEY_COOLDOWN_SET = "bgl_trial_cooldown_set_at"
+        internal const val KEY_COOLDOWN_MONO = "bgl_trial_cooldown_mono_at"
+        internal const val KEY_TRIAL_STARTED_AT = "bgl_trial_started_at"
+    }
+
+    private val handler = Handler(Looper.getMainLooper())
+    private var timerRunnable: Runnable? = null
+
+    var isRunning: Boolean = false
+        private set
+
+    /**
+     * Start the 30-minute trial timer.
+     *
+     * @throws IllegalStateException if cooldown is active.
+     */
+    fun start() {
+        check(!isInCooldown()) {
+            "Trial cooldown active. ${remainingCooldownSeconds()} seconds remaining."
+        }
+
+        isRunning = true
+
+        // Persist trial start time so app restarts can detect an expired trial.
+        prefs.edit().putLong(KEY_TRIAL_STARTED_AT, System.currentTimeMillis() / 1000).apply()
+
+        val runnable = Runnable { expire() }
+        timerRunnable = runnable
+        handler.postDelayed(runnable, TRIAL_DURATION_SECONDS * 1000L)
+    }
+
+    /**
+     * Stop the timer without triggering cooldown (normal stop by user).
+     */
+    fun stop() {
+        timerRunnable?.let { handler.removeCallbacks(it) }
+        timerRunnable = null
+        isRunning = false
+        prefs.edit().remove(KEY_TRIAL_STARTED_AT).apply()
+    }
+
+    /**
+     * Check whether the cooldown period is active.
+     *
+     * Uses monotonic clock (primary) and anti-rollback guard (fallback).
+     *
+     * **Side effect (state repair):** If a previously started trial should have
+     * expired while the app was inactive (killed/restarted), this method detects
+     * the stale [KEY_TRIAL_STARTED_AT] value and transitions the timer into
+     * cooldown. This is intentional — the timer's in-memory state is lost on
+     * process death, so [isInCooldown] reconstructs it from persisted data.
+     */
+    fun isInCooldown(): Boolean {
+        // Check if a previous trial was started but expired while the app was inactive.
+        val trialStartedAt = prefs.getLong(KEY_TRIAL_STARTED_AT, 0)
+        if (trialStartedAt > 0) {
+            val nowSeconds = System.currentTimeMillis() / 1000
+            val elapsed = nowSeconds - trialStartedAt
+            if (elapsed >= TRIAL_DURATION_SECONDS || nowSeconds < trialStartedAt) {
+                // Trial should have expired — persist cooldown and clear trial start
+                prefs.edit().remove(KEY_TRIAL_STARTED_AT).apply()
+                persistCooldown()
+                isRunning = false
+                timerRunnable?.let { handler.removeCallbacks(it) }
+                timerRunnable = null
+                return true
+            }
+        }
+
+        val monoAt = prefs.getLong(KEY_COOLDOWN_MONO, 0)
+        if (monoAt > 0) {
+            val elapsedSinceCooldown = (SystemClock.elapsedRealtime() / 1000) - monoAt
+            if (elapsedSinceCooldown < COOLDOWN_DURATION_SECONDS) {
+                return true
+            }
+        }
+
+        // Anti-rollback guard: if current wall clock is before the time we set cooldown,
+        // someone rolled back the clock → cooldown still active.
+        val setAt = prefs.getLong(KEY_COOLDOWN_SET, 0)
+        val nowSeconds = System.currentTimeMillis() / 1000
+        if (setAt > 0 && nowSeconds < setAt) {
+            return true
+        }
+
+        // Check wall clock expiry as last resort
+        val endsAt = prefs.getLong(KEY_COOLDOWN_ENDS, 0)
+        if (endsAt > 0 && nowSeconds < endsAt) {
+            return true
+        }
+
+        // Cooldown is over — clear persisted values
+        if (monoAt > 0 || setAt > 0 || endsAt > 0) {
+            clearCooldown()
+        }
+
+        return false
+    }
+
+    /**
+     * Remaining cooldown time in seconds (0 if not in cooldown).
+     */
+    fun remainingCooldownSeconds(): Int {
+        // Primary: monotonic clock
+        val monoAt = prefs.getLong(KEY_COOLDOWN_MONO, 0)
+        if (monoAt > 0) {
+            val elapsedSinceCooldown = (SystemClock.elapsedRealtime() / 1000) - monoAt
+            val remaining = COOLDOWN_DURATION_SECONDS - elapsedSinceCooldown
+            if (remaining > 0) {
+                return remaining.toInt()
+            }
+        }
+
+        // Fallback: wall clock
+        val endsAt = prefs.getLong(KEY_COOLDOWN_ENDS, 0)
+        val nowSeconds = System.currentTimeMillis() / 1000
+        val remaining = endsAt - nowSeconds
+        return if (remaining > 0) remaining.toInt() else 0
+    }
+
+    /**
+     * Exposed as `internal` so that same-package tests can trigger expiry
+     * without waiting for the real 30-minute timer.
+     */
+    internal fun expire() {
+        isRunning = false
+        timerRunnable = null
+        prefs.edit().remove(KEY_TRIAL_STARTED_AT).apply()
+        persistCooldown()
+        onExpired()
+    }
+
+    private fun persistCooldown() {
+        val nowSeconds = System.currentTimeMillis() / 1000
+        val monoSeconds = SystemClock.elapsedRealtime() / 1000
+        prefs.edit()
+            .putLong(KEY_COOLDOWN_ENDS, nowSeconds + COOLDOWN_DURATION_SECONDS)
+            .putLong(KEY_COOLDOWN_SET, nowSeconds)
+            .putLong(KEY_COOLDOWN_MONO, monoSeconds)
+            .apply()
+    }
+
+    private fun clearCooldown() {
+        prefs.edit()
+            .remove(KEY_COOLDOWN_ENDS)
+            .remove(KEY_COOLDOWN_SET)
+            .remove(KEY_COOLDOWN_MONO)
+            .remove(KEY_TRIAL_STARTED_AT)
+            .apply()
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/location/BGLAdaptiveFilter.kt

@@ -0,0 +1,94 @@
+package dev.bglocation.core.location
+
+/**
+ * Configuration for the adaptive distance filter.
+ */
+data class BGLAutoDistanceFilterConfig(
+    val targetInterval: Double = DEFAULT_TARGET_INTERVAL,
+    val minDistance: Float = DEFAULT_MIN_DISTANCE,
+    val maxDistance: Float = DEFAULT_MAX_DISTANCE
+) {
+    companion object {
+        const val DEFAULT_TARGET_INTERVAL: Double = 10.0
+        const val DEFAULT_MIN_DISTANCE: Float = 10f
+        const val DEFAULT_MAX_DISTANCE: Float = 500f
+    }
+}
+
+/**
+ * Adaptive distance filter that dynamically adjusts based on speed.
+ *
+ * Uses Exponential Moving Average (EMA) to smooth GPS speed readings
+ * and calculates an effective distance filter so that location updates
+ * arrive at approximately [config.targetInterval] seconds regardless of speed.
+ *
+ * Formula: effectiveDistance = clamp(smoothedSpeed * targetInterval, minDistance, maxDistance)
+ *
+ * The native distance filter is only reconfigured when the change exceeds [RECALC_THRESHOLD]
+ * to avoid expensive LocationRequest restarts on Android.
+ */
+class BGLAdaptiveFilter(
+    private val config: BGLAutoDistanceFilterConfig = BGLAutoDistanceFilterConfig()
+) {
+
+    companion object {
+        /** EMA smoothing factor for acceleration. Lower = smoother but slower to react. */
+        const val EMA_ALPHA_UP: Float = 0.3f
+
+        /** EMA smoothing factor for deceleration. Higher = faster reaction to speed drops. */
+        const val EMA_ALPHA_DOWN: Float = 0.6f
+
+        /** Minimum change in meters to trigger a native distance filter reconfiguration. */
+        const val RECALC_THRESHOLD: Float = 5f
+    }
+
+    private var smoothedSpeed: Float = 0f
+    private var currentDistanceFilter: Float = config.minDistance
+    private var initialized = false
+
+    /**
+     * The current effective distance filter in meters.
+     */
+    val effectiveDistanceFilter: Float
+        get() = currentDistanceFilter
+
+    /**
+     * Update the filter with a new speed reading and determine if the native
+     * distance filter should be reconfigured.
+     *
+     * @param speedMps Current speed in meters per second. Negative values (no GPS speed) are treated as 0.
+     * @return `true` if the native distance filter should be updated (change exceeds threshold),
+     *         `false` if no reconfiguration is needed.
+     */
+    fun update(speedMps: Float): Boolean {
+        val safeSpeed = if (speedMps < 0f || speedMps.isNaN()) 0f else speedMps
+
+        smoothedSpeed = if (!initialized) {
+            initialized = true
+            safeSpeed
+        } else {
+            val alpha = if (safeSpeed < smoothedSpeed) EMA_ALPHA_DOWN else EMA_ALPHA_UP
+            alpha * safeSpeed + (1f - alpha) * smoothedSpeed
+        }
+
+        val rawDistance = (smoothedSpeed * config.targetInterval).toFloat()
+        val clamped = rawDistance.coerceIn(config.minDistance, config.maxDistance)
+
+        val delta = kotlin.math.abs(clamped - currentDistanceFilter)
+        return if (delta >= RECALC_THRESHOLD) {
+            currentDistanceFilter = clamped
+            true
+        } else {
+            false
+        }
+    }
+
+    /**
+     * Reset the filter state. Should be called when tracking stops.
+     */
+    fun reset() {
+        smoothedSpeed = 0f
+        currentDistanceFilter = config.minDistance
+        initialized = false
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/location/BGLHeartbeatTimer.kt

@@ -0,0 +1,38 @@
+package dev.bglocation.core.location
+
+import android.os.Handler
+import android.os.Looper
+
+/**
+ * Repeating timer for heartbeat events using Handler/Looper.
+ * Matches the iOS BGLHeartbeatTimer API for cross-platform symmetry.
+ */
+class BGLHeartbeatTimer(private val handler: Handler = Handler(Looper.getMainLooper())) {
+
+    private var runnable: Runnable? = null
+    var isRunning = false
+        private set
+
+    fun start(intervalSeconds: Int, onTick: () -> Unit) {
+        stop()
+
+        val intervalMs = intervalSeconds * 1000L
+        val tickRunnable = object : Runnable {
+            override fun run() {
+                if (isRunning) {
+                    onTick()
+                    handler.postDelayed(this, intervalMs)
+                }
+            }
+        }
+        runnable = tickRunnable
+        isRunning = true
+        handler.postDelayed(tickRunnable, intervalMs)
+    }
+
+    fun stop() {
+        runnable?.let { handler.removeCallbacks(it) }
+        runnable = null
+        isRunning = false
+    }
+}