@bglocation/capacitor 1.1.0

package/ios/Sources/BGLocationCore/License/BGLLicenseValidator.swift

@@ -0,0 +1,163 @@
+import Foundation
+import Security
+
+/// Result of license key validation.
+public enum LicenseResult: Equatable {
+    case valid(updatesUntil: Int?)
+    case invalid(reason: String)
+    case updatesExpired(updatesUntil: Int)
+}
+
+/// License mode for the plugin.
+public enum LicenseMode {
+    case full
+    case trial
+}
+
+/// Offline RSA-SHA256 license key validator.
+///
+/// Key format: `BGL1-{base64url(payload)}.{base64url(signature)}`
+/// Payload: `{ bid: String, iat: Int, exp?: Int }`
+///
+/// Public key is embedded at compile time — private key never leaves the publisher.
+public class BGLLicenseValidator {
+
+    private static let keyPrefix = "BGL1-"
+    private static let keyMaxObservedTime = "bgl_max_observed_time"
+
+    // RSA-2048 public key (SPKI / X.509 DER, base64-encoded)
+    private static let publicKeyBase64 =
+        "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAygeAaJHcA3s1DOsu4QWP"
+        + "NBNrK7gu6w+FhHMh5cVmy3YRkUrXblHnRCM1EZdfZb8/jX24rtyrrblF6sUDFDa/"
+        + "G/r1DeQUapmcVlbbJbQQbbRziVYQ3wA3N+/uZSJ08ac5CPw09yuIU2ytFkbnx27T"
+        + "nrRQ5Z8u9hSbW9e5YE9c5pG0yngD0IbW2Kz1ZVEH4TkLdNuhjaPr9wyA5Y3paOW3"
+        + "P0Fz9cpHj1eDVEYRZNlzvFuRMvxo2lVSX/FqNuRi4orlyGfHugLjqHihIymz6rVJ"
+        + "k+5lLyjgX6KLbKusn5OzblyedBwyJ6TcPWf7BBxZik6hWuqcv24reeCUMXO5t8eC" + "+wIDAQAB"
+
+    private let defaults: UserDefaults
+
+    public init(defaults: UserDefaults = .standard) {
+        self.defaults = defaults
+    }
+
+    /// Validate a license key against the given bundle ID.
+    ///
+    /// - Parameters:
+    ///   - licenseKey: The GT1 license key string, or nil for trial.
+    ///   - bundleId: The app's bundle identifier.
+    ///   - buildEpoch: Unix epoch seconds when the plugin was built. Used for update gating.
+    /// - Returns: `.valid(updatesUntil:)`, `.updatesExpired(updatesUntil:)`, or `.invalid(reason:)`.
+    public func validate(licenseKey: String?, bundleId: String, buildEpoch: Int = 0)
+        -> LicenseResult
+    {
+        guard let licenseKey = licenseKey, !licenseKey.isEmpty else {
+            return .invalid(reason: "No license key provided")
+        }
+
+        guard licenseKey.hasPrefix(Self.keyPrefix) else {
+            return .invalid(reason: "Unsupported key format")
+        }
+
+        let body = String(licenseKey.dropFirst(Self.keyPrefix.count))
+        let parts = body.split(separator: ".", maxSplits: 1)
+        guard parts.count == 2 else {
+            return .invalid(reason: "Malformed key structure")
+        }
+
+        let payloadB64 = String(parts[0])
+        let signatureB64 = String(parts[1])
+
+        // Decode payload (base64url → Data)
+        guard let payloadData = base64UrlDecode(payloadB64) else {
+            return .invalid(reason: "Invalid payload encoding")
+        }
+
+        // Decode signature (base64url → Data)
+        guard let signatureData = base64UrlDecode(signatureB64) else {
+            return .invalid(reason: "Invalid signature encoding")
+        }
+
+        // Verify RSA-SHA256 signature
+        guard verifySignature(data: payloadData, signature: signatureData) else {
+            return .invalid(reason: "Invalid signature")
+        }
+
+        // Parse payload JSON
+        guard let json = try? JSONSerialization.jsonObject(with: payloadData) as? [String: Any]
+        else {
+            return .invalid(reason: "Invalid payload JSON")
+        }
+
+        guard let bid = json["bid"] as? String else {
+            return .invalid(reason: "Missing bid in payload")
+        }
+
+        // exp is optional — informational only ("updates available until")
+        let exp = json["exp"] as? Int
+
+        // Check bundle ID
+        guard bid == bundleId else {
+            return .invalid(reason: "Bundle ID mismatch")
+        }
+
+        // Update gating: if exp is set and build epoch is after exp, updates have expired
+        if let exp = exp, buildEpoch > 0, exp < buildEpoch {
+            return .updatesExpired(updatesUntil: exp)
+        }
+
+        return .valid(updatesUntil: exp)
+    }
+
+    /// High-water-mark: track the maximum observed time to prevent clock rollback attacks.
+    public func maxObservedTime(now: Int) -> Int {
+        let stored = defaults.integer(forKey: Self.keyMaxObservedTime)
+        let maxTime = max(now, stored)
+        if maxTime != stored {
+            defaults.set(maxTime, forKey: Self.keyMaxObservedTime)
+        }
+        return maxTime
+    }
+
+    // MARK: - Private
+
+    private func base64UrlDecode(_ string: String) -> Data? {
+        var base64 =
+            string
+            .replacingOccurrences(of: "-", with: "+")
+            .replacingOccurrences(of: "_", with: "/")
+
+        // Pad to multiple of 4
+        let remainder = base64.count % 4
+        if remainder > 0 {
+            base64 += String(repeating: "=", count: 4 - remainder)
+        }
+
+        return Data(base64Encoded: base64)
+    }
+
+    private func verifySignature(data: Data, signature: Data) -> Bool {
+        guard let keyData = Data(base64Encoded: Self.publicKeyBase64) else {
+            return false
+        }
+
+        let attributes: [CFString: Any] = [
+            kSecAttrKeyType: kSecAttrKeyTypeRSA,
+            kSecAttrKeyClass: kSecAttrKeyClassPublic,
+            kSecAttrKeySizeInBits: 2048,
+        ]
+
+        guard
+            let publicKey = SecKeyCreateWithData(keyData as CFData, attributes as CFDictionary, nil)
+        else {
+            return false
+        }
+
+        return SecKeyVerifySignature(
+            publicKey,
+            .rsaSignatureMessagePKCS1v15SHA256,
+            data as CFData,
+            signature as CFData,
+            nil
+        )
+    }
+}

