@advenue/react-native 0.8.0 → 1.0.0

package/ios/vendor/AdvenueCore/Tcf.swift

@@ -0,0 +1,48 @@
+import Foundation
+
+/// Maps raw IAB TCF v2 CMP data to the DMA `Consent` shape, per Google's EU
+/// User Consent Policy reading of the TCF purposes:
+///
+/// - `ad_storage` ← Purpose 1
+/// - `ad_user_data` ← Purposes 1 **and** 7
+/// - `ad_personalization` ← Purposes 3 **and** 4
+///
+/// Returns nil when `gdprApplies` is neither 0 nor 1. Absent consent must stay
+/// absent: a guessed value is forwarded to ad networks as a real signal, and a
+/// signal invented on a user's behalf is the one thing consent plumbing must
+/// never do.
+public func tcfToConsent(gdprApplies: Int?, purposeConsents: String?) -> Consent? {
+  guard gdprApplies == 0 || gdprApplies == 1 else { return nil }
+  if gdprApplies == 0 { return Consent(isUserSubjectToGDPR: false) }
+
+  let consents = Array(purposeConsents ?? "")
+  func purpose(_ n: Int) -> Bool { n <= consents.count && consents[n - 1] == "1" }
+
+  return Consent(
+    isUserSubjectToGDPR: true,
+    hasConsentForDataUsage: purpose(1) && purpose(7),
+    hasConsentForAdsPersonalization: purpose(3) && purpose(4),
+    hasConsentForAdStorage: purpose(1))
+}
+
+/// Meta AEM `campaign_ids`, extracted from an `al_applink_data` payload.
+///
+/// The input is the ALREADY percent-decoded query value: decoding again would
+/// corrupt a blob containing '%'. Meta does not publicly document the schema, so
+/// both shapes seen in the wild are accepted, top level first.
+///
+/// The blob is opaque, Meta-encrypted, non-user metadata and is returned
+/// verbatim — never trimmed or re-encoded. The 2048 cap is URL hygiene; the
+/// server re-validates, because an SDK-side cap is advisory at a trust boundary.
+public func extractAemCampaignIds(_ alApplinkData: String) -> String? {
+  guard let data = alApplinkData.data(using: .utf8),
+    let parsed = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+  else { return nil }
+
+  let top = parsed["campaign_ids"] as? String
+  let nested = (parsed["extras"] as? [String: Any])?["campaign_ids"] as? String
+  guard let value = (top?.isEmpty == false ? top : nil) ?? (nested?.isEmpty == false ? nested : nil)
+  else { return nil }
+
+  return value.count <= 2048 ? value : nil
+}

package/ios/vendor/AdvenueCore/Transport.swift

@@ -0,0 +1,14 @@
+import Foundation
+
+/// What the core needs from a transport, and no more.
+///
+/// Declared here rather than in the platform layer so `AdvenueCore` keeps its
+/// only-Foundation property while still owning the flush loop. The loop is
+/// behaviour the `flush/` conformance vectors bind, so it cannot live above the
+/// core: a rule the vectors cannot reach is a rule three implementations can
+/// each interpret differently.
+public protocol EventTransport: Sendable {
+  /// Delivers one batch. Throws `IngestError` on a non-2xx response, and on a
+  /// transport failure, which maps to 408.
+  func send(_ events: [ClientEvent]) async throws
+}

package/ios/vendor/AdvenueFirebase/FirebaseAppInstanceId.swift

@@ -0,0 +1,33 @@
+import Foundation
+
+#if canImport(FirebaseAnalytics)
+  import FirebaseAnalytics
+#endif
+
+/// Supplies the Firebase Analytics app instance id.
+///
+/// This lives in its own product for one reason: declaring FirebaseAnalytics
+/// in the base target would force it on every consumer, including those who
+/// never touch Firebase. The RN module gets away with `#if canImport` because
+/// CocoaPods links the host app's pods together; under SPM `canImport` is
+/// false unless the dependency is declared, so a separate product is the only
+/// correct shape. Adjust draws the same base/plugin line.
+public enum AdvenueFirebase {
+  /// Registers the provider with the SDK. Call after `Advenue.initialize`.
+  public static func register() {
+    Advenue.setAppInstanceIdProvider { await appInstanceId() }
+  }
+
+  /// Nil when Firebase is absent — the SDK carries on without the field
+  /// rather than failing, since an app instance id is an enrichment and not a
+  /// requirement for attribution.
+  public static func appInstanceId() async -> String? {
+    #if canImport(FirebaseAnalytics)
+      return await withCheckedContinuation { continuation in
+        Analytics.appInstanceID { id, _ in continuation.resume(returning: id) }
+      }
+    #else
+      return nil
+    #endif
+  }
+}

