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

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

@@ -0,0 +1,361 @@
+// GENERATED by scripts/sync-native-wallet.mjs from kotlin/authon/src/main/kotlin/dev/authon/sdk/wallet/WalletApi.kt. Do not edit: change the source and run the script.
+package dev.authon.sdk.wallet
+
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonObjectBuilder
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.contentOrNull
+import kotlinx.serialization.json.intOrNull
+import kotlinx.serialization.json.longOrNull
+import kotlinx.serialization.json.put
+import okhttp3.OkHttpClient
+import java.io.IOException
+import java.net.URLEncoder
+
+data class WalletDevice(
+    val id: String,
+    val label: String?,
+    val shareVersion: Int?,
+    val createdAt: String?,
+    val lastUsedAt: String?,
+    val revokedAt: String?,
+)
+
+data class ServerWallet(
+    val id: String,
+    val address: String,
+    val status: String,
+    val protected: Boolean,
+    /** Null without a backup; false for a legacy backup that has no passkey public key. */
+    val backupVerifiable: Boolean?,
+    val shareVersion: Int,
+    val devices: List<WalletDevice>,
+)
+
+/** `GET /v1/wallet/app-config` for this app (platform=android, appId=package name). */
+data class WalletAppConfig(
+    val allowed: Boolean,
+    val approved: Boolean,
+    val projectId: String?,
+    val enabled: Boolean,
+    val chainIds: List<Long>,
+    /** Missing means true: signing needs a confirmation. */
+    val confirmSigning: Boolean,
+    /** PRF salt version for new backups. Missing means 1. */
+    val prfSaltVersion: Int,
+    val rpId: String,
+    val minFrameProtocol: Int?,
+    /** Android: whether the running app's signing certificate is registered; null when not asked or not registered. */
+    val signatureMatches: Boolean? = null,
+    /** `X-Request-Id` of the app-config response. */
+    val diagnosticId: String? = null,
+)
+
+internal data class DeviceProof(val deviceId: String, val challenge: String, val signature: String) {
+    fun fill(b: JsonObjectBuilder) {
+        b.put("deviceId", deviceId)
+        b.put("challenge", challenge)
+        b.put("signature", signature)
+    }
+}
+
+internal data class RestoreStart(
+    val backupCiphertext: String?,
+    val credentialId: String?,
+    val companyShare: String?,
+    val upgradeRecommended: Boolean,
+    val passkeyChallenge: String?,
+)
+
+internal data class CreatedWallet(val wallet: ServerWallet?, val deviceId: String, val walletId: String, val shareVersion: Int)
+
+internal data class EnrolledDevice(val deviceId: String, val shareVersion: Int)
+
+/** HTTP contract of `apps/wallet/src/api.ts` (protocol 2), byte for byte in paths, headers and bodies. */
+internal class WalletApi(
+    apiUrl: String,
+    private val publishableKey: String,
+    private val client: OkHttpClient = Http.defaultClient,
+) {
+    private val base = apiUrl.trimEnd('/')
+
+    private suspend fun call(method: String, path: String, session: String?, body: JsonObject? = null): HttpResult {
+        val headers = LinkedHashMap<String, String>()
+        headers["x-api-key"] = publishableKey
+        headers["accept"] = "application/json"
+        if (session != null) headers["authorization"] = "Bearer $session"
+        if (body != null) headers["content-type"] = "application/json"
+        headers["user-agent"] = Http.userAgent()
+        return try {
+            Http.execute(client, Http.request("$base/v1/wallet$path", method, headers, body))
+        } catch (e: IOException) {
+            throw WalletException(WalletErrorCode.API_ERROR, "network error", e)
+        }
+    }
+
+    private fun ensureOk(res: HttpResult): JsonObject {
+        if (res.ok) return res.json
+        val serverCode = res.json.str("code")
+        val id = res.requestId
+        if (serverCode != null && serverCode in RESTORE_CODES) throw walletError(WalletErrorCode.NEEDS_RESTORE, diagnosticId = id)
+        if (serverCode != null && serverCode in KNOWN_CODES) throw walletError(WalletErrorCode.valueOf(serverCode), diagnosticId = id)
+        throw walletError(STATUS_CODES[res.status] ?: WalletErrorCode.API_ERROR, diagnosticId = id)
+    }
+
+    suspend fun appConfig(packageName: String, certSha256: String? = null): WalletAppConfig {
+        val cert = certSha256?.let { "&certSha256=${enc(it)}" } ?: ""
+        val res = call("GET", "/app-config?platform=android&appId=${enc(packageName)}$cert", null)
+        if (res.status == 403 || res.status == 404) {
+            return WalletAppConfig(false, false, null, false, emptyList(), true, 1, DEFAULT_RP_ID, null, null, res.requestId)
+        }
+        val data = ensureOk(res)
+        val wc = data["walletConfig"] as? JsonObject ?: JsonObject(emptyMap())
+        return WalletAppConfig(
+            allowed = data.bool("allowed") != false,
+            approved = data.bool("approved") == true,
+            projectId = data.str("projectId"),
+            enabled = wc.bool("enabled") != false,
+            chainIds = (wc["chainIds"] as? JsonArray)?.mapNotNull { (it as? JsonPrimitive)?.longOrNull } ?: emptyList(),
+            confirmSigning = wc.bool("confirmSigning") != false,
+            prfSaltVersion = if ((wc["prfSaltVersion"] as? JsonPrimitive)?.intOrNull == 2) 2 else 1,
+            rpId = data.str("rpId") ?: DEFAULT_RP_ID,
+            minFrameProtocol = (data["minFrameProtocol"] as? JsonPrimitive)?.intOrNull,
+            signatureMatches = data.bool("signatureMatches"),
+            diagnosticId = res.requestId,
+        )
+    }
+
+    suspend fun getMe(session: String): ServerWallet? {
+        val res = call("GET", "/me", session)
+        if (res.status == 404) return null
+        val data = ensureOk(res)
+        return normalizeWallet(data["wallet"]?.takeIf { it !is JsonNull } ?: res.json)
+    }
+
+    suspend fun proofChallenge(session: String, kind: String): ProofNonce {
+        val data = ensureOk(call("POST", "/me/proof-challenge", session, buildJsonObject { put("kind", kind) }))
+        val nonce = data.str("nonce")
+        val expiresAt = (data["expiresAt"] as? JsonPrimitive)?.takeIf { !it.isString }?.longOrNull
+        if (nonce == null || expiresAt == null) throw walletError(WalletErrorCode.API_ERROR)
+        return ProofNonce(nonce, expiresAt)
+    }
+
+    suspend fun createWallet(
+        session: String,
+        address: String,
+        companyShare: String,
+        devicePublicKey: DevicePublicJwk,
+        proof: String,
+        bound: ProofNonce,
+    ): CreatedWallet {
+        val body = buildJsonObject {
+            put("address", address)
+            put("companyShare", companyShare)
+            put("devicePublicKey", devicePublicKey.toJson())
+            put("proof", proof)
+            put("nonce", bound.nonce)
+            put("nonceExpiresAt", bound.expiresAt)
+            put("protocol", FRAME_PROTOCOL)
+        }
+        val data = ensureOk(call("POST", "/me", session, body))
+        val wallet = when {
+            data["wallet"] is JsonObject -> normalizeWallet(data["wallet"]!!)
+            data["id"] != null && data["id"] !is JsonNull -> normalizeWallet(data)
+            else -> null
+        }
+        val device = data["device"] as? JsonObject
+        return CreatedWallet(
+            wallet = wallet,
+            walletId = data.str("walletId") ?: wallet?.id ?: "undefined",
+            deviceId = data.str("deviceId") ?: device?.str("id") ?: "undefined",
+            shareVersion = data.int("shareVersion") ?: wallet?.shareVersion ?: 1,
+        )
+    }
+
+    suspend fun confirmWallet(session: String, proof: DeviceProof) {
+        ensureOk(call("POST", "/me/confirm", session, buildJsonObject { proof.fill(this) }))
+    }
+
+    suspend fun discardPending(session: String) {
+        val res = call("DELETE", "/me/pending", session)
+        if (res.status == 404) return
+        ensureOk(res)
+    }
+
+    suspend fun challenge(session: String, deviceId: String): String {
+        val data = ensureOk(call("POST", "/me/share/challenge", session, buildJsonObject { put("deviceId", deviceId) }))
+        return data.str("challenge") ?: throw walletError(WalletErrorCode.API_ERROR)
+    }
+
+    suspend fun releaseShare(session: String, proof: DeviceProof): String {
+        val data = ensureOk(call("POST", "/me/share", session, buildJsonObject { proof.fill(this) }))
+        return data.str("companyShare") ?: throw walletError(WalletErrorCode.API_ERROR)
+    }
+
+    class BackupKeyFields(val credentialPublicKey: String?, val credentialAlg: Int?, val attestationObject: String?)
+
+    suspend fun putBackup(
+        session: String,
+        proof: DeviceProof,
+        backupCiphertext: String,
+        credentialId: String,
+        newCompanyShare: String,
+        key: BackupKeyFields,
+        upgrade: Boolean,
+    ): Int {
+        val body = buildJsonObject {
+            proof.fill(this)
+            put("backupCiphertext", backupCiphertext)
+            put("credentialId", credentialId)
+            put("newCompanyShare", newCompanyShare)
+            if (key.credentialPublicKey != null && key.credentialAlg != null) {
+                put("credentialPublicKey", key.credentialPublicKey)
+                put("credentialAlg", key.credentialAlg)
+            } else if (key.attestationObject != null) {
+                put("attestationObject", key.attestationObject)
+            }
+            if (upgrade) put("upgrade", true)
+            put("protocol", FRAME_PROTOCOL)
+        }
+        val data = ensureOk(call("PUT", "/me/backup", session, body))
+        return data.int("shareVersion") ?: throw walletError(WalletErrorCode.API_ERROR)
+    }
+
+    suspend fun restoreStart(session: String): RestoreStart {
+        val data = ensureOk(call("POST", "/me/restore/start", session, JsonObject(emptyMap())))
+        val companyShare = data.str("companyShare")
+        val passkeyChallenge = data.str("passkeyChallenge")
+        if (companyShare == null && passkeyChallenge == null) throw walletError(WalletErrorCode.API_ERROR)
+        return RestoreStart(
+            backupCiphertext = data.str("backupCiphertext"),
+            credentialId = data.str("credentialId"),
+            companyShare = companyShare,
+            passkeyChallenge = passkeyChallenge,
+            upgradeRecommended = companyShare != null || data.bool("upgradeRecommended") == true,
+        )
+    }
+
+    suspend fun restoreAssert(session: String, assertion: PasskeyAssertion, challenge: String): String {
+        val body = buildJsonObject {
+            put("credentialId", assertion.credentialId)
+            put("clientDataJSON", assertion.clientDataJSON)
+            put("authenticatorData", assertion.authenticatorData)
+            put("signature", assertion.signature)
+            put("challenge", challenge)
+        }
+        val data = ensureOk(call("POST", "/me/restore/assert", session, body))
+        return data.str("companyShare") ?: throw walletError(WalletErrorCode.API_ERROR)
+    }
+
+    suspend fun restore(
+        session: String,
+        newCompanyShare: String,
+        newBackupCiphertext: String,
+        newDevicePublicKey: DevicePublicJwk,
+        credentialId: String,
+        proof: String,
+        bound: ProofNonce,
+    ): EnrolledDevice {
+        val body = buildJsonObject {
+            put("newCompanyShare", newCompanyShare)
+            put("newBackupCiphertext", newBackupCiphertext)
+            put("newDevicePublicKey", newDevicePublicKey.toJson())
+            put("credentialId", credentialId)
+            put("proof", proof)
+            put("nonce", bound.nonce)
+            put("nonceExpiresAt", bound.expiresAt)
+            put("protocol", FRAME_PROTOCOL)
+        }
+        val data = ensureOk(call("POST", "/me/restore", session, body))
+        return EnrolledDevice(
+            data.str("deviceId") ?: (data["device"] as? JsonObject)?.str("id") ?: "undefined",
+            data.int("shareVersion") ?: throw walletError(WalletErrorCode.API_ERROR),
+        )
+    }
+
+    suspend fun addDevice(session: String, devicePublicKey: DevicePublicJwk, proof: String, bound: ProofNonce): EnrolledDevice {
+        val body = buildJsonObject {
+            put("devicePublicKey", devicePublicKey.toJson())
+            put("proof", proof)
+            put("nonce", bound.nonce)
+            put("nonceExpiresAt", bound.expiresAt)
+            put("protocol", FRAME_PROTOCOL)
+        }
+        val data = ensureOk(call("POST", "/me/devices", session, body))
+        return EnrolledDevice(
+            data.str("deviceId") ?: "undefined",
+            data.int("shareVersion") ?: throw walletError(WalletErrorCode.API_ERROR),
+        )
+    }
+
+    suspend fun revokeDevice(session: String, deviceId: String, proof: DeviceProof) {
+        ensureOk(call("DELETE", "/me/devices/${enc(deviceId)}", session, buildJsonObject { proof.fill(this) }))
+    }
+
+    companion object {
+        /** Protocol sent as `protocol` in proof and backup requests (the API's CURRENT_FRAME_PROTOCOL). */
+        const val FRAME_PROTOCOL = 2
+        const val DEFAULT_RP_ID = "wallet.authon.dev"
+
+        private val STATUS_CODES = mapOf(
+            400 to WalletErrorCode.INVALID_REQUEST,
+            401 to WalletErrorCode.UNAUTHORIZED,
+            403 to WalletErrorCode.FORBIDDEN,
+            404 to WalletErrorCode.NOT_FOUND,
+            409 to WalletErrorCode.ALREADY_EXISTS,
+            426 to WalletErrorCode.FRAME_OUTDATED,
+            429 to WalletErrorCode.RATE_LIMITED,
+        )
+        private val RESTORE_CODES = setOf("NEEDS_RESTORE", "DEVICE_REVOKED", "DEVICE_NOT_FOUND", "STALE_SHARE_VERSION")
+        private val KNOWN_CODES = setOf(
+            "NOT_PROTECTED", "ORIGIN_NOT_ALLOWED", "ALREADY_EXISTS", "NOT_FOUND", "LAST_DEVICE", "SESSION_REQUIRED",
+            "WALLET_PENDING", "RATE_LIMITED", "FRAME_OUTDATED", "BACKUP_KEY_REQUIRED", "ALREADY_UPGRADED",
+        )
+
+        /** encodeURIComponent. */
+        fun enc(value: String): String = URLEncoder.encode(value, "UTF-8")
+            .replace("+", "%20").replace("%21", "!").replace("%27", "'")
+            .replace("%28", "(").replace("%29", ")").replace("%7E", "~")
+
+        private fun JsonObject.str(key: String): String? = (this[key] as? JsonPrimitive)?.takeIf { it.isString }?.content
+
+        private fun JsonObject.bool(key: String): Boolean? = (this[key] as? JsonPrimitive)?.takeIf { !it.isString }?.booleanOrNull
+
+        /** `Number(x)` for counters the server sends as numbers (or numeric strings). */
+        private fun JsonObject.int(key: String): Int? = (this[key] as? JsonPrimitive)?.contentOrNull?.toBigDecimalOrNull()?.toInt()
+
+        private fun JsonElement.asObj(): JsonObject = this as? JsonObject ?: JsonObject(emptyMap())
+
+        fun normalizeWallet(raw: JsonElement): ServerWallet {
+            val w = raw.asObj()
+            val prot = w.bool("protected") ?: (w["protectedAt"].let { it != null && it !is JsonNull && (it as? JsonPrimitive)?.contentOrNull?.isNotEmpty() == true })
+            return ServerWallet(
+                id = w.anyString("id") ?: w.anyString("walletId") ?: "undefined",
+                address = w.anyString("address") ?: "undefined",
+                status = w.anyString("status") ?: "active",
+                protected = prot,
+                backupVerifiable = w.bool("backupVerifiable"),
+                shareVersion = w.int("shareVersion") ?: 1,
+                devices = (w["devices"] as? JsonArray)?.mapNotNull { d ->
+                    val o = d as? JsonObject ?: return@mapNotNull null
+                    WalletDevice(
+                        id = o.anyString("id") ?: return@mapNotNull null,
+                        label = o.str("label"),
+                        shareVersion = o.int("shareVersion"),
+                        createdAt = o.str("createdAt"),
+                        lastUsedAt = o.str("lastUsedAt"),
+                        revokedAt = o.str("revokedAt"),
+                    )
+                } ?: emptyList(),
+            )
+        }
+
+        private fun JsonObject.anyString(key: String): String? =
+            (this[key] as? JsonPrimitive)?.takeIf { it !is JsonNull }?.contentOrNull
+    }
+}

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

