crossmate

AccountPushCoordinator.swift (27682B)

---

 import CloudKit
 import CoreData
 import CryptoKit
 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."
     nonisolated private static let friendEncryptionKeyDefaultsPrefix = "push.friendEncryptionKey."
     private static let publishedFriendEncryptionKeyDefaultsPrefix =
         "push.friendEncryptionKeyPublished."
     /// 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 persistence: PersistenceController
     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 lastAccountSeenPresenceUntil: [UUID: Date] = [:]
     /// Monotonic stamp for in-flight registration reconciles. A reconcile
     /// snapshots store state, then suspends (player republish, friend-key
     /// fetch) before handing the address set to the push client; overlapping
     /// reconciles can therefore resume out of order, and an older snapshot
     /// must not overwrite the fresher set a newer reconcile already pushed.
     private var pushRegistrationGeneration = 0
 
     init(
         identity: AuthorIdentity,
         preferences: PlayerPreferences,
         persistence: PersistenceController,
         store: GameStore,
         syncEngine: SyncEngine,
         syncMonitor: SyncMonitor,
         pushClient: PushClient?
     ) {
         self.identity = identity
         self.preferences = preferences
         self.persistence = persistence
         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,
         invitations: 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"]) }
         if !invitations { muted.insert(PingKind.invite.rawValue) }
         return muted
     }
 
     private func currentMutedPushKinds() -> Set<String> {
         Self.mutedPushKinds(
             nudges: preferences.notifiesNudges,
             joins: preferences.notifiesJoins,
             pauses: preferences.notifiesPauses,
             completions: preferences.notifiesCompletions,
             invitations: preferences.notifiesInvitations
         )
     }
 
     /// 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
                         _ = self.preferences.notifiesInvitations
                     } 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()
     }
 
     /// Full reconciliation for lifecycle events that can add/remove games,
     /// change the account credential, or require peer-visible address repair.
     /// This stamps stale local Player rows with the derived per-game address,
     /// then refreshes the worker registration. Friend-invite encryption keys
     /// are minted only from friendship or invite-send paths.
     func reconcilePushRegistration() async {
         await updatePushRegistration(republishPlayerRows: true)
     }
 
     /// Refreshes the worker's address set without repairing every Player row or
     /// minting friend-invite keys. Use this after a narrower caller has
     /// already made the specific local mutation it needs, such as puzzle open
     /// stamping the current game's Player row inside its send burst.
     func refreshPushRegistration() async {
         await updatePushRegistration(republishPlayerRows: false)
     }
 
     private func updatePushRegistration(republishPlayerRows: Bool) async {
         guard let pushClient, preferences.isICloudSyncEnabled else { return }
         guard let authorID = identity.currentID, !authorID.isEmpty else { return }
         pushRegistrationGeneration += 1
         let generation = pushRegistrationGeneration
         let accountAddress = ensureAccountPushAddress(authorID: authorID)
         let secret = ensureAccountPushSecret(authorID: authorID)
         let result = store.reconcileLocalPushAddresses(
             authorID: authorID,
             secret: secret,
             republishPlayerRows: republishPlayerRows
         )
         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))
         bindings.formUnion(await friendEncryptionKeyBindings(localAuthorID: authorID))
         // A newer reconcile started while this one was suspended; its snapshot
         // supersedes this one, so let its setAddresses stand. The Player-row
         // stamping and republish above still hold — they mutate real state
         // rather than racing on the registration snapshot.
         guard generation == pushRegistrationGeneration else { return }
         pushClient.setAddresses(bindings)
     }
 
     private func friendEncryptionKeyBindings(localAuthorID: String) async -> Set<PushAddressBinding> {
         let friends = await friendEncryptionKeyTargets(localAuthorID: localAuthorID)
         var bindings = Set<PushAddressBinding>()
         for friend in friends {
             guard let payload = existingFriendEncryptionKey(pairKey: friend.pairKey) else { continue }
             bindings.insert(PushAddressBinding(address: payload.address))
         }
         return bindings
     }
 
     func ensureFriendInvitationKeyPublished(
         pairKey: String,
         friendZoneID: CKRecordZone.ID,
         friendZoneScope: DatabaseScope
     ) async {
         guard preferences.isICloudSyncEnabled else { return }
         guard let authorID = identity.currentID, !authorID.isEmpty else { return }
         let payload = ensureFriendEncryptionKey(pairKey: pairKey)
         guard let encoded = payload.encodedString() else { return }
         if shouldPublishFriendEncryptionKey(encoded, pairKey: pairKey) {
             // Only record the publish if the decision was actually enqueued; a
             // drop (engine not up yet) must stay unmarked so a later call
             // retries instead of treating the key as already published.
             let enqueued = await syncEngine.enqueueFriendDecision(
                 kind: RecordSerializer.encryptionKeyDecisionKind,
                 key: authorID,
                 payload: encoded,
                 friendZoneID: friendZoneID,
                 friendZoneScope: friendZoneScope
             )
             if enqueued {
                 markFriendEncryptionKeyPublished(encoded, pairKey: pairKey)
             }
         }
         await refreshPushRegistration()
     }
 
     private func friendEncryptionKeyTargets(
         localAuthorID: String
     ) async -> [(pairKey: String, zoneID: CKRecordZone.ID, scope: DatabaseScope)] {
         let ctx = persistence.container.newBackgroundContext()
         return await ctx.perform {
             let req = NSFetchRequest<FriendEntity>(entityName: "FriendEntity")
             req.predicate = NSPredicate(format: "isBlocked == NO")
             return ((try? ctx.fetch(req)) ?? []).compactMap { friend in
                 guard let friendAuthorID = friend.authorID,
                       !friendAuthorID.isEmpty
                 else { return nil }
                 let pairKey = friend.pairKey ?? FriendZone.pairKey(localAuthorID, friendAuthorID)
                 guard FriendZone.outboxAccepted(pairKey: pairKey) else { return nil }
                 // The friend decrypts our invite pushes by reading our key from
                 // their inbox — our outbox (shared DB).
                 return (
                     pairKey,
                     FriendZone.outboxZoneID(pairKey: pairKey, friendAuthorID: friendAuthorID),
                     .shared
                 )
             }
         }
     }
 
     private func friendEncryptionKeyTarget(
         pairKey: String,
         localAuthorID: String
     ) async -> (zoneID: CKRecordZone.ID, scope: DatabaseScope)? {
         await friendEncryptionKeyTargets(localAuthorID: localAuthorID)
             .first { $0.pairKey == pairKey }
             .map { ($0.zoneID, $0.scope) }
     }
 
     private func ensureFriendEncryptionKey(pairKey: String) -> FriendEncryptionKeyPayload {
         let key = Self.friendEncryptionKeyDefaultsPrefix + pairKey
         if let existing = FriendEncryptionKeyPayload.decode(UserDefaults.standard.string(forKey: key)) {
             return existing
         }
         guard let fresh = FriendEncryptionKeyPayload.fresh() else {
             preconditionFailure("Unable to mint friend encryption key")
         }
         UserDefaults.standard.set(fresh.encodedString(), forKey: key)
         return fresh
     }
 
     private func existingFriendEncryptionKey(pairKey: String) -> FriendEncryptionKeyPayload? {
         FriendEncryptionKeyPayload.decode(
             UserDefaults.standard.string(forKey: Self.friendEncryptionKeyDefaultsPrefix + pairKey)
         )
     }
 
     /// This device's own friend-channel key for `pairKey` — the key it publishes
     /// to that friend (mirrored into the friend's `FriendEncryptionKeyDirectory`
     /// under this account's authorID). The counterpart a recipient verifies a
     /// live engagement frame against, so the sender signs with the same value.
     /// Nil until the key has been minted for the pair.
     nonisolated static func localFriendChannelKey(pairKey: String) -> SymmetricKey? {
         FriendEncryptionKeyPayload.decode(
             UserDefaults.standard.string(forKey: friendEncryptionKeyDefaultsPrefix + pairKey)
         )?.symmetricKey
     }
 
     private func shouldPublishFriendEncryptionKey(_ encoded: String, pairKey: String) -> Bool {
         UserDefaults.standard.string(
             forKey: Self.publishedFriendEncryptionKeyDefaultsPrefix + pairKey
         ) != encoded
     }
 
     private func markFriendEncryptionKeyPublished(_ encoded: String, pairKey: String) {
         UserDefaults.standard.set(
             encoded,
             forKey: Self.publishedFriendEncryptionKeyDefaultsPrefix + pairKey
         )
     }
 
     /// 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 publishInvitePush(
         to friendAuthorID: String,
         gameID: UUID,
         puzzleTitle: String,
         inviterName: String
     ) async {
         guard let pushClient else {
             syncMonitor.note("push(invite): skipped (no pushClient)")
             return
         }
         guard let authorID = identity.currentID, !authorID.isEmpty else {
             syncMonitor.note("push(invite): skipped (no local identity)")
             return
         }
         // The friend's directory entry only supplies their registered push
         // address. The payload must be sealed with *our own* per-pair key: the
         // friend's Notification Service Extension opens an invite push with the
         // sender's key, looked up by `fromAuthorID` — i.e. the key we minted and
         // mirrored into their directory under our authorID, not their own key.
         guard let remote = FriendEncryptionKeyDirectory.payload(for: friendAuthorID) else {
             syncMonitor.note("push(invite): skipped (no encryption key for \(friendAuthorID))")
             return
         }
         let pairKey = FriendZone.pairKey(authorID, friendAuthorID)
         if let target = await friendEncryptionKeyTarget(pairKey: pairKey, localAuthorID: authorID) {
             await ensureFriendInvitationKeyPublished(
                 pairKey: pairKey,
                 friendZoneID: target.zoneID,
                 friendZoneScope: target.scope
             )
         }
         guard let key = ensureFriendEncryptionKey(
             pairKey: pairKey
         ).symmetricKey else {
             syncMonitor.note("push(invite): skipped (no local encryption key for \(friendAuthorID))")
             return
         }
         await pushClient.publish(
             kind: PingKind.invite.rawValue,
             gameID: gameID,
             addressees: [
                 PushClient.Addressee(
                     address: remote.address,
                     payload: PushPayload(
                         event: .invite,
                         puzzleTitle: puzzleTitle,
                         playerName: inviterName
                     )
                 )
             ],
             title: "Crossmate",
             puzzleTitle: puzzleTitle,
             gameCredentialed: false,
             payloadKey: key,
             collapseID: PushClient.gameCollapseID(gameID),
             body: PushClient.genericAlertBody
         )
     }
 
     func publishAccountSeenPush(gameID: UUID, presenceUntil: Date) async {
         guard let pushClient else {
             syncMonitor.note("push(\(Self.accountSeenPushKind)): skipped (no pushClient)")
             return
         }
         guard let authorID = identity.currentID, !authorID.isEmpty else {
             syncMonitor.note("push(\(Self.accountSeenPushKind)): skipped (no authorID)")
             return
         }
         if shouldCoalesceAccountSeen(gameID: gameID, presenceUntil: presenceUntil) {
             syncMonitor.note(
                 "push(accountSeen): coalesced \(gameID.uuidString.prefix(8)) " +
                 "presenceUntil=\(presenceUntil.ISO8601Format())"
             )
             return
         }
         let address = ensureAccountPushAddress(authorID: authorID)
         lastAccountSeenPresenceUntil[gameID] = presenceUntil
         await pushClient.publishAccountEvent(
             kind: Self.accountSeenPushKind,
             gameID: gameID,
             address: address,
             presenceUntil: presenceUntil
         )
     }
 
     private func shouldCoalesceAccountSeen(gameID: UUID, presenceUntil: Date) -> Bool {
         guard let previous = lastAccountSeenPresenceUntil[gameID] else { return false }
         return abs(presenceUntil.timeIntervalSince(previous)) <= Self.accountSeenCoalesceWindow
     }
 
     @discardableResult
     private func publishAccountEvent(kind: String, gameID: UUID, presenceUntil: 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,
             presenceUntil: presenceUntil
         )
         return true
     }
 }