crossmate

PushClient.swift (27394B)

---

 import CryptoKit
 import Foundation
 
 /// Uploads this device's APNs token to the Crossmate push worker and keeps
 /// the registration in sync with the current iCloud authorID. The worker
 /// itself is idempotent — re-posting an unchanged triple is a no-op — so the
 /// only client-side state is a small dedup cache to avoid redundant network
 /// chatter on every cold launch.
 @MainActor
 final class PushClient {
     enum Environment: String {
         case sandbox
         case production
     }
 
     private let baseURL: URL
     private let deviceID: String
     private let environment: Environment
     private let session: URLSession
     private let log: (String) -> Void
     private let authenticator: PushRequestAuthenticator
 
     private var apnsToken: String?
     private var authorID: String?
     /// The addresses this device should be reachable at, each bound to its
     /// game's shared push credential. One per shared game the account
     /// participates in, plus the account-scoped sibling address (nil
     /// credential). The worker keys game addresses under their `credID`.
     private var bindings: Set<PushAddressBinding> = []
     /// Push kinds this device has muted in notification settings. Registered
     /// with the worker as a denylist so muted pushes are dropped before APNs.
     private var mutedKinds: Set<String> = []
     private var lastRegistered: Registration?
 
     /// Resolves (minting if needed) the shared push credential for a game.
     /// Set by AppServices to read from the GameStore. Publishes use it to sign
     /// the request the worker verifies against the credential it holds.
     var gameCredentialResolver: (@MainActor (UUID) -> GamePushCredentials?)?
 
     /// Resolves (minting if needed) the per-game content key used to encrypt the
     /// structured payload. Set by AppServices to read from the GameStore. When
     /// nil (or unresolved), a publish ships its generic cleartext body with no
     /// encrypted payload — degraded but never leaking personal text.
     var contentKeyResolver: (@MainActor (UUID) -> SymmetricKey?)?
 
     /// The cleartext alert body the worker forwards to APNs in place of the real
     /// notification text. The personal wording is encrypted into the payload and
     /// recomposed on the device by the notification service extension; this is
     /// all the worker (and a recipient whose NSE can't decrypt) ever sees.
     static let genericAlertBody = "New activity in one of your puzzles"
 
     /// Game credentials already registered with the worker this session
     /// (credID → secret), so `/games/:credID/register` is posted at most once
     /// per credential value.
     private var registeredGameCredentials: [UUID: String] = [:]
 
     /// The `(token, bindings, mutedKinds)` triple last successfully reconciled
     /// with the worker. All must match for a reconcile to be a no-op, so a
     /// token rotation re-binds every address, a binding change (including a
     /// credID rotation) registers the delta, and a notification-preference
     /// change re-registers every address with the new denylist.
     private struct Registration: Equatable {
         let token: String
         let bindings: Set<PushAddressBinding>
         let mutedKinds: Set<String>
     }
 
     /// `nil` when the worker isn't configured (e.g. a fresh checkout without a
     /// `Local.xcconfig`) or when the bundle's APNs environment is missing or
     /// unrecognised. The rest of the app treats a nil PushClient as "push
     /// notifications are disabled" rather than crashing.
     /// Dedicated session for worker traffic. `waitsForConnectivity` lets a send
     /// issued right at app-foreground — before the radio/path is back up — wait
     /// for connectivity instead of failing immediately (a common source of the
     /// `-1005`/`-1009` registration failures), bounded by the resource timeout.
     /// It governs connection establishment, not a mid-transfer drop, so it pairs
     /// with the transport retry in `sendAuthorized` rather than replacing it.
     /// A dedicated session also keeps the worker's connection pool off `.shared`,
     /// so unrelated traffic doesn't churn the pooled connections it reuses.
     static func makeWorkerSession() -> URLSession {
         let config = URLSessionConfiguration.default
         config.waitsForConnectivity = true
         config.timeoutIntervalForRequest = 30
         config.timeoutIntervalForResource = 60
         return URLSession(configuration: config)
     }
 
     init?(
         deviceID: String = RecordSerializer.localDeviceID,
         session: URLSession = PushClient.makeWorkerSession(),
         log: @escaping (String) -> Void = { _ in }
     ) {
         guard
             let rawBase = Bundle.main.object(forInfoDictionaryKey: "CrossmatePushBaseURL") as? String,
             case let trimmedBase = rawBase.trimmingCharacters(in: .whitespacesAndNewlines),
             !trimmedBase.isEmpty,
             let base = URL(string: trimmedBase)
         else { return nil }
         self.baseURL = base
         self.deviceID = deviceID
         self.session = session
         self.log = log
         self.authenticator = PushRequestAuthenticator(
             baseURL: base,
             deviceID: deviceID,
             session: session
         )
         // CrossmateAPSEnvironment carries the same APS_ENVIRONMENT build
         // setting that fills the aps-environment entitlement, so the
         // environment registered with the worker always matches the
         // environment the APNs token was issued for.
         switch Bundle.main.object(forInfoDictionaryKey: "CrossmateAPSEnvironment") as? String {
         case "development":
             self.environment = .sandbox
         case "production":
             self.environment = .production
         case let other:
             log("Push disabled: unrecognised APNs environment \(other ?? "<missing>")")
             return nil
         }
     }
 
     func updateAPNsToken(_ data: Data) {
         let hex = data.map { String(format: "%02x", $0) }.joined()
         if hex == apnsToken { return }
         apnsToken = hex
         Task { await reconcile() }
     }
 
     /// Records the current account identity. Used only as the `fromAuthorID`
     /// display field on outgoing pushes — the worker no longer keys anything
     /// on identity, so an account switch is reflected purely through the
     /// address set changing (see `setAddresses`).
     func updateAuthorID(_ newAuthorID: String?) {
         let normalized = newAuthorID?.trimmingCharacters(in: .whitespaces)
         authorID = (normalized?.isEmpty == false) ? normalized : nil
     }
 
     /// Sets the full set of address→credential bindings this device should be
     /// registered under. The caller (AccountPushCoordinator) recomputes this
     /// from Core Data on launch, when a shared game appears, and on account
     /// switch. Bindings that drop out are unregistered so a left/old-account
     /// game stops delivering here.
     func setAddresses(_ next: Set<PushAddressBinding>) {
         if next == bindings { return }
         bindings = next
         Task { await reconcile() }
     }
 
     /// Sets the push kinds this device's notification settings have muted.
     /// The caller (AccountPushCoordinator) mirrors this from preferences on
     /// launch and on every settings change.
     func setMutedKinds(_ next: Set<String>) {
         if next == mutedKinds { return }
         mutedKinds = next
         Task { await reconcile() }
     }
 
     private func reconcile() async {
         guard let apnsToken else { return }
         let desired = bindings
         let signature = Registration(
             token: apnsToken,
             bindings: desired,
             mutedKinds: mutedKinds
         )
         if lastRegistered == signature { return }
         let toRemove = (lastRegistered?.bindings ?? []).subtracting(desired)
         do {
             // Register each game's shared credential first, so the worker
             // accepts the addresses bound to it.
             for creds in Set(desired.compactMap(\.credentials)) {
                 await registerGameCredential(creds)
             }
             if !desired.isEmpty {
                 try await register(
                     token: apnsToken,
                     bindings: Array(desired),
                     mutedKinds: signature.mutedKinds.sorted()
                 )
             }
             if !toRemove.isEmpty {
                 await unregister(bindings: Array(toRemove))
             }
             lastRegistered = signature
         } catch {
             // Worker is idempotent; the next token delivery or address change
             // will retry. Bubble the failure into diagnostics rather than
             // surfacing a user-facing error.
             log("Push register failed: \(error.localizedDescription)")
         }
     }
 
     /// One push addressee, identified by the recipient's per-(account, game)
     /// `pushAddress` capability rather than an identity. `body`, if set,
     /// overrides the top-level broadcast `body` for this recipient only — the
     /// receiver-side notification text can then be personalised (e.g. the
     /// pause-summary counts that depend on when that specific peer last read
     /// the puzzle).
     struct Addressee: Sendable, Equatable {
         let address: String
         let body: String?
         /// Structured semantics for this recipient, encoded into the wire
         /// `payload` field. The worker forwards it opaquely; the notification
         /// service extension decodes it (e.g. to decide the badge).
         let payload: PushPayload?
 
         init(address: String, body: String? = nil, payload: PushPayload? = nil) {
             self.address = address
             self.body = body
             self.payload = payload
         }
     }
 
     /// Fire-and-forget publish. The worker maps each addressee's `address` to
     /// that account's registered device tokens and fans the push out to all
     /// of them. Failures are logged but never surfaced — pushes are advisory
     /// and the next event will retry the underlying state on its own.
     /// When `broadcast` is true the worker fans the push out to every device
     /// registered under the game's credential — the whole room — instead of an
     /// explicit `addressees` list, so the sender needn't know who the
     /// participants are (their Player records may not have synced yet). The
     /// uniform `broadcastPayload` and `body` are delivered to all of them, and
     /// `excludeAddress` (the sender's own derived game address) keeps the
     /// sender's other devices from being notified. Broadcast is only meaningful
     /// for a game-credentialed push.
     /// Stable `apns-collapse-id` for a game's notification tile. All alert
     /// pushes for one game share it, so APNs keeps a single replacing tile in
     /// Notification Center (the receiver's NSE then folds successive `pause`
     /// summaries into it). 41 chars — well under APNs' 64-byte limit.
     static func gameCollapseID(_ gameID: UUID) -> String {
         "game-\(gameID.uuidString)"
     }
 
     func publish(
         kind: String,
         gameID: UUID,
         addressees: [Addressee],
         title: String,
         puzzleTitle: String? = nil,
         background: Bool = false,
         gameCredentialed: Bool = true,
         broadcast: Bool = false,
         excludeAddress: String? = nil,
         broadcastPayload: PushPayload? = nil,
         collapseID: String? = nil,
         extra: [String: Any] = [:],
         body: String
     ) async {
         guard broadcast || !addressees.isEmpty else { return }
         // A game push must prove participation: resolve (minting if needed) the
         // game's shared credential, register it with the worker, and sign the
         // request below. Account-scoped publishes (sibling-device hints) carry
         // no game and stay on the App-Attest-only path.
         var credential: GamePushCredentials?
         if gameCredentialed {
             guard let creds = gameCredentialResolver?(gameID) else {
                 log("push(\(kind)): skipped (no game credential)")
                 return
             }
             await registerGameCredential(creds)
             credential = creds
         }
         log(broadcast
             ? "push(\(kind)): broadcasting to room"
             : "push(\(kind)): publishing to \(addressees.count) addressee(s)")
         // Stamp the puzzle title onto each addressee's structured payload so the
         // receiver's extension can recompose the body from components (swapping
         // in its private nickname) rather than editing the sender's text.
         // Injected here so the call sites pass it once, not per addressee.
         // Resolve (and mint) the game's content key only when there is a payload
         // to seal, so account-scoped pushes that carry none don't mint one.
         let needsContentKey = broadcastPayload != nil || addressees.contains { $0.payload != nil }
         let contentKey = needsContentKey ? contentKeyResolver?(gameID) : nil
         // Encrypt each addressee's structured payload under the content key and
         // ship it as `enc`. The per-recipient cleartext `body` (personalised
         // pause counts) is deliberately *not* sent: those counts live in the
         // sealed payload's event, and the receiver's NSE recomposes the body —
         // so the worker never sees the wording. An addressee whose payload can't
         // be sealed (no key resolved) still gets the push, with the generic body.
         let addresseePayloads: [[String: Any]] = addressees.map { addressee in
             var entry: [String: Any] = ["address": addressee.address]
             if var payload = addressee.payload {
                 if let puzzleTitle { payload.puzzleTitle = puzzleTitle }
                 if let contentKey, let sealed = PushPayloadCipher.seal(payload, key: contentKey) {
                     entry["enc"] = sealed
                 }
             }
             return entry
         }
         var payload: [String: Any] = [
             "kind": kind,
             "gameID": gameID.uuidString,
             "fromAuthorID": authorID ?? "",
             "senderDeviceID": deviceID,
             "title": title,
             // Generic wording only; the real body is sealed into the payload and
             // recomposed on-device. A bodyless (background) push stays bodyless.
             "alertBody": body.isEmpty ? "" : Self.genericAlertBody,
             "addressees": addresseePayloads,
             "background": background
         ]
         // The credID names which registered credential the worker verifies the
         // game signature against and scopes delivery to. Covered by the body
         // hash (App Attest), so it can't be swapped without breaking auth.
         if let credential {
             payload["credID"] = credential.credID.uuidString
         }
         // Forwarded verbatim into the APNs `apns-collapse-id` header by the
         // worker (alert pushes only). Opaque to the worker — the coalescing
         // policy it encodes lives here, not in the worker.
         if let collapseID {
             payload["collapseID"] = collapseID
         }
         // Broadcast: the worker resolves targets from the credential's whole
         // address set, so the empty `addressees` above is ignored. Carry the
         // uniform payload at top level (the per-addressee slot is unused) and
         // name the sender's own address so its other devices are skipped.
         if broadcast {
             payload["broadcast"] = true
             if let excludeAddress { payload["excludeAddress"] = excludeAddress }
             if var broadcastPayload {
                 if let puzzleTitle { broadcastPayload.puzzleTitle = puzzleTitle }
                 if let contentKey, let sealed = PushPayloadCipher.seal(broadcastPayload, key: contentKey) {
                     payload["enc"] = sealed
                 }
             }
         }
         for (key, value) in extra {
             payload[key] = value
         }
         var request = URLRequest(url: baseURL.appendingPathComponent("publish"))
         request.httpMethod = "POST"
         do {
             let body = try JSONSerialization.data(withJSONObject: payload)
             request.httpBody = body
             let (data, response) = try await sendAuthorized(
                 request,
                 method: "POST",
                 path: "/publish",
                 body: body,
                 gameCredential: credential
             )
             guard response.statusCode == 200 else {
                 throw URLError(.badServerResponse)
             }
             log("push(\(kind)): worker accepted\(Self.deliverySummary(from: data))")
         } catch {
             log("push(\(kind)) failed: \(error.localizedDescription)")
         }
     }
 
     func publishAccountEvent(
         kind: String,
         gameID: UUID,
         address: String,
         readAt: Date? = nil
     ) async {
         var extra: [String: Any] = [:]
         if let readAt {
             extra["readAt"] = Self.iso8601.string(from: readAt)
         }
         await publish(
             kind: kind,
             gameID: gameID,
             addressees: [Addressee(address: address)],
             title: "",
             background: true,
             gameCredentialed: false,
             extra: extra,
             body: ""
         )
     }
 
     /// Formats the worker's publish response counts for the diagnostics log,
     /// e.g. " (delivered=2 muted=1 removed=0 failed=0)". Production delivery
     /// is only observable through the on-device log, so this is where "why
     /// didn't that push arrive?" gets answered — `muted` in particular means
     /// a recipient device turned that notification kind off in settings.
     /// Returns "" for an unparseable body (e.g. a worker predating a count).
     nonisolated static func deliverySummary(from data: Data) -> String {
         guard let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
             return ""
         }
         let counts = ["delivered", "muted", "removed", "failed"].compactMap { key in
             (json[key] as? Int).map { "\(key)=\($0)" }
         }
         return counts.isEmpty ? "" : " (\(counts.joined(separator: " ")))"
     }
 
     private static let iso8601: ISO8601DateFormatter = {
         let formatter = ISO8601DateFormatter()
         formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
         formatter.timeZone = TimeZone(secondsFromGMT: 0)
         return formatter
     }()
 
     /// Encodes the bindings as the worker's `[{address, credID?}]` wire shape.
     /// A nil credential (the account-scoped address) omits `credID`, so the
     /// worker stores it on the legacy address-only key.
     private func addressPayload(for bindings: [PushAddressBinding]) -> [[String: Any]] {
         bindings.map { binding in
             var entry: [String: Any] = ["address": binding.address]
             if let credID = binding.credentials?.credID {
                 entry["credID"] = credID.uuidString
             }
             return entry
         }
     }
 
     private func register(
         token: String,
         bindings: [PushAddressBinding],
         mutedKinds: [String]
     ) async throws {
         var request = URLRequest(url: baseURL.appendingPathComponent("register"))
         request.httpMethod = "POST"
         let body: [String: Any] = [
             "deviceID": deviceID,
             "token": token,
             "environment": environment.rawValue,
             "addresses": addressPayload(for: bindings),
             "mutedKinds": mutedKinds
         ]
         let data = try JSONSerialization.data(withJSONObject: body)
         request.httpBody = data
         let (_, response) = try await sendAuthorized(
             request,
             method: "POST",
             path: "/register",
             body: data
         )
         try assert204(response)
     }
 
     private func unregister(bindings: [PushAddressBinding]) async {
         var request = URLRequest(url: baseURL.appendingPathComponent("register"))
         request.httpMethod = "DELETE"
         let data = (try? JSONSerialization.data(withJSONObject: [
             "deviceID": deviceID,
             "addresses": addressPayload(for: bindings)
         ])) ?? Data()
         request.httpBody = data
         do {
             let (_, response) = try await sendAuthorized(
                 request,
                 method: "DELETE",
                 path: "/register",
                 body: data
             )
             try assert204(response)
         } catch {
             log("Push unregister failed: \(error.localizedDescription)")
         }
     }
 
     /// Registers a game's shared push credential with the worker (first-write-
     /// wins) so it will verify publishes signed with that secret. Idempotent
     /// and deduped per session; mirrors `EngagementHost.registerRoom`. A 409
     /// means a different secret is already registered under this credID — only
     /// possible on an (astronomically unlikely) credID collision, so it is
     /// logged rather than retried.
     private func registerGameCredential(_ credentials: GamePushCredentials) async {
         if registeredGameCredentials[credentials.credID] == credentials.secret { return }
         let path = "/games/\(credentials.credID.uuidString)/register"
         var request = URLRequest(
             url: baseURL
                 .appendingPathComponent("games")
                 .appendingPathComponent(credentials.credID.uuidString)
                 .appendingPathComponent("register")
         )
         request.httpMethod = "POST"
         let data = (try? JSONSerialization.data(withJSONObject: ["secret": credentials.secret])) ?? Data()
         request.httpBody = data
         do {
             let (_, response) = try await sendAuthorized(
                 request,
                 method: "POST",
                 path: path,
                 body: data
             )
             switch response.statusCode {
             case 200..<300:
                 registeredGameCredentials[credentials.credID] = credentials.secret
             case 409:
                 log("Push game-credential rejected (secret mismatch) for \(credentials.credID)")
             default:
                 log("Push game-credential register failed: HTTP \(response.statusCode)")
             }
         } catch {
             log("Push game-credential register failed: \(error.localizedDescription)")
         }
     }
 
     private func sendAuthorized(
         _ request: URLRequest,
         method: String,
         path: String,
         body: Data,
         gameCredential: GamePushCredentials? = nil
     ) async throws -> (Data, HTTPURLResponse) {
         // Transport-level retry. `-1005 networkConnectionLost` / `-1001 timedOut`
         // against the Cloudflare worker are usually a keep-alive connection-reuse
         // race — the edge closed a pooled connection the device then reused —
         // rather than a real outage (CloudKit keeps syncing through them). They're
         // retryable: a fresh attempt opens a new connection. Each attempt re-signs
         // via the full overload below — `signedHeaders` mints a fresh nonce and a
         // new App Attest assertion whose counter is monotonic — so a retry can't
         // replay a stale assertion and regress the worker's stored counter. Every
         // worker write reached through here is idempotent, so re-sending is safe.
         // Bounded: a genuinely offline device exhausts the attempts and the next
         // reconcile trigger re-registers.
         let maxAttempts = 3
         var attempt = 0
         while true {
             do {
                 return try await sendAuthorized(
                     request,
                     method: method,
                     path: path,
                     body: body,
                     gameCredential: gameCredential,
                     retryAfterRegistrationReset: true
                 )
             } catch let error as URLError
                 where Self.isRetryableTransport(error.code) && attempt + 1 < maxAttempts {
                 attempt += 1
                 // Short backoff (200ms, 400ms) so an instantaneous reuse race
                 // isn't hammered and a momentarily-busy edge gets a beat.
                 try? await Task.sleep(for: .milliseconds(200 * attempt))
             }
         }
     }
 
     /// Transport failures worth retrying for an idempotent worker write.
     /// Deliberately excludes `.notConnectedToInternet`/`.cancelled` — a truly
     /// offline or cancelled send should fail fast and let the next reconcile
     /// re-register rather than spin through the backoff.
     private static func isRetryableTransport(_ code: URLError.Code) -> Bool {
         switch code {
         case .networkConnectionLost, .timedOut, .cannotConnectToHost,
              .cannotFindHost, .dnsLookupFailed, .secureConnectionFailed:
             return true
         default:
             return false
         }
     }
 
     private func sendAuthorized(
         _ request: URLRequest,
         method: String,
         path: String,
         body: Data,
         gameCredential: GamePushCredentials?,
         retryAfterRegistrationReset: Bool
     ) async throws -> (Data, HTTPURLResponse) {
         var request = request
         request.setValue("application/json", forHTTPHeaderField: "Content-Type")
         let headers = try await authenticator.signedHeaders(
             method: method,
             path: path,
             body: body
         )
         for (key, value) in headers {
             request.setValue(value, forHTTPHeaderField: key)
         }
         // Prove game participation by signing the App Attest request's own
         // body hash / timestamp / nonce with the game secret. The worker
         // re-derives this from the secret it holds for the body's credID.
         if let gameCredential,
            let bodyHash = headers["X-Crossmate-Body-SHA256"],
            let timestamp = headers["X-Crossmate-Timestamp"],
            let nonce = headers["X-Crossmate-Nonce"] {
             let payload = GamePushSigner.signaturePayload(
                 credID: gameCredential.credID,
                 bodyHash: bodyHash,
                 timestamp: timestamp,
                 nonce: nonce
             )
             if let signature = try? GamePushSigner.signature(
                 payload: payload,
                 secret: gameCredential.secret
             ) {
                 request.setValue(signature, forHTTPHeaderField: "X-Crossmate-Game-Signature")
             }
         }
         let (data, response) = try await session.data(for: request)
         guard let http = response as? HTTPURLResponse else {
             throw URLError(.badServerResponse)
         }
         if http.statusCode == 401, retryAfterRegistrationReset {
             await authenticator.resetRegistration()
             return try await sendAuthorized(
                 request,
                 method: method,
                 path: path,
                 body: body,
                 gameCredential: gameCredential,
                 retryAfterRegistrationReset: false
             )
         }
         return (data, http)
     }
 
     private func assert204(_ response: HTTPURLResponse) throws {
         guard response.statusCode == 204 else {
             throw URLError(.badServerResponse)
         }
     }
 }