@@ -0,0 +1,91 @@
+// GENERATED by scripts/sync-native-wallet.mjs from kotlin/authon/src/main/kotlin/dev/authon/sdk/wallet/WalletCapabilities.kt. Do not edit: change the source and run the script.
+package dev.authon.sdk.wallet
+
+/** NATIVE.md section 9. [wire] is the contract string. */
+enum class CapabilityStatus(val wire: String) { AVAILABLE("available"), UNAVAILABLE("unavailable"), UNKNOWN("unknown") }
+
+data class CapabilityCheck(val status: CapabilityStatus, val reason: String? = null) {
+    companion object {
+        val AVAILABLE = CapabilityCheck(CapabilityStatus.AVAILABLE)
+        fun unavailable(reason: String) = CapabilityCheck(CapabilityStatus.UNAVAILABLE, reason)
+        fun unknown(reason: String) = CapabilityCheck(CapabilityStatus.UNKNOWN, reason)
+    }
+}
+
+/**
+ * Whether this device and app can use the wallet, answered before sign-in: no session, no
+ * login or passkey UI, no wallet is created.
+ */
+data class WalletCapabilities(
+    /** Any unavailable -> unavailable; else any unknown -> unknown; else available. */
+    val ready: CapabilityStatus,
+    val app: CapabilityCheck,
+    val wallet: CapabilityCheck,
+    val secureStorage: CapabilityCheck,
+    val deviceLock: CapabilityCheck,
+    val passkeyBackup: CapabilityCheck,
+    /** `X-Request-Id` of the app-config response, when the API answered. */
+    val diagnosticId: String?,
+) {
+    companion object {
+        fun readyOf(checks: List<CapabilityCheck>): CapabilityStatus = when {
+            checks.any { it.status == CapabilityStatus.UNAVAILABLE } -> CapabilityStatus.UNAVAILABLE
+            checks.any { it.status == CapabilityStatus.UNKNOWN } -> CapabilityStatus.UNKNOWN
+            else -> CapabilityStatus.AVAILABLE
+        }
+    }
+}
+
+/** Static device checks behind capabilities(); the Android implementation is [AndroidCapabilityProbe]. */
+interface CapabilityProbe {
+    /** SHA-256 of the running app's signing certificate, uppercase hex with colons; null when unreadable. */
+    fun signingCertSha256(): String?
+    suspend fun secureStorage(): CapabilityCheck
+    fun deviceLock(): CapabilityCheck
+    fun passkeyBackup(): CapabilityCheck
+}
+
+internal object Capabilities {
+    const val APP_NOT_REGISTERED = "APP_NOT_REGISTERED"
+    const val APP_SIGNATURE_MISMATCH = "APP_SIGNATURE_MISMATCH"
+    const val APP_NOT_APPROVED = "APP_NOT_APPROVED"
+    const val WALLET_DISABLED = "WALLET_DISABLED"
+    const val NETWORK_ERROR = "NETWORK_ERROR"
+    const val API_ERROR = "API_ERROR"
+    const val HARDWARE_KEYSTORE_UNAVAILABLE = "HARDWARE_KEYSTORE_UNAVAILABLE"
+    const val SIMULATOR = "SIMULATOR"
+    const val CHECK_FAILED = "CHECK_FAILED"
+    const val DEVICE_LOCK_NOT_SET = "DEVICE_LOCK_NOT_SET"
+    const val OS_UNSUPPORTED = "OS_UNSUPPORTED"
+    const val PASSKEY_API_UNAVAILABLE = "PASSKEY_API_UNAVAILABLE"
+    const val PRF_PROVIDER_UNVERIFIED = "PRF_PROVIDER_UNVERIFIED"
+
+    fun appCheck(cfg: WalletAppConfig): CapabilityCheck = when {
+        !cfg.allowed || cfg.projectId == null -> CapabilityCheck.unavailable(APP_NOT_REGISTERED)
+        cfg.signatureMatches == false -> CapabilityCheck.unavailable(APP_SIGNATURE_MISMATCH)
+        !cfg.approved -> CapabilityCheck.unknown(APP_NOT_APPROVED)
+        else -> CapabilityCheck.AVAILABLE
+    }
+
+    fun walletCheck(cfg: WalletAppConfig): CapabilityCheck =
+        if (cfg.enabled) CapabilityCheck.AVAILABLE else CapabilityCheck.unavailable(WALLET_DISABLED)
+
+    suspend fun evaluate(api: WalletApi, appId: String, probe: CapabilityProbe): Pair<WalletCapabilities, WalletAppConfig?> {
+        val cert = runCatching { probe.signingCertSha256() }.getOrNull()
+        var config: WalletAppConfig? = null
+        val (app, wallet, diagnosticId) = try {
+            val cfg = api.appConfig(appId, cert)
+            config = cfg
+            Triple(appCheck(cfg), walletCheck(cfg), cfg.diagnosticId)
+        } catch (e: WalletException) {
+            // No response at all (WalletApi wraps the IOException) vs. an API error.
+            val reason = if (e.cause is java.io.IOException) NETWORK_ERROR else API_ERROR
+            Triple(CapabilityCheck.unknown(reason), CapabilityCheck.unknown(reason), e.diagnosticId)
+        }
+        val secure = runCatching { probe.secureStorage() }.getOrElse { CapabilityCheck.unknown(CHECK_FAILED) }
+        val lock = runCatching { probe.deviceLock() }.getOrElse { CapabilityCheck.unknown(CHECK_FAILED) }
+        val passkey = runCatching { probe.passkeyBackup() }.getOrElse { CapabilityCheck.unknown(PASSKEY_API_UNAVAILABLE) }
+        val checks = listOf(app, wallet, secure, lock, passkey)
+        return WalletCapabilities(WalletCapabilities.readyOf(checks), app, wallet, secure, lock, passkey, diagnosticId) to config
+    }
+}

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

