Repository Public
1import CryptoKit2import Foundation3import Observation45/// How this device describes itself to the account (shown in the list of registered devices).6struct DeviceDescription: Sendable {7 var name: String8 var platform: String // "macos", "ios" or "ipados"9 var model: String10 var appVersion: String11}1213struct AccountUser: Codable, Equatable, Sendable {14 var id: String15 var displayName: String16 var createdAt: Double?17}1819/// The signed-in session kept in the keychain. The token is opaque; the server stores only its hash.20struct StoredSession: Codable, Equatable, Sendable {21 var token: String22 var user: AccountUser23 var deviceID: String24 var expiresAt: Double25}2627struct AccountDetails: Decodable, Equatable, Sendable {28 struct User: Decodable, Equatable, Sendable { var id: String; var displayName: String; var createdAt: Double; var hasRecovery: Bool }29 struct Device: Decodable, Equatable, Identifiable, Sendable {30 var id: String; var name: String; var platform: String; var model: String; var appVersion: String31 var createdAt: Double; var lastSeenAt: Double; var lastSyncAt: Double?; var hasSyncKey: Bool; var activeSessions: Int; var isCurrent: Bool32 var encPublicKey: String33 }34 struct Passkey: Decodable, Equatable, Identifiable, Sendable {35 var id: String; var label: String; var synced: Bool; var deviceType: String?; var createdAt: Double; var lastUsedAt: Double?36 }37 struct Session: Decodable, Equatable, Sendable { var deviceId: String; var createdAt: Double; var lastUsedAt: Double; var expiresAt: Double; var isCurrent: Bool }38 struct Sync: Decodable, Equatable, Sendable { var initialized: Bool; var keyVersion: Int?; var hasEnvelope: Bool; var records: Int }39 var user: User40 var currentDeviceId: String41 var devices: [Device]42 var passkeys: [Passkey]43 var sessions: [Session]44 var sync: Sync45}4647struct PendingDevice: Decodable, Equatable, Identifiable, Sendable {48 var id: String49 var name: String50 var platform: String51 var model: String52 var encPublicKey: String53 var createdAt: Double5455 /// The code to compare with the one shown on the waiting device before approving it.56 var verificationCode: String { SyncCrypto.verificationCode(forPublicKey: encPublicKey) }57}5859/// Where this device stands with respect to the account's encryption key.60enum SyncKeyStatus: Equatable, Sendable {61 case signedOut62 /// Signed in on the first device: sync has not been set up yet.63 case notSetUp64 /// Another device (or the recovery key) must hand over the account key.65 case waitingForApproval(verificationCode: String)66 case ready67}6869/// SP Identity + the key side of SP Sync: account, passkeys, sessions, devices and the account encryption key.70/// Secrets (session token, device private key, account key) live only in the keychain.71@MainActor72@Observable73final class AccountService {74 private(set) var session: StoredSession?75 private(set) var keyStatus: SyncKeyStatus = .signedOut76 private(set) var isBusy = false7778 @ObservationIgnored let backend: BackendClient79 @ObservationIgnored private let secrets: SecretStore80 @ObservationIgnored private let authorizer: PasskeyAuthorizer81 @ObservationIgnored private let device: @Sendable () -> DeviceDescription82 @ObservationIgnored private let tokenBox: TokenBox83 @ObservationIgnored private let keyBox: KeyBox84 /// Called after the session or key state changes (sync starts, stops or resets on it).85 @ObservationIgnored var onStateChange: (@MainActor () -> Void)?8687 private enum Account { static let session = "identity.session", deviceKey = "identity.device-key", accountKey = "sync.account-key" }8889 /// Thread-safe holders so the network client and the sync engine can read the token and key off the main actor.90 final class TokenBox: @unchecked Sendable {91 private let lock = NSLock(); private var value: String?92 func get() -> String? { lock.lock(); defer { lock.unlock() }; return value }93 func set(_ v: String?) { lock.lock(); value = v; lock.unlock() }94 }95 final class KeyBox: @unchecked Sendable {96 private let lock = NSLock(); private var value: SymmetricKey?97 func get() -> SymmetricKey? { lock.lock(); defer { lock.unlock() }; return value }98 func set(_ v: SymmetricKey?) { lock.lock(); value = v; lock.unlock() }99 }100101 init(configuration: BackendConfiguration = .current(), secrets: SecretStore, authorizer: PasskeyAuthorizer,102 urlSession: URLSession? = nil, device: @escaping @Sendable () -> DeviceDescription) {103 self.secrets = secrets104 self.authorizer = authorizer105 self.device = device106 let tokenBox = TokenBox(), keyBox = KeyBox()107 self.tokenBox = tokenBox108 self.keyBox = keyBox109 backend = BackendClient(configuration: configuration, session: urlSession, token: { tokenBox.get() })110 if let text = secrets.secret(for: Account.session), let stored = try? JSONDecoder().decode(StoredSession.self, from: Data(text.utf8)),111 stored.expiresAt > Date().timeIntervalSince1970 * 1000 {112 session = stored113 tokenBox.set(stored.token)114 if let raw = secrets.secret(for: Account.accountKey).flatMap({ Data(base64Encoded: $0) }), raw.count == 32 {115 keyBox.set(SymmetricKey(data: raw))116 keyStatus = .ready117 } else {118 keyStatus = .waitingForApproval(verificationCode: SyncCrypto.verificationCode(forPublicKey: SyncCrypto.publicKeyString(deviceKey())))119 }120 }121 }122123 var isSignedIn: Bool { session != nil }124 var accountKeyProvider: @Sendable () -> SymmetricKey? { let box = keyBox; return { box.get() } }125 var currentDeviceID: String? { session?.deviceID }126127 // MARK: Device key128129 /// This device's key-agreement key pair. Created once; the private half never leaves the keychain.130 private func deviceKey() -> Curve25519.KeyAgreement.PrivateKey {131 if let text = secrets.secret(for: Account.deviceKey), let raw = Data(base64Encoded: text),132 let key = try? Curve25519.KeyAgreement.PrivateKey(rawRepresentation: raw) { return key }133 let key = SyncCrypto.newDeviceKey()134 secrets.setSecret(key.rawRepresentation.base64EncodedString(), for: Account.deviceKey)135 return key136 }137138 private struct DevicePayload: Encodable, Sendable { var id: String?; var name: String; var platform: String; var model: String; var appVersion: String; var encPublicKey: String }139140 private func devicePayload() -> DevicePayload {141 let d = device()142 return DevicePayload(id: session?.deviceID ?? secrets.secret(for: "identity.last-device-id"), name: d.name, platform: d.platform, model: d.model,143 appVersion: d.appVersion, encPublicKey: SyncCrypto.publicKeyString(deviceKey()))144 }145146 // MARK: Wire types147148 private struct OptionsResponse<Options: Decodable & Sendable>: Decodable, Sendable { var challengeId: String; var options: Options }149 private struct SessionResponse: Decodable, Sendable {150 struct SyncState: Decodable, Sendable { var initialized: Bool; var hasEnvelope: Bool }151 var sessionToken: String; var expiresAt: Double; var user: AccountUser; var deviceId: String; var sync: SyncState152 }153 private struct VerifyBody: Encodable, Sendable { var challengeId: String; var credential: WebAuthnJSON.Credential; var device: DevicePayload?; var label: String? }154 private struct OK: Decodable, Sendable { var ok: Bool }155156 private func run<T>(_ body: () async throws -> T) async throws -> T {157 isBusy = true158 defer { isBusy = false }159 return try await body()160 }161162 private func challengeData(_ text: String) throws -> Data {163 guard let data = SyncCrypto.data(base64URL: text) else { throw BackendError(kind: .invalidResponse, code: "bad_challenge", message: L("The server sent an unreadable answer."), status: 0) }164 return data165 }166167 private func adopt(_ response: SessionResponse) {168 let stored = StoredSession(token: response.sessionToken, user: response.user, deviceID: response.deviceId, expiresAt: response.expiresAt)169 // A different account on this device must never inherit the previous account's key.170 if let previous = secrets.secret(for: "identity.last-user-id"), previous != response.user.id {171 secrets.setSecret(nil, for: Account.accountKey)172 keyBox.set(nil)173 }174 secrets.setSecret(response.user.id, for: "identity.last-user-id")175 secrets.setSecret(response.deviceId, for: "identity.last-device-id")176 if let data = try? JSONEncoder().encode(stored) { secrets.setSecret(String(decoding: data, as: UTF8.self), for: Account.session) }177 session = stored178 tokenBox.set(stored.token)179 if keyBox.get() == nil, let raw = secrets.secret(for: Account.accountKey).flatMap({ Data(base64Encoded: $0) }), raw.count == 32 { keyBox.set(SymmetricKey(data: raw)) }180 if keyBox.get() != nil { keyStatus = .ready }181 else if !response.sync.initialized { keyStatus = .notSetUp }182 else { keyStatus = .waitingForApproval(verificationCode: SyncCrypto.verificationCode(forPublicKey: SyncCrypto.publicKeyString(deviceKey()))) }183 onStateChange?()184 }185186 private func store(accountKey key: SymmetricKey) {187 secrets.setSecret(SyncCrypto.data(key).base64EncodedString(), for: Account.accountKey)188 keyBox.set(key)189 keyStatus = .ready190 onStateChange?()191 }192193 // MARK: Account creation and sign-in194195 /// Creates an account with a new passkey on this device, then sets up sync.196 /// Returns the recovery kit, which the user must keep: it is shown once and never stored by the server.197 @discardableResult198 func createAccount(displayName: String, inviteCode: String?) async throws -> SyncCrypto.RecoveryKit {199 try await run {200 struct Body: Encodable, Sendable { var displayName: String; var inviteCode: String? }201 let start: OptionsResponse<WebAuthnJSON.RegistrationOptions> = try await backend.send(202 "POST", "/api/auth/register/options", body: Body(displayName: displayName, inviteCode: inviteCode), authenticated: false)203 guard let userID = SyncCrypto.data(base64URL: start.options.user.id) else { throw PasskeyError.failed(L("The server sent an unreadable answer.")) }204 let registration = try await authorizer.register(challenge: try challengeData(start.options.challenge),205 relyingParty: start.options.rp.id ?? backend.configuration.relyingParty,206 userID: userID, userName: start.options.user.name)207 var payload = devicePayload(); payload.id = nil208 let response: SessionResponse = try await backend.send(209 "POST", "/api/auth/register/verify",210 body: VerifyBody(challengeId: start.challengeId, credential: .init(registration), device: payload, label: nil), authenticated: false)211 adopt(response)212 return try await setUpSync()213 }214 }215216 /// Signs in with an existing passkey (Touch ID / Face ID / passcode). The passkey itself identifies the account.217 func signIn() async throws {218 try await run {219 let start: OptionsResponse<WebAuthnJSON.AuthenticationOptions> = try await backend.send(220 "POST", "/api/auth/login/options", body: BackendClient.Empty(), authenticated: false)221 let assertion = try await authorizer.assert(challenge: try challengeData(start.options.challenge),222 relyingParty: start.options.rpId ?? backend.configuration.relyingParty, allowedCredentials: [])223 let response: SessionResponse = try await backend.send(224 "POST", "/api/auth/login/verify",225 body: VerifyBody(challengeId: start.challengeId, credential: .init(assertion), device: devicePayload(), label: nil), authenticated: false)226 adopt(response)227 _ = try? await refreshKey()228 }229 }230231 /// Lost every passkey: proves possession of the recovery kit, registers a new passkey here and recovers the data key.232 func recover(with kit: SyncCrypto.RecoveryKit) async throws {233 try await run {234 struct Body: Encodable, Sendable { var userId: String; var recoveryAuth: String }235 let start: OptionsResponse<WebAuthnJSON.RegistrationOptions> = try await backend.send(236 "POST", "/api/auth/recover/options", body: Body(userId: kit.userID, recoveryAuth: kit.authenticator), authenticated: false)237 guard let userID = SyncCrypto.data(base64URL: start.options.user.id) else { throw PasskeyError.failed(L("The server sent an unreadable answer.")) }238 let registration = try await authorizer.register(challenge: try challengeData(start.options.challenge),239 relyingParty: start.options.rp.id ?? backend.configuration.relyingParty,240 userID: userID, userName: start.options.user.name)241 let response: SessionResponse = try await backend.send(242 "POST", "/api/auth/recover/verify",243 body: VerifyBody(challengeId: start.challengeId, credential: .init(registration), device: devicePayload(), label: nil), authenticated: false)244 adopt(response)245 try await unlock(with: kit)246 }247 }248249 // MARK: Account key250251 private struct KeysResponse: Decodable, Sendable {252 struct Envelope: Decodable, Sendable { var sealed: String; var fromDeviceId: String; var fromDeviceName: String }253 var initialized: Bool; var keyCheck: String?; var isHolder: Bool; var envelope: Envelope?254 }255256 /// First device: creates the account key, uploads only its verifier and a copy sealed under the new recovery key.257 func setUpSync() async throws -> SyncCrypto.RecoveryKit {258 guard let session else { throw SyncFailure.notSignedIn }259 struct Body: Encodable, Sendable { var keyProof: String; var recoveryBlob: String; var recoveryAuth: String }260 let key = SyncCrypto.newAccountKey()261 let kit = SyncCrypto.RecoveryKit(userID: session.user.id)262 let _: OK = try await backend.send("POST", "/api/sync/keys/bootstrap",263 body: Body(keyProof: SyncCrypto.keyProof(key), recoveryBlob: try kit.seal(key), recoveryAuth: kit.authenticator))264 store(accountKey: key)265 return kit266 }267268 /// Checks whether another device has approved this one, and if so opens the envelope. Returns the resulting status.269 @discardableResult270 func refreshKey() async throws -> SyncKeyStatus {271 guard let session else { keyStatus = .signedOut; return keyStatus }272 let state: KeysResponse = try await backend.send("GET", "/api/sync/keys")273 if !state.initialized {274 // The server has no key: either sync was never set up, or its data was erased. A local key is then stale.275 if keyBox.get() != nil { secrets.setSecret(nil, for: Account.accountKey); keyBox.set(nil) }276 keyStatus = .notSetUp277 onStateChange?()278 return keyStatus279 }280 if let key = keyBox.get() {281 if state.keyCheck == SyncCrypto.keyCheck(key) { keyStatus = .ready; return keyStatus }282 secrets.setSecret(nil, for: Account.accountKey); keyBox.set(nil)283 }284 if let envelope = state.envelope,285 let key = try? SyncCrypto.openEnvelope(envelope.sealed, with: deviceKey(), userID: session.user.id, deviceID: session.deviceID),286 state.keyCheck == SyncCrypto.keyCheck(key) {287 store(accountKey: key)288 return keyStatus289 }290 keyStatus = .waitingForApproval(verificationCode: SyncCrypto.verificationCode(forPublicKey: SyncCrypto.publicKeyString(deviceKey())))291 return keyStatus292 }293294 /// Opens the account key with the recovery kit instead of waiting for another device.295 func unlock(with kit: SyncCrypto.RecoveryKit) async throws {296 guard let session, kit.userID == session.user.id else { throw SyncCrypto.Failure.wrongKey }297 struct Recovery: Decodable, Sendable { var recoveryBlob: String; var keyCheck: String }298 struct Claim: Encodable, Sendable { var keyProof: String }299 let recovery: Recovery = try await backend.send("GET", "/api/sync/keys/recovery")300 let key = try kit.open(recovery.recoveryBlob)301 guard SyncCrypto.keyCheck(key) == recovery.keyCheck else { throw SyncCrypto.Failure.wrongKey }302 let _: OK = try await backend.send("POST", "/api/sync/keys/claim", body: Claim(keyProof: SyncCrypto.keyProof(key)))303 store(accountKey: key)304 }305306 /// Issues a new recovery kit (the previous one stops working).307 func newRecoveryKit() async throws -> SyncCrypto.RecoveryKit {308 guard let session, let key = keyBox.get() else { throw SyncFailure.keyUnavailable }309 struct Body: Encodable, Sendable { var keyProof: String; var recoveryBlob: String; var recoveryAuth: String }310 let kit = SyncCrypto.RecoveryKit(userID: session.user.id)311 let _: OK = try await backend.send("PUT", "/api/sync/keys/recovery",312 body: Body(keyProof: SyncCrypto.keyProof(key), recoveryBlob: try kit.seal(key), recoveryAuth: kit.authenticator))313 return kit314 }315316 func pendingDevices() async throws -> [PendingDevice] {317 guard keyBox.get() != nil else { return [] }318 struct Response: Decodable, Sendable { var devices: [PendingDevice] }319 let response: Response = try await backend.send("GET", "/api/sync/keys/pending")320 return response.devices321 }322323 /// Hands the account key to a waiting device, sealed to the public key whose verification code the user just compared.324 func approve(_ pending: PendingDevice) async throws {325 guard let session, let key = keyBox.get() else { throw SyncFailure.keyUnavailable }326 struct Body: Encodable, Sendable { var deviceId: String; var encPublicKey: String; var envelope: String; var keyProof: String }327 let envelope = try SyncCrypto.sealEnvelope(accountKey: key, to: pending.encPublicKey, userID: session.user.id, deviceID: pending.id)328 let _: OK = try await backend.send("POST", "/api/sync/keys/approve",329 body: Body(deviceId: pending.id, encPublicKey: pending.encPublicKey, envelope: envelope, keyProof: SyncCrypto.keyProof(key)))330 }331332 // MARK: Account management333334 func details() async throws -> AccountDetails { try await backend.send("GET", "/api/account") }335336 func rename(_ displayName: String) async throws {337 struct Body: Encodable, Sendable { var displayName: String }338 let _: OK = try await backend.send("PATCH", "/api/account", body: Body(displayName: displayName))339 if var stored = session {340 stored.user.displayName = displayName341 session = stored342 if let data = try? JSONEncoder().encode(stored) { secrets.setSecret(String(decoding: data, as: UTF8.self), for: Account.session) }343 }344 }345346 /// Confirms the user's presence with a passkey before a destructive action.347 func confirmWithPasskey() async throws {348 let start: OptionsResponse<WebAuthnJSON.AuthenticationOptions> = try await backend.send("POST", "/api/auth/reauth/options", body: BackendClient.Empty())349 let allowed = (start.options.allowCredentials ?? []).compactMap { SyncCrypto.data(base64URL: $0.id) }350 let assertion = try await authorizer.assert(challenge: try challengeData(start.options.challenge),351 relyingParty: start.options.rpId ?? backend.configuration.relyingParty, allowedCredentials: allowed)352 let _: OK = try await backend.send("POST", "/api/auth/reauth/verify",353 body: VerifyBody(challengeId: start.challengeId, credential: .init(assertion), device: nil, label: nil))354 }355356 func addPasskey(label: String) async throws {357 try await run {358 let start: OptionsResponse<WebAuthnJSON.RegistrationOptions> = try await backend.send("POST", "/api/auth/passkeys/options", body: BackendClient.Empty())359 guard let userID = SyncCrypto.data(base64URL: start.options.user.id) else { throw PasskeyError.failed(L("The server sent an unreadable answer.")) }360 let registration = try await authorizer.register(challenge: try challengeData(start.options.challenge),361 relyingParty: start.options.rp.id ?? backend.configuration.relyingParty,362 userID: userID, userName: start.options.user.name)363 struct Added: Decodable, Sendable { var ok: Bool }364 let _: Added = try await backend.send("POST", "/api/auth/passkeys/verify",365 body: VerifyBody(challengeId: start.challengeId, credential: .init(registration), device: nil, label: label))366 }367 }368369 func removePasskey(id: String) async throws {370 try await run {371 try await confirmWithPasskey()372 let _: OK = try await backend.send("DELETE", "/api/auth/passkeys/" + (id.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? id))373 }374 }375376 func removeDevice(id: String) async throws {377 struct Response: Decodable, Sendable { var ok: Bool; var signedOutSelf: Bool }378 let response: Response = try await backend.send("DELETE", "/api/devices/" + id)379 if response.signedOutSelf { clearLocalSession(forgetKey: true) }380 }381382 func signOut() async {383 _ = try? await backend.send("POST", "/api/auth/logout", body: BackendClient.Empty(), as: OK.self)384 clearLocalSession(forgetKey: true)385 }386387 func signOutEverywhere() async throws {388 struct Response: Decodable, Sendable { var ok: Bool }389 let _: Response = try await backend.send("POST", "/api/auth/logout-all", body: BackendClient.Empty())390 clearLocalSession(forgetKey: true)391 }392393 /// Deletes the account, its passkeys, devices and every synchronized record on the server. Local data stays on this device.394 func deleteAccount() async throws {395 try await run {396 try await confirmWithPasskey()397 let _: OK = try await backend.send("DELETE", "/api/account")398 clearLocalSession(forgetKey: true)399 }400 }401402 /// Erases the synchronized copy on the server (and the key material) but keeps the account.403 func eraseSyncedData() async throws {404 guard let key = keyBox.get() else { throw SyncFailure.keyUnavailable }405 let _: OK = try await backend.send("DELETE", "/api/sync/data", headers: ["X-SP-Key-Proof": SyncCrypto.keyProof(key)])406 secrets.setSecret(nil, for: Account.accountKey)407 keyBox.set(nil)408 keyStatus = .notSetUp409 onStateChange?()410 }411412 /// The server said the session is no longer valid (expired, revoked from another device).413 func sessionWasRejected() { if session != nil { clearLocalSession(forgetKey: false) } }414415 private func clearLocalSession(forgetKey: Bool) {416 secrets.setSecret(nil, for: Account.session)417 if forgetKey { secrets.setSecret(nil, for: Account.accountKey); keyBox.set(nil) }418 tokenBox.set(nil)419 session = nil420 keyStatus = .signedOut421 onStateChange?()422 }423}424