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

package/README.md

@@ -1,3 +1,222 @@
-# 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.1.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).
+- EVM chains: personal_sign, EIP-712 v4, legacy / EIP-2930 / EIP-1559 transactions, HD accounts
+  `m/44'/60'/0'/0/n`.
+
+## 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 |
+|---|---|
+| `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 })` | HD account addresses `{ index, path, address }` (public, no approval). |
+| `signMessage(message, { account })` | EIP-191 personal_sign; `message` is text or `{ raw: '0x...' }`. |
+| `signTypedData(typedData, { account })` | EIP-712 v4. |
+| `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. |
+
+### Errors
+
+Every failure is an `AuthonWalletError` with a `code`. 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).
+
+```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,4 @@
+<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" />
+</manifest>

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

@@ -0,0 +1,181 @@
+package dev.authon.reactnative.wallet
+
+import android.content.pm.ApplicationInfo
+import dev.authon.sdk.wallet.AuthonWallet
+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 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("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 ->
+      call(id, token) { w ->
+        w.accounts(start.toLong(), count).map { mapOf("index" to it.index.toInt(), "path" to it.path, "address" to it.address) }
+      }
+    }
+
+    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("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))
+  }
+
+  // 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 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/AuthonWallet.kt

@@ -0,0 +1,191 @@
+// GENERATED by scripts/sync-native-wallet.mjs from kotlin/authon/src/main/kotlin/dev/authon/sdk/wallet/AuthonWallet.kt. Do not edit: change the source and run the script.
+package dev.authon.sdk.wallet
+
+import android.app.Activity
+import android.content.Context
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import okhttp3.OkHttpClient
+import kotlin.coroutines.CoroutineContext
+
+data class WalletOptions(
+    /** Replaces the default approval dialog. The app is inside the trust boundary, so this is allowed. */
+    val approver: WalletApprover? = null,
+    /** Also require the device lock (BiometricPrompt) before every signature. */
+    val requireDeviceAuthentication: Boolean = false,
+    /** Replaces the Keystore device store (tests). */
+    val deviceStore: DeviceStore? = null,
+    /** Replaces the Credential Manager passkeys (tests). */
+    val passkeys: PasskeyProvider? = null,
+    /** TEST ONLY: accept software-backed Keystore keys (emulators). Never enable in production. */
+    val allowSoftwareKeysForTesting: Boolean = false,
+)
+
+/**
+ * Authon embedded wallet on Android. Same wallet row and `/v1/wallet/me/...` API (protocol 2) as the
+ * web frame, so web and app share one address per project user.
+ *
+ * The device stores only its share D. Every signature or accounts call fetches the company share A
+ * with a device-key proof, combines D+A in memory, derives the key, signs and wipes; the full key is
+ * never stored. All secrets stay inside this process (see README: trust model).
+ *
+ * Errors are [WalletException]s with the web frame's codes.
+ */
+class AuthonWallet internal constructor(
+    private val api: WalletApi,
+    private val packageName: String,
+    private val sessionProvider: suspend () -> String?,
+    private val store: DeviceStore,
+    private val passkeysFactory: (rpId: String) -> PasskeyProvider,
+    private val approver: WalletApprover?,
+    private val deviceAuthenticator: DeviceAuthenticator?,
+    private val dispatcher: CoroutineContext = Dispatchers.Default,
+) {
+    /**
+     * Core constructor (no dependency on the Authon auth client, so wrappers such as the React
+     * Native module can reuse this package alone). [sessionProvider] returns the Authon access
+     * token; [appId] is the package name registered in the console.
+     */
+    @JvmOverloads
+    constructor(
+        context: Context,
+        publishableKey: String,
+        apiUrl: String = DEFAULT_API_URL,
+        appId: String = context.packageName,
+        sessionProvider: suspend () -> String?,
+        activityProvider: () -> Activity?,
+        options: WalletOptions = WalletOptions(),
+        httpClient: OkHttpClient? = null,
+    ) : this(
+        api = if (httpClient != null) WalletApi(apiUrl, publishableKey, httpClient) else WalletApi(apiUrl, publishableKey),
+        packageName = appId,
+        sessionProvider = sessionProvider,
+        store = options.deviceStore ?: KeystoreDeviceStore(context, options.allowSoftwareKeysForTesting),
+        passkeysFactory = { rpId -> options.passkeys ?: CredentialManagerPasskeys(activityProvider, rpId) },
+        approver = options.approver ?: DialogWalletApprover(activityProvider),
+        deviceAuthenticator = if (options.requireDeviceAuthentication) BiometricDeviceAuthenticator(activityProvider) else null,
+    )
+
+    private val mutex = Mutex()
+    private var config: WalletAppConfig? = null
+
+    /** This app's wallet configuration from the API (cached after the first success). */
+    suspend fun appConfig(): WalletAppConfig = run { config ?: api.appConfig(packageName).also { config = it } }
+
+    private class Ready(val ops: WalletOps, val session: String, val config: WalletAppConfig)
+
+    private suspend fun ready(): Ready {
+        val cfg = appConfig()
+        val projectId = cfg.projectId
+        if (!cfg.allowed || projectId == null) throw walletError(WalletErrorCode.ORIGIN_NOT_ALLOWED, "this app is not registered for the Authon wallet")
+        if (!cfg.enabled) throw walletError(WalletErrorCode.ORIGIN_NOT_ALLOWED, "the wallet is disabled for this project")
+        if ((cfg.minFrameProtocol ?: 0) > WalletApi.FRAME_PROTOCOL) throw walletError(WalletErrorCode.FRAME_OUTDATED)
+        val session = sessionProvider()?.takeIf { it.isNotEmpty() } ?: throw walletError(WalletErrorCode.UNAUTHORIZED, "token required")
+        val ctx = WalletContext(
+            api = api,
+            store = store,
+            passkeys = passkeysFactory(cfg.rpId),
+            projectId = projectId,
+            confirmSigning = cfg.confirmSigning,
+            backupVersion = cfg.prfSaltVersion,
+            approver = approver,
+            deviceAuthenticator = deviceAuthenticator,
+        )
+        return Ready(WalletOps(ctx), session, cfg)
+    }
+
+    private fun requirePasskeyApproval(cfg: WalletAppConfig) {
+        if (!cfg.approved) {
+            throw walletError(WalletErrorCode.ORIGIN_NOT_ALLOWED, "this app is not yet approved for ${cfg.rpId} passkeys")
+        }
+    }
+
+    private suspend fun <T> op(block: suspend (Ready) -> T): T = withContext(dispatcher) {
+        mutex.withLock {
+            try {
+                block(ready())
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Throwable) {
+                throw e.toWalletException()
+            }
+        }
+    }
+
+    /** The wallet; NOT_FOUND when this user has none yet. */
+    suspend fun status(): PublicWallet = op { it.ops.toPublicWallet(it.ops.status(it.session)) }
+
+    /** Creates the wallet (two-phase; resumes or discards an interrupted attempt), or returns the existing one. */
+    suspend fun create(): PublicWallet = op { it.ops.toPublicWallet(it.ops.createWallet(it.session)) }
+
+    suspend fun accounts(start: Long = 0, count: Int = 1): List<WalletAccount> = op { it.ops.accounts(it.session, start, count) }
+
+    suspend fun signMessage(message: String, account: SignAccount = SignAccount.PRIMARY): String =
+        signMessage(WalletMessage.Text(message), account)
+
+    suspend fun signMessage(message: WalletMessage, account: SignAccount = SignAccount.PRIMARY): String =
+        op { it.ops.signMessage(it.session, message, account) }
+
+    /** personal_sign over raw bytes given as 0x hex. */
+    suspend fun signRawMessage(hex: String, account: SignAccount = SignAccount.PRIMARY): String =
+        signMessage(WalletMessage.Raw(hex), account)
+
+    /** EIP-712 v4 typed data as a JSON string. */
+    suspend fun signTypedData(typedDataJson: String, account: SignAccount = SignAccount.PRIMARY): String =
+        op { it.ops.signTypedData(it.session, parseObject(typedDataJson), account) }
+
+    /** EIP-712 v4 typed data as a map (`domain`, `types`, `primaryType`, `message`). */
+    suspend fun signTypedData(typedData: Map<String, Any?>, account: SignAccount = SignAccount.PRIMARY): String =
+        op { it.ops.signTypedData(it.session, JsValues.toJson(typedData) as JsonObject, account) }
+
+    /** Signs a legacy / EIP-2930 / EIP-1559 transaction given like the web frame's `tx` (numbers as numbers, decimal or hex strings). */
+    suspend fun signTransaction(transaction: Map<String, Any?>, account: SignAccount = SignAccount.PRIMARY): String =
+        op { it.ops.signTransaction(it.session, JsValues.toJson(transaction) as JsonObject, account) }
+
+    suspend fun signTransaction(transactionJson: String, account: SignAccount = SignAccount.PRIMARY): String =
+        op { it.ops.signTransaction(it.session, parseObject(transactionJson), account) }
+
+    /** Creates the passkey backup (B) of an unprotected wallet. */
+    suspend fun protect(): ProtectResult = op {
+        requirePasskeyApproval(it.config)
+        it.ops.protect(it.session)
+    }
+
+    /** Replaces a legacy backup (no passkey public key) with a verifiable one, from a device that holds the wallet. */
+    suspend fun upgradeBackup(): ProtectResult = op {
+        requirePasskeyApproval(it.config)
+        it.ops.upgradeBackup(it.session)
+    }
+
+    /** Restores the wallet on this device with the backup passkey. */
+    suspend fun restore(mode: RestoreMode = RestoreMode.ADD): RestoreResult = op {
+        requirePasskeyApproval(it.config)
+        it.ops.restore(it.session, mode)
+    }
+
+    /** Revokes a device; signed with this device's key. */
+    suspend fun revokeDevice(deviceId: String): Boolean = op { it.ops.revokeDevice(it.session, deviceId) }
+
+    private fun parseObject(json: String): JsonObject =
+        runCatching { Json.parseToJsonElement(json) as? JsonObject }.getOrNull()
+            ?: throw walletError(WalletErrorCode.INVALID_REQUEST, "expected a JSON object")
+
+    companion object {
+        const val DEFAULT_API_URL = "https://api.authon.dev"
+
+        internal fun forTesting(
+            api: WalletApi,
+            packageName: String,
+            sessionProvider: suspend () -> String?,
+            store: DeviceStore,
+            passkeys: PasskeyProvider,
+            approver: WalletApprover?,
+            deviceAuthenticator: DeviceAuthenticator? = null,
+        ) = AuthonWallet(api, packageName, sessionProvider, store, { passkeys }, approver, deviceAuthenticator)
+    }
+}