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

package/android/src/vendor/kotlin/dev/authon/sdk/wallet/WalletOps.kt

@@ -0,0 +1,551 @@
+// GENERATED by scripts/sync-native-wallet.mjs from kotlin/authon/src/main/kotlin/dev/authon/sdk/wallet/WalletOps.kt. Do not edit: change the source and run the script.
+package dev.authon.sdk.wallet
+
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+
+internal class WalletContext(
+    val api: WalletApi,
+    val store: DeviceStore,
+    val passkeys: PasskeyProvider,
+    val projectId: String,
+    /** From the project's server-side settings only. */
+    val confirmSigning: Boolean = true,
+    /** PRF salt version for new backups (server flag). */
+    val backupVersion: Int = Prf.DEFAULT_WRITE_BACKUP_VERSION,
+    val approver: WalletApprover? = null,
+    val deviceAuthenticator: DeviceAuthenticator? = null,
+)
+
+internal data class WalletStatus(
+    val exists: Boolean,
+    val pending: Boolean,
+    val hasLocalShare: Boolean,
+    val needsRestore: Boolean,
+    val deviceId: String?,
+    val wallet: ServerWallet?,
+)
+
+/** The flows of `apps/wallet/src/ops.ts`, step for step. */
+internal class WalletOps(private val ctx: WalletContext) {
+
+    fun toPublicWallet(st: WalletStatus): PublicWallet {
+        val w = st.wallet
+        if (w == null || st.pending) throw walletError(WalletErrorCode.NOT_FOUND)
+        return PublicWallet(
+            address = w.address,
+            protected = w.protected,
+            backupUpgradeRecommended = w.protected && w.backupVerifiable == false,
+            needsRestore = st.needsRestore,
+            devices = w.devices.filter { it.revokedAt == null }.map {
+                PublicWallet.Device(it.id, it.label, it.createdAt, it.lastUsedAt, it.id == st.deviceId)
+            },
+        )
+    }
+
+    private fun recordKey(session: String) = DeviceStorage.storageKey(ctx.projectId, decodeUserId(session))
+
+    suspend fun status(session: String): WalletStatus {
+        val wallet = ctx.api.getMe(session)
+        val local = ctx.store.get(recordKey(session))
+        val pending = wallet?.status == "pending"
+        val device = if (local != null && wallet != null) wallet.devices.firstOrNull { it.id == local.deviceId } else null
+        val hasLocal = !pending && local != null && wallet != null && local.walletId == wallet.id && device != null &&
+            device.revokedAt == null && (device.shareVersion ?: local.shareVersion) == wallet.shareVersion &&
+            local.shareVersion == wallet.shareVersion
+        val exists = wallet != null && !pending
+        return WalletStatus(exists, pending, hasLocal, exists && !hasLocal, if (hasLocal) local!!.deviceId else null, wallet)
+    }
+
+    private fun openShare(record: DeviceRecord): ByteArray = try {
+        record.keys.open(SealedShare(record.iv, record.ciphertext), Bytes.utf8(record.key))
+    } catch (e: Exception) {
+        throw WalletException(WalletErrorCode.NEEDS_RESTORE, "local share unreadable", e)
+    }
+
+    private suspend fun deviceProof(session: String, record: DeviceRecord): DeviceProof {
+        val challenge = ctx.api.challenge(session, record.deviceId)
+        val signature = try {
+            record.keys.sign(Bytes.utf8(challenge))
+        } catch (e: Exception) {
+            throw WalletException(WalletErrorCode.NEEDS_RESTORE, "device key unavailable", e)
+        }
+        return DeviceProof(record.deviceId, challenge, Bytes.toBase64(signature))
+    }
+
+    /** Reads the record back and checks that it opens to [share]; storage that drops writes fails here. */
+    private suspend fun verifyPersisted(key: String, deviceId: String, walletId: String, share: ByteArray?): DeviceRecord {
+        val stored = ctx.store.get(key)
+        if (stored == null || stored.deviceId != deviceId || stored.walletId != walletId) {
+            throw walletError(WalletErrorCode.STORAGE_UNAVAILABLE, "device share was not persisted")
+        }
+        if (share != null) {
+            var opened: ByteArray? = null
+            try {
+                opened = openShare(stored)
+                if (!Bytes.sameBytes(opened, share)) throw walletError(WalletErrorCode.STORAGE_UNAVAILABLE, "device share read back differs")
+            } catch (e: WalletException) {
+                if (e.code == WalletErrorCode.STORAGE_UNAVAILABLE) throw e
+                throw walletError(WalletErrorCode.STORAGE_UNAVAILABLE, "device share cannot be read back")
+            } finally {
+                Bytes.wipe(opened)
+            }
+        }
+        return stored
+    }
+
+    private suspend fun finishPending(session: String, wallet: ServerWallet): Boolean {
+        val key = recordKey(session)
+        val record = ctx.store.get(key)
+        if (record == null || record.walletId != wallet.id || wallet.devices.none { it.id == record.deviceId }) return false
+        var share: ByteArray? = null
+        try {
+            share = openShare(record)
+            verifyPersisted(key, record.deviceId, wallet.id, share)
+        } catch (_: Exception) {
+            return false
+        } finally {
+            Bytes.wipe(share)
+        }
+        ctx.api.confirmWallet(session, deviceProof(session, record))
+        return true
+    }
+
+    /**
+     * Two-phase creation: register address + A (wallet pending), store D, read it back, then
+     * confirm with a challenge signed by the stored device key. A pending wallet left behind is
+     * confirmed (D is here) or discarded and recreated (D is not).
+     */
+    suspend fun createWallet(session: String, attempt: Int = 0): WalletStatus {
+        val existing = status(session)
+        if (existing.exists) return existing
+        if (existing.pending && existing.wallet != null) {
+            if (finishPending(session, existing.wallet)) return status(session)
+            if (attempt > 0) throw walletError(WalletErrorCode.STORAGE_UNAVAILABLE)
+            ctx.api.discardPending(session)
+            runCatching { ctx.store.delete(recordKey(session)) }
+            return createWallet(session, attempt + 1)
+        }
+
+        val key = recordKey(session)
+        val secret = HdWallet.generateSecret()
+        var shares: HdWallet.SplitShares? = null
+        var keys: DeviceKeys? = null
+        var stored = false
+        var registered = false
+        try {
+            val address = HdWallet.address(secret)
+            shares = HdWallet.splitUnprotected(secret)
+            keys = ctx.store.generateKeys()
+            val sealed = keys.seal(shares.device, Bytes.utf8(key))
+            val bound = ctx.api.proofChallenge(session, "create")
+            val proof = Proof.sign(secret, Proof.createTypedData(ctx.projectId, decodeUserId(session), keys.publicJwk, bound))
+            val created = ctx.api.createWallet(session, address, Bytes.toBase64(shares.company), keys.publicJwk, proof, bound)
+            registered = true
+            val record = DeviceRecord(
+                key, keys, sealed.iv, sealed.ciphertext, created.deviceId, created.walletId, address, created.shareVersion,
+                System.currentTimeMillis(),
+            )
+            ctx.store.put(record)
+            stored = true
+            val persisted = verifyPersisted(key, created.deviceId, created.walletId, shares.device)
+            ctx.api.confirmWallet(session, deviceProof(session, persisted))
+        } catch (e: WalletException) {
+            if (!stored) keys?.let { runCatching { ctx.store.discardKeys(it) } }
+            if (e.code == WalletErrorCode.ALREADY_EXISTS && attempt == 0) return createWallet(session, attempt + 1)
+            if (registered && e.code == WalletErrorCode.STORAGE_UNAVAILABLE) {
+                runCatching { ctx.api.discardPending(session) }
+                runCatching { ctx.store.delete(key) }
+            }
+            throw e
+        } catch (e: Exception) {
+            if (!stored) keys?.let { runCatching { ctx.store.discardKeys(it) } }
+            throw e
+        } finally {
+            Bytes.wipe(secret)
+            shares?.wipe()
+        }
+        return status(session)
+    }
+
+    private class Local(val record: DeviceRecord, val wallet: ServerWallet)
+
+    private suspend fun requireLocal(session: String): Local {
+        val wallet = ctx.api.getMe(session)
+        if (wallet == null || wallet.status == "pending") throw walletError(WalletErrorCode.NOT_FOUND)
+        val record = ctx.store.get(recordKey(session))
+        if (record == null || record.walletId != wallet.id) throw walletError(WalletErrorCode.NEEDS_RESTORE)
+        return Local(record, wallet)
+    }
+
+    private suspend fun fetchCompanyShare(session: String, record: DeviceRecord): String =
+        ctx.api.releaseShare(session, deviceProof(session, record))
+
+    private suspend fun approveRequest(summary: SignSummary) {
+        val approver = ctx.approver ?: throw walletError(WalletErrorCode.CONFIRM_WINDOW_BLOCKED, "no approval UI is available")
+        if (!approver.approve(summary)) throw walletError(WalletErrorCode.USER_CANCELLED)
+    }
+
+    private suspend fun authenticateDevice(reason: String) {
+        val auth = ctx.deviceAuthenticator ?: return
+        if (!auth.authenticate(reason)) throw walletError(WalletErrorCode.USER_CANCELLED)
+    }
+
+    private fun withAccountRow(summary: SignSummary, account: SignAccount): SignSummary =
+        if (account.index == 0L) summary else summary.copy(rows = listOf(SignRow("Account", account.address!!, mono = true)) + summary.rows)
+
+    private suspend fun <T> withSecret(
+        session: String,
+        approve: (() -> SignSummary)?,
+        target: SignAccount,
+        fn: (EvmAccount) -> T,
+    ): T {
+        val summary = if (approve != null && ctx.confirmSigning) withAccountRow(approve(), target) else null
+        val local = requireLocal(session)
+        // Approval comes before A is requested, so a rejected request never assembles k.
+        if (summary != null) approveRequest(summary)
+        if (approve != null) authenticateDevice(summary?.title ?: "Sign")
+        val companyB64 = fetchCompanyShare(session, local.record)
+        val device = openShare(local.record)
+        val company = Bytes.fromBase64(companyB64)
+        var secret: ByteArray? = null
+        try {
+            secret = HdWallet.assemble(device, company)
+            val primary = HdWallet.account(secret, 0)
+            if (!primary.address.equals(local.wallet.address, ignoreCase = true)) throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+            if (target.index == 0L) return fn(primary)
+            if (!HdWallet.isHdSecret(secret)) throw walletError(WalletErrorCode.ACCOUNT_UNAVAILABLE, "this wallet has only account 0")
+            val account = HdWallet.account(secret, target.index)
+            if (!account.address.equals(target.address, ignoreCase = true)) throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+            return fn(account)
+        } finally {
+            Bytes.wipe(secret, device, company)
+        }
+    }
+
+    suspend fun accounts(session: String, start: Long, count: Int, chain: WalletChain = WalletChain.EVM): List<WalletAccount> {
+        if (!HdWallet.isAccountIndex(start) || count < 1 || !HdWallet.isAccountIndex(start + count - 1)) {
+            throw walletError(WalletErrorCode.INVALID_REQUEST, "start..start+count-1 must stay within 0..${HdWallet.MAX_ACCOUNT_INDEX}")
+        }
+        val local = requireLocal(session)
+        val companyB64 = fetchCompanyShare(session, local.record)
+        val device = openShare(local.record)
+        val company = Bytes.fromBase64(companyB64)
+        var secret: ByteArray? = null
+        try {
+            secret = HdWallet.assemble(device, company)
+            if (!HdWallet.address(secret).equals(local.wallet.address, ignoreCase = true)) throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+            if (chain != WalletChain.EVM) {
+                return Chains.addresses(secret, chain, start, count).mapIndexed { i, a ->
+                    val publicKey = if (chain == WalletChain.XRP) Bytes.toHex(Chains.secpPublicKey(secret, chain, start + i)).uppercase() else null
+                    WalletAccount(start + i, Chains.path(chain, start + i), a, chain, publicKey)
+                }
+            }
+            if (!HdWallet.isHdSecret(secret) && (start != 0L || count != 1)) {
+                throw walletError(WalletErrorCode.ACCOUNT_UNAVAILABLE, "this wallet has only account 0")
+            }
+            return HdWallet.addresses(secret, start, count).mapIndexed { i, a -> WalletAccount(start + i, HdWallet.evmPath(start + i), a) }
+        } finally {
+            Bytes.wipe(secret, device, company)
+        }
+    }
+
+    private fun reserved() = walletError(WalletErrorCode.INVALID_REQUEST, "this message is reserved for wallet key proofs and cannot be signed")
+
+    suspend fun signMessage(session: String, message: WalletMessage, account: SignAccount = SignAccount.PRIMARY): String {
+        val (summaryInput, bytes, text) = when (message) {
+            is WalletMessage.Text -> Triple(Summaries.Message.Text(message.text), Bytes.utf8(message.text), message.text)
+            is WalletMessage.Raw -> {
+                if (!Regex("^0x[0-9a-fA-F]*$").matches(message.hex)) {
+                    throw walletError(WalletErrorCode.INVALID_REQUEST, "message must be a string or {raw}")
+                }
+                Triple(Summaries.Message.Raw(message.hex), Bytes.fromHex(message.hex), Proof.rawMessageText(message.hex))
+            }
+        }
+        if (text != null && Proof.isReservedMessageText(text)) throw reserved()
+        return withSecret(session, { Summaries.message(summaryInput) }, account) { it.signMessage(bytes) }
+    }
+
+    suspend fun signTypedData(session: String, typedData: JsonObject, account: SignAccount = SignAccount.PRIMARY): String {
+        fun present(k: String) = typedData[k].let { it != null && it !is kotlinx.serialization.json.JsonNull && !(it is JsonPrimitive && it.isString && it.content.isEmpty()) }
+        if (!present("types") || !present("primaryType") || !present("message")) {
+            throw walletError(WalletErrorCode.INVALID_REQUEST, "typedData incomplete")
+        }
+        if (Proof.isReservedTypedData(typedData)) throw reserved()
+        val digest = Eip712.hashTypedData(typedData)
+        return withSecret(session, { Summaries.typedData(typedData) }, account) { it.signDigest(digest).toHex() }
+    }
+
+    suspend fun signTransaction(session: String, transaction: JsonObject, account: SignAccount = SignAccount.PRIMARY): String {
+        val tx = EvmTransaction.parse(transaction)
+        return withSecret(session, { Summaries.transaction(tx.fields) }, account) { it.signTransaction(tx) }
+    }
+
+    /**
+     * Signs an app-built transaction on a non-EVM chain (NATIVE.md section 12). The summary and the
+     * fee-payer check come from the payload before A is requested; after assembly the derived
+     * address must equal [address]. Solana, TRON, Bitcoin (mainnet/testnet) and XRP.
+     */
+    suspend fun signChainTransaction(session: String, chain: WalletChain, account: Long, address: String, payload: Map<String, Any?>): Map<String, String> {
+        if (chain == WalletChain.EVM) {
+            throw walletError(WalletErrorCode.UNSUPPORTED_TYPE, "signing is not available for chain ${chain.wire}")
+        }
+        if (!HdWallet.isAccountIndex(account)) {
+            throw walletError(WalletErrorCode.INVALID_REQUEST, "account must be an integer 0..${HdWallet.MAX_ACCOUNT_INDEX}")
+        }
+        if (address.isEmpty()) throw walletError(WalletErrorCode.INVALID_REQUEST, "address of the signing account required")
+        val summary: SignSummary
+        val sign: (ByteArray) -> Map<String, String>
+        if (chain == WalletChain.SOLANA) {
+            val messageB64 = payload["message"] as? String ?: throw walletError(WalletErrorCode.INVALID_REQUEST, "payload.message (base64) required")
+            val message = Bytes.fromBase64(messageB64)
+            val cluster = (payload["cluster"] as? String)?.takeIf { it.length <= 32 }
+            summary = Solana.summarize(Solana.parse(message), address, if (cluster != null) "Solana $cluster" else "Solana (network chosen by the app)")
+            sign = { secret ->
+                val key = Solana.privateKey(secret, account)
+                try {
+                    if (Solana.addressOf(key) != address) throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+                    mapOf("signature" to Solana.sign(message, key))
+                } finally {
+                    Bytes.wipe(key)
+                }
+            }
+        } else if (chain == WalletChain.BITCOIN || chain == WalletChain.BITCOIN_TESTNET) {
+            val psbtB64 = payload["psbt"] as? String ?: throw walletError(WalletErrorCode.INVALID_REQUEST, "payload.psbt (base64) required")
+            val psbt = Bitcoin.parse(Bytes.fromBase64(psbtB64))
+            summary = Bitcoin.summarize(psbt, address, chain)
+            sign = { secret ->
+                val key = Chains.secpPrivateKey(secret, chain, account)
+                try {
+                    if (Chains.addressOfKey(chain, key) != address) throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+                    Bitcoin.sign(psbt, key, chain)
+                } finally {
+                    Bytes.wipe(key)
+                }
+            }
+        } else if (chain == WalletChain.XRP) {
+            val hex = payload["txBlobHex"] as? String
+            if (hex == null || !Regex("^([0-9a-fA-F]{2})+$").matches(hex)) {
+                throw walletError(WalletErrorCode.INVALID_REQUEST, "payload.txBlobHex (encodeForSigning output) required")
+            }
+            val blob = Bytes.fromHex(hex)
+            val tx = Xrp.parse(blob)
+            if (tx.account != address) throw walletError(WalletErrorCode.ADDRESS_MISMATCH, "the transaction account is not the signing account")
+            summary = Xrp.summarize(tx, address, tx.signingPubKey!!)
+            sign = { secret ->
+                val key = Chains.secpPrivateKey(secret, WalletChain.XRP, account)
+                try {
+                    val pub = Chains.compressedPublicKey(key)
+                    if (Xrp.addressOfPublicKey(pub) != address || !pub.contentEquals(tx.signingPubKey!!)) {
+                        throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+                    }
+                    Xrp.sign(blob, key)
+                } finally {
+                    Bytes.wipe(key)
+                }
+            }
+        } else {
+            val hex = payload["rawDataHex"] as? String
+            if (hex == null || !Regex("^([0-9a-fA-F]{2})+$").matches(hex)) {
+                throw walletError(WalletErrorCode.INVALID_REQUEST, "payload.rawDataHex required")
+            }
+            val raw = Bytes.fromHex(hex)
+            summary = Tron.summarize(Tron.parse(raw), address)
+            sign = { secret ->
+                val key = Chains.secpPrivateKey(secret, WalletChain.TRON, account)
+                try {
+                    if (Chains.addressOfKey(WalletChain.TRON, key) != address) throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+                    Tron.sign(raw, key)
+                } finally {
+                    Bytes.wipe(key)
+                }
+            }
+        }
+        val local = requireLocal(session)
+        if (ctx.confirmSigning) approveRequest(summary)
+        authenticateDevice(summary.title)
+        val companyB64 = fetchCompanyShare(session, local.record)
+        val device = openShare(local.record)
+        val company = Bytes.fromBase64(companyB64)
+        var secret: ByteArray? = null
+        try {
+            secret = HdWallet.assemble(device, company)
+            if (!HdWallet.address(secret).equals(local.wallet.address, ignoreCase = true)) throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+            return sign(secret)
+        } finally {
+            Bytes.wipe(secret, device, company)
+        }
+    }
+
+    private suspend fun writeBackup(session: String, upgrade: Boolean): ProtectResult {
+        val local = requireLocal(session)
+        val record = local.record
+        val wallet = local.wallet
+        if (!upgrade && wallet.protected) return ProtectResult(true, wallet.shareVersion)
+        if (upgrade) {
+            if (!wallet.protected) throw walletError(WalletErrorCode.NOT_PROTECTED)
+            if (wallet.backupVerifiable != false) throw walletError(WalletErrorCode.ALREADY_UPGRADED)
+        }
+        val key = recordKey(session)
+        val user = decodeUserId(session)
+        val version = ctx.backupVersion
+        val salt = Prf.salt(version, ctx.projectId, wallet.id)
+        val passkeyUser = Prf.passkeyUserId("${ctx.projectId}:$user")
+        val pk = ctx.passkeys.create(passkeyUser, wallet.address, salt)
+        var oldDevice: ByteArray? = null
+        var oldCompany: ByteArray? = null
+        var secret: ByteArray? = null
+        var shares: HdWallet.SplitShares? = null
+        var backupKey: ByteArray? = null
+        try {
+            val companyB64 = fetchCompanyShare(session, record)
+            oldDevice = openShare(record)
+            oldCompany = Bytes.fromBase64(companyB64)
+            secret = HdWallet.assemble(oldDevice, oldCompany)
+            if (!HdWallet.address(secret).equals(wallet.address, ignoreCase = true)) throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+            shares = HdWallet.splitProtected(secret)
+            backupKey = Prf.deriveBackupKey(pk.prfOutput)
+            val backupCiphertext = Prf.encryptBackup(backupKey, shares.backup!!, wallet.id, version)
+            val proof = deviceProof(session, record)
+            val keyFields = if (pk.publicKey != null && pk.publicKeyAlg != null) {
+                WalletApi.BackupKeyFields(pk.publicKey, pk.publicKeyAlg, null)
+            } else {
+                WalletApi.BackupKeyFields(null, null, pk.attestationObject)
+            }
+            val shareVersion = ctx.api.putBackup(
+                session, proof, backupCiphertext, pk.credentialId, Bytes.toBase64(shares.company), keyFields, upgrade,
+            )
+            val sealed = record.keys.seal(shares.device, Bytes.utf8(key))
+            ctx.store.put(record.copy(iv = sealed.iv, ciphertext = sealed.ciphertext, shareVersion = shareVersion))
+            return ProtectResult(true, shareVersion)
+        } finally {
+            Bytes.wipe(secret, oldDevice, oldCompany, pk.prfOutput, backupKey)
+            shares?.wipe()
+        }
+    }
+
+    suspend fun protect(session: String): ProtectResult = writeBackup(session, upgrade = false)
+
+    suspend fun upgradeBackup(session: String): ProtectResult = writeBackup(session, upgrade = true)
+
+    suspend fun restore(session: String, mode: RestoreMode = RestoreMode.ADD): RestoreResult {
+        val wallet = ctx.api.getMe(session)
+        if (wallet == null || wallet.status == "pending") throw walletError(WalletErrorCode.NOT_FOUND)
+        val start = ctx.api.restoreStart(session)
+        val backupCiphertext = start.backupCiphertext
+        val credentialId = start.credentialId
+        if (backupCiphertext == null || credentialId == null) throw walletError(WalletErrorCode.NOT_PROTECTED)
+
+        val key = recordKey(session)
+        val version = Prf.backupVersionOf(backupCiphertext)
+        val salt = Prf.salt(version, ctx.projectId, wallet.id)
+        val challenge = start.passkeyChallenge?.let { Bytes.fromBase64(it) }
+        val got = ctx.passkeys.get(credentialId, salt, challenge)
+        val prfOutput = got.prfOutput
+        var company: ByteArray? = null
+        var backup: ByteArray? = null
+        var secret: ByteArray? = null
+        var shares: HdWallet.SplitShares? = null
+        var backupKey: ByteArray? = null
+        try {
+            backupKey = Prf.deriveBackupKey(prfOutput)
+            backup = Prf.decryptBackup(backupKey, backupCiphertext, wallet.id)
+            val companyB64 = start.companyShare ?: ctx.api.restoreAssert(session, got.assertion, start.passkeyChallenge!!)
+            company = Bytes.fromBase64(companyB64)
+            secret = HdWallet.assemble(backup, company)
+            if (!HdWallet.address(secret).equals(wallet.address, ignoreCase = true)) throw walletError(WalletErrorCode.ADDRESS_MISMATCH)
+
+            val upgradeRecommended = start.upgradeRecommended
+            if (mode == RestoreMode.ADD) {
+                val added = addThisDevice(session, key, wallet, secret, company, backup)
+                return RestoreResult(true, added, upgradeRecommended)
+            }
+
+            shares = HdWallet.splitProtected(secret)
+            val keys = ctx.store.generateKeys()
+            var stored = false
+            try {
+                val bound = ctx.api.proofChallenge(session, "restore")
+                val proof = Proof.sign(secret, Proof.restoreTypedData(wallet.id, wallet.shareVersion, keys.publicJwk, bound))
+                // The PRF output belongs to this backup's salt version, so the new backup keeps it.
+                val newBackupCiphertext = Prf.encryptBackup(backupKey, shares.backup!!, wallet.id, version)
+                val res = ctx.api.restore(
+                    session, Bytes.toBase64(shares.company), newBackupCiphertext, keys.publicJwk, credentialId, proof, bound,
+                )
+                val sealed = keys.seal(shares.device, Bytes.utf8(key))
+                ctx.store.put(
+                    DeviceRecord(key, keys, sealed.iv, sealed.ciphertext, res.deviceId, wallet.id, wallet.address, res.shareVersion, System.currentTimeMillis()),
+                )
+                stored = true
+                return RestoreResult(true, res.shareVersion, upgradeRecommended)
+            } finally {
+                if (!stored) runCatching { ctx.store.discardKeys(keys) }
+            }
+        } finally {
+            Bytes.wipe(prfOutput, company, backup, secret, backupKey)
+            shares?.wipe()
+        }
+    }
+
+    private suspend fun addThisDevice(
+        session: String,
+        key: String,
+        wallet: ServerWallet,
+        secret: ByteArray,
+        company: ByteArray,
+        backup: ByteArray,
+    ): Int {
+        val device = HdWallet.deriveShare(company, backup)
+        var check1: ByteArray? = null
+        var check2: ByteArray? = null
+        try {
+            check1 = HdWallet.assemble(device, company)
+            check2 = HdWallet.assemble(device, backup)
+            if (!Bytes.sameBytes(check1, secret) || !Bytes.sameBytes(check2, secret)) {
+                throw walletError(WalletErrorCode.INTERNAL, "derived share mismatch")
+            }
+            val keys = ctx.store.generateKeys()
+            var stored = false
+            try {
+                val bound = ctx.api.proofChallenge(session, "device")
+                val proof = Proof.sign(secret, Proof.deviceTypedData(wallet.id, wallet.shareVersion, keys.publicJwk, bound))
+                val res = ctx.api.addDevice(session, keys.publicJwk, proof, bound)
+                val sealed = keys.seal(device, Bytes.utf8(key))
+                ctx.store.put(
+                    DeviceRecord(key, keys, sealed.iv, sealed.ciphertext, res.deviceId, wallet.id, wallet.address, res.shareVersion, System.currentTimeMillis()),
+                )
+                stored = true
+                return res.shareVersion
+            } finally {
+                if (!stored) runCatching { ctx.store.discardKeys(keys) }
+            }
+        } finally {
+            Bytes.wipe(device, check1, check2)
+        }
+    }
+
+    suspend fun revokeDevice(session: String, deviceId: String): Boolean {
+        if (deviceId.isEmpty()) throw walletError(WalletErrorCode.INVALID_REQUEST, "deviceId required")
+        val local = requireLocal(session)
+        ctx.api.revokeDevice(session, deviceId, deviceProof(session, local.record))
+        if (local.record.deviceId == deviceId) ctx.store.delete(recordKey(session))
+        return true
+    }
+
+    companion object {
+        /** The `sub` claim of the session JWT (no verification; the API verifies the token). */
+        fun decodeUserId(session: String): String {
+            val part = session.split('.').getOrNull(1)?.takeIf { it.isNotEmpty() }
+                ?: throw walletError(WalletErrorCode.UNAUTHORIZED, "malformed session token")
+            return try {
+                val claims = Json.parseToJsonElement(String(Bytes.fromBase64(part), Charsets.UTF_8)) as JsonObject
+                val sub = claims["sub"] as? JsonPrimitive
+                if (sub == null || !sub.isString || sub.content.isEmpty()) throw IllegalStateException()
+                sub.content
+            } catch (_: Exception) {
+                throw walletError(WalletErrorCode.UNAUTHORIZED, "malformed session token")
+            }
+        }
+    }
+}