package/ios/Sources/BGLocationCore/License/BGLTrialTimer.swift

@@ -0,0 +1,168 @@
+import Foundation
+
+/// 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
+/// an anti-rollback guard on wall clock (iOS has no public monotonic clock API
+/// that survives reboot, so we rely on `now < cooldownSetAt` detection).
+public class BGLTrialTimer {
+
+    public static let trialDurationSeconds = 30 * 60  // 30 min
+    public static let cooldownDurationSeconds = 60 * 60  // 1 hour
+
+    static let keyCooldownEnds = "bgl_trial_cooldown_ends_at"
+    static let keyCooldownSet = "bgl_trial_cooldown_set_at"
+    static let keyCooldownMono = "bgl_trial_cooldown_mono_at"
+    static let keyTrialStartedAt = "bgl_trial_started_at"
+
+    private let defaults: UserDefaults
+    private let onExpired: () -> Void
+    private var timer: DispatchSourceTimer?
+
+    public private(set) var isRunning = false
+
+    /// Monotonic reference (ProcessInfo systemUptime) — does not survive reboot
+    /// but covers clock manipulation while the app is running.
+    private var monoStarted: TimeInterval = 0
+
+    public init(defaults: UserDefaults = .standard, onExpired: @escaping () -> Void) {
+        self.defaults = defaults
+        self.onExpired = onExpired
+    }
+
+    /// Start the 30-minute trial timer.
+    /// - Throws: `NSError` if cooldown is active (caller should check `isInCooldown()` first).
+    public func start() {
+        precondition(
+            !isInCooldown(),
+            "Trial cooldown active. \(remainingCooldownSeconds()) seconds remaining.")
+
+        isRunning = true
+        monoStarted = ProcessInfo.processInfo.systemUptime
+
+        // Persist the trial start time so that app restarts can detect an expired trial.
+        defaults.set(Int(Date().timeIntervalSince1970), forKey: Self.keyTrialStartedAt)
+
+        let source = DispatchSource.makeTimerSource(queue: .main)
+        source.schedule(deadline: .now() + .seconds(Self.trialDurationSeconds))
+        source.setEventHandler { [weak self] in
+            self?.expire()
+        }
+        source.resume()
+        timer = source
+    }
+
+    /// Stop the timer without triggering cooldown (normal stop by user).
+    public func stop() {
+        timer?.cancel()
+        timer = nil
+        isRunning = false
+        defaults.removeObject(forKey: Self.keyTrialStartedAt)
+    }
+
+    /// Check whether the cooldown period is active.
+    ///
+    /// **Side effect (state repair):** If a previously started trial should have
+    /// expired while the app was inactive (killed/restarted), this method detects
+    /// the stale `keyTrialStartedAt` 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.
+    public func isInCooldown() -> Bool {
+        // Check if a previous trial was started but expired while the app was inactive.
+        // If so, trigger the cooldown now.
+        let trialStartedAt = defaults.integer(forKey: Self.keyTrialStartedAt)
+        if trialStartedAt > 0 {
+            let nowSeconds = Int(Date().timeIntervalSince1970)
+            let elapsed = nowSeconds - trialStartedAt
+            if elapsed >= Self.trialDurationSeconds || nowSeconds < trialStartedAt {
+                // Trial should have expired — persist cooldown and clear trial start
+                defaults.removeObject(forKey: Self.keyTrialStartedAt)
+                persistCooldown()
+                isRunning = false
+                timer?.cancel()
+                timer = nil
+                return true
+            }
+        }
+
+        // Check monotonic time if available (within same app session)
+        let monoAt = defaults.double(forKey: Self.keyCooldownMono)
+        if monoAt > 0 {
+            let currentMono = ProcessInfo.processInfo.systemUptime
+            let elapsed = currentMono - monoAt
+            if elapsed < Double(Self.cooldownDurationSeconds) && elapsed >= 0 {
+                return true
+            }
+        }
+
+        let nowSeconds = Int(Date().timeIntervalSince1970)
+
+        // Anti-rollback guard: if current time is before the time we set cooldown,
+        // someone rolled back the clock → cooldown still active.
+        let setAt = defaults.integer(forKey: Self.keyCooldownSet)
+        if setAt > 0 && nowSeconds < setAt {
+            return true
+        }
+
+        // Check wall clock expiry
+        let endsAt = defaults.integer(forKey: Self.keyCooldownEnds)
+        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).
+    public func remainingCooldownSeconds() -> Int {
+        // Try monotonic first
+        let monoAt = defaults.double(forKey: Self.keyCooldownMono)
+        if monoAt > 0 {
+            let currentMono = ProcessInfo.processInfo.systemUptime
+            let elapsed = currentMono - monoAt
+            let remaining = Double(Self.cooldownDurationSeconds) - elapsed
+            if remaining > 0 && elapsed >= 0 {
+                return Int(remaining)
+            }
+        }
+
+        // Fallback: wall clock
+        let endsAt = defaults.integer(forKey: Self.keyCooldownEnds)
+        let nowSeconds = Int(Date().timeIntervalSince1970)
+        let remaining = endsAt - nowSeconds
+        return remaining > 0 ? remaining : 0
+    }
+
+    // MARK: - Internal (visible for testing)
+
+    /// Exposed as `internal` so that `@testable import` tests can trigger expiry
+    /// without waiting for the real 30-minute timer.
+    func expire() {
+        isRunning = false
+        timer = nil
+        defaults.removeObject(forKey: Self.keyTrialStartedAt)
+        persistCooldown()
+        onExpired()
+    }
+
+    private func persistCooldown() {
+        let nowSeconds = Int(Date().timeIntervalSince1970)
+        let monoNow = ProcessInfo.processInfo.systemUptime
+        defaults.set(nowSeconds + Self.cooldownDurationSeconds, forKey: Self.keyCooldownEnds)
+        defaults.set(nowSeconds, forKey: Self.keyCooldownSet)
+        defaults.set(monoNow, forKey: Self.keyCooldownMono)
+    }
+
+    private func clearCooldown() {
+        defaults.removeObject(forKey: Self.keyCooldownEnds)
+        defaults.removeObject(forKey: Self.keyCooldownSet)
+        defaults.removeObject(forKey: Self.keyCooldownMono)
+        defaults.removeObject(forKey: Self.keyTrialStartedAt)
+    }
+}

