@bubblsdk/react-native-sdk 4.1.6 → 5.0.0-alpha.1

package/ios-extension/Sources/BubblCore/API/ApiResponse.swift

@@ -0,0 +1,90 @@
+import Foundation
+
+/// A device API v1 response: its status, body and headers, and — for an error — what the engine
+/// should do about it (`handling`, from the contract's error table).
+package struct ApiResponse: Sendable {
+    package let status: Int
+    package let body: String
+    private let raw: HttpResponse
+    private let forcedHandling: ErrorHandling?
+
+    package init(_ raw: HttpResponse, handledAs forcedHandling: ErrorHandling? = nil) {
+        status = raw.status
+        body = raw.body
+        self.raw = raw
+        self.forcedHandling = forcedHandling
+    }
+
+    package var isSuccessful: Bool { (200...299).contains(status) || status == 304 }
+
+    /// The body as a JSON object, or nil when it isn't one (a 304, or a proxy's error page).
+    package var json: [String: Any]? { JSON.object(body) }
+
+    /// The body decoded as `T`, or nil when it isn't one. Codable reads the same on every
+    /// platform, so parsing goes through here rather than `json`.
+    package func decode<T: Decodable>(_ type: T.Type) -> T? {
+        try? JSONDecoder().decode(type, from: Data(body.utf8))
+    }
+
+    /// The error's stable `code`, when the body has one.
+    package var code: String? {
+        (json?["code"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+    }
+
+    /// What to do about a failed response; nil for a success.
+    package var handling: ErrorHandling? {
+        isSuccessful ? nil : forcedHandling ?? ErrorActions.forResponse(status: status, code: code)
+    }
+
+    /// The same response, handled as `handling` says instead of by its code.
+    package func handled(as handling: ErrorHandling) -> ApiResponse {
+        ApiResponse(raw, handledAs: handling)
+    }
+
+    package func header(_ name: String) -> String? { raw.header(name) }
+}
+
+/// Why a call to the device API didn't get through, reduced to what whoever scheduled it (a
+/// background task, an app resume) has to do next. Built from the contract's error table.
+package enum ApiFailure: Sendable, Equatable {
+    /// Try again later with exponential backoff (5xx, no network).
+    case backoff
+    /// The server asked for a wait (429, request_in_progress).
+    case retryAfter(seconds: Int)
+    /// Stop calling the API for a while (workspace paused, free tier); keep queuing.
+    case pause(hours: Int, code: String?)
+    /// The server doesn't know this device yet: PUT /device, then try again.
+    case describeDevice
+    /// The request can never succeed as sent: discard it (and refetch geofences, if said).
+    case drop(refreshGeofences: Bool, status: Int, code: String?)
+    /// Something only a developer can fix (misconfiguration): surface it in diagnostics.
+    case stopped(status: Int, code: String?)
+
+    private static let defaultRetrySeconds = 30
+    private static let defaultPauseHours = 1
+
+    /// What a failed `response` means for the caller. Never called with a success.
+    package static func of(_ response: ApiResponse) -> ApiFailure {
+        guard let handling = response.handling else { return .stopped(status: response.status, code: response.code) }
+
+        switch handling.action {
+        case .backoff:
+            return .backoff
+        case .waitAndRetry:
+            let seconds = response.header("Retry-After").flatMap { Int($0.trimmingCharacters(in: .whitespaces)) }
+            return .retryAfter(seconds: max(seconds ?? defaultRetrySeconds, 1))
+        case .pause:
+            return .pause(hours: handling.pauseHours ?? defaultPauseHours, code: response.code)
+        case .describeDevice:
+            return .describeDevice
+        case .drop:
+            return .drop(refreshGeofences: false, status: response.status, code: response.code)
+        case .dropAndRefreshGeofences:
+            return .drop(refreshGeofences: true, status: response.status, code: response.code)
+        // The client has already registered again or corrected the clock once; what's left of
+        // those, and everything else, needs a person.
+        case .reRegister, .correctClockAndRetry, .stopAndReport, .showMessage:
+            return .stopped(status: response.status, code: response.code)
+        }
+    }
+}

package/ios-extension/Sources/BubblCore/API/CredentialStore.swift

@@ -0,0 +1,116 @@
+import Foundation
+
+/// The install's credential, read together so a registration in between can't mix old and new.
+package struct SigningCredential: Sendable, Equatable {
+    package let keyId: String
+    package let secret: String
+
+    package init(keyId: String, secret: String) {
+        self.keyId = keyId
+        self.secret = secret
+    }
+}
+
+/// What reading the credential found. `unavailable` is not `missing`: before the first unlock
+/// after a reboot iOS can relaunch the app (for a region event) while the Keychain can't be read
+/// yet. Taking that for "not registered" would register again and replace a working credential.
+package enum CredentialRead: Sendable, Equatable {
+    case present(SigningCredential)
+    case missing
+    case unavailable
+}
+
+/// Where the install's signing credential lives: the Keychain on a device
+/// (AfterFirstUnlockThisDeviceOnly), memory in tests.
+package protocol CredentialStore: Sendable {
+    /// The key id and secret, read together.
+    func read() -> CredentialRead
+
+    /// Keep a new credential, replacing any old one. Throws when it couldn't be kept (the Keychain
+    /// refused it): the registration it came from then doesn't count.
+    func save(keyId: String, secret: String) throws
+
+    /// Forget the credential (deleteMyData, or an earlier installation's). Throws when it couldn't
+    /// be forgotten (the Keychain refused), so nothing claims the device's data is gone when it isn't.
+    func clear() throws
+}
+
+/// A credential kept only while this install's id is. On iOS the Keychain outlives the app and its
+/// files don't: after a reinstall the old install's credential would sign for a new install id.
+/// A credential with no install id beside it (none saved, not merely unreadable) belongs to an
+/// earlier installation, so it's forgotten and this install registers as itself, as on Android,
+/// where uninstalling wipes the Keystore. Checked once per process: from then on a credential is
+/// only saved by a registration, which makes the install id first.
+package final class InstallBoundCredentialStore: CredentialStore, @unchecked Sendable {
+    private let base: any CredentialStore
+    private let installId: any ValueStore<String>
+    private let lock = NSLock()
+    private var checked = false
+
+    package init(_ base: any CredentialStore, installId: any ValueStore<String>) {
+        self.base = base
+        self.installId = installId
+    }
+
+    package func read() -> CredentialRead {
+        lock.sync {
+            let read = base.read()
+            guard !checked, case .present = read else {
+                if read == .missing { checked = true }
+                return read
+            }
+            let id: String?
+            do {
+                id = try installId.load()
+            } catch {
+                return .unavailable
+            }
+            if let id, !id.isEmpty {
+                checked = true
+                return read
+            }
+            do {
+                try base.clear()
+            } catch {
+                // Still there: not this install's, and not gone either. Asked again next time.
+                return .unavailable
+            }
+            checked = true
+            BubblLog.info("A credential left by an earlier installation of the app was forgotten")
+            return .missing
+        }
+    }
+
+    package func save(keyId: String, secret: String) throws {
+        try base.save(keyId: keyId, secret: secret)
+    }
+
+    package func clear() throws {
+        try base.clear()
+    }
+}
+
+/// A CredentialStore in memory: for tests, and for nothing else.
+package final class InMemoryCredentialStore: CredentialStore, @unchecked Sendable {
+    private let lock = NSLock()
+    private var credential: SigningCredential?
+
+    package init() {}
+
+    /// The current key id, for tests.
+    package func keyId() -> String? {
+        lock.sync { credential?.keyId }
+    }
+
+    package func read() -> CredentialRead {
+        lock.sync { credential.map(CredentialRead.present) ?? .missing }
+    }
+
+    package func save(keyId: String, secret: String) throws {
+        lock.sync { credential = SigningCredential(keyId: keyId, secret: secret) }
+    }
+
+    package func clear() throws {
+        lock.sync { credential = nil }
+    }
+}

package/ios-extension/Sources/BubblCore/API/DeviceApiClient.swift

@@ -0,0 +1,239 @@
+import Foundation
+
+/// Why a request wasn't made, other than having no network. Both mean "later": nothing was
+/// refused, and the install keeps its identity.
+package enum DeviceApiError: Error {
+    /// The credential can't be read yet (the device hasn't been unlocked since it started).
+    /// Registering now would replace a working credential, so the request waits instead.
+    case credentialsLocked
+    /// POST /installs succeeded but its credential couldn't be kept, so it doesn't count.
+    case credentialNotSaved(any Error)
+}
+
+/// The engine's client for the device API v1 (contracts/v1/device-api-v1.yaml): registers the
+/// install, signs every other request with its credential, and deals with the errors that have
+/// one right answer, so callers only see the rest:
+///
+///  - no credential yet: POST /installs first;
+///  - timestamp_out_of_range: take the server's clock, retry once;
+///  - invalid_key / invalid_signature / credential_revoked: register again, once, then retry
+///    once (a second failure is returned as it is, so this can never loop).
+///
+/// Every response's Date header keeps the clock in step. Registering is serialised: requests
+/// that find the credential missing or refused wait for one registration rather than each
+/// doing one (found on a device: sync, config and geofences all start at once on first launch).
+package final class DeviceApiClient: Sendable {
+    private let baseUrl: String
+    /// Nil for a device started with a credential issued outside the app: it never registers.
+    private let apiKey: String?
+    private let onCredentialRejected: @Sendable () -> Void
+    private let userAgent: String
+    private let http: any HttpClient
+    private let credentials: any CredentialStore
+    private let clock: ServerClock
+    private let installBody: @Sendable () throws -> [String: Any]
+    private let onRegistered: @Sendable ([String: Any]) -> Void
+    private let registration = AsyncMutex()
+
+    /// - Parameters:
+    ///   - installBody: what POST /installs sends (api_key is added here): the install id the SDK
+    ///     keeps for this installation, and what the device says about itself. It throws when the
+    ///     install id can't be read yet (before the first unlock): nothing is sent then.
+    ///   - onRegistered: told the install response's `data` (device and config) after each
+    ///     successful registration.
+    package init(
+        baseUrl: String,
+        apiKey: String?,
+        sdkVersion: String,
+        http: any HttpClient,
+        credentials: any CredentialStore,
+        clock: ServerClock,
+        installBody: @escaping @Sendable () throws -> [String: Any],
+        onRegistered: @escaping @Sendable ([String: Any]) -> Void = { _ in },
+        onCredentialRejected: @escaping @Sendable () -> Void = {}
+    ) {
+        var trimmed = baseUrl
+        while trimmed.hasSuffix("/") { trimmed.removeLast() }
+        self.baseUrl = trimmed
+        self.apiKey = apiKey
+        userAgent = "Bubbl-iOS-SDK/\(sdkVersion)"
+        self.http = http
+        self.credentials = credentials
+        self.clock = clock
+        self.installBody = installBody
+        self.onRegistered = onRegistered
+        self.onCredentialRejected = onCredentialRejected
+    }
+
+    /// POST /installs: registers (or registers again) and keeps the credential it returns.
+    /// Unsigned; the public API key identifies the company. The response tells the caller why
+    /// when it failed (e.g. own_app_not_in_plan, or a wrong API key).
+    package func register() async throws -> ApiResponse {
+        try await registration.withLock { try await self.registerLocked() }
+    }
+
+    /// A signed request to `path` (from the API root, no leading slash: "api/v1/geofences").
+    /// `query` values are sent as given; `body` is sent and signed byte for byte; `headers` are
+    /// added as they are (e.g. Idempotency-Key, If-None-Match).
+    ///
+    /// Throws when the request couldn't be made at all: no response (offline), or a
+    /// `DeviceApiError` (the credential can't be read yet, or couldn't be kept). Either way it's
+    /// worth trying again later; nothing was refused.
+    package func request(
+        _ method: String,
+        _ path: String,
+        query: [String: String] = [:],
+        body: String? = nil,
+        headers: [String: String] = [:]
+    ) async throws -> ApiResponse {
+        if try credentialKeyId() == nil {
+            // The first to get here registers; the rest wait, find the credential, and use it.
+            let registered = try await registration.withLock { () async throws -> ApiResponse? in
+                try self.credentialKeyId() != nil ? nil : try await self.registerLocked()
+            }
+            if let registered, !registered.isSuccessful { return registered }
+        }
+
+        var sent = try await send(method, path, query: query, body: body, headers: headers)
+
+        if sent.response.handling?.action == .correctClockAndRetry {
+            if let serverTime = JSON.int64(sent.response.json?["server_time"]), serverTime > 0 {
+                clock.sync(serverSeconds: serverTime)
+            }
+            sent = try await send(method, path, query: query, body: body, headers: headers)
+        }
+
+        if sent.response.handling?.action == .reRegister {
+            let refusedKeyId = sent.keyId
+            let registered = try await registration.withLock { () async throws -> ApiResponse? in
+                // Another request may have registered again since this one was signed (it was
+                // refused for the same reason): use that credential rather than replace it.
+                try self.credentialKeyId() != refusedKeyId ? nil : try await self.registerLocked()
+            }
+            if let registered, !registered.isSuccessful { return registered }
+            sent = try await send(method, path, query: query, body: body, headers: headers)
+        }
+
+        return sent.response
+    }
+
+    /// The credential's key id, nil when there's none; throws when it can't be read yet (never
+    /// "none" for a locked Keychain, or a working credential would be replaced).
+    private func credentialKeyId() throws -> String? {
+        switch credentials.read() {
+        case .present(let credential): credential.keyId
+        case .missing: nil
+        case .unavailable: throw DeviceApiError.credentialsLocked
+        }
+    }
+
+    /// A response, and the key id the request was signed with (nil if it couldn't be signed).
+    private struct Sent: Sendable {
+        let response: ApiResponse
+        let keyId: String?
+    }
+
+    /// What a device started with a credential gets where an install would register.
+    static let credentialRejected = #"{"message":"The device's credential was refused: start Bubbl with a new one.","code":"credential_rejected"}"#
+
+    private func registerLocked() async throws -> ApiResponse {
+        // Started with a credential issued outside the app: nothing here can renew it (there's no
+        // API key), so where an install would register, the app is told and has to start Bubbl
+        // with a new one.
+        guard let apiKey else {
+            onCredentialRejected()
+            return ApiResponse(HttpResponse(status: 401, body: Self.credentialRejected)).handled(as: ErrorHandling(.stopAndReport))
+        }
+        var install: [String: Any]
+        do {
+            install = try installBody()
+        } catch {
+            throw DeviceApiError.credentialsLocked
+        }
+        install["api_key"] = apiKey
+        let body = JSON.string(install)
+        let response = try await execute(HttpRequest(method: "POST", url: url("api/v1/installs"), headers: jsonHeaders(body: body), body: body))
+
+        if response.isSuccessful,
+           let data = response.json?["data"] as? [String: Any],
+           let credential = data["credential"] as? [String: Any],
+           let keyId = credential["key_id"] as? String, !keyId.isEmpty,
+           let secret = credential["secret"] as? String, !secret.isEmpty {
+            // Not kept, not registered: the next request registers again rather than carry on
+            // with a credential this install no longer has.
+            do {
+                try credentials.save(keyId: keyId, secret: secret)
+            } catch {
+                throw DeviceApiError.credentialNotSaved(error)
+            }
+            onRegistered(data)
+        }
+
+        // invalid_key here means the public API key itself is wrong: registering again can't fix
+        // that, so it's reported rather than retried.
+        if response.handling?.action == .reRegister {
+            return response.handled(as: ErrorHandling(.stopAndReport))
+        }
+        return response
+    }
+
+    private func send(_ method: String, _ path: String, query: [String: String], body: String?, headers: [String: String]) async throws -> Sent {
+        let credential: SigningCredential
+        switch credentials.read() {
+        case .present(let current):
+            credential = current
+        case .missing:
+            // The credential vanished (cleared mid-request): the server's answer would be
+            // missing_signature, so say that without a round trip.
+            return Sent(response: ApiResponse(HttpResponse(status: 401, body: #"{"message":"Not registered.","code":"missing_signature"}"#)), keyId: nil)
+        case .unavailable:
+            throw DeviceApiError.credentialsLocked
+        }
+
+        let fullUrl = url(path, query: query)
+        let timestamp = clock.nowSeconds()
+        // The server signs the request path it sees, which includes any prefix in the base URL.
+        let signedPath = String((URLComponents(string: fullUrl)?.percentEncodedPath ?? "").drop { $0 == "/" })
+        let signature = RequestSigner.sign(secret: credential.secret, method: method, path: signedPath, timestamp: Int(timestamp), body: body ?? "", query: query)
+
+        var allHeaders = jsonHeaders(body: body)
+        allHeaders.merge(headers) { _, new in new }
+        allHeaders["X-Bubbl-Key-Id"] = credential.keyId
+        allHeaders["X-Bubbl-Timestamp"] = String(timestamp)
+        allHeaders["X-Bubbl-Signature"] = signature
+
+        let response = try await execute(HttpRequest(method: method, url: fullUrl, headers: allHeaders, body: body))
+        return Sent(response: response, keyId: credential.keyId)
+    }
+
+    private func execute(_ request: HttpRequest) async throws -> ApiResponse {
+        let response = try await http.execute(request)
+        clock.sync(dateHeader: response.header("Date"))
+        let result = ApiResponse(response)
+        if let said = Self.wrongEnvironment(result) { BubblLog.error(said) }
+        return result
+    }
+
+    /// What the log says for wrong_environment (a pk_test_ key at the Production address, or the
+    /// other way round): the server's message, and the address the key belongs to (`base_url`).
+    package static func wrongEnvironment(_ response: ApiResponse) -> String? {
+        guard response.code == "wrong_environment" else { return nil }
+        let json = response.json
+        let message = (json?["message"] as? String).flatMap { $0.isEmpty ? nil : $0 } ?? "The API key and the address are for different workspaces."
+        let address = (json?["base_url"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+        return "Bubbl: the API key and baseUrl don't match (wrong_environment). \(message)" + (address.map { " Use baseUrl \($0) with this key." } ?? "")
+    }
+
+    /// The URL for `path`, with `query` in canonical order (the same encoding that's signed).
+    private func url(_ path: String, query: [String: String] = [:]) -> String {
+        let canonical = RequestSigner.canonicalQuery(query)
+        let relative = path.hasPrefix("/") ? String(path.dropFirst()) : path
+        return "\(baseUrl)/\(relative)" + (canonical.isEmpty ? "" : "?\(canonical)")
+    }
+
+    private func jsonHeaders(body: String?) -> [String: String] {
+        var headers = ["Accept": "application/json", "User-Agent": userAgent]
+        if body != nil { headers["Content-Type"] = "application/json" }
+        return headers
+    }
+}

package/ios-extension/Sources/BubblCore/API/ErrorActions.swift

@@ -0,0 +1,68 @@
+/// What the engine does about a failed request. The device API contract's errors fixture
+/// (contracts/v1/fixtures/v1/errors.json) is the source of truth for which code gets which
+/// action, and ErrorActionsContractTests checks this against it. Raw values are the fixture's.
+package enum ErrorAction: String, Sendable, CaseIterable {
+    /// POST /installs again, once and one at a time, then retry.
+    case reRegister = "re_register"
+    /// Take the clock offset from server_time (or the Date header) and retry once.
+    case correctClockAndRetry = "correct_clock_and_retry"
+    /// Stop calling the API for a while (ErrorHandling.pauseHours); keep queuing.
+    case pause
+    /// PUT /device, then retry.
+    case describeDevice = "describe_device"
+    /// Drop the item and fetch geofences again: the location is gone.
+    case dropAndRefreshGeofences = "drop_and_refresh_geofences"
+    /// Discard the request or item (it can never succeed as sent) and log it.
+    case drop
+    /// Wait for Retry-After, then retry.
+    case waitAndRetry = "wait_and_retry"
+    /// Stop and surface it in diagnostics: something is misconfigured.
+    case stopAndReport = "stop_and_report"
+    /// The pairing UI shows the server's message.
+    case showMessage = "show_message"
+    /// 5xx or network failure: exponential backoff with jitter.
+    case backoff
+}
+
+/// An ErrorAction, with how long to pause for `.pause`.
+package struct ErrorHandling: Sendable, Equatable {
+    package let action: ErrorAction
+    package let pauseHours: Int?
+
+    package init(_ action: ErrorAction, pauseHours: Int? = nil) {
+        self.action = action
+        self.pauseHours = pauseHours
+    }
+}
+
+package enum ErrorActions {
+    /// The handling for a response's status and error `code` (nil when the body had none). An
+    /// unknown code falls back on its status, so a newer server can't wedge an older SDK.
+    package static func forResponse(status: Int, code: String?) -> ErrorHandling {
+        switch code {
+        case "missing_signature": ErrorHandling(.stopAndReport)
+        case "timestamp_out_of_range": ErrorHandling(.correctClockAndRetry)
+        case "invalid_key", "invalid_signature", "credential_revoked": ErrorHandling(.reRegister)
+        case "workspace_paused": ErrorHandling(.pause, pauseHours: 6)
+        case "own_app_not_in_plan": ErrorHandling(.pause, pauseHours: 24)
+        // Sandbox: no room for another device awaiting approval; back off as for a paused workspace.
+        case "sandbox_pending_full": ErrorHandling(.pause, pauseHours: 6)
+        // A Sandbox key at the Production address or the other way round: only the app can fix it.
+        case "wrong_environment": ErrorHandling(.stopAndReport)
+        case "showcase_only", "unknown_notification": ErrorHandling(.drop)
+        case "device_not_registered": ErrorHandling(.describeDevice)
+        case "request_in_progress", "too_many_failed_attempts": ErrorHandling(.waitAndRetry)
+        case "unknown_location": ErrorHandling(.dropAndRefreshGeofences)
+        // The message goes back to whoever asked (pairing; Bubbl.registerTestDevice).
+        case "invalid_pairing_code", "invalid_test_device_code", "test_devices_full": ErrorHandling(.showMessage)
+        case "rate_limited": ErrorHandling(.waitAndRetry)
+        default:
+            switch status {
+            case 422: ErrorHandling(.drop)
+            case 429: ErrorHandling(.waitAndRetry)
+            case 500...: ErrorHandling(.backoff)
+            default: ErrorHandling(.stopAndReport)
+            }
+        }
+    }
+}

package/ios-extension/Sources/BubblCore/API/Http.swift

@@ -0,0 +1,39 @@
+/// One HTTP request as the engine sends it: the full URL, and the body's exact text.
+package struct HttpRequest: Sendable, Equatable {
+    package var method: String
+    package var url: String
+    package var headers: [String: String]
+    package var body: String?
+
+    package init(method: String, url: String, headers: [String: String] = [:], body: String? = nil) {
+        self.method = method
+        self.url = url
+        self.headers = headers
+        self.body = body
+    }
+}
+
+/// The response: status, body text and headers (names as the server sent them).
+package struct HttpResponse: Sendable, Equatable {
+    package var status: Int
+    package var body: String
+    package var headers: [String: [String]]
+
+    package init(status: Int, body: String, headers: [String: [String]] = [:]) {
+        self.status = status
+        self.body = body
+        self.headers = headers
+    }
+
+    /// A header's first value, matched without regard to case (HTTP header names aren't).
+    package func header(_ name: String) -> String? {
+        headers.first { $0.key.caseInsensitiveCompare(name) == .orderedSame }?.value.first
+    }
+}
+
+/// Sends one request. The engine's only way out to the network, so tests swap it for a fake
+/// and no HTTP library is forced on the app. Throws when there's no response at all (offline,
+/// timed out); any HTTP status is a response.
+package protocol HttpClient: Sendable {
+    func execute(_ request: HttpRequest) async throws -> HttpResponse
+}

package/ios-extension/Sources/BubblCore/API/ServerClock.swift

@@ -0,0 +1,69 @@
+import Foundation
+
+/// The server's idea of "now", for request timestamps: a signed request is refused when its
+/// timestamp is more than 300 s from the server's clock, and phone clocks drift or are set by
+/// hand. The offset comes from each response's Date header, and from the server_time a
+/// timestamp_out_of_range error carries.
+package final class ServerClock: @unchecked Sendable {
+    /// Offset changes smaller than this are ignored: the Date header has one-second resolution
+    /// and a response takes time to arrive.
+    private static let toleranceSeconds: Int64 = 5
+
+    private let lock = NSLock()
+    private var offset: Int64
+    private let deviceNowSeconds: @Sendable () -> Int64
+    private let onChange: @Sendable (Int64) -> Void
+
+    /// - Parameter onChange: told each new offset, so it can be kept across launches.
+    package init(
+        initialOffsetSeconds: Int64 = 0,
+        deviceNowSeconds: @escaping @Sendable () -> Int64 = { Int64(Date().timeIntervalSince1970) },
+        onChange: @escaping @Sendable (Int64) -> Void = { _ in }
+    ) {
+        offset = initialOffsetSeconds
+        self.deviceNowSeconds = deviceNowSeconds
+        self.onChange = onChange
+    }
+
+    package var offsetSeconds: Int64 {
+        lock.sync { offset }
+    }
+
+    /// Unix seconds as the server would read them now.
+    package func nowSeconds() -> Int64 {
+        deviceNowSeconds() + offsetSeconds
+    }
+
+    /// Adopt the server's time.
+    package func sync(serverSeconds: Int64) {
+        let candidate = serverSeconds - deviceNowSeconds()
+        let changed: Bool = lock.sync {
+            guard abs(candidate - offset) >= Self.toleranceSeconds else { return false }
+            offset = candidate
+            return true
+        }
+        if changed { onChange(candidate) }
+    }
+
+    /// sync(serverSeconds:) from an HTTP Date header (RFC 1123); an absent or unreadable one
+    /// changes nothing.
+    package func sync(dateHeader: String?) {
+        guard let dateHeader, let date = Self.httpDate(dateHeader) else { return }
+        sync(serverSeconds: Int64(date.timeIntervalSince1970))
+    }
+
+    /// Parses "Sun, 06 Nov 1994 08:49:37 GMT". One formatter for every response, used one at a
+    /// time (DateFormatter isn't safe to share across threads everywhere the core runs).
+    package static func httpDate(_ value: String) -> Date? {
+        httpDateLock.sync { httpDateFormatter.date(from: value.trimmingCharacters(in: .whitespaces)) }
+    }
+
+    private static let httpDateLock = NSLock()
+    private static let httpDateFormatter: DateFormatter = {
+        let formatter = DateFormatter()
+        formatter.locale = Locale(identifier: "en_US_POSIX")
+        formatter.timeZone = TimeZone(identifier: "GMT")
+        formatter.dateFormat = "EEE, dd MMM yyyy HH:mm:ss zzz"
+        return formatter
+    }()
+}

package/ios-extension/Sources/BubblCore/BubblVersion.swift

@@ -0,0 +1,5 @@
+/// The SDK's version, sent as X-Bubbl-SDK-Version. Stamped from version.txt by
+/// scripts/sync-version.mjs; don't edit it by hand.
+package enum BubblVersion {
+    package static let sdk = "5.0.0-alpha.1"
+}