crossmate

AccountPushCoordinator.swift (17537B)

---

 import Foundation
 import Observation
 
 /// Owns the account-scoped push credentials and worker registration that used
 /// to live in `AppServices`: minting, caching, and rotating the account push
 /// secret (the HMAC key per-game addresses derive from) and the account push
 /// address, publishing both as `Decision` records so the account's devices
 /// converge, adopting a sibling's inbound copies under version gating, and
 /// keeping this device registered with the push worker for every shared game.
 @MainActor
 final class AccountPushCoordinator {
     private static let accountPushAddressDefaultsPrefix = "push.accountAddress."
     private static let accountPushSecretDefaultsPrefix = "push.accountSecret."
     /// Generation of the locally-held push secret. Bumped on a deliberate
     /// rotation and tracked so a stale inbound copy can't supersede the current
     /// value (see `RecordSerializer.decisionVersion`).
     private static let accountPushSecretVersionDefaultsPrefix = "push.accountSecretVersion."
     static let accountJoinedPushKind = "accountJoined"
     static let accountSeenPushKind = "accountSeen"
     private static let accountSeenCoalesceWindow: TimeInterval = 30
 
     private let identity: AuthorIdentity
     private let preferences: PlayerPreferences
     private let store: GameStore
     private let syncEngine: SyncEngine
     private let syncMonitor: SyncMonitor
     private let pushClient: PushClient?
 
     private var preferenceObservationTask: Task<Void, Never>?
     private var preferenceDebounceTask: Task<Void, Never>?
     private var lastAccountSeenReadAt: [UUID: Date] = [:]
 
     init(
         identity: AuthorIdentity,
         preferences: PlayerPreferences,
         store: GameStore,
         syncEngine: SyncEngine,
         syncMonitor: SyncMonitor,
         pushClient: PushClient?
     ) {
         self.identity = identity
         self.preferences = preferences
         self.store = store
         self.syncEngine = syncEngine
         self.syncMonitor = syncMonitor
         self.pushClient = pushClient
         // Seed the worker denylist before the first registration (no-op until
         // an APNs token arrives), then keep it mirrored as settings change.
         pushClient?.setMutedKinds(currentMutedPushKinds())
         startObservingNotificationPreferences()
     }
 
     /// Maps the notification toggles to the worker `kind` denylist. The
     /// "Completions" toggle covers both completion outcomes.
     nonisolated static func mutedPushKinds(
         nudges: Bool,
         joins: Bool,
         pauses: Bool,
         completions: Bool
     ) -> Set<String> {
         var muted: Set<String> = []
         if !nudges { muted.insert("nudge") }
         if !joins { muted.insert("join") }
         if !pauses { muted.insert("pause") }
         if !completions { muted.formUnion(["win", "resign"]) }
         return muted
     }
 
     private func currentMutedPushKinds() -> Set<String> {
         Self.mutedPushKinds(
             nudges: preferences.notifiesNudges,
             joins: preferences.notifiesJoins,
             pauses: preferences.notifiesPauses,
             completions: preferences.notifiesCompletions
         )
     }
 
     /// Re-registers with the worker when a notification toggle changes, so a
     /// muted kind takes effect without waiting for the next launch. Debounced
     /// like `PlayerNamePublisher` so a burst of toggle flips lands as one
     /// registration; `PushClient` dedups unchanged sets anyway.
     private func startObservingNotificationPreferences() {
         preferenceObservationTask = Task { [weak self] in
             guard let self else { return }
             while !Task.isCancelled {
                 await withCheckedContinuation { (cont: CheckedContinuation<Void, Never>) in
                     withObservationTracking {
                         _ = self.preferences.notifiesNudges
                         _ = self.preferences.notifiesJoins
                         _ = self.preferences.notifiesPauses
                         _ = self.preferences.notifiesCompletions
                     } onChange: {
                         cont.resume()
                     }
                 }
                 guard !Task.isCancelled else { break }
                 self.preferenceDebounceTask?.cancel()
                 self.preferenceDebounceTask = Task { [weak self] in
                     do {
                         try await Task.sleep(for: .milliseconds(250))
                     } catch {
                         return
                     }
                     guard let self, !Task.isCancelled else { return }
                     self.pushClient?.setMutedKinds(self.currentMutedPushKinds())
                 }
             }
         }
     }
 
     /// Adopts an account push address learned from a sibling device's
     /// `Decision` record, then re-reconciles so this device registers under
     /// the converged address.
     func adoptInboundPushAddress(_ address: String) async {
         guard let authorID = identity.currentID, !authorID.isEmpty else { return }
         cacheAccountPushAddress(address, authorID: authorID)
         await reconcilePushRegistration()
     }
 
     /// Adopts an account push secret learned from a sibling device's
     /// `Decision` record. Gate adoption on the generation: take a strictly
     /// newer secret (a rotation), or an equal-generation one that differs
     /// (the mint-race loser converging on the server's value). Ignore an
     /// older copy so a late-arriving stale Decision can't undo a rotation.
     /// Adopting changes every derived address, so reconcile re-derives,
     /// rewrites the local Player rows, and re-registers the new set with the
     /// worker.
     func adoptInboundPushSecret(_ secret: String, version: Int64) async {
         guard let authorID = identity.currentID, !authorID.isEmpty else { return }
         let local = accountPushSecretVersion(authorID: authorID)
         let current = UserDefaults.standard.string(
             forKey: accountPushSecretDefaultsKey(authorID: authorID)
         )
         guard version > local || (version == local && secret != current) else { return }
         cacheAccountPushSecret(secret, version: version, authorID: authorID)
         await reconcilePushRegistration()
     }
 
     /// Ensures this device is registered with the push worker under the
     /// account's per-game push address for every shared game, minting and
     /// publishing any address that doesn't exist yet so peers learn where to
     /// reach this account. Deduped inside `PushClient`, so it's cheap to call
     /// repeatedly — on launch (sync ready), when a shared game appears
     /// (inbound Player records), and on account switch. This is what makes a
     /// push reach *all* of the account's devices, not just the one a game was
     /// opened on, and survive an APNs token rotation.
     func reconcilePushRegistration() async {
         guard let pushClient, preferences.isICloudSyncEnabled else { return }
         guard let authorID = identity.currentID, !authorID.isEmpty else { return }
         let accountAddress = ensureAccountPushAddress(authorID: authorID)
         let secret = ensureAccountPushSecret(authorID: authorID)
         let result = store.reconcileLocalPushAddresses(authorID: authorID, secret: secret)
         for gameID in result.republishGameIDs {
             await syncEngine.enqueuePlayer(
                 gameID: gameID,
                 authorID: authorID,
                 reason: "pushAddress"
             )
         }
         // The account-scoped sibling address carries no game credential.
         var bindings = Set(result.bindings)
         bindings.insert(PushAddressBinding(address: accountAddress))
         pushClient.setAddresses(bindings)
     }
 
     /// Stamps `gameID`'s local Player row with the derived push address inside
     /// the puzzle-open send burst, so it ships on the same Player-record write
     /// as the read-cursor lease and display name.
     @discardableResult
     func setDerivedPushAddress(gameID: UUID, authorID: String) -> String? {
         let secret = ensureAccountPushSecret(authorID: authorID)
         return store.setPushAddress(gameID: gameID, authorID: authorID, secret: secret)
     }
 
     private func ensureAccountPushAddress(authorID: String) -> String {
         let key = accountPushAddressDefaultsKey(authorID: authorID)
         if let existing = UserDefaults.standard.string(forKey: key), !existing.isEmpty {
             // Already minted and published (or learned from a sibling). The
             // Decision write is durable across launches via CKSyncEngine's
             // pending-change queue and convergence rides the LWW conflict
             // callback, so there's nothing to re-assert here — re-publishing
             // would stamp a fresh `createdAt` and re-upload the record on every
             // `accountSeen`/reconcile for a value that never changes.
             return existing
         }
         let address = "acct-\(UUID().uuidString)"
         UserDefaults.standard.set(address, forKey: key)
         publishAccountPushAddressDecision(address)
         return address
     }
 
     private func cacheAccountPushAddress(_ address: String, authorID: String) {
         guard !address.isEmpty else { return }
         UserDefaults.standard.set(address, forKey: accountPushAddressDefaultsKey(authorID: authorID))
     }
 
     private func accountPushAddressDefaultsKey(authorID: String) -> String {
         Self.accountPushAddressDefaultsPrefix + authorID
     }
 
     /// Mints (if needed) the account-wide push secret — the HMAC key every
     /// per-game push address is derived from. Converges across the account's own
     /// devices through a `Decision` exactly like the account address; never sent
     /// to peers or the worker, so only the account's devices can derive. A fresh
     /// mint starts at `decisionBaseVersion`; a deliberate replacement goes
     /// through `rotateAccountPushSecret`, which bumps the generation so it
     /// supersedes the converged value.
     ///
     /// This secret derives the per-game push *addresses*; participation is now
     /// enforced separately by the per-game push credential in the Game record
     /// (`GamePushCredentials`), which the worker verifies before delivering a
     /// game push. The account secret still matters — it stays inside the
     /// account's private CloudKit database so only the account's own devices can
     /// derive its addresses, and it backs the account-scoped sibling pushes
     /// (accountJoined/accountSeen), which carry no game and remain gated by App
     /// Attest alone.
     private func ensureAccountPushSecret(authorID: String) -> String {
         let key = accountPushSecretDefaultsKey(authorID: authorID)
         if let existing = UserDefaults.standard.string(forKey: key), !existing.isEmpty {
             return existing
         }
         let secret = Self.generatePushSecret()
         let version = RecordSerializer.decisionBaseVersion
         cacheAccountPushSecret(secret, version: version, authorID: authorID)
         publishAccountPushSecretDecision(secret, version: version)
         return secret
     }
 
     /// Rotates the account-wide push secret to a fresh value at the next
     /// generation. The bumped version lets the new secret overwrite the existing
     /// `Decision` (otherwise an equal-generation write converges back onto the
     /// server's value); every one of the account's devices adopts it inbound and
     /// re-derives its per-game addresses. Safe to call when nothing is minted yet
     /// — it simply mints the first generation.
     func rotateAccountPushSecret() {
         guard let authorID = identity.currentID, !authorID.isEmpty else { return }
         let secret = Self.generatePushSecret()
         let version = accountPushSecretVersion(authorID: authorID) + 1
         cacheAccountPushSecret(secret, version: version, authorID: authorID)
         publishAccountPushSecretDecision(secret, version: version)
         Task { @MainActor [weak self] in
             await self?.reconcilePushRegistration()
         }
     }
 
     private static func generatePushSecret() -> String {
         var bytes = [UInt8](repeating: 0, count: 32)
         let status = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
         // A failed mint would otherwise produce the base64 of 32 zero bytes —
         // a predictable HMAC key that converges durably across the account's
         // devices. Crashing is preferable to publishing that.
         precondition(status == errSecSuccess, "SecRandomCopyBytes failed: \(status)")
         return Data(bytes).base64URLEncodedString()
     }
 
     private func cacheAccountPushSecret(_ secret: String, version: Int64, authorID: String) {
         guard !secret.isEmpty else { return }
         UserDefaults.standard.set(secret, forKey: accountPushSecretDefaultsKey(authorID: authorID))
         UserDefaults.standard.set(version, forKey: accountPushSecretVersionDefaultsKey(authorID: authorID))
     }
 
     private func accountPushSecretDefaultsKey(authorID: String) -> String {
         Self.accountPushSecretDefaultsPrefix + authorID
     }
 
     private func accountPushSecretVersionDefaultsKey(authorID: String) -> String {
         Self.accountPushSecretVersionDefaultsPrefix + authorID
     }
 
     /// Generation of the locally-held push secret. Defaults to
     /// `decisionBaseVersion` when a secret exists without a stored version (a
     /// value cached by the pre-rotation build) and to one below that when no
     /// secret is cached at all, so a first mint or any inbound copy supersedes it.
     private func accountPushSecretVersion(authorID: String) -> Int64 {
         let defaults = UserDefaults.standard
         if let stored = defaults.object(
             forKey: accountPushSecretVersionDefaultsKey(authorID: authorID)
         ) as? NSNumber {
             return stored.int64Value
         }
         let secret = defaults.string(forKey: accountPushSecretDefaultsKey(authorID: authorID))
         return (secret ?? "").isEmpty
             ? RecordSerializer.decisionBaseVersion - 1
             : RecordSerializer.decisionBaseVersion
     }
 
     /// True once both the account push secret and address are cached for this
     /// account — i.e. `ensureAccountPushSecret`/`ensureAccountPushAddress` would
     /// hit their early returns rather than mint. Used at startup to decide
     /// whether a pre-reconcile fetch is needed to adopt a sibling's value first.
     func hasCachedAccountPushCredentials(authorID: String) -> Bool {
         let defaults = UserDefaults.standard
         let secret = defaults.string(forKey: accountPushSecretDefaultsKey(authorID: authorID))
         let address = defaults.string(forKey: accountPushAddressDefaultsKey(authorID: authorID))
         return !(secret ?? "").isEmpty && !(address ?? "").isEmpty
     }
 
     private func publishAccountPushSecretDecision(_ secret: String, version: Int64) {
         Task.detached { [syncEngine] in
             await syncEngine.enqueueDecision(
                 kind: RecordSerializer.accountDecisionKind,
                 key: RecordSerializer.accountPushSecretDecisionKey,
                 payload: secret,
                 version: version
             )
         }
     }
 
     private func publishAccountPushAddressDecision(_ address: String) {
         // This can be reached from callbacks that SyncEngine invokes while a
         // CKSyncEngine delegate method is still unwinding. Match the existing
         // friend-accept pattern: do not use plain `Task {}`, which can inherit
         // the current actor and re-enter before CloudKit's delegate guard clears.
         Task.detached { [syncEngine] in
             await syncEngine.enqueueDecision(
                 kind: RecordSerializer.accountDecisionKind,
                 key: RecordSerializer.accountPushAddressDecisionKey,
                 payload: address
             )
         }
     }
 
     func publishAccountJoinedPush(gameID: UUID) async {
         await publishAccountEvent(kind: Self.accountJoinedPushKind, gameID: gameID)
     }
 
     func publishAccountSeenPush(gameID: UUID, readAt: Date) async {
         if shouldCoalesceAccountSeen(gameID: gameID, readAt: readAt) {
             syncMonitor.note(
                 "push(accountSeen): coalesced \(gameID.uuidString.prefix(8)) " +
                 "readAt=\(readAt.ISO8601Format())"
             )
             return
         }
         if await publishAccountEvent(kind: Self.accountSeenPushKind, gameID: gameID, readAt: readAt) {
             lastAccountSeenReadAt[gameID] = readAt
         }
     }
 
     private func shouldCoalesceAccountSeen(gameID: UUID, readAt: Date) -> Bool {
         guard let previous = lastAccountSeenReadAt[gameID] else { return false }
         return abs(readAt.timeIntervalSince(previous)) <= Self.accountSeenCoalesceWindow
     }
 
     @discardableResult
     private func publishAccountEvent(kind: String, gameID: UUID, readAt: Date? = nil) async -> Bool {
         guard let pushClient else {
             syncMonitor.note("push(\(kind)): skipped (no pushClient)")
             return false
         }
         guard let authorID = identity.currentID, !authorID.isEmpty else {
             syncMonitor.note("push(\(kind)): skipped (no authorID)")
             return false
         }
         let address = ensureAccountPushAddress(authorID: authorID)
         await pushClient.publishAccountEvent(
             kind: kind,
             gameID: gameID,
             address: address,
             readAt: readAt
         )
         return true
     }
 }