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

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @authon/react-native-wallet
+
+## 0.4.0
+
+- `signChainTransaction({ chain, account, address, payload })` for app-built transactions on other chains (NATIVE.md section 12): Solana (`{ message }` → `{ signature }`), TRON (`{ rawDataHex }` → `{ txID, signature }`), Bitcoin and Bitcoin testnet (`{ psbt }` → `{ psbt, txHex? }`) and XRP (`{ txBlobHex }` → `{ signature }`). EVM stays on `signTransaction` (`INVALID_PARAMS` for `chain: 'evm'`). The native approval UI summarizes the transaction before the key is assembled.
+- `getAccounts` passes through `publicKey` when the native wallet returns one (XRP).
+
+## 0.3.0
+
+- `getAccounts({ start, count, chain })`: account addresses on `evm` (default), `tron`, `xrp`, `bitcoin`, `bitcoin-testnet` and `solana`, derived from the same seed with the standard paths. Each account carries its `chain`; a native wallet that answers without it is refused (`UNSUPPORTED_TYPE`). Signing stays EVM only.
+
+## 0.2.0
+
+- `capabilities()`: checks before sign-in whether this device and app can use the wallet (app registration and approval, wallet enabled, hardware key storage, device lock, passkey backup support), with reason codes and the app-config `diagnosticId`. No session needed.
+- `AuthonWalletError` has `diagnosticId` (server request ID) and `retryable`, passed through from the Swift and Kotlin wallets.
+- iOS: a second signature right after the first no longer hangs; the approval sheet fails with `CONFIRM_WINDOW_BLOCKED` when it cannot be shown.
+
+## 0.1.0
+
+- First release: Expo module over the Swift and Kotlin embedded wallets (status, create/ensure, accounts, personal_sign, EIP-712, transactions, passkey protect/upgrade/restore, device revoke), `useAuthonWallet()` with `@authon/react-native`.

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# @authon/react-native-wallet
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> The Authon embedded wallet for React Native and Expo: an Expo native module around the Swift
+> (`AuthonWallet`) and Kotlin (`dev.authon.sdk.wallet`) wallet implementations.
+
+[![License](https://img.shields.io/badge/license-MIT-blue)](../../LICENSE)
+[![Version](https://img.shields.io/badge/version-0.4.0-blue)]()
+
+It is the same wallet as the web SDK (`@authon/js`): same wallet row, same `/v1/wallet/me/*` API,
+same shares. A user gets the same address in your web app and your mobile app, and the app install
+appears as one more device in the wallet's device list.
+
+- The device keeps only its share D, sealed by a Secure Enclave (iOS) or Android Keystore key. Every
+  signature fetches the company share A with a device-key proof, combines the shares in native memory,
+  signs and wipes the key. The full key is never stored.
+- **No secret crosses the JS bridge.** D, A, the backup share B, the key and the passkey PRF output stay
+  in Swift / Kotlin. JS receives addresses, signatures, wallet status and the device list only.
+- Signing is confirmed with the SDKs' native approval UI (a SwiftUI sheet on iOS, a dialog on
+  Android) when the project requires confirmation (the default, a server-side setting).
+- Passkey backup and restore use the RP ID `wallet.authon.dev`, so a backup made on the web restores
+  in the app and the other way round.
+
+## Requirements
+
+- **An Expo development build or a bare React Native app.** Expo Go does not contain this native
+  module (calls fail with `NOT_CONFIGURED`). Expo SDK 53+ / React Native 0.76+.
+- iOS 16+ (iOS 18+ for passkey backup and restore, which need the passkey PRF extension).
+- Android minSdk 28, compileSdk 35+. Passkey backup and restore need Google Play services with a
+  passkey provider that supports PRF (Google Password Manager on Android 9+ with current Play services).
+- Signing: EVM (personal_sign, EIP-712 v4, legacy / EIP-2930 / EIP-1559 transactions), HD accounts
+  `m/44'/60'/0'/0/n`.
+- Addresses (receive / display) from the same seed: TRON `m/44'/195'/n'/0/0`, XRP `m/44'/144'/n'/0/0`,
+  Bitcoin P2WPKH `m/84'/0'/n'/0/0` (testnet `m/84'/1'/n'/0/0`), Solana `m/44'/501'/n'/0'`. These
+  chains sign through `signChainTransaction` (the app builds the transaction; fees, balances and broadcast are up to the app). A wallet created before HD wallets has EVM account 0 only
+  (`ACCOUNT_UNAVAILABLE` for other chains).
+
+## Install
+
+```bash
+npx expo install @authon/react-native-wallet expo-build-properties
+```
+
+```json
+// app.json
+{
+  "expo": {
+    "ios": {
+      "bundleIdentifier": "com.example.app",
+      "associatedDomains": ["webcredentials:wallet.authon.dev"]
+    },
+    "android": { "package": "com.example.app" },
+    "plugins": [
+      ["expo-build-properties", { "ios": { "deploymentTarget": "16.0" }, "android": { "minSdkVersion": 28 } }]
+    ]
+  }
+}
+```
+
+Then build a development build: `npx expo prebuild` and `npx expo run:ios` / `npx expo run:android`
+(or EAS Build). Rebuild the app after installing or updating the package.
+
+## Register the app in the Authon console
+
+The wallet API only serves apps registered for the project, and passkeys only work for apps an
+Authon administrator has approved:
+
+1. Authon console, Project, Wallet, **Native apps**: add
+   - iOS: your Apple **Team ID** and **bundle ID** (the app ID is `TEAMID.bundleId`),
+   - Android: the **package name** and the **SHA-256 fingerprint of your release signing
+     certificate** (for Play App Signing, the app signing key from Play Console, not the upload key).
+2. Wait for approval. Adding or changing an entry resets it to "not approved". Until it is approved,
+   `appConfig().approved` is false, and `protect()`, `upgradeBackup()` and `restore()` fail with
+   `ORIGIN_NOT_ALLOWED`. Signing and accounts work as soon as the app is registered.
+3. After approval, wallet.authon.dev publishes your app in `/.well-known/apple-app-site-association`
+   (`webcredentials`) and `/.well-known/assetlinks.json` (`get_login_creds`). The iOS app needs the
+   Associated Domains entitlement `webcredentials:wallet.authon.dev` (above).
+
+## Usage
+
+### With @authon/react-native
+
+Inside `<AuthonProvider>` the hook takes the session token from the provider and follows sign-in and
+sign-out:
+
+```tsx
+import { AuthonProvider } from '@authon/react-native';
+import { useAuthonWallet } from '@authon/react-native-wallet';
+
+function WalletScreen() {
+  const { wallet, current, isLoaded, error } = useAuthonWallet({ publishableKey: 'pk_live_...' });
+
+  if (!isLoaded) return <Spinner />;
+  if (!current) return <Button title="Create wallet" onPress={() => wallet.ensure()} />;
+  return (
+    <>
+      <Text>{current.address}</Text>
+      {!current.protected && <Button title="Back up with a passkey" onPress={() => wallet.protect()} />}
+      <Button title="Sign" onPress={() => wallet.signMessage('Hello from Authon')} />
+    </>
+  );
+}
+
+export default function App() {
+  return (
+    <AuthonProvider publishableKey="pk_live_...">
+      <WalletScreen />
+    </AuthonProvider>
+  );
+}
+```
+
+### Without the provider
+
+```ts
+import { createAuthonWallet } from '@authon/react-native-wallet';
+
+const wallet = createAuthonWallet({
+  publishableKey: 'pk_live_...',
+  getToken: async () => mySession.accessToken, // the Authon session token, refreshed when needed
+});
+
+const { address } = await wallet.ensure();
+const signature = await wallet.signMessage('Hello');
+```
+
+`getToken` is called before every wallet call and the token is passed to native code for that call
+only. The token is the Authon session token, not a wallet secret. Call `wallet.dispose()` on sign-out.
+
+## API
+
+Method names and result shapes follow `@authon/js` (`WalletClient`).
+
+| Method | Description |
+|---|---|
+| `capabilities()` | Pre-sign-in check of this device and app (see below). No session, creates nothing, opens no UI. |
+| `appConfig()` | App registration and wallet settings: `{ projectId, allowed, approved, enabled, chainIds, confirmSigning, rpId, minFrameProtocol }`. No session needed. |
+| `get()` / `status()` | The signed-in user's wallet `{ address, protected, needsRestore, backupUpgradeRecommended, devices }`, or `null` when there is none. |
+| `create()` | Creates the wallet (or returns the existing one). |
+| `ensure()` | `get()`, then `create()` when there is no wallet. Concurrent calls share one request. |
+| `isProtected()` | True when the wallet has a passkey backup. |
+| `getAccounts({ start, count, chain })` | HD account addresses `{ index, path, address, chain }` (public, no approval). `chain`: `evm` (default), `tron`, `xrp`, `bitcoin`, `bitcoin-testnet`, `solana`. |
+| `signMessage(message, { account })` | EIP-191 personal_sign; `message` is text or `{ raw: '0x...' }`. |
+| `signTypedData(typedData, { account })` | EIP-712 v4. |
+| `signChainTransaction({ chain, account, address, payload })` | Signs an app-built transaction: Solana `{ message }` (base64 Message) → `{ signature }` (base58); TRON `{ rawDataHex }` → `{ txID, signature }`; Bitcoin / testnet `{ psbt }` (base64, every input with witness_utxo; only our P2WPKH inputs are signed) → `{ psbt, txHex? }` (txHex when every input is ours); XRP `{ txBlobHex }` (encodeForSigning output with SigningPubKey = `getAccounts({ chain: 'xrp' })` `publicKey`) → `{ signature }` (DER). The approval UI summarizes it; unknown programs are shown as high risk. `address` must be the account's address on that chain (`ADDRESS_MISMATCH` otherwise). |
+| `signTransaction(tx, { account })` | Legacy, EIP-2930 or EIP-1559; returns the serialized signed transaction. `bigint` values are allowed. |
+| `protect()` | Creates the passkey backup. Do not let users receive funds before the wallet is protected. |
+| `upgradeBackup()` | Replaces a legacy backup (`backupUpgradeRecommended`) with a verifiable one. |
+| `restore({ resetOtherDevices })` | Restores on this install with the backup passkey; `resetOtherDevices: true` revokes every other device. |
+| `revokeDevice(deviceId)` | Revokes a device. |
+| `onChange(listener)` | Called with the wallet after create/protect/restore/revoke, and `null` on dispose. |
+| `provider(chainId)` | Minimal EIP-1193 provider: `eth_chainId`, `eth_accounts`, `eth_requestAccounts`, `personal_sign`, `eth_signTypedData_v4`, `eth_signTransaction`. |
+| `dispose()` | Releases the native instance and rejects calls in flight (`DISPOSED`). The device share stays on the device. |
+
+`account` (default 0) selects the HD account. For accounts other than 0 the client first reads the
+account's address and the native wallet refuses to sign when the derived key does not match it.
+
+Options of `createAuthonWallet` / `useAuthonWallet`:
+
+| Option | Description |
+|---|---|
+| `publishableKey` | Project publishable key. |
+| `apiUrl` | Defaults to `https://api.authon.dev`. |
+| `getToken` | Session token getter (optional with the hook inside `<AuthonProvider>`). |
+| `appId` | `TEAMID.bundleId` (iOS) / package name (Android), or `{ ios, android }`. Detected when omitted. |
+| `requireDeviceAuthentication` | Also ask for Face ID / Touch ID / passcode (iOS) or BiometricPrompt (Android) before each signature. |
+| `testing` | **Test only**, refused outside debug builds: `{ allowSoftwareKeys, autoApprove }` for simulators and emulators (software device keys instead of Secure Enclave / StrongBox, and no approval UI). Never ship it. |
+
+### Before sign-in: `capabilities()`
+
+```ts
+const caps = await wallet.capabilities();
+if (caps.ready === 'unavailable') showWalletUnavailable(caps); // tell the user before sign-in
+// 'unknown': continue, but be ready for that feature to fail
+```
+
+`{ ready, app, wallet, secureStorage, deviceLock, passkeyBackup, diagnosticId }`; each check is
+`{ status: 'available' | 'unavailable' | 'unknown', reason }`. `ready` is `unavailable` if any check is,
+else `unknown` if any is, else `available`. It answers for a release build (the `testing` options are
+ignored).
+
+| Check | unavailable reason | unknown reason |
+|---|---|---|
+| `app` | `APP_NOT_REGISTERED`, `APP_SIGNATURE_MISMATCH` (Android: the running app's signing certificate differs from the registered one) | `APP_NOT_APPROVED` (signing works, passkey backup waits for approval), `NETWORK_ERROR`, `API_ERROR` |
+| `wallet` | `WALLET_DISABLED` | `NETWORK_ERROR` |
+| `secureStorage` | `HARDWARE_KEYSTORE_UNAVAILABLE` | `SIMULATOR` (simulators and emulators never count as hardware protected), `CHECK_FAILED` |
+| `deviceLock` | `DEVICE_LOCK_NOT_SET` | `CHECK_FAILED` |
+| `passkeyBackup` | `OS_UNSUPPORTED` (iOS < 18, Android < 9), `PASSKEY_API_UNAVAILABLE` | `PRF_PROVIDER_UNVERIFIED` (the provider's PRF support is confirmed on the first `protect()`) |
+
+### Errors
+
+Every failure is an `AuthonWalletError` with `code`, `message`, `diagnosticId` (the server's request ID
+when an API response caused it; log it, never secrets) and `retryable`. Codes are the web wallet's
+(`NOT_FOUND`, `NEEDS_RESTORE`, `NOT_PROTECTED`, `PRF_UNSUPPORTED`, `ORIGIN_NOT_ALLOWED`,
+`USER_CANCELLED`, `UNAUTHORIZED`, `ADDRESS_MISMATCH`, `STORAGE_UNAVAILABLE`, `LAST_DEVICE`,
+`MESSAGE_TOO_LARGE`, `FRAME_OUTDATED`, `BACKUP_KEY_REQUIRED`, `ALREADY_UPGRADED`,
+`ACCOUNT_UNAVAILABLE`, ...), reported unchanged by the Swift and Kotlin wallets. The JS layer adds
+`NOT_SIGNED_IN` (no token), `INVALID_PARAMS`, `DISPOSED` and `NOT_CONFIGURED` (native module missing).
+`USER_CANCELLED` means the user rejected the approval or closed the passkey sheet: go back without an
+error message. `CONFIRM_WINDOW_BLOCKED` means the approval UI could not be shown; nothing was signed.
+
+```ts
+try {
+  await wallet.signMessage(text);
+} catch (e) {
+  if (e instanceof AuthonWalletError && e.code === 'USER_CANCELLED') return; // rejected in the approval UI
+  throw e;
+}
+```
+
+## Trust model
+
+The web wallet runs in a separate origin (wallet.authon.dev), so the page that embeds it can never
+read the device share or the key. In an app SDK the wallet runs **inside your app's process**:
+
+| | Web frame | App SDK (this package) |
+|---|---|---|
+| Where secrets live | Separate origin frame; the site's code cannot read D or k | Inside the app process; the app's own code could in principle reach D, A and k |
+| Authon alone | Holds A only, cannot sign | Same |
+| The app operator alone | Cannot sign | Can reach k at the moment the user signs in this app (the app is inside the trust boundary) |
+| Revoking a device | Server stops serving A | Same; the key is never stored, so the server really blocks the device |
+
+So the app SDK stays non-custodial with respect to Authon, but not with respect to the developer of
+the app that embeds it. This is the common limit of every in-app embedded wallet SDK. The bridge keeps
+secrets out of JS (JS bundles, logs, crash reporters and over-the-air updates never see them), but it
+does not protect against native code in the same app.
+
+## Testing on simulators and emulators
+
+Simulators and emulators have no Secure Enclave / StrongBox and no real passkey PRF. For automated
+tests, pass `testing: { allowSoftwareKeys: true, autoApprove: true }` in a debug build only. Passkey
+`protect()` / `restore()` cannot be exercised there; they are covered by the Swift and Kotlin SDKs'
+tests (software WebAuthn test doubles and the live API tests) and need a real device for acceptance.
+`examples/react-native-wallet` contains such a debug smoke app.
+
+## How the native code is shared
+
+The module compiles the native SDKs' own sources; there is no separate wallet implementation:
+
+- `ios/vendor/` is generated from `swift/Sources/AuthonWallet`, `swift/Sources/CSecp256k1` and
+  `swift/Sources/CKeccak`,
+- `android/src/vendor/kotlin/` is generated from `kotlin/authon/.../dev/authon/sdk/wallet`
+  (without `AuthonWalletAuth.kt`, which needs the Kotlin auth client), plus `android/consumer-rules.pro`.
+
+`node scripts/sync-native-wallet.mjs` (run by this package's `build`) regenerates them, `prepublishOnly` refuses to publish stale copies, and
+`--check` (also part of the test suite) fails on any drift. Do not edit the generated files.
+
+Note for apps that also include the native `dev.authon:authon-android` artifact: it contains the same
+`dev.authon.sdk.wallet` classes, so use one or the other.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,40 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'dev.authon'
+version = '0.1.0'
+
+android {
+  namespace 'dev.authon.reactnative.wallet'
+  // compileSdk comes from the app (Expo 53+ uses 35 or later, which androidx.credentials 1.6.0 needs).
+  // The wallet needs API 28 (StrongBox, BiometricPrompt), so the app's minSdkVersion must be 28 or later.
+  defaultConfig {
+    minSdkVersion 28
+    versionCode 1
+    versionName '0.1.0'
+    consumerProguardFiles 'consumer-rules.pro'
+  }
+  // src/vendor/kotlin is generated from kotlin/authon (dev.authon.sdk.wallet) by scripts/sync-native-wallet.mjs.
+  sourceSets {
+    main.java.srcDirs += 'src/vendor/kotlin'
+  }
+  packagingOptions {
+    resources.excludes += ['META-INF/versions/9/OSGI-INF/MANIFEST.MF', 'META-INF/DEPENDENCIES']
+  }
+}
+
+// The dependency set of dev.authon.sdk.wallet (see kotlin/authon/build.gradle.kts).
+dependencies {
+  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2'
+  implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.1'
+  implementation 'com.squareup.okhttp3:okhttp:4.12.0'
+  implementation('org.web3j:crypto:4.14.0') {
+    exclude group: 'io.consensys.protocols', module: 'jc-kzg-4844'
+    exclude group: 'io.consensys.tuweni'
+    exclude group: 'com.fasterxml.jackson.core'
+  }
+  implementation 'androidx.credentials:credentials:1.6.0'
+  implementation 'androidx.credentials:credentials-play-services-auth:1.6.0'
+}

package/android/consumer-rules.pro

@@ -0,0 +1,10 @@
+# GENERATED by scripts/sync-native-wallet.mjs from kotlin/authon/consumer-rules.pro. Do not edit: change the source and run the script.
+# web3j ships EIP-4844 blob support that needs KZG/tuweni; the Authon SDK never calls it.
+-dontwarn ethereum.ckzg4844.**
+-dontwarn org.apache.tuweni.**
+-dontwarn org.slf4j.**
+-dontwarn com.fasterxml.jackson.**
+-keep class org.web3j.crypto.** { *; }
+# Credential Manager with Play Services
+-if class androidx.credentials.CredentialManager
+-keep class androidx.credentials.playservices.** { *; }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,8 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET" />
+  <uses-permission android:name="android.permission.USE_BIOMETRIC" />
+  <!-- capabilities(): checks whether Google Play services (passkey provider) is installed. -->
+  <queries>
+    <package android:name="com.google.android.gms" />
+  </queries>
+</manifest>

package/android/src/main/java/dev/authon/reactnative/wallet/AuthonWalletModule.kt

@@ -0,0 +1,235 @@
+package dev.authon.reactnative.wallet
+
+import android.content.pm.ApplicationInfo
+import dev.authon.sdk.wallet.AuthonWallet
+import dev.authon.sdk.wallet.CapabilityCheck
+import dev.authon.sdk.wallet.WalletCapabilities
+import dev.authon.sdk.wallet.WalletChain
+import dev.authon.sdk.wallet.PublicWallet
+import dev.authon.sdk.wallet.RestoreMode
+import dev.authon.sdk.wallet.SignAccount
+import dev.authon.sdk.wallet.WalletApprover
+import dev.authon.sdk.wallet.WalletAppConfig
+import dev.authon.sdk.wallet.WalletErrorCode
+import dev.authon.sdk.wallet.WalletException
+import dev.authon.sdk.wallet.WalletMessage
+import dev.authon.sdk.wallet.WalletOptions
+import expo.modules.kotlin.functions.Coroutine
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import java.util.concurrent.ConcurrentHashMap
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.doubleOrNull
+import kotlinx.serialization.json.longOrNull
+import kotlin.coroutines.AbstractCoroutineContextElement
+import kotlin.coroutines.CoroutineContext
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.withContext
+
+/**
+ * Bridges the AuthonWallet core (src/vendor/kotlin, generated from kotlin/authon) to JS.
+ *
+ * Only public data crosses the bridge: addresses, signatures, status and devices. The device share,
+ * the company share, the key and passkey PRF output stay inside the core. Every function resolves an
+ * envelope `{ ok: true, value }` or `{ ok: false, code, message }` with the web wallet's error codes.
+ */
+class AuthonWalletModule : Module() {
+  private val wallets = ConcurrentHashMap<String, AuthonWallet>()
+
+  override fun definition() = ModuleDefinition {
+    Name("AuthonWallet")
+
+    AsyncFunction("configure") { id: String, config: Map<String, Any?> ->
+      envelope { configure(id, config); null }
+    }
+
+    AsyncFunction("release") { id: String ->
+      wallets.remove(id)
+      mapOf("ok" to true, "value" to null)
+    }
+
+    AsyncFunction("appConfig") Coroutine { id: String ->
+      call(id, null) { appConfig(it.appConfig()) }
+    }
+
+    AsyncFunction("capabilities") Coroutine { id: String ->
+      call(id, null) { capabilities(it.capabilities()) }
+    }
+
+    AsyncFunction("status") Coroutine { id: String, token: String ->
+      call(id, token) { wallet(it.status()) }
+    }
+
+    AsyncFunction("create") Coroutine { id: String, token: String ->
+      call(id, token) { wallet(it.create()) }
+    }
+
+    AsyncFunction("accounts") Coroutine { id: String, token: String, start: Int, count: Int, chain: String ->
+      call(id, token) { w ->
+        w.accounts(start.toLong(), count, WalletChain.fromWire(chain)).map {
+          mapOf("index" to it.index.toInt(), "path" to it.path, "address" to it.address, "chain" to it.chain.wire, "publicKey" to it.publicKey)
+        }
+      }
+    }
+
+    AsyncFunction("signMessage") Coroutine { id: String, token: String, kind: String, message: String, account: Int, address: String? ->
+      call(id, token) {
+        val payload = if (kind == "raw") WalletMessage.Raw(message) else WalletMessage.Text(message)
+        it.signMessage(payload, SignAccount.parse(account.toLong(), address))
+      }
+    }
+
+    AsyncFunction("signTypedData") Coroutine { id: String, token: String, typedDataJson: String, account: Int, address: String? ->
+      call(id, token) { it.signTypedData(typedDataJson, SignAccount.parse(account.toLong(), address)) }
+    }
+
+    AsyncFunction("signTransaction") Coroutine { id: String, token: String, transactionJson: String, account: Int, address: String? ->
+      call(id, token) { it.signTransaction(transactionJson, SignAccount.parse(account.toLong(), address)) }
+    }
+
+    AsyncFunction("signChainTransaction") Coroutine { id: String, token: String, chain: String, account: Int, address: String, payloadJson: String ->
+      call(id, token) { it.signChainTransaction(WalletChain.fromWire(chain), account.toLong(), address, parsePayload(payloadJson)) }
+    }
+
+    AsyncFunction("protect") Coroutine { id: String, token: String ->
+      call(id, token) { mapOf("shareVersion" to it.protect().shareVersion) }
+    }
+
+    AsyncFunction("upgradeBackup") Coroutine { id: String, token: String ->
+      call(id, token) { mapOf("shareVersion" to it.upgradeBackup().shareVersion) }
+    }
+
+    AsyncFunction("restore") Coroutine { id: String, token: String, reset: Boolean ->
+      call(id, token) {
+        val r = it.restore(if (reset) RestoreMode.RESET else RestoreMode.ADD)
+        mapOf("shareVersion" to r.shareVersion, "backupUpgradeRecommended" to r.backupUpgradeRecommended)
+      }
+    }
+
+    AsyncFunction("revokeDevice") Coroutine { id: String, token: String, deviceId: String ->
+      call(id, token) { it.revokeDevice(deviceId); null }
+    }
+  }
+
+  // Instances
+
+  private fun configure(id: String, config: Map<String, Any?>) {
+    val context = appContext.reactContext ?: throw WalletException(WalletErrorCode.INTERNAL, "no React context")
+    val publishableKey = (config["publishableKey"] as? String)?.takeIf { it.isNotEmpty() }
+      ?: throw WalletException(WalletErrorCode.INVALID_REQUEST, "publishableKey required")
+    val apiUrl = (config["apiUrl"] as? String)?.takeIf { it.isNotEmpty() } ?: AuthonWallet.DEFAULT_API_URL
+    val appId = (config["appId"] as? String)?.takeIf { it.isNotEmpty() } ?: context.packageName
+    val testing = config["testing"] as? Map<*, *> ?: emptyMap<String, Any?>()
+    val softwareKeys = testing["allowSoftwareKeys"] == true
+    val autoApprove = testing["autoApprove"] == true
+    val debuggable = (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
+    if ((softwareKeys || autoApprove) && !debuggable) {
+      throw WalletException(WalletErrorCode.INVALID_REQUEST, "testing options are only available in debug builds")
+    }
+    val activity = { appContext.currentActivity }
+    wallets[id] = AuthonWallet(
+      context = context.applicationContext,
+      publishableKey = publishableKey,
+      apiUrl = apiUrl,
+      appId = appId,
+      // The token is the Authon session token for this call, not a wallet secret.
+      sessionProvider = { currentCoroutineContext()[CallToken]?.token },
+      activityProvider = activity,
+      options = WalletOptions(
+        // Debug builds only (checked above): approves without UI for automated smoke tests.
+        approver = if (autoApprove) WalletApprover { true } else null,
+        requireDeviceAuthentication = config["requireDeviceAuthentication"] == true,
+        allowSoftwareKeysForTesting = softwareKeys,
+      ),
+    )
+  }
+
+  private suspend fun call(id: String, token: String?, body: suspend (AuthonWallet) -> Any?): Map<String, Any?> {
+    val wallet = wallets[id] ?: return failure(WalletException(WalletErrorCode.INVALID_REQUEST, "wallet not configured"))
+    return try {
+      val value = if (token == null) body(wallet) else withContext(CallToken(token)) { body(wallet) }
+      mapOf("ok" to true, "value" to value)
+    } catch (e: CancellationException) {
+      failure(WalletException(WalletErrorCode.USER_CANCELLED))
+    } catch (e: Throwable) {
+      failure(e)
+    }
+  }
+
+  private inline fun envelope(body: () -> Any?): Map<String, Any?> = try {
+    mapOf("ok" to true, "value" to body())
+  } catch (e: Throwable) {
+    failure(e)
+  }
+
+  private fun failure(e: Throwable): Map<String, Any?> {
+    val w = e as? WalletException ?: WalletException(WalletErrorCode.INTERNAL, "unexpected error")
+    return mapOf(
+      "ok" to false,
+      "code" to w.code.name,
+      "message" to (w.message ?: w.code.name),
+      "diagnosticId" to w.diagnosticId,
+      "retryable" to w.retryable,
+    )
+  }
+
+  private fun parsePayload(json: String): Map<String, Any?> {
+    val obj = runCatching { Json.parseToJsonElement(json) }.getOrNull() as? JsonObject
+      ?: throw WalletException(WalletErrorCode.INVALID_REQUEST, "payload must be a JSON object")
+    return obj.mapValues { (_, v) -> plain(v) }
+  }
+
+  private fun plain(e: JsonElement): Any? = when (e) {
+    is JsonNull -> null
+    is JsonObject -> e.mapValues { (_, v) -> plain(v) }
+    is JsonArray -> e.map { plain(it) }
+    is JsonPrimitive -> if (e.isString) e.content else e.booleanOrNull ?: e.longOrNull ?: e.doubleOrNull
+  }
+
+  // Public data only
+
+  private fun wallet(w: PublicWallet): Map<String, Any?> = mapOf(
+    "address" to w.address,
+    "protected" to w.protected,
+    "needsRestore" to w.needsRestore,
+    "backupUpgradeRecommended" to w.backupUpgradeRecommended,
+    "devices" to w.devices.map {
+      mapOf("id" to it.id, "label" to it.label, "createdAt" to it.createdAt, "lastUsedAt" to it.lastUsedAt, "current" to it.current)
+    },
+  )
+
+  private fun capabilities(c: WalletCapabilities): Map<String, Any?> {
+    fun check(k: CapabilityCheck) = mapOf("status" to k.status.wire, "reason" to k.reason)
+    return mapOf(
+      "ready" to c.ready.wire,
+      "app" to check(c.app),
+      "wallet" to check(c.wallet),
+      "secureStorage" to check(c.secureStorage),
+      "deviceLock" to check(c.deviceLock),
+      "passkeyBackup" to check(c.passkeyBackup),
+      "diagnosticId" to c.diagnosticId,
+    )
+  }
+
+  private fun appConfig(c: WalletAppConfig): Map<String, Any?> = mapOf(
+    "projectId" to c.projectId,
+    "allowed" to c.allowed,
+    "approved" to c.approved,
+    "enabled" to c.enabled,
+    "chainIds" to c.chainIds.map { it.toDouble() },
+    "confirmSigning" to c.confirmSigning,
+    "rpId" to c.rpId,
+    "minFrameProtocol" to c.minFrameProtocol,
+  )
+
+  private class CallToken(val token: String) : AbstractCoroutineContextElement(CallToken) {
+    companion object Key : CoroutineContext.Key<CallToken>
+  }
+}

package/android/src/vendor/GENERATED.md

@@ -0,0 +1,4 @@
+# Generated sources
+
+Everything in this folder is copied from `kotlin/authon/src/main/kotlin/dev/authon/sdk/wallet (without AuthonWalletAuth.kt)` by
+`scripts/sync-native-wallet.mjs` (run by the package build). Do not edit these files; change the native SDK sources and run the script. `--check` fails on any difference.

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

@@ -0,0 +1,86 @@
+// GENERATED by scripts/sync-native-wallet.mjs from kotlin/authon/src/main/kotlin/dev/authon/sdk/wallet/AndroidCapabilityProbe.kt. Do not edit: change the source and run the script.
+package dev.authon.sdk.wallet
+
+import android.app.KeyguardManager
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import java.security.KeyPairGenerator
+import java.security.KeyStore
+import java.security.MessageDigest
+import java.security.spec.ECGenParameterSpec
+import java.util.UUID
+
+/** Device checks for capabilities() on Android. Test-only software-key settings are ignored. */
+class AndroidCapabilityProbe(context: Context) : CapabilityProbe {
+    private val appContext = context.applicationContext
+
+    override fun signingCertSha256(): String? {
+        if (Build.VERSION.SDK_INT < 28) return null
+        val info = appContext.packageManager.getPackageInfo(appContext.packageName, PackageManager.GET_SIGNING_CERTIFICATES)
+        val cert = info.signingInfo?.apkContentsSigners?.firstOrNull() ?: return null
+        return fingerprint(cert.toByteArray())
+    }
+
+    override suspend fun secureStorage(): CapabilityCheck = withContext(Dispatchers.IO) {
+        if (isEmulator()) return@withContext CapabilityCheck.unknown(Capabilities.SIMULATOR)
+        val alias = "dev.authon.wallet.probe.${UUID.randomUUID()}"
+        val ks = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
+        try {
+            val spec = KeyGenParameterSpec.Builder(alias, KeyProperties.PURPOSE_SIGN)
+                .setAlgorithmParameterSpec(ECGenParameterSpec("secp256r1"))
+                .setDigests(KeyProperties.DIGEST_SHA256)
+                .build()
+            val pair = KeyPairGenerator.getInstance(KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore").apply { initialize(spec) }.generateKeyPair()
+            when (KeystoreSecurity.levelOf(pair.private)) {
+                KeySecurityLevel.STRONGBOX, KeySecurityLevel.TRUSTED_ENVIRONMENT, KeySecurityLevel.UNKNOWN_SECURE -> CapabilityCheck.AVAILABLE
+                KeySecurityLevel.SOFTWARE -> CapabilityCheck.unavailable(Capabilities.HARDWARE_KEYSTORE_UNAVAILABLE)
+                KeySecurityLevel.UNKNOWN -> CapabilityCheck.unknown(Capabilities.CHECK_FAILED)
+            }
+        } catch (_: Exception) {
+            CapabilityCheck.unknown(Capabilities.CHECK_FAILED)
+        } finally {
+            runCatching { ks.deleteEntry(alias) }
+        }
+    }
+
+    override fun deviceLock(): CapabilityCheck {
+        val km = appContext.getSystemService(KeyguardManager::class.java) ?: return CapabilityCheck.unknown(Capabilities.CHECK_FAILED)
+        return if (km.isDeviceSecure) CapabilityCheck.AVAILABLE else CapabilityCheck.unavailable(Capabilities.DEVICE_LOCK_NOT_SET)
+    }
+
+    override fun passkeyBackup(): CapabilityCheck {
+        if (Build.VERSION.SDK_INT < 28) return CapabilityCheck.unavailable(Capabilities.OS_UNSUPPORTED)
+        // Android 14+ ships the Credential Manager framework service; older versions need Play services.
+        val framework = Build.VERSION.SDK_INT >= 34 && appContext.getSystemService("credential") != null
+        val playServices = try {
+            appContext.packageManager.getApplicationInfo("com.google.android.gms", 0).enabled
+        } catch (_: PackageManager.NameNotFoundException) {
+            false
+        }
+        return if (framework || playServices) {
+            CapabilityCheck.unknown(Capabilities.PRF_PROVIDER_UNVERIFIED)
+        } else {
+            CapabilityCheck.unavailable(Capabilities.PASSKEY_API_UNAVAILABLE)
+        }
+    }
+
+    companion object {
+        fun fingerprint(der: ByteArray): String =
+            MessageDigest.getInstance("SHA-256").digest(der).joinToString(":") { "%02X".format(it.toInt() and 0xff) }
+
+        /** Conservative emulator detection (goldfish/ranchu hardware, generic/emulator builds). */
+        fun isEmulator(): Boolean {
+            val hw = Build.HARDWARE.lowercase()
+            val fp = Build.FINGERPRINT.lowercase()
+            val product = Build.PRODUCT.lowercase()
+            return hw.contains("goldfish") || hw.contains("ranchu") || fp.startsWith("generic") ||
+                fp.contains("emulator") || fp.contains("/sdk_gphone") || product.startsWith("sdk_gphone") ||
+                product.contains("emulator") || product.contains("simulator")
+        }
+    }
+}