package/ios/vendor/AdvenuePlatform/AdvertisingIdentity.swift

@@ -0,0 +1,87 @@
+import Foundation
+
+#if canImport(AdSupport)
+  import AdSupport
+#endif
+#if canImport(AppTrackingTransparency)
+  import AppTrackingTransparency
+#endif
+#if canImport(UIKit)
+  import UIKit
+#endif
+
+public enum TrackingAuthorization: String, Sendable {
+  case notDetermined = "not_determined"
+  case restricted
+  case denied
+  case authorized
+}
+
+/// The all-zero IDFA. Apple returns it when tracking is not authorised, and it
+/// is not an identifier — it must never travel as one, or every unauthorised
+/// device looks like the same device.
+public let ZERO_IDFA = "00000000-0000-0000-0000-000000000000"
+
+/// ATT, IDFA and the vendor id.
+///
+/// The SDK never prompts on its own: Apple gives the app control of the
+/// timing, an early call silently answers `notDetermined`, and a prompt the
+/// user did not expect is a review risk that is not the SDK's to take.
+public struct AdvertisingIdentity: Sendable {
+  public init() {}
+
+  public var status: TrackingAuthorization {
+    #if canImport(AppTrackingTransparency)
+      switch ATTrackingManager.trackingAuthorizationStatus {
+      case .authorized: return .authorized
+      case .denied: return .denied
+      case .restricted: return .restricted
+      default: return .notDetermined
+      }
+    #else
+      return .notDetermined
+    #endif
+  }
+
+  /// The IDFA, or nil when it is unavailable or all zeros.
+  public var advertisingId: String? {
+    #if canImport(AdSupport)
+      guard status == .authorized else { return nil }
+      let id = ASIdentifierManager.shared().advertisingIdentifier.uuidString
+      return id == ZERO_IDFA ? nil : id
+    #else
+      return nil
+    #endif
+  }
+
+  /// Available without ATT because it is not an advertising identifier.
+  /// First-party fraud and dedup only — never cross-network attribution, which
+  /// would be "tracking" under Apple's policy.
+  public var vendorId: String? {
+    #if canImport(UIKit)
+      return UIDevice.current.identifierForVendor?.uuidString
+    #else
+      return nil
+    #endif
+  }
+
+  /// True when the user limited tracking. This is the field that separates
+  /// "denied" from "organic" on the server, so a false value here sends a
+  /// consent signal the user never gave.
+  public var limitAdTracking: Bool {
+    status == .denied || status == .restricted
+  }
+
+  /// Presents the system prompt. The app decides when.
+  public func requestAuthorization() async -> TrackingAuthorization {
+    #if canImport(AppTrackingTransparency)
+      return await withCheckedContinuation { continuation in
+        ATTrackingManager.requestTrackingAuthorization { _ in
+          continuation.resume(returning: self.status)
+        }
+      }
+    #else
+      return .notDetermined
+    #endif
+  }
+}

package/ios/vendor/AdvenuePlatform/ChallengeFetcher.swift

@@ -0,0 +1,42 @@
+import Foundation
+
+/// Fetches the one-time App Attest challenge.
+///
+/// Served by the **ingestion** host, not the dashboard API: the SDK already
+/// talks to it and it is the service that will verify the attestation.
+public struct HttpChallengeFetcher: ChallengeSource {
+  private let endpoint: String
+  private let apiKey: String
+  private let session: URLSession
+
+  public init(
+    endpoint: String = DEFAULT_ENDPOINT, apiKey: String, session: URLSession = .shared
+  ) {
+    self.endpoint = endpoint
+    self.apiKey = apiKey
+    self.session = session
+  }
+
+  public func challenge(deviceId: String) async throws -> String {
+    let escaped =
+      deviceId.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? deviceId
+    var request = URLRequest(
+      url: URL(string: "\(endpoint)/v1/attest/challenge?deviceId=\(escaped)")!)
+    request.httpMethod = "GET"
+    request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
+    // Matches the deadline the RN SDK uses. Attestation is enrichment: it never
+    // holds the install.
+    request.timeoutInterval = 5
+
+    let (payload, response) = try await session.data(for: request)
+    guard let http = response as? HTTPURLResponse,
+      (200..<300).contains(http.statusCode)
+    else { throw AttestationError.attestFailed }
+
+    guard let body = try? JSONSerialization.jsonObject(with: payload) as? [String: Any],
+      let challenge = body["challenge"] as? String, !challenge.isEmpty
+    else { throw AttestationError.badChallenge }
+
+    return challenge
+  }
+}