package/android/src/vendor/kotlin/dev/authon/sdk/wallet/WalletTypes.kt

@@ -0,0 +1,78 @@
+// GENERATED by scripts/sync-native-wallet.mjs from kotlin/authon/src/main/kotlin/dev/authon/sdk/wallet/WalletTypes.kt. Do not edit: change the source and run the script.
+package dev.authon.sdk.wallet
+
+/** What apps see about the wallet (the frame's PublicWallet). */
+data class PublicWallet(
+    val address: String,
+    /** False until a passkey backup exists. An unprotected wallet is lost with this app's storage. */
+    val protected: Boolean,
+    /** True for a legacy backup without a passkey public key; call upgradeBackup() from a device that holds the wallet. */
+    val backupUpgradeRecommended: Boolean,
+    val needsRestore: Boolean,
+    val devices: List<Device>,
+) {
+    data class Device(val id: String, val label: String?, val createdAt: String?, val lastUsedAt: String?, val current: Boolean)
+}
+
+data class WalletAccount(
+    val index: Long,
+    val path: String,
+    val address: String,
+    val chain: WalletChain = WalletChain.EVM,
+    /** XRP: the compressed public key (uppercase hex) the app puts in SigningPubKey. */
+    val publicKey: String? = null,
+)
+
+/**
+ * Which account signs. Account 0 is the wallet address the server knows; another account must
+ * name the address the caller expects (from accounts()), and signing is refused when it differs.
+ */
+data class SignAccount(val index: Long = 0, val address: String? = null) {
+    companion object {
+        val PRIMARY = SignAccount()
+
+        fun parse(index: Long?, address: String?): SignAccount {
+            if (index == null || index == 0L) return PRIMARY
+            if (!HdWallet.isAccountIndex(index)) {
+                throw walletError(WalletErrorCode.INVALID_REQUEST, "account must be an integer 0..${HdWallet.MAX_ACCOUNT_INDEX}")
+            }
+            if (address == null || !Regex("^0x[0-9a-fA-F]{40}$").matches(address)) {
+                throw walletError(WalletErrorCode.INVALID_REQUEST, "address of the signing account required")
+            }
+            return SignAccount(index, address)
+        }
+    }
+}
+
+sealed class WalletMessage {
+    /** UTF-8 text. */
+    data class Text(val text: String) : WalletMessage()
+
+    /** Raw bytes as 0x hex. */
+    data class Raw(val hex: String) : WalletMessage()
+}
+
+enum class RestoreMode {
+    /** Enroll this device next to the existing ones (default). */
+    ADD,
+
+    /** Re-split the key and revoke every other device (lost device). */
+    RESET,
+}
+
+data class ProtectResult(val protected: Boolean, val shareVersion: Int)
+
+data class RestoreResult(val restored: Boolean, val shareVersion: Int, val backupUpgradeRecommended: Boolean)
+
+/**
+ * Shows a signing request and returns true when the user approves. Called before the company share
+ * is requested, so a rejected request never assembles the key.
+ */
+fun interface WalletApprover {
+    suspend fun approve(summary: SignSummary): Boolean
+}
+
+/** Optional extra gate (device lock / biometrics) before any key assembly. Throw or return false to refuse. */
+fun interface DeviceAuthenticator {
+    suspend fun authenticate(reason: String): Boolean
+}