@authon/react-native-wallet 0.0.0-stage → 0.4.0

package/ios/vendor/AuthonWallet/Wallet/WalletOps.swift

@@ -0,0 +1,654 @@
+// GENERATED by scripts/sync-native-wallet.mjs from swift/Sources/AuthonWallet/Wallet/WalletOps.swift. Do not edit: change the source and run the script.
+import Foundation
+
+public struct WalletStatus: Equatable, Sendable {
+    public var exists: Bool
+    /// The server has a wallet that was never confirmed (device share not persisted).
+    public var pending: Bool
+    public var hasLocalShare: Bool
+    public var needsRestore: Bool
+    public var deviceId: String?
+    public var wallet: ServerWallet?
+}
+
+/// What apps see (ops.ts toPublicWallet).
+public struct PublicWallet: Equatable, Sendable {
+    public struct Device: Equatable, Sendable {
+        public var id: String
+        public var label: String?
+        public var createdAt: String?
+        public var lastUsedAt: String?
+        public var current: Bool
+    }
+
+    public var address: String
+    /// False until a passkey backup exists. An unprotected wallet is lost with this device.
+    public var isProtected: Bool
+    /// A legacy backup without a passkey public key; call upgradeBackup() from a device that holds the wallet.
+    public var backupUpgradeRecommended: Bool
+    public var needsRestore: Bool
+    public var devices: [Device]
+
+    init(_ st: WalletStatus) throws {
+        guard let w = st.wallet, !st.pending else { throw WalletError(.notFound) }
+        address = w.address
+        isProtected = w.isProtected
+        backupUpgradeRecommended = w.isProtected && w.backupVerifiable == false
+        needsRestore = st.needsRestore
+        devices = w.devices.filter { $0.revokedAt == nil }.map {
+            Device(id: $0.id, label: $0.label, createdAt: $0.createdAt, lastUsedAt: $0.lastUsedAt, current: $0.id == st.deviceId)
+        }
+    }
+}
+
+public struct WalletAccount: Equatable, Sendable {
+    public var index: Int
+    public var path: String
+    public var address: String
+    public var chain: WalletChain
+    /// XRP only: the compressed public key (uppercase hex) to put in SigningPubKey.
+    public var publicKey: String? = nil
+}
+
+/// Which account signs. Account 0 is the wallet address the server knows; another account
+/// must name the address the caller expects, and signing is refused when it differs.
+public struct SignAccount: Equatable, Sendable {
+    public var index: Int
+    public var address: String?
+
+    public static let primary = SignAccount(index: 0, address: nil)
+
+    public init(index: Int, address: String?) {
+        self.index = index
+        self.address = address
+    }
+
+    /// ops.ts parseSignAccount.
+    public static func parse(index: Int?, address: String?) throws -> SignAccount {
+        guard let index, index != 0 else { return .primary }
+        guard WalletShares.isAccountIndex(index) else {
+            throw WalletError(.invalidRequest, "account must be an integer 0..\(WalletShares.maxAccountIndex)")
+        }
+        guard let address, address.count == 42, address.hasPrefix("0x"), Bytes.isHex(address) else {
+            throw WalletError(.invalidRequest, "address of the signing account required")
+        }
+        return SignAccount(index: index, address: address)
+    }
+}
+
+/// A personal_sign payload.
+public enum WalletMessage: Equatable, Sendable {
+    case text(String)
+    /// 0x-prefixed hex bytes.
+    case raw(String)
+}
+
+enum ParsedMessage: Equatable {
+    case text(String)
+    case raw(String)
+}
+
+public enum RestoreMode: String, Sendable {
+    /// Enroll this device on the current shares; other devices keep working.
+    case add
+    /// Re-split the key and revoke every other device (lost device).
+    case reset
+}
+
+public struct ProtectResult: Equatable, Sendable {
+    public var shareVersion: Int
+}
+
+public struct RestoreResult: Equatable, Sendable {
+    public var shareVersion: Int
+    public var backupUpgradeRecommended: Bool
+}
+
+struct WalletContext {
+    var api: WalletAPIClient
+    var store: DeviceStore
+    var passkeys: PasskeyProvider
+    var projectId: String
+    /// From the project's server-side settings only.
+    var confirmSigning: Bool
+    var backupVersion: BackupVersion
+    var approver: WalletApprover?
+    var deviceAuthenticator: DeviceAuthenticator?
+}
+
+/// The wallet operations, step for step the same as `apps/wallet/src/ops.ts`.
+struct WalletOps {
+    let ctx: WalletContext
+
+    static func decodeUserId(_ session: String) throws -> String {
+        let parts = session.split(separator: ".", omittingEmptySubsequences: false)
+        guard parts.count > 1, !parts[1].isEmpty else { throw WalletError(.unauthorized, "malformed session token") }
+        guard let bytes = Bytes.fromBase64(String(parts[1])),
+              let claims = try? JSONValue.parse(String(decoding: bytes, as: UTF8.self)),
+              case .string(let sub) = claims["sub"] ?? .null, !sub.isEmpty else {
+            throw WalletError(.unauthorized, "malformed session token")
+        }
+        return sub
+    }
+
+    private func recordKey(_ session: String) throws -> String {
+        storageKey(projectId: ctx.projectId, userId: try Self.decodeUserId(session))
+    }
+
+    func status(_ session: String) async throws -> WalletStatus {
+        let wallet = try await ctx.api.getMe(session)
+        let local = try ctx.store.get(try recordKey(session))
+        let pending = wallet?.status == "pending"
+        // A local share only counts while the server still trusts this device at the current share version.
+        var hasLocal = false
+        if !pending, let local, let wallet, local.walletId == wallet.id,
+           let device = wallet.devices.first(where: { $0.id == local.deviceId }), device.revokedAt == nil {
+            hasLocal = (device.shareVersion ?? local.shareVersion) == wallet.shareVersion && local.shareVersion == wallet.shareVersion
+        }
+        let exists = wallet != nil && !pending
+        return WalletStatus(
+            exists: exists,
+            pending: pending,
+            hasLocalShare: hasLocal,
+            needsRestore: exists && !hasLocal,
+            deviceId: hasLocal ? local?.deviceId : nil,
+            wallet: wallet
+        )
+    }
+
+    private func deviceProof(_ session: String, _ record: DeviceRecord) async throws -> DeviceProof {
+        let challenge = try await ctx.api.challenge(session, deviceId: record.deviceId)
+        let signature = Bytes.base64(try ctx.store.sign(challenge: challenge, record: record))
+        return DeviceProof(deviceId: record.deviceId, challenge: challenge, signature: signature)
+    }
+
+    /// Reads the record back and checks it opens to `share`; storage that drops writes fails here.
+    @discardableResult
+    private func verifyPersisted(_ key: String, deviceId: String, walletId: String, share: [UInt8]?) throws -> DeviceRecord {
+        guard let stored = try? ctx.store.get(key), stored.deviceId == deviceId, stored.walletId == walletId else {
+            throw WalletError(.storageUnavailable, "device share was not persisted")
+        }
+        if let share {
+            var opened: [UInt8]
+            do {
+                opened = try ctx.store.open(stored)
+            } catch {
+                throw WalletError(.storageUnavailable, "device share cannot be read back")
+            }
+            defer { opened.wipe() }
+            guard opened == share else { throw WalletError(.storageUnavailable, "device share read back differs") }
+        }
+        return stored
+    }
+
+    /// Confirms a pending wallet whose device record is present and readable here.
+    private func finishPending(_ session: String, _ wallet: ServerWallet) async throws -> Bool {
+        let key = try recordKey(session)
+        guard let record = try? ctx.store.get(key), record.walletId == wallet.id,
+              wallet.devices.contains(where: { $0.id == record.deviceId }) else { return false }
+        do {
+            var share = try ctx.store.open(record)
+            defer { share.wipe() }
+            try verifyPersisted(key, deviceId: record.deviceId, walletId: wallet.id, share: share)
+        } catch {
+            return false
+        }
+        try await ctx.api.confirmWallet(session, try await deviceProof(session, record))
+        return true
+    }
+
+    /// Two-phase creation: register address and A (pending), store D and read it back, then
+    /// confirm with a challenge signed by the stored device key. A pending wallet left by an
+    /// interrupted attempt is confirmed (D is here) or discarded and recreated (D is not).
+    func create(_ session: String, attempt: Int = 0) async throws -> WalletStatus {
+        let existing = try await status(session)
+        if existing.exists { return existing }
+        if existing.pending, let w = existing.wallet {
+            if try await finishPending(session, w) { return try await status(session) }
+            if attempt > 0 { throw WalletError(.storageUnavailable) }
+            try await ctx.api.discardPending(session)
+            try? ctx.store.delete(try recordKey(session))
+            return try await create(session, attempt: attempt + 1)
+        }
+
+        let key = try recordKey(session)
+        let userId = try Self.decodeUserId(session)
+        var secret = try WalletShares.generateSecret()
+        var device = [UInt8]()
+        var company = [UInt8]()
+        var registered = false
+        var keys: DeviceKeys?
+        var stored = false
+        defer {
+            secret.wipe()
+            device.wipe()
+            company.wipe()
+        }
+        do {
+            let address = try WalletShares.address(secret)
+            (device, company) = try WalletShares.splitUnprotected(secret)
+            let k = try ctx.store.generateKeys()
+            keys = k
+            let sealed = try ctx.store.seal(device, keys: k, storageKey: key)
+            let bound = try await ctx.api.proofChallenge(session, kind: .create)
+            let proof = try WalletProof.signCreate(secret, projectId: ctx.projectId, userId: userId, deviceKey: k.publicJwk, bound: bound)
+            let created = try await ctx.api.createWallet(session, address: address, companyShare: Bytes.base64(company), devicePublicKey: k.publicJwk, proof: proof, bound: bound)
+            registered = true
+            let record = DeviceRecord(
+                key: key, deviceId: created.deviceId, walletId: created.walletId, address: address,
+                shareVersion: created.shareVersion, createdAt: Date().timeIntervalSince1970 * 1000,
+                publicJwk: k.publicJwk, keyHandle: k.handle, sealedShare: sealed
+            )
+            do {
+                try ctx.store.put(record)
+            } catch {
+                throw WalletError(.storageUnavailable, "device share was not persisted")
+            }
+            stored = true
+            let readBack = try verifyPersisted(key, deviceId: created.deviceId, walletId: created.walletId, share: device)
+            try await ctx.api.confirmWallet(session, try await deviceProof(session, readBack))
+        } catch {
+            if !stored, let keys { ctx.store.discardKeys(keys) }
+            if let e = error as? WalletError, e.code == .alreadyExists, attempt == 0 {
+                return try await create(session, attempt: attempt + 1)
+            }
+            if registered, let e = error as? WalletError, e.code == .storageUnavailable {
+                try? await ctx.api.discardPending(session)
+                try? ctx.store.delete(key)
+            }
+            throw error
+        }
+        return try await status(session)
+    }
+
+    private func requireLocal(_ session: String) async throws -> (record: DeviceRecord, wallet: ServerWallet) {
+        guard let wallet = try await ctx.api.getMe(session), wallet.status != "pending" else { throw WalletError(.notFound) }
+        guard let record = try ctx.store.get(try recordKey(session)), record.walletId == wallet.id else {
+            throw WalletError(.needsRestore)
+        }
+        return (record, wallet)
+    }
+
+    private func fetchCompanyShare(_ session: String, _ record: DeviceRecord) async throws -> [UInt8] {
+        let b64 = try await ctx.api.releaseShare(session, try await deviceProof(session, record))
+        guard let bytes = Bytes.fromBase64(b64) else { throw WalletError(.apiError) }
+        return bytes
+    }
+
+    /// The user's approval for a signature, before A is requested. No approver means no signature.
+    private func approve(_ summary: SignSummary) async throws {
+        guard let approver = ctx.approver else { throw WalletError(.internal, "confirmation unavailable") }
+        try await approver.approveSignature(summary)
+    }
+
+    private func withSecret<T>(
+        _ session: String,
+        account target: SignAccount,
+        summary build: (() throws -> SignSummary)?,
+        _ fn: (EvmAccount) throws -> T
+    ) async throws -> T {
+        // Built (and size-checked) only when someone will see it.
+        let summary = try build.flatMap { b in ctx.confirmSigning ? Summaries.withAccountRow(try b(), target) : nil }
+        let local = try await requireLocal(session)
+        if let summary { try await approve(summary) }
+        if let auth = ctx.deviceAuthenticator { try await auth.authenticate(reason: summary?.title ?? "Sign with your wallet") }
+        var company = try await fetchCompanyShare(session, local.record)
+        var device = try ctx.store.open(local.record)
+        var secret = [UInt8]()
+        defer {
+            secret.wipe()
+            device.wipe()
+            company.wipe()
+        }
+        secret = try WalletShares.assemble(device, company)
+        let primary = try WalletShares.account(secret)
+        defer { primary.wipe() }
+        guard primary.address.lowercased() == local.wallet.address.lowercased() else { throw WalletError(.addressMismatch) }
+        if target.index == 0 { return try fn(primary) }
+        guard WalletShares.isHdSecret(secret) else { throw WalletError(.accountUnavailable, "this wallet has only account 0") }
+        let account = try WalletShares.account(secret, index: target.index)
+        defer { account.wipe() }
+        guard account.address.lowercased() == target.address?.lowercased() else { throw WalletError(.addressMismatch) }
+        return try fn(account)
+    }
+
+    func accounts(_ session: String, start: Int = 0, count: Int = 1, chain: WalletChain = .evm) async throws -> [WalletAccount] {
+        guard WalletShares.isAccountIndex(start), count >= 1, WalletShares.isAccountIndex(start + count - 1) else {
+            throw WalletError(.invalidRequest, "start..start+count-1 must stay within 0..\(WalletShares.maxAccountIndex)")
+        }
+        let local = try await requireLocal(session)
+        var company = try await fetchCompanyShare(session, local.record)
+        var device = try ctx.store.open(local.record)
+        var secret = [UInt8]()
+        defer {
+            secret.wipe()
+            device.wipe()
+            company.wipe()
+        }
+        secret = try WalletShares.assemble(device, company)
+        guard try WalletShares.address(secret).lowercased() == local.wallet.address.lowercased() else { throw WalletError(.addressMismatch) }
+        if chain != .evm {
+            let list = try ChainAddresses.addresses(secret, chain: chain, start: start, count: count)
+            let keys = chain == .xrp ? try ChainAddresses.xrpPublicKeys(secret, start: start, count: count) : nil
+            return list.enumerated().map {
+                WalletAccount(index: start + $0.offset, path: chain.path(start + $0.offset), address: $0.element, chain: chain, publicKey: keys?[$0.offset])
+            }
+        }
+        if !WalletShares.isHdSecret(secret) && (start != 0 || count != 1) {
+            throw WalletError(.accountUnavailable, "this wallet has only account 0")
+        }
+        let list = try WalletShares.addresses(secret, start: start, count: count)
+        return list.enumerated().map { WalletAccount(index: start + $0.offset, path: WalletShares.evmPath(start + $0.offset), address: $0.element, chain: .evm) }
+    }
+
+    private static func reserved() -> WalletError {
+        WalletError(.invalidRequest, "this message is reserved for wallet key proofs and cannot be signed")
+    }
+
+    static func parseMessage(_ m: WalletMessage) throws -> ParsedMessage {
+        switch m {
+        case .text(let s): return .text(s)
+        case .raw(let hex):
+            guard hex.hasPrefix("0x"), Bytes.isHex(hex) else { throw WalletError(.invalidRequest, "message must be a string or {raw}") }
+            return .raw(hex)
+        }
+    }
+
+    func signMessage(_ session: String, _ message: WalletMessage, account: SignAccount = .primary) async throws -> String {
+        let parsed = try Self.parseMessage(message)
+        let text: String?
+        let payload: EvmAccount.Message
+        switch parsed {
+        case .text(let s):
+            text = s
+            payload = .text(s)
+        case .raw(let hex):
+            text = WalletProof.rawMessageText(hex)
+            payload = .raw(Bytes.fromHex(hex) ?? [])
+        }
+        if let text, WalletProof.isReservedMessageText(text) { throw Self.reserved() }
+        return try await withSecret(session, account: account, summary: { try Summaries.message(parsed) }) { try $0.signMessage(payload) }
+    }
+
+    func signTypedData(_ session: String, _ typedData: JSONValue, account: SignAccount = .primary) async throws -> String {
+        guard case .object = typedData else { throw WalletError(.invalidRequest) }
+        guard typedData["types"]?.isTruthy == true, typedData["primaryType"]?.isTruthy == true, typedData["message"]?.isTruthy == true else {
+            throw WalletError(.invalidRequest, "typedData incomplete")
+        }
+        if WalletProof.isReservedTypedData(typedData) { throw Self.reserved() }
+        let td = try TypedData(typedData)
+        // Malformed typed data is refused before anyone is asked to approve it.
+        _ = try td.digest()
+        return try await withSecret(session, account: account, summary: { try Summaries.typedData(typedData) }) { try $0.signTypedData(td) }
+    }
+
+    private static let bigintFields = ["value", "gas", "gasPrice", "maxFeePerGas", "maxPriorityFeePerGas", "maxFeePerBlobGas"]
+    private static let numberFields = ["nonce", "chainId"]
+
+    /// ops.ts parseTransaction: numeric fields as BigInt, nonce and chainId as Number.
+    static func parseTransaction(_ value: JSONValue) throws -> JSONObject {
+        guard var tx = value.objectValue else { throw WalletError(.invalidRequest) }
+        for f in bigintFields + numberFields {
+            guard let v = tx[f] else { continue }
+            guard let n = v.jsBigInt else { throw WalletError(.invalidRequest, "transaction numeric field invalid") }
+            tx[f] = .number(n.description)
+        }
+        guard tx["chainId"] != nil else { throw WalletError(.invalidRequest, "chainId required") }
+        return tx
+    }
+
+    func signTransaction(_ session: String, _ transaction: JSONValue, account: SignAccount = .primary) async throws -> String {
+        let tx = try Self.parseTransaction(transaction)
+        let evmTx = try EvmTransaction(tx)
+        return try await withSecret(session, account: account, summary: { Summaries.transaction(tx) }) { try $0.signTransaction(evmTx) }
+    }
+
+    /// Signs a transaction on a chain other than EVM (section 12; Solana and TRON). The summary is
+    /// built from the payload and the expected address before the company share is requested.
+    func signChainTransaction(_ session: String, chain: WalletChain, account index: Int, address: String, payload: JSONValue) async throws -> [String: String] {
+        guard WalletShares.isAccountIndex(index) else {
+            throw WalletError(.invalidRequest, "account must be an integer 0..\(WalletShares.maxAccountIndex)")
+        }
+        guard !address.isEmpty else { throw WalletError(.invalidRequest, "address of the signing account required") }
+        let summary: SignSummary
+        let sign: ([UInt8]) throws -> [String: String]
+        switch chain {
+        case .solana:
+            guard case .string(let b64) = payload["message"] ?? .null, let message = Bytes.fromBase64(b64) else {
+                throw WalletError(.invalidRequest, "payload.message (base64) required")
+            }
+            let network: String
+            if case .string(let cluster) = payload["cluster"] ?? .null, cluster.utf16.count <= 32 {
+                network = "Solana \(cluster)"
+            } else {
+                network = "Solana (network chosen by the app)"
+            }
+            summary = try Solana.summarize(try Solana.parse(message), signer: address, network: network)
+            sign = { secret in
+                var key = try Solana.privateKey(secret, index: index)
+                defer { key.wipe() }
+                let signed = Solana.sign(message, privateKey: key)
+                guard signed.address == address else { throw WalletError(.addressMismatch) }
+                return ["signature": signed.signature]
+            }
+        case .bitcoin, .bitcoinTestnet:
+            guard case .string(let b64) = payload["psbt"] ?? .null, let bytes = Bytes.fromBase64(b64) else {
+                throw WalletError(.invalidRequest, "payload.psbt (base64) required")
+            }
+            let psbt = try Bitcoin.parse(bytes)
+            summary = try Bitcoin.summarize(psbt, signer: address, chain: chain)
+            sign = { secret in
+                var key = try ChainAddresses.secpPrivateKey(secret, chain: chain, index: index)
+                defer { key.wipe() }
+                guard try ChainAddresses.secpAddress(chain, privateKey: key) == address else { throw WalletError(.addressMismatch) }
+                return try Bitcoin.sign(psbt, privateKey: key)
+            }
+        case .xrp:
+            guard case .string(let hex) = payload["txBlobHex"] ?? .null, Self.isPlainHex(hex), let blob = Bytes.fromHex(hex) else {
+                throw WalletError(.invalidRequest, "payload.txBlobHex (encodeForSigning output) required")
+            }
+            let tx = try XRP.parse(blob)
+            guard tx.account == address else { throw WalletError(.addressMismatch, "the transaction account is not the signing account") }
+            summary = try XRP.summarize(tx, signer: address, signerPublicKey: tx.signingPubKey!)
+            sign = { secret in
+                var key = try ChainAddresses.secpPrivateKey(secret, chain: .xrp, index: index)
+                defer { key.wipe() }
+                let pub = try Secp256k1.publicKey(of: key, compressed: true)
+                guard try XRP.address(publicKey: pub) == address, pub == tx.signingPubKey else { throw WalletError(.addressMismatch) }
+                return try XRP.sign(blob, privateKey: key)
+            }
+        case .evm:
+            throw WalletError(.unsupportedType, "use signTransaction for EVM")
+        case .tron:
+            guard case .string(let hex) = payload["rawDataHex"] ?? .null, Self.isPlainHex(hex), let raw = Bytes.fromHex(hex) else {
+                throw WalletError(.invalidRequest, "payload.rawDataHex required")
+            }
+            summary = try Tron.summarize(try Tron.parse(raw), signer: address)
+            sign = { secret in
+                var key = try ChainAddresses.secpPrivateKey(secret, chain: .tron, index: index)
+                defer { key.wipe() }
+                guard try ChainAddresses.secpAddress(.tron, privateKey: key) == address else { throw WalletError(.addressMismatch) }
+                return try Tron.sign(raw, privateKey: key)
+            }
+        }
+        let local = try await requireLocal(session)
+        if ctx.confirmSigning { try await approve(summary) }
+        if let auth = ctx.deviceAuthenticator { try await auth.authenticate(reason: summary.title) }
+        var company = try await fetchCompanyShare(session, local.record)
+        var device = try ctx.store.open(local.record)
+        var secret = [UInt8]()
+        defer {
+            secret.wipe()
+            device.wipe()
+            company.wipe()
+        }
+        secret = try WalletShares.assemble(device, company)
+        guard try WalletShares.address(secret).lowercased() == local.wallet.address.lowercased() else { throw WalletError(.addressMismatch) }
+        return try sign(secret)
+    }
+
+    /// /^([0-9a-fA-F]{2})+$/
+    static func isPlainHex(_ s: String) -> Bool {
+        !s.isEmpty && s.count % 2 == 0 && s.utf8.allSatisfy { (0x30...0x39).contains($0) || (0x41...0x46).contains($0) || (0x61...0x66).contains($0) }
+    }
+
+    // MARK: - Backup
+
+    private func writeBackup(_ session: String, upgrade: Bool) async throws -> ProtectResult {
+        let (record, wallet) = try await requireLocal(session)
+        if !upgrade && wallet.isProtected { return ProtectResult(shareVersion: wallet.shareVersion) }
+        if upgrade {
+            guard wallet.isProtected else { throw WalletError(.notProtected) }
+            guard wallet.backupVerifiable == false else { throw WalletError(.alreadyUpgraded) }
+        }
+        let key = try recordKey(session)
+        let user = try Self.decodeUserId(session)
+        let version = ctx.backupVersion
+        let salt = WalletBackup.prfSalt(version, projectId: ctx.projectId, walletId: wallet.id)
+        let passkeyUser = WalletBackup.passkeyUserId(projectId: ctx.projectId, userId: user)
+        if let approver = ctx.approver { try await approver.confirmPasskeyAction(upgrade ? .upgradeBackup : .protect) }
+        var pk = try await ctx.passkeys.create(userId: passkeyUser, userName: wallet.address, salt: salt)
+        var oldCompany = [UInt8]()
+        var oldDevice = [UInt8]()
+        var secret = [UInt8]()
+        var shares: (device: [UInt8], company: [UInt8], backup: [UInt8]) = ([], [], [])
+        defer {
+            pk.prfOutput.wipe()
+            oldCompany.wipe()
+            oldDevice.wipe()
+            secret.wipe()
+            shares.device.wipe()
+            shares.company.wipe()
+            shares.backup.wipe()
+        }
+        oldCompany = try await fetchCompanyShare(session, record)
+        oldDevice = try ctx.store.open(record)
+        secret = try WalletShares.assemble(oldDevice, oldCompany)
+        guard try WalletShares.address(secret).lowercased() == wallet.address.lowercased() else { throw WalletError(.addressMismatch) }
+        shares = try WalletShares.splitProtected(secret)
+        let backupKey = WalletBackup.deriveKey(prfOutput: pk.prfOutput)
+        let backupCiphertext = try WalletBackup.encrypt(key: backupKey, share: shares.backup, walletId: wallet.id, version: version)
+        let proof = try await deviceProof(session, record)
+        let keyFields: WalletAPIClient.BackupKeyFields
+        if let pub = pk.publicKey, let alg = pk.publicKeyAlg {
+            keyFields = .init(credentialPublicKey: pub, credentialAlg: alg)
+        } else {
+            keyFields = .init(attestationObject: pk.attestationObject)
+        }
+        let shareVersion = try await ctx.api.putBackup(
+            session, proof: proof, backupCiphertext: backupCiphertext, credentialId: pk.credentialId,
+            newCompanyShare: Bytes.base64(shares.company), key: keyFields, upgrade: upgrade
+        )
+        let sealed = try ctx.store.seal(shares.device, keys: DeviceKeys(handle: record.keyHandle, publicJwk: record.publicJwk), storageKey: key)
+        var updated = record
+        updated.sealedShare = sealed
+        updated.shareVersion = shareVersion
+        try ctx.store.put(updated)
+        return ProtectResult(shareVersion: shareVersion)
+    }
+
+    func protect(_ session: String) async throws -> ProtectResult { try await writeBackup(session, upgrade: false) }
+
+    /// Replaces a legacy backup (no passkey public key) from a device that holds the wallet.
+    func upgradeBackup(_ session: String) async throws -> ProtectResult { try await writeBackup(session, upgrade: true) }
+
+    func restore(_ session: String, mode: RestoreMode = .add) async throws -> RestoreResult {
+        guard let wallet = try await ctx.api.getMe(session), wallet.status != "pending" else { throw WalletError(.notFound) }
+        let start = try await ctx.api.restoreStart(session)
+        guard let ciphertext = start.backupCiphertext, !ciphertext.isEmpty, let credentialId = start.credentialId, !credentialId.isEmpty else {
+            throw WalletError(.notProtected)
+        }
+        let key = try recordKey(session)
+        let version = WalletBackup.version(of: ciphertext)
+        let salt = WalletBackup.prfSalt(version, projectId: ctx.projectId, walletId: wallet.id)
+        let challenge = start.passkeyChallenge.flatMap(Bytes.fromBase64)
+        if let approver = ctx.approver { try await approver.confirmPasskeyAction(mode == .reset ? .restoreReset : .restore) }
+        var got = try await ctx.passkeys.get(credentialId: credentialId, salt: salt, challenge: challenge)
+        var company = [UInt8]()
+        var backup = [UInt8]()
+        var secret = [UInt8]()
+        var shares: (device: [UInt8], company: [UInt8], backup: [UInt8]) = ([], [], [])
+        defer {
+            got.prfOutput.wipe()
+            company.wipe()
+            backup.wipe()
+            secret.wipe()
+            shares.device.wipe()
+            shares.company.wipe()
+            shares.backup.wipe()
+        }
+        let backupKey = WalletBackup.deriveKey(prfOutput: got.prfOutput)
+        backup = try WalletBackup.decrypt(key: backupKey, payload: ciphertext, walletId: wallet.id)
+        let companyB64: String
+        if let c = start.companyShare, !c.isEmpty {
+            companyB64 = c
+        } else {
+            companyB64 = try await ctx.api.restoreAssert(session, got.assertion, challenge: start.passkeyChallenge ?? "")
+        }
+        guard let c = Bytes.fromBase64(companyB64) else { throw WalletError(.apiError) }
+        company = c
+        secret = try WalletShares.assemble(backup, company)
+        guard try WalletShares.address(secret).lowercased() == wallet.address.lowercased() else { throw WalletError(.addressMismatch) }
+
+        let upgradeRecommended = start.upgradeRecommended
+        if mode == .add {
+            let shareVersion = try await addThisDevice(session, key: key, wallet: wallet, secret: secret, company: company, backup: backup)
+            return RestoreResult(shareVersion: shareVersion, backupUpgradeRecommended: upgradeRecommended)
+        }
+
+        shares = try WalletShares.splitProtected(secret)
+        let keys = try ctx.store.generateKeys()
+        var stored = false
+        defer { if !stored { ctx.store.discardKeys(keys) } }
+        let bound = try await ctx.api.proofChallenge(session, kind: .restore)
+        let proof = try WalletProof.signRestore(secret, walletId: wallet.id, currentShareVersion: wallet.shareVersion, deviceKey: keys.publicJwk, bound: bound)
+        // The PRF output belongs to this backup's salt version, so the new backup keeps it.
+        let newBackup = try WalletBackup.encrypt(key: backupKey, share: shares.backup, walletId: wallet.id, version: version)
+        let res = try await ctx.api.restore(
+            session, newCompanyShare: Bytes.base64(shares.company), newBackupCiphertext: newBackup,
+            newDevicePublicKey: keys.publicJwk, credentialId: credentialId, proof: proof, bound: bound
+        )
+        let sealed = try ctx.store.seal(shares.device, keys: keys, storageKey: key)
+        try ctx.store.put(DeviceRecord(
+            key: key, deviceId: res.deviceId, walletId: wallet.id, address: wallet.address, shareVersion: res.shareVersion,
+            createdAt: Date().timeIntervalSince1970 * 1000, publicJwk: keys.publicJwk, keyHandle: keys.handle, sealedShare: sealed
+        ))
+        stored = true
+        return RestoreResult(shareVersion: res.shareVersion, backupUpgradeRecommended: upgradeRecommended)
+    }
+
+    private func addThisDevice(_ session: String, key: String, wallet: ServerWallet, secret: [UInt8], company: [UInt8], backup: [UInt8]) async throws -> Int {
+        var device = try WalletShares.deriveShare(company, backup)
+        var check1 = [UInt8]()
+        var check2 = [UInt8]()
+        defer {
+            device.wipe()
+            check1.wipe()
+            check2.wipe()
+        }
+        check1 = try WalletShares.assemble(device, company)
+        check2 = try WalletShares.assemble(device, backup)
+        guard check1 == secret, check2 == secret else { throw WalletError(.internal, "derived share mismatch") }
+        let keys = try ctx.store.generateKeys()
+        var stored = false
+        defer { if !stored { ctx.store.discardKeys(keys) } }
+        let bound = try await ctx.api.proofChallenge(session, kind: .device)
+        let proof = try WalletProof.signDevice(secret, walletId: wallet.id, shareVersion: wallet.shareVersion, deviceKey: keys.publicJwk, bound: bound)
+        let res = try await ctx.api.addDevice(session, devicePublicKey: keys.publicJwk, proof: proof, bound: bound)
+        let sealed = try ctx.store.seal(device, keys: keys, storageKey: key)
+        try ctx.store.put(DeviceRecord(
+            key: key, deviceId: res.deviceId, walletId: wallet.id, address: wallet.address, shareVersion: res.shareVersion,
+            createdAt: Date().timeIntervalSince1970 * 1000, publicJwk: keys.publicJwk, keyHandle: keys.handle, sealedShare: sealed
+        ))
+        stored = true
+        return res.shareVersion
+    }
+
+    /// Revokes a device with a request signed by this device's key.
+    func revokeDevice(_ session: String, deviceId: String) async throws {
+        guard !deviceId.isEmpty else { throw WalletError(.invalidRequest, "deviceId required") }
+        let (record, _) = try await requireLocal(session)
+        try await ctx.api.revokeDevice(session, deviceId: deviceId, proof: try await deviceProof(session, record))
+        if record.deviceId == deviceId { try ctx.store.delete(try recordKey(session)) }
+    }
+}