package/ios/vendor/AdvenuePlatform/ConversionFetcher.swift

@@ -0,0 +1,63 @@
+import Foundation
+
+/// Asks the server what this device was attributed to.
+///
+/// A `pending` answer means the pipeline has not decided yet. Most devices are
+/// organic and will answer pending forever, which is why the caller has a
+/// budget rather than a loop.
+public struct HttpConversionFetcher: ConversionFetcher {
+  private let endpoint: String
+  private let apiKey: String
+  private let deviceId: String
+  private let session: URLSession
+
+  public init(
+    endpoint: String = DEFAULT_API_ENDPOINT,
+    apiKey: String,
+    deviceId: String,
+    session: URLSession = .shared
+  ) {
+    self.endpoint = endpoint
+    self.apiKey = apiKey
+    self.deviceId = deviceId
+    self.session = session
+  }
+
+  public func fetch() async throws -> ConversionResult {
+    let escaped =
+      deviceId.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? deviceId
+    var request = URLRequest(url: URL(string: "\(endpoint)/sdk/conversion-data?deviceId=\(escaped)")!)
+    request.httpMethod = "GET"
+    request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
+    request.timeoutInterval = 15
+
+    let payload: Data
+    let response: URLResponse
+    do {
+      (payload, response) = try await session.data(for: request)
+    } catch {
+      // No status to reason about; 408 marks it retryable, as sdk-core does.
+      throw IngestError(status: 408)
+    }
+    guard let http = response as? HTTPURLResponse else { throw IngestError(status: 408) }
+    guard (200..<300).contains(http.statusCode) else {
+      throw IngestError(status: http.statusCode)
+    }
+
+    guard let body = try? JSONSerialization.jsonObject(with: payload) as? [String: Any] else {
+      return .pending
+    }
+    if body["pending"] as? Bool == true { return .pending }
+
+    return .resolved(
+      DeepLink(
+        deepLinkValue: body["deepLinkValue"] as? String,
+        campaign: body["campaign"] as? String,
+        network: body["network"] as? String,
+        influencerId: body["influencerId"] as? String))
+  }
+}
+
+/// The dashboard API, which is where the conversion lookup lives — not the
+/// ingest host.
+public let DEFAULT_API_ENDPOINT = "https://api.advenue.io"

package/ios/vendor/AdvenuePlatform/CryptoKitSigner.swift

@@ -0,0 +1,19 @@
+import CryptoKit
+import Foundation
+
+/// Production HMAC-SHA256. `AdvenueCore` never imports CryptoKit — that is
+/// what lets its conformance vectors build and run on Linux — so the
+/// implementation is injected from here.
+///
+/// This type and the swift-crypto one used by the core's tests are verified
+/// against the SAME signing vectors, which is how their agreement is
+/// established without compiling both into one binary.
+public struct CryptoKitSigner: Signer {
+  public init() {}
+
+  public func hmacSHA256Hex(secret: String, message: String) -> String {
+    let key = SymmetricKey(data: Data(secret.utf8))
+    let mac = HMAC<SHA256>.authenticationCode(for: Data(message.utf8), using: key)
+    return mac.map { String(format: "%02x", $0) }.joined()
+  }
+}

package/ios/vendor/AdvenuePlatform/DeviceCheckAttestation.swift