package/ios/Sources/BGLocationCore/Location/BGLAdaptiveFilter.swift

@@ -0,0 +1,91 @@
+import Foundation
+
+/// Configuration for the adaptive distance filter.
+public struct AutoDistanceFilterConfig {
+    public static let defaultTargetInterval: Double = 10.0
+    public static let defaultMinDistance: Double = 10.0
+    public static let defaultMaxDistance: Double = 500.0
+
+    public let targetInterval: Double
+    public let minDistance: Double
+    public let maxDistance: Double
+
+    public init(
+        targetInterval: Double = Self.defaultTargetInterval,
+        minDistance: Double = Self.defaultMinDistance,
+        maxDistance: Double = Self.defaultMaxDistance
+    ) {
+        self.targetInterval = targetInterval
+        self.minDistance = minDistance
+        self.maxDistance = maxDistance
+    }
+}
+
+/// 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 `recalcThreshold`
+/// to avoid unnecessary reconfiguration overhead.
+public class BGLAdaptiveFilter {
+
+    /// EMA smoothing factor for acceleration. Lower = smoother but slower to react.
+    public static let emaAlphaUp: Double = 0.3
+
+    /// EMA smoothing factor for deceleration. Higher = faster reaction to speed drops.
+    public static let emaAlphaDown: Double = 0.6
+
+    /// Minimum change in meters to trigger a native distance filter reconfiguration.
+    public static let recalcThreshold: Double = 5.0
+
+    private let config: AutoDistanceFilterConfig
+    private var smoothedSpeed: Double = 0.0
+    private var initialized = false
+
+    /// The current effective distance filter in meters.
+    public private(set) var effectiveDistanceFilter: Double
+
+    public init(config: AutoDistanceFilterConfig = AutoDistanceFilterConfig()) {
+        self.config = config
+        self.effectiveDistanceFilter = config.minDistance
+    }
+
+    /// Update the filter with a new speed reading and determine if the native
+    /// distance filter should be reconfigured.
+    ///
+    /// - Parameter speedMps: Current speed in meters per second. Negative values (no GPS speed) are treated as 0.
+    /// - Returns: `true` if the native distance filter should be updated (change exceeds threshold),
+    ///            `false` if no reconfiguration is needed.
+    public func update(speedMps: Double) -> Bool {
+        let safeSpeed = speedMps.isNaN ? 0.0 : max(speedMps, 0.0)
+
+        if !initialized {
+            initialized = true
+            smoothedSpeed = safeSpeed
+        } else {
+            let alpha = safeSpeed < smoothedSpeed ? Self.emaAlphaDown : Self.emaAlphaUp
+            smoothedSpeed = alpha * safeSpeed + (1.0 - alpha) * smoothedSpeed
+        }
+
+        let rawDistance = smoothedSpeed * config.targetInterval
+        let clamped = min(max(rawDistance, config.minDistance), config.maxDistance)
+
+        let delta = abs(clamped - effectiveDistanceFilter)
+        if delta >= Self.recalcThreshold {
+            effectiveDistanceFilter = clamped
+            return true
+        }
+        return false
+    }
+
+    /// Reset the filter state. Should be called when tracking stops.
+    public func reset() {
+        smoothedSpeed = 0.0
+        effectiveDistanceFilter = config.minDistance
+        initialized = false
+    }
+}

