Crossmate/Services/PushRequestAuthenticator.swift (19708B)
1import CryptoKit
2import DeviceCheck
3import Foundation
4
5enum PushRequestAuthError: LocalizedError {
6 case appAttestUnsupported
7 case missingChallenge
8 case malformedKeyID
9 case challengeBadRequest(reason: String)
10 case challengeRouteMissing
11 case challengeRateLimited(retryAfter: TimeInterval?)
12 case challengeServerError(status: Int)
13 case challengeRejected(status: Int)
14 case attestationRejected(status: Int)
15 case invalidResponse
16
17 var errorDescription: String? {
18 switch self {
19 case .appAttestUnsupported:
20 "App Attest is not available on this device."
21 case .missingChallenge:
22 "The push worker did not return an App Attest challenge."
23 case .malformedKeyID:
24 "App Attest returned an invalid key identifier."
25 case let .challengeBadRequest(reason):
26 "The push worker rejected the App Attest challenge request (HTTP 400: \(reason))."
27 case .challengeRouteMissing:
28 "The push worker has no App Attest challenge route (HTTP 404)."
29 case let .challengeRateLimited(retryAfter):
30 if let retryAfter {
31 "The push worker rate-limited App Attest enrollment (HTTP 429; retry after \(Int(retryAfter.rounded(.up))) seconds)."
32 } else {
33 "The push worker rate-limited App Attest enrollment (HTTP 429)."
34 }
35 case let .challengeServerError(status):
36 "The push worker failed while issuing an App Attest challenge (HTTP \(status))."
37 case let .challengeRejected(status):
38 "The push worker rejected the App Attest challenge request (HTTP \(status))."
39 case let .attestationRejected(status):
40 "The push worker rejected this app installation's attestation (HTTP \(status))."
41 case .invalidResponse:
42 "The push worker returned an invalid authentication response."
43 }
44 }
45
46 var retryAfter: TimeInterval? {
47 if case let .challengeRateLimited(retryAfter) = self { retryAfter } else { nil }
48 }
49}
50
51protocol AppAttestServicing: Sendable {
52 var isSupported: Bool { get }
53 func generateKey() async throws -> String
54 func attestKey(_ keyID: String, clientDataHash: Data) async throws -> Data
55 func generateAssertion(_ keyID: String, clientDataHash: Data) async throws -> Data
56}
57
58private struct SystemAppAttestService: AppAttestServicing {
59 var isSupported: Bool { DCAppAttestService.shared.isSupported }
60
61 func generateKey() async throws -> String {
62 try await DCAppAttestService.shared.generateKey()
63 }
64
65 func attestKey(_ keyID: String, clientDataHash: Data) async throws -> Data {
66 try await DCAppAttestService.shared.attestKey(keyID, clientDataHash: clientDataHash)
67 }
68
69 func generateAssertion(_ keyID: String, clientDataHash: Data) async throws -> Data {
70 try await DCAppAttestService.shared.generateAssertion(keyID, clientDataHash: clientDataHash)
71 }
72}
73
74struct PushAuthKeyStore: Sendable {
75 var load: @Sendable (String) -> Data?
76 var save: @Sendable (String, Data) throws -> Void
77 var delete: @Sendable (String) -> Void
78
79 static let keychain = PushAuthKeyStore(
80 load: { KeychainHelper.load(key: $0) },
81 save: { try KeychainHelper.save(key: $0, data: $1) },
82 delete: { KeychainHelper.delete(key: $0) }
83 )
84}
85
86
87
88
89
90actor PushRequestAuthenticator {
91 private static let keyIDKey = "push.appAttest.keyID.v1"
92 private static let pendingKeyIDKey = "push.appAttest.pendingKeyID.v1"
93 private static let pendingEnrollmentKey = "push.appAttest.pendingEnrollment.v1"
94 private static let maximumKeyIDCharacters = 256
95 private static let maximumKeyIDBytes = 128
96 private static let maximumBackoff: TimeInterval = 5 * 60
97 private static let maximumRetryAfter: TimeInterval = 24 * 60 * 60
98
99 private let baseURL: URL
100 private let deviceID: String
101 private let session: URLSession
102 private let service: any AppAttestServicing
103 private let keyStore: PushAuthKeyStore
104 private let now: @Sendable () -> Date
105 private let sleep: @Sendable (TimeInterval) async throws -> Void
106 private let jitter: @Sendable () -> Double
107
108 private var cachedKeyID: String?
109 private var registeringTask: Task<String, Error>?
110 private var consecutiveFailures = 0
111 private var retryNotBefore: Date?
112
113 init(
114 baseURL: URL,
115 deviceID: String,
116 session: URLSession,
117 service: any AppAttestServicing = SystemAppAttestService(),
118 keyStore: PushAuthKeyStore = .keychain,
119 now: @escaping @Sendable () -> Date = Date.init,
120 sleep: @escaping @Sendable (TimeInterval) async throws -> Void = {
121 try await Task.sleep(for: .seconds($0))
122 },
123 jitter: @escaping @Sendable () -> Double = { Double.random(in: 0.8...1.2) }
124 ) {
125 self.baseURL = baseURL
126 self.deviceID = deviceID
127 self.session = session
128 self.service = service
129 self.keyStore = keyStore
130 self.now = now
131 self.sleep = sleep
132 self.jitter = jitter
133 }
134
135 func signedHeaders(
136 method: String,
137 path: String,
138 body: Data
139 ) async throws -> [String: String] {
140 let keyID = try await registeredKeyID()
141 return try await assertionHeaders(
142 keyID: keyID,
143 method: method,
144 path: path,
145 body: body
146 )
147 }
148
149 func resetRegistration() {
150 cachedKeyID = nil
151 registeringTask?.cancel()
152 registeringTask = nil
153 consecutiveFailures = 0
154 retryNotBefore = nil
155 keyStore.delete(Self.keyIDKey)
156 keyStore.delete(Self.pendingKeyIDKey)
157 keyStore.delete(Self.pendingEnrollmentKey)
158 }
159
160 private func registeredKeyID() async throws -> String {
161 if let cachedKeyID { return cachedKeyID }
162 if let data = keyStore.load(Self.keyIDKey),
163 let keyID = String(data: data, encoding: .utf8),
164 !keyID.isEmpty {
165 cachedKeyID = keyID
166 return keyID
167 }
168 if let registeringTask {
169 return try await registeringTask.value
170 }
171 let delay = max(0, retryNotBefore?.timeIntervalSince(now()) ?? 0)
172 let task = Task {
173 if delay > 0 { try await sleep(delay) }
174 return try await registerFreshKey()
175 }
176 registeringTask = task
177 do {
178 let keyID = try await task.value
179 registeringTask = nil
180 cachedKeyID = keyID
181 consecutiveFailures = 0
182 retryNotBefore = nil
183 return keyID
184 } catch {
185 registeringTask = nil
186 recordRegistrationFailure(error)
187 throw error
188 }
189 }
190
191 private func registerFreshKey() async throws -> String {
192 guard service.isSupported else {
193 throw PushRequestAuthError.appAttestUnsupported
194 }
195 let keyID: String
196 if let data = keyStore.load(Self.pendingKeyIDKey),
197 let pending = String(data: data, encoding: .utf8),
198 !pending.isEmpty {
199 keyID = pending
200 } else {
201 keyID = try await service.generateKey()
202
203
204
205 try keyStore.save(Self.pendingKeyIDKey, Data(keyID.utf8))
206 }
207 let networkKeyID = try Self.canonicalKeyID(keyID)
208 var pending = loadPendingEnrollment(keyID: keyID, networkKeyID: networkKeyID)
209 if pending == nil {
210 let challenge = try await fetchChallenge(for: networkKeyID)
211 pending = PendingEnrollment(
212 keyID: keyID,
213 networkKeyID: networkKeyID,
214 challenge: challenge,
215 attestation: nil
216 )
217 try savePendingEnrollment(pending!)
218 }
219 var enrollment = pending!
220 if enrollment.attestation == nil {
221 let clientDataHash = Self.clientDataHashForAttestation(
222 challenge: enrollment.challenge,
223 deviceID: deviceID,
224 keyID: networkKeyID
225 )
226 enrollment.attestation = try await service.attestKey(
227 keyID,
228 clientDataHash: clientDataHash
229 )
230
231
232
233 try savePendingEnrollment(enrollment)
234 }
235 do {
236 try await submitAttestation(
237 keyID: networkKeyID,
238 challenge: enrollment.challenge,
239 attestation: enrollment.attestation!
240 )
241 } catch let error as PushRequestAuthError {
242
243
244
245 if case let .attestationRejected(status) = error, (400..<500).contains(status) {
246 keyStore.delete(Self.pendingKeyIDKey)
247 keyStore.delete(Self.pendingEnrollmentKey)
248 }
249 throw error
250 }
251 try keyStore.save(Self.keyIDKey, Data(keyID.utf8))
252 keyStore.delete(Self.pendingKeyIDKey)
253 keyStore.delete(Self.pendingEnrollmentKey)
254 return keyID
255 }
256
257 private func fetchChallenge(for keyID: String) async throws -> String {
258 var request = URLRequest(
259 url: baseURL.appendingPathComponent("attest").appendingPathComponent("challenge")
260 )
261 request.httpMethod = "POST"
262 request.setValue("application/json", forHTTPHeaderField: "Content-Type")
263 request.httpBody = try JSONEncoder().encode(
264 ChallengeRequest(deviceID: deviceID, keyID: keyID)
265 )
266 let (data, response) = try await session.data(for: request)
267 guard let http = response as? HTTPURLResponse else {
268 throw PushRequestAuthError.invalidResponse
269 }
270 guard http.statusCode == 200 else {
271 throw Self.challengeError(response: http, data: data, now: now())
272 }
273 let decoded = try JSONDecoder().decode(ChallengeResponse.self, from: data)
274 guard !decoded.challenge.isEmpty else {
275 throw PushRequestAuthError.missingChallenge
276 }
277 return decoded.challenge
278 }
279
280 private func submitAttestation(
281 keyID: String,
282 challenge: String,
283 attestation: Data
284 ) async throws {
285 var request = URLRequest(
286 url: baseURL.appendingPathComponent("attest").appendingPathComponent("register")
287 )
288 request.httpMethod = "POST"
289 request.setValue("application/json", forHTTPHeaderField: "Content-Type")
290 let body = AttestationRequest(
291 deviceID: deviceID,
292 keyID: keyID,
293 challenge: challenge,
294 attestationObject: attestation.base64URLEncodedString()
295 )
296 request.httpBody = try JSONEncoder().encode(body)
297 let (_, response) = try await session.data(for: request)
298 guard let http = response as? HTTPURLResponse else {
299 throw PushRequestAuthError.invalidResponse
300 }
301 guard http.statusCode == 204 else {
302 throw PushRequestAuthError.attestationRejected(status: http.statusCode)
303 }
304 }
305
306 private func assertionHeaders(
307 keyID: String,
308 method: String,
309 path: String,
310 body: Data
311 ) async throws -> [String: String] {
312 let networkKeyID = try Self.canonicalKeyID(keyID)
313 let timestamp = String(Int(Date().timeIntervalSince1970))
314 let nonce = UUID().uuidString
315 let bodyHash = Data(SHA256.hash(data: body)).base64URLEncodedString()
316 let canonical = Self.canonicalRequest(
317 method: method,
318 path: path,
319 bodyHash: bodyHash,
320 timestamp: timestamp,
321 nonce: nonce,
322 deviceID: deviceID,
323 keyID: networkKeyID
324 )
325 let clientDataHash = Data(SHA256.hash(data: Data(canonical.utf8)))
326 let assertion = try await service.generateAssertion(keyID, clientDataHash: clientDataHash)
327 return [
328 "X-Crossmate-Auth-Version": "appattest-v1",
329 "X-Crossmate-Device-ID": deviceID,
330 "X-Crossmate-Key-ID": networkKeyID,
331 "X-Crossmate-Timestamp": timestamp,
332 "X-Crossmate-Nonce": nonce,
333 "X-Crossmate-Body-SHA256": bodyHash,
334 "X-Crossmate-Assertion": assertion.base64URLEncodedString()
335 ]
336 }
337
338 private func recordRegistrationFailure(_ error: Error) {
339 consecutiveFailures = min(consecutiveFailures + 1, 16)
340 let exponential = min(
341 Self.maximumBackoff,
342 2 * pow(2, Double(consecutiveFailures - 1))
343 )
344 let retryAfter = min(
345 (error as? PushRequestAuthError)?.retryAfter ?? 0,
346 Self.maximumRetryAfter
347 )
348 let delay = max(retryAfter, exponential * min(max(jitter(), 0.5), 1.5))
349 retryNotBefore = now().addingTimeInterval(delay)
350 }
351
352 private func loadPendingEnrollment(
353 keyID: String,
354 networkKeyID: String
355 ) -> PendingEnrollment? {
356 guard let data = keyStore.load(Self.pendingEnrollmentKey),
357 let pending = try? JSONDecoder().decode(PendingEnrollment.self, from: data),
358 pending.keyID == keyID,
359 pending.networkKeyID == networkKeyID
360 else {
361 keyStore.delete(Self.pendingEnrollmentKey)
362 return nil
363 }
364 return pending
365 }
366
367 private func savePendingEnrollment(_ pending: PendingEnrollment) throws {
368 try keyStore.save(Self.pendingEnrollmentKey, JSONEncoder().encode(pending))
369 }
370
371 static func canonicalKeyID(_ keyID: String) throws -> String {
372 guard !keyID.isEmpty, keyID.count <= maximumKeyIDCharacters else {
373 throw PushRequestAuthError.malformedKeyID
374 }
375 let alphabet = CharacterSet(charactersIn: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/_-=")
376 guard keyID.unicodeScalars.allSatisfy(alphabet.contains) else {
377 throw PushRequestAuthError.malformedKeyID
378 }
379 let usesStandardAlphabet = keyID.contains("+") || keyID.contains("/")
380 let usesURLSafeAlphabet = keyID.contains("-") || keyID.contains("_")
381 guard !(usesStandardAlphabet && usesURLSafeAlphabet) else {
382 throw PushRequestAuthError.malformedKeyID
383 }
384 if let firstPaddingIndex = keyID.firstIndex(of: "=") {
385 let firstPadding = keyID.distance(from: keyID.startIndex, to: firstPaddingIndex)
386 guard keyID.dropFirst(firstPadding).allSatisfy({ $0 == "=" }) else {
387 throw PushRequestAuthError.malformedKeyID
388 }
389 }
390 let unpadded = keyID.trimmingCharacters(in: CharacterSet(charactersIn: "="))
391 guard keyID.count - unpadded.count <= 2 else {
392 throw PushRequestAuthError.malformedKeyID
393 }
394 var standard = unpadded.replacingOccurrences(of: "-", with: "+")
395 .replacingOccurrences(of: "_", with: "/")
396 guard standard.count % 4 != 1 else { throw PushRequestAuthError.malformedKeyID }
397 standard += String(repeating: "=", count: (4 - standard.count % 4) % 4)
398 guard let bytes = Data(base64Encoded: standard),
399 !bytes.isEmpty,
400 bytes.count <= maximumKeyIDBytes
401 else {
402 throw PushRequestAuthError.malformedKeyID
403 }
404 let canonical = bytes.base64URLEncodedString()
405 let suppliedCanonical = unpadded.replacingOccurrences(of: "+", with: "-")
406 .replacingOccurrences(of: "/", with: "_")
407 guard canonical == suppliedCanonical else {
408 throw PushRequestAuthError.malformedKeyID
409 }
410 return canonical
411 }
412
413 static func challengeError(
414 response: HTTPURLResponse,
415 data: Data,
416 now: Date
417 ) -> PushRequestAuthError {
418 switch response.statusCode {
419 case 400:
420 return .challengeBadRequest(reason: safeChallengeReason(data))
421 case 404:
422 return .challengeRouteMissing
423 case 429:
424 return .challengeRateLimited(retryAfter: retryAfter(response, now: now))
425 case 500..<600:
426 return .challengeServerError(status: response.statusCode)
427 default:
428 return .challengeRejected(status: response.statusCode)
429 }
430 }
431
432 private static func safeChallengeReason(_ data: Data) -> String {
433 let reason = String(data: data.prefix(160), encoding: .utf8)?
434 .trimmingCharacters(in: .whitespacesAndNewlines)
435 let knownReasons = [
436 "Body too large",
437 "Body must be JSON",
438 "deviceID and keyID required",
439 "Malformed deviceID or keyID",
440 "Rate limit exceeded",
441 "Not found"
442 ]
443 return knownReasons.contains(reason ?? "") ? reason! : "unrecognized response"
444 }
445
446 private static func retryAfter(_ response: HTTPURLResponse, now: Date) -> TimeInterval? {
447 guard let value = response.value(forHTTPHeaderField: "Retry-After") else { return nil }
448 if let seconds = TimeInterval(value), seconds >= 0 { return seconds }
449 let formatter = DateFormatter()
450 formatter.locale = Locale(identifier: "en_US_POSIX")
451 formatter.timeZone = TimeZone(secondsFromGMT: 0)
452 formatter.dateFormat = "EEE',' dd MMM yyyy HH':'mm':'ss z"
453 guard let date = formatter.date(from: value) else { return nil }
454 return max(0, date.timeIntervalSince(now))
455 }
456
457 private static func clientDataHashForAttestation(
458 challenge: String,
459 deviceID: String,
460 keyID: String
461 ) -> Data {
462 let canonical = [
463 "crossmate-appattest-v1",
464 challenge,
465 deviceID,
466 keyID
467 ].joined(separator: "\n")
468 return Data(SHA256.hash(data: Data(canonical.utf8)))
469 }
470
471 static func canonicalRequest(
472 method: String,
473 path: String,
474 bodyHash: String,
475 timestamp: String,
476 nonce: String,
477 deviceID: String,
478 keyID: String
479 ) -> String {
480 [
481 "crossmate-push-request-v1",
482 method.uppercased(),
483 path,
484 bodyHash,
485 timestamp,
486 nonce,
487 deviceID,
488 keyID
489 ].joined(separator: "\n")
490 }
491
492 private struct ChallengeRequest: Encodable {
493 var deviceID: String
494 var keyID: String
495 }
496
497 private struct ChallengeResponse: Decodable {
498 var challenge: String
499 }
500
501 private struct AttestationRequest: Encodable {
502 var deviceID: String
503 var keyID: String
504 var challenge: String
505 var attestationObject: String
506 }
507
508 private struct PendingEnrollment: Codable {
509 var keyID: String
510 var networkKeyID: String
511 var challenge: String
512 var attestation: Data?
513 }
514}