← All repositories

crossmate

A collaborative crossword app for iPhone and iPad

git clone https://code.inqk.net/crossmate.git


Crossmate/Sync/FriendZone.swift (9095B)

1import CloudKit
2import CryptoKit
3import Foundation
4
5/// Pure helpers for the friendship channel. A friendship is realised as *two*
6/// mailbox zones, both named `friend-<pairKey>` and distinguished by owner:
7/// each user owns one (their inbox, in their private database) and is a
8/// `.readWrite` participant in the other's (their outbox, appearing in their
9/// shared database). You write to the friend by writing into their inbox (your
10/// outbox); you receive by reading your own inbox. Blocking is a permission
11/// downgrade on the inbox *you own*, so it is server-enforced and reversible.
12///
13/// Everything here is deterministic and side-effect-free so both devices
14/// derive the same zone names without coordination. The CloudKit lifecycle
15/// lives in `FriendController`.
16enum FriendZone {
17    /// Zone-name prefix. The shared-DB sync paths branch on this to keep a
18    /// friend zone from being mistaken for a `game-<UUID>` zone.
19    static let zonePrefix = "friend-"
20
21    /// Stable, symmetric key for the unordered pair of iCloud user record
22    /// names. `pairKey(a, b) == pairKey(b, a)` and the same inputs always
23    /// produce the same bounded-length string, so both devices independently
24    /// derive the same friend-zone name.
25    static func pairKey(_ a: String, _ b: String) -> String {
26        let joined = [a, b].sorted().joined(separator: "\u{1}")
27        let digest = SHA256.hash(data: Data(joined.utf8))
28        return digest.map { String(format: "%02x", $0) }.joined()
29    }
30
31    /// Friend-zone name for a pair key. Valid CKRecordZone name: prefix plus
32    /// 64 lowercase hex characters.
33    static func zoneName(pairKey: String) -> String {
34        "\(zonePrefix)\(pairKey)"
35    }
36
37    static func isFriendZone(_ zoneName: String) -> Bool {
38        zoneName.hasPrefix(zonePrefix)
39    }
40
41    /// The mailbox this device owns for the pair — its *inbox*. The friend
42    /// writes invites / name / key records into it; this device reads them. It
43    /// lives in this device's private database, so the owner name is the
44    /// current-user default. (`scope == 0`.)
45    static func inboxZoneID(pairKey: String) -> CKRecordZone.ID {
46        CKRecordZone.ID(zoneName: zoneName(pairKey: pairKey), ownerName: CKCurrentUserDefaultName)
47    }
48
49    /// The friend's mailbox — this device's *outbox*. This device is a
50    /// `.readWrite` participant and writes invites / name / key records here for
51    /// the friend to read. It appears in this device's shared database, owned by
52    /// the friend, whose CloudKit user-record name is `friendAuthorID` — which
53    /// is exactly the shared-zone owner name. (`scope == 1`.)
54    static func outboxZoneID(pairKey: String, friendAuthorID: String) -> CKRecordZone.ID {
55        CKRecordZone.ID(zoneName: zoneName(pairKey: pairKey), ownerName: friendAuthorID)
56    }
57
58    // The two bootstrap halves are independent and each rides a Ping that is
59    // re-fetched on every sync, so each needs its own idempotency guard. These
60    // are per-device markers: a sibling or restored device may still need to
61    // adopt the CloudKit state locally.
62    private static let inboxEstablishedPrefix = "friend.inboxEstablished."
63    private static let outboxAcceptedPrefix = "friend.outboxAccepted."
64
65    static func inboxEstablished(pairKey: String) -> Bool {
66        UserDefaults.standard.bool(forKey: inboxEstablishedPrefix + pairKey)
67    }
68
69    static func markInboxEstablished(pairKey: String) {
70        UserDefaults.standard.set(true, forKey: inboxEstablishedPrefix + pairKey)
71    }
72
73    static func outboxAccepted(pairKey: String) -> Bool {
74        UserDefaults.standard.bool(forKey: outboxAcceptedPrefix + pairKey)
75    }
76
77    static func markOutboxAccepted(pairKey: String) {
78        UserDefaults.standard.set(true, forKey: outboxAcceptedPrefix + pairKey)
79    }
80
81    private static let bootstrapHealAtPrefix = "friend.bootstrapHealAt."
82
83    /// Minimum spacing between bootstrap re-announcements for one pair. Each
84    /// re-announcement is a fresh broadcast Ping record that is never
85    /// consumed, so a friend whose devices stay dormant must not accrue one
86    /// per launch.
87    static let bootstrapHealCooldown: TimeInterval = 24 * 60 * 60
88
89    static func canAttemptBootstrapHeal(pairKey: String, now: Date = Date()) -> Bool {
90        guard let last = UserDefaults.standard.object(
91            forKey: bootstrapHealAtPrefix + pairKey
92        ) as? Date else { return true }
93        return now.timeIntervalSince(last) >= bootstrapHealCooldown
94    }
95
96    static func markBootstrapHealAttempted(pairKey: String, now: Date = Date()) {
97        UserDefaults.standard.set(now, forKey: bootstrapHealAtPrefix + pairKey)
98    }
99
100    /// Owner election: the user whose record name sorts first creates and
101    /// owns the zone; the other accepts the share. Deterministic on both
102    /// devices. Equal IDs (same user) can never be friends — returns false.
103    static func isOwner(localAuthorID: String, remoteAuthorID: String) -> Bool {
104        localAuthorID != remoteAuthorID && localAuthorID < remoteAuthorID
105    }
106
107    /// Whether `localAuthorID` is the intended acceptor for a game-zone
108    /// friendship bootstrap. `.friend` Pings are broadcast to every game
109    /// participant, so a third collaborator must ignore a pairwise bootstrap
110    /// meant for someone else instead of attempting to accept the CKShare.
111    static func canAcceptBootstrap(_ payload: BootstrapPayload, localAuthorID: String?) -> Bool {
112        guard let localAuthorID, !localAuthorID.isEmpty else { return false }
113        guard localAuthorID != payload.ownerAuthorID else { return false }
114        return pairKey(localAuthorID, payload.ownerAuthorID) == payload.pairKey
115    }
116
117    /// Payload carried in a `.friend` Ping (written into the *game* zone) so
118    /// the non-owner can accept the friend-zone share without an out-of-band
119    /// link.
120    struct BootstrapPayload: Codable, Equatable {
121        let friendShareURL: String
122        let pairKey: String
123        let ownerAuthorID: String
124
125        func encodedString() -> String? {
126            guard let data = try? JSONEncoder().encode(self) else { return nil }
127            return String(data: data, encoding: .utf8)
128        }
129
130        static func decode(_ raw: String?) -> BootstrapPayload? {
131            guard let raw, let data = raw.data(using: .utf8) else { return nil }
132            return try? JSONDecoder().decode(BootstrapPayload.self, from: data)
133        }
134    }
135
136    /// Payload carried in an `.invite` Ping (written into the *friend* zone)
137    /// so the recipient can accept the game's `CKShare` from the "Invited"
138    /// section without an out-of-band link.
139    struct InvitePayload: Codable, Equatable {
140        let gameShareURL: String
141        /// The game's grid silhouette, as a `GridSilhouette`-encoded segment,
142        /// so the recipient's "Invited" row can preview the puzzle's shape
143        /// without a CloudKit round-trip — the internal-invite counterpart to
144        /// the silhouette segment carried in share links. `nil` for non-square
145        /// grids (which get no preview) and for invites from older senders.
146        let gridSilhouette: String?
147        /// The puzzle's full XD source. The recipient already syncs the friend
148        /// zone, so this arrives with the Ping and lets the accept path build a
149        /// playable game immediately — the shared-zone fetch then only updates
150        /// it. Recipients discard this fast-accept source when it exceeds
151        /// `XD.maxSourceBytes`, falling back to the canonical shared-zone
152        /// fetch. `nil` for invites from older senders, which fall back to the
153        /// fetch.
154        let puzzleSource: String?
155        /// The owner's shared game notification credential. Direct invites can
156        /// build a playable game before the shared-zone Game record has synced;
157        /// carrying the credential here lets the joiner register under the same
158        /// worker namespace immediately instead of minting a temporary one.
159        let notification: String?
160
161        // An explicit init keeps the optionals out of the inline default
162        // (which would exclude them from Codable) while letting existing call
163        // sites omit them; a missing JSON key decodes to `nil`.
164        init(
165            gameShareURL: String,
166            gridSilhouette: String? = nil,
167            puzzleSource: String? = nil,
168            notification: String? = nil
169        ) {
170            self.gameShareURL = gameShareURL
171            self.gridSilhouette = gridSilhouette
172            self.puzzleSource = puzzleSource
173            self.notification = notification
174        }
175
176        func encodedString() -> String? {
177            guard let data = try? JSONEncoder().encode(self) else { return nil }
178            return String(data: data, encoding: .utf8)
179        }
180
181        static func decode(_ raw: String?) -> InvitePayload? {
182            guard let raw, let data = raw.data(using: .utf8) else { return nil }
183            return try? JSONDecoder().decode(InvitePayload.self, from: data)
184        }
185    }
186}