@@ -0,0 +1,91 @@
+import CryptoKit
+import Foundation
+
+#if canImport(DeviceCheck)
+  import DeviceCheck
+#endif
+
+/// App Attest and DeviceCheck, ported from the React Native module.
+///
+/// **Unavailable in every simulator.** `DCAppAttestService.isSupported` and
+/// `DCDevice.isSupported` are both false there, so the tests here settle that we
+/// degrade rather than crash and that the key cache behaves — not that Apple
+/// produces a verifiable attestation. That is a device claim and it is on the
+/// checklist.
+public struct DeviceCheckAttestation: Attestation {
+  /// The cached key id. Apple charges for `generateKey`, and more importantly a
+  /// key can be attested only once, so the id has to outlive the call.
+  /// The account name the React Native module already uses. Matching it is not
+  /// cosmetic: an app upgrading onto this SDK would otherwise regenerate its
+  /// attest key, and the server has the old key id recorded as attested for
+  /// that device — a fresh one arriving reads as a new device or a
+  /// re-attestation. A key can be attested only once, so the waste is real too.
+  public static let KEY_ID_KEY = "app-attest-key-id"
+
+  private let secure: any SecureStore
+
+  public init(secure: any SecureStore) {
+    self.secure = secure
+  }
+
+  /// The server re-derives this hash from the same challenge, so these bytes
+  /// are a contract rather than an implementation detail.
+  public static func clientDataHash(challenge: String) throws -> Data {
+    guard let bytes = challenge.data(using: .utf8) else {
+      throw AttestationError.badChallenge
+    }
+    return Data(SHA256.hash(data: bytes))
+  }
+
+  public func attest(challenge: String) async throws -> AttestationResult {
+    #if canImport(DeviceCheck)
+      guard #available(iOS 14.0, *) else { throw AttestationError.unsupported }
+      let service = DCAppAttestService.shared
+      guard service.isSupported else { throw AttestationError.unsupported }
+
+      let hash = try Self.clientDataHash(challenge: challenge)
+      let keyId = try await resolveKeyId(service)
+
+      do {
+        let object = try await service.attestKey(keyId, clientDataHash: hash)
+        return AttestationResult(
+          keyId: keyId, attestationObject: object.base64EncodedString())
+      } catch {
+        // A key can be attested only once. When Apple calls a cached id
+        // invalid — it was already attested, or it went bad — that id is
+        // permanently dead. Dropping it makes the NEXT call generate a fresh
+        // key; keeping it makes every later attempt loop on a corpse.
+        if (error as? DCError)?.code == .invalidKey {
+          secure.delete(Self.KEY_ID_KEY)
+        }
+        throw AttestationError.attestFailed
+      }
+    #else
+      throw AttestationError.unsupported
+    #endif
+  }
+
+  public func deviceCheckToken() async throws -> String {
+    #if canImport(DeviceCheck)
+      guard DCDevice.current.isSupported else { throw AttestationError.unsupported }
+      let data = try await DCDevice.current.generateToken()
+      return data.base64EncodedString()
+    #else
+      throw AttestationError.unsupported
+    #endif
+  }
+
+  #if canImport(DeviceCheck)
+    @available(iOS 14.0, *)
+    private func resolveKeyId(_ service: DCAppAttestService) async throws -> String {
+      if case .found(let cached) = secure.read(Self.KEY_ID_KEY) { return cached }
+      do {
+        let generated = try await service.generateKey()
+        secure.write(generated, forKey: Self.KEY_ID_KEY)
+        return generated
+      } catch {
+        throw AttestationError.keyGeneration
+      }
+    }
+  #endif
+}

package/ios/vendor/AdvenuePlatform/DeviceInfo.swift

@@ -0,0 +1,65 @@
+import Foundation
+
+#if canImport(UIKit)
+  import UIKit
+#endif
+
+/// Device metadata for Meta CAPI `extinfo`.
+///
+/// Best-effort per field: a field is **omitted**, never defaulted, when its
+/// source is unavailable. A placeholder zero reaching the warehouse is
+/// indistinguishable from a real measurement, which is worse than a gap — the
+/// Android collector follows the same rule.
+public func collectDeviceInfo() -> [String: AdvenueValue] {
+  var info: [String: AdvenueValue] = [:]
+
+  info["model"] = .string(hardwareModel())
+  info["locale"] = .string(Locale.current.identifier)
+  info["timezone"] = .string(TimeZone.current.identifier)
+  info["cpuCores"] = .int(ProcessInfo.processInfo.processorCount)
+
+  if let bundleId = Bundle.main.bundleIdentifier {
+    info["packageName"] = .string(bundleId)
+  }
+  if let short = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String {
+    info["shortVersion"] = .string(short)
+  }
+  if let build = Bundle.main.infoDictionary?["CFBundleVersion"] as? String {
+    info["longVersion"] = .string(build)
+  }
+
+  #if canImport(UIKit)
+    let screen = UIScreen.main.bounds
+    info["screenWidth"] = .int(Int(screen.width))
+    info["screenHeight"] = .int(Int(screen.height))
+    info["screenDensity"] = .double(Double(UIScreen.main.scale))
+  #endif
+
+  if let attributes = try? FileManager.default.attributesOfFileSystem(
+    forPath: NSHomeDirectory())
+  {
+    let gigabyte = 1024.0 * 1024.0 * 1024.0
+    if let total = attributes[.systemSize] as? NSNumber {
+      info["totalStorageGb"] = .double(total.doubleValue / gigabyte)
+    }
+    if let free = attributes[.systemFreeSize] as? NSNumber {
+      info["freeStorageGb"] = .double(free.doubleValue / gigabyte)
+    }
+  }
+
+  return info
+}
+
+/// The hardware identifier (`iPhone16,2`), which is what Meta's extinfo wants —
+/// `UIDevice.model` answers "iPhone" for every iPhone ever made and is useless
+/// for segmentation.
+private func hardwareModel() -> String {
+  var systemInfo = utsname()
+  uname(&systemInfo)
+  let mirror = Mirror(reflecting: systemInfo.machine)
+  let identifier = mirror.children.reduce(into: "") { partial, element in
+    guard let value = element.value as? Int8, value != 0 else { return }
+    partial.append(Character(UnicodeScalar(UInt8(value))))
+  }
+  return identifier.isEmpty ? "unknown" : identifier
+}

