crossmate

GamePushCredentials.swift (6667B)

---

 import CryptoKit
 import Foundation
 
 /// The shared per-game notification credentials, stored in the Game record's
 /// `notification` field (synced only to CKShare participants, like the
 /// `engagement` room creds). Carries two distinct kinds of secret:
 ///
 /// - `secret` / `credID`: the push-worker auth material. Possession of `secret`
 ///   proves participation — the worker verifies publish signatures and
 ///   credID-scoped address registrations against the copy registered under
 ///   `credID`. `credID` is an unguessable capability that doubles as the
 ///   worker's storage key, exactly as `EngagementRoomCredentials.roomID` does
 ///   for the room worker.
 /// - `contentKey`: a **worker-blind** symmetric key (base64 of 32 random
 ///   bytes). The structured push payload is encrypted under it (see
 ///   `PushPayloadCipher`) so the worker and APNs only ever see ciphertext for
 ///   the personal fields. Optional so records minted before it existed still
 ///   decode; `ensure`-paths add one to a legacy credential in place.
 ///
 /// IMPORTANT: only `secret` and `credID` may ever be sent to the push worker
 /// (registration sends `{secret}`, publishes name `credID`). The encoded blob
 /// as a whole — which now also holds `contentKey` — must never leave the device
 /// for a Worker, or the encryption is pointless.
 ///
 /// Unlike room creds these are durable, so there is no expiry. They are,
 /// however, *rotated* — replaced wholesale by any remaining participant when
 /// someone leaves or is removed, so departed access ends. `gen` is the
 /// monotonic rotation generation: a receiver only adopts an inbound credential
 /// whose generation is at least its local one, so a stale device re-pushing
 /// its whole Game record (which carries this blob) can't resurrect superseded
 /// credentials. Optional so blobs minted before rotation existed still decode;
 /// absent means generation 1, matching what a fresh mint uses (see
 /// `RecordSerializer.decisionBaseVersion` for the same convention).
 struct GamePushCredentials: Codable, Equatable, Hashable, Sendable {
     var ver: Int
     var credID: UUID
     var secret: String
     var contentKey: String?
     var gen: Int64?
 
     init(credID: UUID = UUID(), secret: String, contentKey: String? = nil, gen: Int64? = nil, ver: Int = 1) {
         self.ver = ver
         self.credID = credID
         self.secret = secret
         self.contentKey = contentKey
         self.gen = gen
     }
 
     /// The rotation generation, with legacy (field-less) blobs reporting 1.
     var generation: Int64 { gen ?? 1 }
 
     func encoded() throws -> String {
         let data = try JSONEncoder().encode(self)
         guard let string = String(data: data, encoding: .utf8) else {
             throw GamePushError.invalidPayloadEncoding
         }
         return string
     }
 
     static func decode(_ string: String?) -> GamePushCredentials? {
         guard let data = string?.data(using: .utf8) else { return nil }
         return try? JSONDecoder().decode(GamePushCredentials.self, from: data)
     }
 
     /// Mints a fresh credential: a random 256-bit worker auth secret (base64url,
     /// to satisfy the worker's `isAcceptableSecret` >= 32 key-byte check) and a
     /// random 256-bit content key (standard base64, decoded directly by the NSE
     /// via `PushPayloadCipher`).
     static func fresh() throws -> GamePushCredentials {
         try GamePushCredentials(
             secret: Data.secureRandom(count: 32).base64URLEncodedString(),
             contentKey: Data.secureRandom(count: 32).base64EncodedString()
         )
     }
 
     /// A fresh content key (standard base64 of 32 random bytes), used to backfill
     /// a legacy credential minted before content keys existed.
     static func freshContentKey() throws -> String {
         try Data.secureRandom(count: 32).base64EncodedString()
     }
 
     /// A full replacement credential — new `credID`, worker secret, and content
     /// key — at the next generation after `current`. Minted by a remaining
     /// participant when someone leaves or is removed: the departed device holds
     /// every field of the old credential, so nothing short of replacing all
     /// three revokes its push access.
     static func rotated(after current: GamePushCredentials) throws -> GamePushCredentials {
         var fresh = try GamePushCredentials.fresh()
         fresh.gen = current.generation + 1
         return fresh
     }
 }
 
 /// One address this device should be reachable at, paired with the per-game
 /// credential it is bound to. The account-scoped sibling address has no game,
 /// so `gameID` and `credentials` are nil and it registers on the legacy
 /// (credID-less) key. Game addresses carry the shared credential so the worker
 /// stores and resolves them under `credID`.
 struct PushAddressBinding: Hashable, Sendable {
     let gameID: UUID?
     let address: String
     let credentials: GamePushCredentials?
 
     init(gameID: UUID? = nil, address: String, credentials: GamePushCredentials? = nil) {
         self.gameID = gameID
         self.address = address
         self.credentials = credentials
     }
 }
 
 enum GamePushError: LocalizedError {
     case invalidPayloadEncoding
     case invalidSecret
 
     var errorDescription: String? {
         switch self {
         case .invalidPayloadEncoding:
             "Unable to encode game push credentials."
         case .invalidSecret:
             "The game push secret is invalid."
         }
     }
 }
 
 /// HMAC-SHA256 signer for participant-gated publishes. Mirrors
 /// `EngagementSocketAuthenticator`: the worker re-derives the identical
 /// signature from the secret it holds for `credID` and rejects the publish if
 /// they differ. The signed payload reuses the App Attest request's body hash,
 /// timestamp, and nonce (already validated and bound to the request) so no
 /// extra freshness state is needed.
 enum GamePushSigner {
     static let signatureVersion = "crossmate-push-game-v1"
 
     static func signaturePayload(
         credID: UUID,
         bodyHash: String,
         timestamp: String,
         nonce: String
     ) -> String {
         [
             signatureVersion,
             credID.uuidString,
             bodyHash,
             timestamp,
             nonce
         ].joined(separator: "\n")
     }
 
     static func signature(payload: String, secret: String) throws -> String {
         guard let secretData = Data(base64URLEncoded: secret) else {
             throw GamePushError.invalidSecret
         }
         let key = SymmetricKey(data: secretData)
         let mac = HMAC<SHA256>.authenticationCode(for: Data(payload.utf8), using: key)
         return Data(mac).base64URLEncodedString()
     }
 }