@@ -0,0 +1,74 @@
+// GENERATED by scripts/sync-native-wallet.mjs from kotlin/authon/src/main/kotlin/dev/authon/sdk/wallet/WalletError.kt. Do not edit: change the source and run the script.
+package dev.authon.sdk.wallet
+
+/** Error codes of the web wallet frame (`apps/wallet/src/errors.ts`); [name] is the wire string. */
+enum class WalletErrorCode {
+    NOT_FOUND,
+    NEEDS_RESTORE,
+    NOT_PROTECTED,
+    PRF_UNSUPPORTED,
+    ORIGIN_NOT_ALLOWED,
+    USER_CANCELLED,
+    NEEDS_POPUP,
+    INVALID_REQUEST,
+    UNSUPPORTED_TYPE,
+    UNAUTHORIZED,
+    FORBIDDEN,
+    ALREADY_EXISTS,
+    RATE_LIMITED,
+    ADDRESS_MISMATCH,
+    STORAGE_UNAVAILABLE,
+    API_ERROR,
+    INTERNAL,
+    LAST_DEVICE,
+    SESSION_REQUIRED,
+    WALLET_PENDING,
+
+    /** The approval UI could not be shown. Nothing was signed. */
+    CONFIRM_WINDOW_BLOCKED,
+
+    /** The approval UI was dismissed before the user approved. Nothing was signed. */
+    CONFIRM_WINDOW_CLOSED,
+
+    /** The message or typed data is too long to show in full; it is refused. */
+    MESSAGE_TOO_LARGE,
+
+    /** The API no longer serves this SDK protocol version. */
+    FRAME_OUTDATED,
+
+    /** The backup passkey did not report a usable public key. */
+    BACKUP_KEY_REQUIRED,
+
+    /** upgradeBackup on a wallet whose backup is already verifiable. */
+    ALREADY_UPGRADED,
+
+    /** The wallet predates HD wallets and has only account 0. */
+    ACCOUNT_UNAVAILABLE,
+}
+
+/**
+ * A wallet error with the fields of NATIVE.md section 10. [diagnosticId] is the server's request id
+ * when the API answered (log only this id, never tokens or key material).
+ */
+class WalletException(
+    val code: WalletErrorCode,
+    message: String? = null,
+    cause: Throwable? = null,
+    val diagnosticId: String? = null,
+    val retryable: Boolean = code in RETRYABLE,
+) : Exception(message ?: code.name, cause) {
+    companion object {
+        /** Codes worth retrying unchanged (later); everything else needs a different action. */
+        val RETRYABLE: Set<WalletErrorCode> = setOf(
+            WalletErrorCode.API_ERROR,
+            WalletErrorCode.RATE_LIMITED,
+            WalletErrorCode.WALLET_PENDING,
+        )
+    }
+}
+
+internal fun walletError(code: WalletErrorCode, message: String? = null, diagnosticId: String? = null): WalletException =
+    WalletException(code, message, diagnosticId = diagnosticId)
+
+internal fun Throwable.toWalletException(): WalletException =
+    this as? WalletException ?: WalletException(WalletErrorCode.INTERNAL, "unexpected error", this)