package/ios/vendor/AdvenuePlatform/ForegroundTracker.swift

@@ -0,0 +1,55 @@
+/// What UIKit told us about the app.
+public enum LifecycleSignal: Sendable {
+  case didBecomeActive
+  /// Transient. Control Center, an incoming call, the app switcher preview —
+  /// none of which is a backgrounding, and all of which are followed by
+  /// `didBecomeActive` again.
+  case willResignActive
+  case didEnterBackground
+}
+
+public enum ForegroundTransition: Sendable, Equatable {
+  case none
+  case enteredForeground
+  case enteredBackground
+}
+
+/// The foreground/background decision, as a pure state machine — no UIKit type
+/// appears in this file, which is what makes it provable without a device.
+///
+/// It is deliberately simpler than the Android tracker, and the difference is
+/// the platform rather than an omission. Android has to survive a rotation
+/// recreating the activity, which walks a started-activity counter 1 → 0 → 1
+/// and needs both a configuration-change check and a 700 ms debounce to avoid
+/// emitting a phantom `session_end`. iOS recreates nothing, and
+/// `didEnterBackground` is unambiguous, so pairing it against `didBecomeActive`
+/// is the whole rule.
+///
+/// What DOES bite on iOS is the transient interruption, and that is what
+/// `willResignActive` is here to be ignored for. Reading it as a backgrounding
+/// ends a session every time a notification banner appears.
+public struct ForegroundTracker: Sendable {
+  private var inForeground: Bool
+
+  /// - Parameter inForeground: seed for an SDK that already opened its own
+  ///   session at `initialize`, so the activation that follows does not open a
+  ///   second one.
+  public init(inForeground: Bool = false) {
+    self.inForeground = inForeground
+  }
+
+  public mutating func on(_ signal: LifecycleSignal) -> ForegroundTransition {
+    switch signal {
+    case .willResignActive:
+      return .none
+    case .didBecomeActive:
+      if inForeground { return .none }
+      inForeground = true
+      return .enteredForeground
+    case .didEnterBackground:
+      if !inForeground { return .none }
+      inForeground = false
+      return .enteredBackground
+    }
+  }
+}

package/ios/vendor/AdvenuePlatform/HttpTransport.swift