package/ios/Sources/BGLocationCore/Location/BGLHeartbeatTimer.swift

@@ -0,0 +1,50 @@
+import Foundation
+
+/// Repeating timer for heartbeat events using DispatchSourceTimer.
+/// Runs on a dedicated `.utility` QoS queue to survive background execution.
+public class BGLHeartbeatTimer {
+
+    private let intervalSeconds: Int
+    private let onTick: () -> Void
+    private var timer: DispatchSourceTimer?
+    private let queue = DispatchQueue(
+        label: "dev.bglocation.heartbeat",
+        qos: .utility
+    )
+    public private(set) var isRunning = false
+
+    public init(intervalSeconds: Int, onTick: @escaping () -> Void) {
+        self.intervalSeconds = intervalSeconds
+        self.onTick = onTick
+    }
+
+    /// Start the repeating timer.
+    public func start() {
+        stop()
+
+        let interval = TimeInterval(intervalSeconds)
+        let source = DispatchSource.makeTimerSource(queue: queue)
+        source.schedule(
+            deadline: .now() + interval,
+            repeating: interval,
+            leeway: .seconds(1)
+        )
+        source.setEventHandler { [weak self] in
+            self?.onTick()
+        }
+        source.resume()
+        timer = source
+        isRunning = true
+    }
+
+    /// Stop and cancel the timer.
+    public func stop() {
+        timer?.cancel()
+        timer = nil
+        isRunning = false
+    }
+
+    deinit {
+        stop()
+    }
+}