@@ -0,0 +1,96 @@
+import Foundation
+
+/// What the SDK POSTs. `apiKey` travels in the body, matching
+/// `eventBatchSchema`.
+struct EventBatch: Encodable {
+  let apiKey: String
+  let events: [ClientEvent]
+}
+
+public let DEFAULT_ENDPOINT = "https://ingest.advenue.io"
+/// The schema caps a batch at 100 events.
+
+/// Batched ingest over URLSession.
+///
+/// Throws `IngestError` on a non-2xx so the caller can distinguish a transient
+/// failure from a poison payload; a transport failure maps to 408, matching
+/// sdk-core so both SDKs retry exactly the same cases.
+public struct HttpTransport: EventTransport, Sendable {
+  private let endpoint: String
+  private let apiKey: String
+  private let signingSecret: String?
+  private let signer: any Signer
+  private let clock: any Clock
+  private let session: URLSession
+  /// Receives the app the server reported for an ACCEPTED batch. Purely
+  /// diagnostic: it runs after the batch is already accepted, so nothing it
+  /// does can turn a successful ingest into a failure.
+  private let onAccepted: @Sendable (String) -> Void
+
+  public init(
+    endpoint: String = DEFAULT_ENDPOINT,
+    apiKey: String,
+    signingSecret: String? = nil,
+    signer: any Signer = CryptoKitSigner(),
+    clock: any Clock = SystemClock(),
+    session: URLSession = .shared,
+    onAccepted: @escaping @Sendable (String) -> Void = { _ in }
+  ) {
+    self.onAccepted = onAccepted
+    self.endpoint = endpoint
+    self.apiKey = apiKey
+    self.signingSecret = signingSecret
+    self.signer = signer
+    self.clock = clock
+    self.session = session
+  }
+
+  /// The exact request this transport would send. Public so a test can assert
+  /// the wire shape — endpoint, headers, body, signature — without a network
+  /// round trip, which is the part that has to be right.
+  public func buildRequest(_ events: [ClientEvent]) throws -> URLRequest {
+    let body = try EventEncoding.canonicalEncoder()
+      .encode(EventBatch(apiKey: apiKey, events: events))
+    var request = URLRequest(url: URL(string: "\(endpoint)/v1/events")!)
+    request.httpMethod = "POST"
+    request.setValue("application/json", forHTTPHeaderField: "content-type")
+    request.httpBody = body
+    request.timeoutInterval = 15
+
+    if let secret = signingSecret {
+      let timestamp = String(clock.nowMs())
+      request.setValue(timestamp, forHTTPHeaderField: "X-Advenue-Timestamp")
+      request.setValue(
+        signRequest(
+          signer, secret: secret, timestamp: timestamp,
+          body: String(decoding: body, as: UTF8.self)),
+        forHTTPHeaderField: "X-Advenue-Signature")
+    }
+    return request
+  }
+
+  public func send(_ events: [ClientEvent]) async throws {
+    let request = try buildRequest(events)
+    let response: URLResponse
+    let payload: Data
+    do {
+      (payload, response) = try await session.data(for: request)
+    } catch {
+      // No status to reason about. 408 marks it retryable, which is what
+      // sdk-core does for the same case.
+      throw IngestError(status: 408)
+    }
+    guard let http = response as? HTTPURLResponse else { throw IngestError(status: 408) }
+    guard (200..<300).contains(http.statusCode) else {
+      throw IngestError(status: http.statusCode)
+    }
+
+    // Diagnostics only — the batch is already accepted at this point, so a
+    // missing or unparseable body must change nothing.
+    if let body = try? JSONSerialization.jsonObject(with: payload) as? [String: Any],
+      let appId = body["appId"] as? String, !appId.isEmpty
+    {
+      onAccepted(appId)
+    }
+  }
+}

package/ios/vendor/AdvenuePlatform/Identity.swift

@@ -0,0 +1,52 @@
+import Foundation
+
+/// Survives uninstall — Keychain.
+public let DEVICE_ID_KEY = "advenue.device_id"
+/// Dies with the app — UserDefaults.
+public let INSTALLATION_ID_KEY = "advenue.installation_id"
+
+public enum IdentityResolution: Equatable, Sendable {
+  case resolved(deviceId: String, installationId: String)
+  /// The Keychain could not be read. The caller waits for
+  /// `protectedDataDidBecomeAvailable` rather than inventing an identity.
+  case deferred
+}
+
+/// Resolves the pair the SDK stamps on every event.
+///
+/// The asymmetry is the design: `device_id` lives in the Keychain and survives
+/// uninstall, `installation_id` lives in UserDefaults and does not. Reinstall
+/// detection rests entirely on that difference, so neither half may quietly
+/// move to the other store.
+///
+/// A locked Keychain returns `.deferred` and mints nothing. Treating it as
+/// absent is what would stamp a whole background launch with a device id
+/// belonging to no real device — reachable since #26 introduced silent push,
+/// which can start the app before the first unlock after a reboot.
+public func resolveIdentity(
+  secure: any SecureStore,
+  store: any KeyValueStore,
+  uuid: any UUIDSource
+) -> IdentityResolution {
+  let deviceId: String
+  switch secure.read(DEVICE_ID_KEY) {
+  case .found(let existing):
+    deviceId = existing
+  case .unavailable:
+    return .deferred
+  case .absent:
+    let minted = uuid.next()
+    secure.write(minted, forKey: DEVICE_ID_KEY)
+    deviceId = minted
+  }
+
+  let installationId: String
+  if let existing = store.string(forKey: INSTALLATION_ID_KEY) {
+    installationId = existing
+  } else {
+    installationId = uuid.next()
+    store.set(installationId, forKey: INSTALLATION_ID_KEY)
+  }
+
+  return .resolved(deviceId: deviceId, installationId: installationId)
+}