package/ios/Sources/BGLocationCore/Location/BGLLocationData.swift

@@ -0,0 +1,48 @@
+import Foundation
+
+/// Typed location data model for iOS.
+///
+/// Replaces untyped `[String: Any]` dictionaries throughout the plugin's
+/// internal layer (buffer, HTTP sender, helpers). Conversion to `[String: Any]`
+/// happens only at the Capacitor bridge boundary (event emission).
+public struct BGLLocationData: Equatable {
+    public let latitude: Double
+    public let longitude: Double
+    public let accuracy: Double
+    public let speed: Double
+    public let heading: Double
+    public let altitude: Double
+    public let timestamp: Double
+    public let isMoving: Bool
+    public let isMock: Bool
+
+    public init(
+        latitude: Double, longitude: Double, accuracy: Double, speed: Double, heading: Double,
+        altitude: Double, timestamp: Double, isMoving: Bool, isMock: Bool
+    ) {
+        self.latitude = latitude
+        self.longitude = longitude
+        self.accuracy = accuracy
+        self.speed = speed
+        self.heading = heading
+        self.altitude = altitude
+        self.timestamp = timestamp
+        self.isMoving = isMoving
+        self.isMock = isMock
+    }
+
+    /// Convert to a dictionary suitable for the Capacitor JS bridge.
+    public func toDict() -> [String: Any] {
+        return [
+            "latitude": latitude,
+            "longitude": longitude,
+            "accuracy": accuracy,
+            "speed": speed,
+            "heading": heading,
+            "altitude": altitude,
+            "timestamp": timestamp,
+            "isMoving": isMoving,
+            "isMock": isMock,
+        ]
+    }
+}

package/ios/Sources/BGLocationCore/Location/BGLLocationHelpers.swift

@@ -0,0 +1,42 @@
+import CoreLocation
+
+/// Pure helper functions extracted for testability.
+/// These functions depend only on CoreLocation — no Capacitor dependency.
+public enum BGLLocationHelpers {
+
+    /// Convert CLLocation to a typed BGLLocationData model.
+    public static func mapLocation(_ location: CLLocation, isMoving: Bool) -> BGLLocationData {
+        return BGLLocationData(
+            latitude: location.coordinate.latitude,
+            longitude: location.coordinate.longitude,
+            accuracy: location.horizontalAccuracy,
+            speed: max(location.speed, 0),
+            heading: location.course >= 0 ? location.course : -1.0,
+            altitude: location.altitude,
+            timestamp: location.timestamp.timeIntervalSince1970 * 1000,
+            isMoving: isMoving,
+            isMock: false  // iOS does not expose mock location detection
+        )
+    }
+
+    /// Convert CLLocation to a dictionary suitable for the JS bridge.
+    /// Convenience wrapper for backward compatibility at the Capacitor boundary.
+    public static func locationToDict(_ location: CLLocation, isMoving: Bool) -> [String: Any] {
+        return mapLocation(location, isMoving: isMoving).toDict()
+    }
+
+    /// Map a string accuracy value to CLLocationAccuracy.
+    public static func mapAccuracy(_ value: String) -> CLLocationAccuracy {
+        switch value {
+        case "high":
+            return kCLLocationAccuracyBest
+        case "balanced":
+            return kCLLocationAccuracyHundredMeters
+        case "low":
+            return kCLLocationAccuracyKilometer
+        default:
+            print("BGLocation: Unknown desiredAccuracy '\(value)', falling back to 'high'")
+            return kCLLocationAccuracyBest
+        }
+    }
+}