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

package/src/client.ts

@@ -0,0 +1,459 @@
+import { Platform } from 'expo-modules-core';
+import { AuthonWalletError } from './errors';
+import { getNativeModule, type AuthonWalletNativeModule, type NativeResult } from './native';
+import type {
+  AuthonWalletOptions,
+  EIP1193Provider,
+  EmbeddedWallet,
+  EmbeddedWalletDevice,
+  Hex,
+  TypedDataPayload,
+  WalletAccount,
+  CapabilityCheck,
+  CapabilityStatus,
+  WalletAppConfig,
+  WalletCapabilities,
+  WalletChain,
+  WalletChainSignRequest,
+  WalletChangeListener,
+  WalletMessage,
+  WalletSignOptions,
+  WalletTransactionRequest,
+} from './types';
+
+const MAX_ACCOUNT_INDEX = 0x7fffffff;
+let counter = 0;
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const str = (v: unknown): string | null => (typeof v === 'string' ? v : null);
+
+/** Copies only the public fields, so nothing else the native side might add reaches the app. */
+function toWallet(value: unknown): EmbeddedWallet {
+  if (!isObject(value) || typeof value.address !== 'string') throw new AuthonWalletError('UNKNOWN', 'Wallet returned no wallet');
+  const devices: EmbeddedWalletDevice[] = Array.isArray(value.devices)
+    ? value.devices.filter(isObject).map((d) => ({
+        id: String(d.id),
+        label: str(d.label),
+        createdAt: str(d.createdAt),
+        lastUsedAt: str(d.lastUsedAt),
+        current: d.current === true,
+      }))
+    : [];
+  return {
+    address: value.address,
+    protected: value.protected === true,
+    needsRestore: value.needsRestore === true,
+    backupUpgradeRecommended: value.backupUpgradeRecommended === true,
+    devices,
+  };
+}
+
+const CHAINS: WalletChain[] = ['evm', 'tron', 'xrp', 'bitcoin', 'bitcoin-testnet', 'solana'];
+
+function toAccounts(value: unknown): WalletAccount[] {
+  if (!Array.isArray(value)) throw new AuthonWalletError('UNKNOWN', 'Wallet returned no accounts');
+  return value.filter(isObject).map((a) => {
+    const account: WalletAccount = { index: Number(a.index), path: String(a.path), address: String(a.address) };
+    if (CHAINS.includes(a.chain as WalletChain)) account.chain = a.chain as WalletChain;
+    if (typeof a.publicKey === 'string' && /^(0x)?[0-9a-fA-F]+$/.test(a.publicKey)) account.publicKey = a.publicKey;
+    return account;
+  });
+}
+
+function toHex(value: unknown): Hex {
+  if (typeof value !== 'string' || !/^0x[0-9a-fA-F]*$/.test(value)) throw new AuthonWalletError('UNKNOWN', 'Wallet returned no signature');
+  return value as Hex;
+}
+
+function toAppConfig(value: unknown): WalletAppConfig {
+  if (!isObject(value)) throw new AuthonWalletError('UNKNOWN', 'Wallet returned no app config');
+  return {
+    projectId: str(value.projectId),
+    allowed: value.allowed === true,
+    approved: value.approved === true,
+    enabled: value.enabled === true,
+    chainIds: Array.isArray(value.chainIds) ? value.chainIds.map(Number) : [],
+    confirmSigning: value.confirmSigning !== false,
+    rpId: String(value.rpId ?? ''),
+    minFrameProtocol: typeof value.minFrameProtocol === 'number' ? value.minFrameProtocol : null,
+  };
+}
+
+const STATUSES: CapabilityStatus[] = ['available', 'unavailable', 'unknown'];
+
+function toCheck(value: unknown): CapabilityCheck {
+  const v = isObject(value) ? value : {};
+  const status = STATUSES.includes(v.status as CapabilityStatus) ? (v.status as CapabilityStatus) : 'unknown';
+  return { status, reason: status === 'available' ? null : str(v.reason) ?? 'CHECK_FAILED' };
+}
+
+function toCapabilities(value: unknown): WalletCapabilities {
+  if (!isObject(value)) throw new AuthonWalletError('UNKNOWN', 'Wallet returned no capabilities');
+  const checks = {
+    app: toCheck(value.app),
+    wallet: toCheck(value.wallet),
+    secureStorage: toCheck(value.secureStorage),
+    deviceLock: toCheck(value.deviceLock),
+    passkeyBackup: toCheck(value.passkeyBackup),
+  };
+  const all = Object.values(checks).map((c) => c.status);
+  const ready: CapabilityStatus = all.includes('unavailable') ? 'unavailable' : all.includes('unknown') ? 'unknown' : 'available';
+  return { ready, ...checks, diagnosticId: str(value.diagnosticId) };
+}
+
+/** bigint → 0x hex (transactions, like @authon/js). */
+const txReplacer = (_key: string, v: unknown) => (typeof v === 'bigint' ? `0x${v.toString(16)}` : v);
+/** bigint → decimal string (EIP-712 integer values). */
+const typedReplacer = (_key: string, v: unknown) => (typeof v === 'bigint' ? v.toString(10) : v);
+
+/**
+ * The Authon embedded wallet in a React Native app. Signing runs in the native Swift / Kotlin
+ * wallet; JS only sees addresses, signatures, status and devices.
+ */
+export class AuthonWalletClient {
+  private readonly id = `authon-wallet-${++counter}`;
+  private readonly options: AuthonWalletOptions;
+  private readonly listeners = new Set<WalletChangeListener>();
+  private readonly accountAddresses = new Map<number, string>();
+  private configured: Promise<AuthonWalletNativeModule> | null = null;
+  private ensuring: Promise<EmbeddedWallet> | null = null;
+  /** Bumped by dispose(); results of calls started before it are dropped (DISPOSED). */
+  private generation = 0;
+
+  constructor(options: AuthonWalletOptions) {
+    if (!options?.publishableKey) throw new AuthonWalletError('INVALID_PARAMS', 'publishableKey is required');
+    if (typeof options.getToken !== 'function') throw new AuthonWalletError('INVALID_PARAMS', 'getToken is required');
+    this.options = options;
+  }
+
+  /** App registration and wallet settings (does not need a session). */
+  async appConfig(): Promise<WalletAppConfig> {
+    const generation = this.generation;
+    const native = await this.native();
+    return toAppConfig(this.unwrap(await native.appConfig(this.id), generation));
+  }
+
+  /**
+   * Whether this device and app can use the wallet, before sign-in (no session, creates nothing,
+   * opens no UI). `ready === 'unavailable'`: tell the user before signing in; `unknown`: continue
+   * but expect that feature to fail. Answers for release builds (test options are ignored).
+   */
+  async capabilities(): Promise<WalletCapabilities> {
+    const generation = this.generation;
+    const native = await this.native();
+    return toCapabilities(this.unwrap(await native.capabilities(this.id), generation));
+  }
+
+  /** The signed-in user's wallet, or null when there is none yet. */
+  async get(): Promise<EmbeddedWallet | null> {
+    try {
+      return this.remember(toWallet(await this.call((n, id, token) => n.status(id, token))));
+    } catch (error) {
+      if (error instanceof AuthonWalletError && error.code === 'NOT_FOUND') return null;
+      throw error;
+    }
+  }
+
+  /** Same as `get()` (the frame method is `wallet.status`). */
+  status(): Promise<EmbeddedWallet | null> {
+    return this.get();
+  }
+
+  /** Creates the wallet (two-phase on the server), or returns the existing one. */
+  async create(): Promise<EmbeddedWallet> {
+    const wallet = this.remember(toWallet(await this.call((n, id, token) => n.create(id, token))));
+    this.notify(wallet);
+    return wallet;
+  }
+
+  /** Returns the wallet, creating it first when the user has none. Concurrent calls share one request. */
+  ensure(): Promise<EmbeddedWallet> {
+    if (this.ensuring) return this.ensuring;
+    const run = (async () => (await this.get()) ?? (await this.create()))();
+    this.ensuring = run;
+    const clear = () => {
+      if (this.ensuring === run) this.ensuring = null;
+    };
+    run.then(clear, clear);
+    return run;
+  }
+
+  /** True when the wallet exists and has a passkey backup. */
+  async isProtected(): Promise<boolean> {
+    return (await this.get())?.protected === true;
+  }
+
+  /**
+   * Addresses of accounts `start`..`start + count - 1` (public, no approval) on `chain` (default
+   * `evm`). Signing is EVM only for now; other chains are for receiving and display.
+   */
+  async getAccounts(options: { start?: number; count?: number; chain?: WalletChain } = {}): Promise<WalletAccount[]> {
+    const start = options.start ?? 0;
+    const count = options.count ?? 1;
+    const chain = options.chain;
+    if (!Number.isInteger(start) || start < 0 || start > MAX_ACCOUNT_INDEX || !Number.isInteger(count) || count < 1) {
+      throw new AuthonWalletError('INVALID_PARAMS', 'start must be an integer 0..2147483647 and count a positive integer');
+    }
+    if (chain !== undefined && !CHAINS.includes(chain)) {
+      throw new AuthonWalletError('INVALID_PARAMS', `chain must be one of ${CHAINS.join(', ')}`);
+    }
+    const list = toAccounts(await this.call((n, id, token) => n.accounts(id, token, start, count, chain ?? 'evm')));
+    if (chain && list.some((account) => account.chain !== chain)) {
+      // A native wallet without multichain support would answer with EVM addresses.
+      throw new AuthonWalletError('UNSUPPORTED_TYPE', 'This wallet build does not support other chains yet');
+    }
+    // Only EVM addresses can name a signing account.
+    if (!chain || chain === 'evm') for (const account of list) this.accountAddresses.set(account.index, account.address);
+    return list;
+  }
+
+  /**
+   * EIP-191 personal_sign. The native approval sheet / dialog shows the full text first when the
+   * project requires confirmation (default); rejecting gives USER_CANCELLED and nothing is signed.
+   */
+  async signMessage(message: WalletMessage, options: WalletSignOptions = {}): Promise<Hex> {
+    let kind: 'text' | 'raw';
+    let text: string;
+    if (typeof message === 'string') {
+      kind = 'text';
+      text = message;
+    } else if (isObject(message) && typeof message.raw === 'string') {
+      kind = 'raw';
+      text = message.raw;
+    } else {
+      throw new AuthonWalletError('INVALID_PARAMS', 'message must be a string or { raw: hex }');
+    }
+    const [account, address] = await this.account(options.account);
+    return toHex(await this.call((n, id, token) => n.signMessage(id, token, kind, text, account, address)));
+  }
+
+  /** EIP-712 v4 typed data. */
+  async signTypedData(typedData: TypedDataPayload, options: WalletSignOptions = {}): Promise<Hex> {
+    if (!isObject(typedData)) throw new AuthonWalletError('INVALID_PARAMS', 'typedData must be an object');
+    const json = JSON.stringify(typedData, typedReplacer);
+    const [account, address] = await this.account(options.account);
+    return toHex(await this.call((n, id, token) => n.signTypedData(id, token, json, account, address)));
+  }
+
+  /** Signs a legacy, EIP-2930 or EIP-1559 transaction and returns the serialized signed transaction. */
+  async signTransaction(tx: WalletTransactionRequest, options: WalletSignOptions = {}): Promise<Hex> {
+    if (!isObject(tx)) throw new AuthonWalletError('INVALID_PARAMS', 'transaction must be an object');
+    const json = JSON.stringify(tx, txReplacer);
+    const [account, address] = await this.account(options.account);
+    return toHex(await this.call((n, id, token) => n.signTransaction(id, token, json, account, address)));
+  }
+
+  /**
+   * Signs an app-built transaction on another chain (NATIVE.md section 12): Solana `{ signature }`,
+   * TRON `{ signature, txID }`, Bitcoin `{ psbt, txHex? }`, XRP `{ signature }`. The native approval
+   * UI shows what the transaction does (unknown programs / contracts are shown as high risk).
+   */
+  async signChainTransaction(request: WalletChainSignRequest): Promise<Record<string, string>> {
+    if (!isObject(request) || (request.chain as WalletChain) === 'evm') {
+      throw new AuthonWalletError('INVALID_PARAMS', 'use signTransaction for EVM');
+    }
+    if (!CHAINS.includes(request.chain)) throw new AuthonWalletError('INVALID_PARAMS', `chain must be one of ${CHAINS.filter((c) => c !== 'evm').join(', ')}`);
+    const account = request.account ?? 0;
+    if (!Number.isInteger(account) || account < 0 || account > MAX_ACCOUNT_INDEX || typeof request.address !== 'string' || !request.address) {
+      throw new AuthonWalletError('INVALID_PARAMS', 'account index and its address are required');
+    }
+    if (!isObject(request.payload)) throw new AuthonWalletError('INVALID_PARAMS', 'payload must be an object');
+    const payload = JSON.stringify(request.payload, txReplacer);
+    const result = await this.call((n, id, token) => n.signChainTransaction(id, token, request.chain, account, request.address, payload));
+    if (!isObject(result)) throw new AuthonWalletError('UNKNOWN', 'Wallet returned no signature');
+    // Signatures and signed transactions only; anything that is not a string is dropped.
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(result)) if (typeof v === 'string') out[k] = v;
+    return out;
+  }
+
+  /** Creates the passkey backup (iOS 18+ / Android with PRF support). Needs an approved app registration. */
+  async protect(): Promise<void> {
+    await this.call((n, id, token) => n.protect(id, token));
+    await this.refresh();
+  }
+
+  /** Replaces a legacy backup with a verifiable one, on a device that holds the wallet. */
+  async upgradeBackup(): Promise<void> {
+    await this.call((n, id, token) => n.upgradeBackup(id, token));
+    await this.refresh();
+  }
+
+  /**
+   * Restores the wallet on this install with the backup passkey. By default this install is added
+   * as another device; `resetOtherDevices: true` re-splits the key and revokes every other device.
+   */
+  async restore(options: { resetOtherDevices?: boolean } = {}): Promise<void> {
+    const reset = options.resetOtherDevices === true;
+    await this.call((n, id, token) => n.restore(id, token, reset));
+    await this.refresh();
+  }
+
+  /** Revokes a device (signed with this install's device key). */
+  async revokeDevice(deviceId: string): Promise<void> {
+    if (typeof deviceId !== 'string' || !deviceId) throw new AuthonWalletError('INVALID_PARAMS', 'deviceId required');
+    await this.call((n, id, token) => n.revokeDevice(id, token, deviceId));
+    await this.refresh();
+  }
+
+  onChange(listener: WalletChangeListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** A minimal EIP-1193 provider (same methods as @authon/js). */
+  provider(chainId: number): EIP1193Provider {
+    const hexChainId = `0x${chainId.toString(16)}`;
+    return {
+      request: async ({ method, params }) => {
+        const list = Array.isArray(params) ? params : [];
+        switch (method) {
+          case 'eth_chainId':
+            return hexChainId;
+          case 'eth_accounts': {
+            const wallet = await this.get();
+            return wallet ? [wallet.address] : [];
+          }
+          case 'eth_requestAccounts':
+            return [(await this.ensure()).address];
+          case 'personal_sign': {
+            const data = list[0];
+            if (typeof data !== 'string') throw new AuthonWalletError('INVALID_PARAMS', 'personal_sign requires a message');
+            return this.signMessage({ raw: data });
+          }
+          case 'eth_signTypedData_v4': {
+            const raw = list[1];
+            const typed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+            if (!isObject(typed)) throw new AuthonWalletError('INVALID_PARAMS', 'eth_signTypedData_v4 requires typed data');
+            return this.signTypedData(typed as unknown as TypedDataPayload);
+          }
+          case 'eth_signTransaction': {
+            const tx = list[0];
+            if (!isObject(tx)) throw new AuthonWalletError('INVALID_PARAMS', 'eth_signTransaction requires a transaction');
+            return this.signTransaction({ chainId: hexChainId, ...(tx as WalletTransactionRequest) });
+          }
+          default:
+            throw Object.assign(new AuthonWalletError('UNSUPPORTED_METHOD', `Method ${method} is not supported`), { code: 4200 });
+        }
+      },
+    };
+  }
+
+  /**
+   * Call on sign-out: releases the native instance, rejects calls in flight with DISPOSED and
+   * forgets cached account addresses. The device share stays on the device. Like @authon/js, the
+   * client can be used again afterwards (it reconnects on the next call).
+   */
+  dispose(): void {
+    this.generation++;
+    const configured = this.configured;
+    this.configured = null;
+    this.ensuring = null;
+    this.accountAddresses.clear();
+    configured?.then((n) => n.release(this.id)).catch(() => {});
+    this.notify(null);
+  }
+
+  // Internals
+
+  private async native(): Promise<AuthonWalletNativeModule> {
+    if (!this.configured) {
+      const run = (async () => {
+        const native = getNativeModule();
+        if (!native) {
+          throw new AuthonWalletError(
+            'NOT_CONFIGURED',
+            '@authon/react-native-wallet native module not found. Use a development build (not Expo Go) and rebuild the app.',
+          );
+        }
+        const appId = this.options.appId;
+        const platformAppId = typeof appId === 'string' ? appId : Platform.OS === 'ios' ? appId?.ios : appId?.android;
+        this.unwrap(
+          await native.configure(this.id, {
+            publishableKey: this.options.publishableKey,
+            apiUrl: this.options.apiUrl ?? null,
+            appId: platformAppId ?? null,
+            requireDeviceAuthentication: this.options.requireDeviceAuthentication === true,
+            testing: {
+              allowSoftwareKeys: this.options.testing?.allowSoftwareKeys === true,
+              autoApprove: this.options.testing?.autoApprove === true,
+            },
+          }),
+        );
+        return native;
+      })();
+      this.configured = run;
+      run.catch(() => {
+        if (this.configured === run) this.configured = null;
+      });
+    }
+    return this.configured;
+  }
+
+  private async token(): Promise<string> {
+    const token = await this.options.getToken();
+    if (typeof token !== 'string' || !token) throw new AuthonWalletError('NOT_SIGNED_IN', 'Sign in before using the wallet');
+    return token;
+  }
+
+  private async call(fn: (native: AuthonWalletNativeModule, id: string, token: string) => Promise<NativeResult<unknown>>): Promise<unknown> {
+    const generation = this.generation;
+    const native = await this.native();
+    const token = await this.token();
+    return this.unwrap(await fn(native, this.id, token), generation);
+  }
+
+  private unwrap<T>(result: NativeResult<T>, generation = this.generation): T {
+    if (generation !== this.generation) throw new AuthonWalletError('DISPOSED', 'Wallet was disposed');
+    if (!isObject(result)) throw new AuthonWalletError('UNKNOWN', 'Wallet returned no result');
+    if (result.ok === true) return result.value as T;
+    const code = typeof result.code === 'string' && result.code ? result.code : 'UNKNOWN';
+    throw new AuthonWalletError(code, typeof result.message === 'string' && result.message ? result.message : code, {
+      diagnosticId: typeof result.diagnosticId === 'string' && result.diagnosticId ? result.diagnosticId : null,
+      retryable: result.retryable === true,
+    });
+  }
+
+  /** For accounts other than 0 the native wallet needs the expected address and refuses on mismatch. */
+  private async account(index: number | undefined): Promise<[number, string | null]> {
+    if (index === undefined || index === 0) return [0, null];
+    if (!Number.isInteger(index) || index < 0 || index > MAX_ACCOUNT_INDEX) {
+      throw new AuthonWalletError('INVALID_PARAMS', 'account must be an integer 0..2147483647');
+    }
+    let address = this.accountAddresses.get(index);
+    if (!address) {
+      const [account] = await this.getAccounts({ start: index, count: 1 });
+      if (!account || account.index !== index) throw new AuthonWalletError('UNKNOWN', 'Wallet returned another account');
+      address = account.address;
+    }
+    return [index, address];
+  }
+
+  /** A different wallet (another user) invalidates the cached account addresses. */
+  private remember(wallet: EmbeddedWallet): EmbeddedWallet {
+    const known = this.accountAddresses.get(0);
+    if (known && known.toLowerCase() !== wallet.address.toLowerCase()) this.accountAddresses.clear();
+    this.accountAddresses.set(0, wallet.address);
+    return wallet;
+  }
+
+  private async refresh(): Promise<void> {
+    this.notify(await this.get());
+  }
+
+  private notify(wallet: EmbeddedWallet | null): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(wallet);
+      } catch {
+        // A listener error must not break the wallet call.
+      }
+    }
+  }
+}
+
+export function createAuthonWallet(options: AuthonWalletOptions): AuthonWalletClient {
+  return new AuthonWalletClient(options);
+}

package/src/errors.ts

@@ -0,0 +1,58 @@
+/**
+ * Error codes of the web wallet (`@authon/js` WalletErrorCode, frame `errors.ts`). The native
+ * Swift and Kotlin wallets report the same strings; they reach JS unchanged.
+ */
+export type 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'
+  | 'CONFIRM_WINDOW_BLOCKED'
+  | 'CONFIRM_WINDOW_CLOSED'
+  | 'MESSAGE_TOO_LARGE'
+  | 'FRAME_OUTDATED'
+  | 'BACKUP_KEY_REQUIRED'
+  | 'ALREADY_UPGRADED'
+  | 'ACCOUNT_UNAVAILABLE'
+  /** Raised in JS: getToken() returned no token. */
+  | 'NOT_SIGNED_IN'
+  /** Raised in JS: bad arguments caught before the native call. */
+  | 'INVALID_PARAMS'
+  | 'UNSUPPORTED_METHOD'
+  /** Raised in JS: the client was disposed. */
+  | 'DISPOSED'
+  /** Raised in JS: the native module is missing (Expo Go, or the app was not rebuilt). */
+  | 'NOT_CONFIGURED'
+  | 'UNKNOWN'
+  | (string & {});
+
+export class AuthonWalletError extends Error {
+  readonly code: WalletErrorCode;
+  /** The server's request ID when the failure came from an API response; log this, never secrets. */
+  readonly diagnosticId: string | null;
+  /** Whether trying the same call again can succeed (from the native wallet's code table). */
+  readonly retryable: boolean;
+  constructor(code: WalletErrorCode, message?: string, options: { diagnosticId?: string | null; retryable?: boolean } = {}) {
+    super(message ?? code);
+    this.name = 'AuthonWalletError';
+    this.code = code;
+    this.diagnosticId = options.diagnosticId ?? null;
+    this.retryable = options.retryable ?? false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export { AuthonWalletClient, createAuthonWallet } from './client';
+export { AuthonWalletError } from './errors';
+export type { WalletErrorCode } from './errors';
+export { useAuthonWallet } from './useAuthonWallet';
+export type { UseAuthonWalletOptions, UseAuthonWalletResult } from './useAuthonWallet';
+export type {
+  AuthonWalletOptions,
+  CapabilityCheck,
+  CapabilityStatus,
+  WalletCapabilities,
+  WalletChain,
+  WalletChainSignRequest,
+  EIP1193Provider,
+  EIP1193RequestArguments,
+  EmbeddedWallet,
+  EmbeddedWalletDevice,
+  Hex,
+  TokenGetter,
+  TypedDataPayload,
+  WalletAccount,
+  WalletAppConfig,
+  WalletChangeListener,
+  WalletMessage,
+  WalletSignOptions,
+  WalletTransactionRequest,
+} from './types';

package/src/native.ts

@@ -0,0 +1,52 @@
+import { requireOptionalNativeModule } from 'expo-modules-core';
+
+/** Every native function resolves an envelope instead of rejecting. */
+export type NativeResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; code: string; message?: string; diagnosticId?: string | null; retryable?: boolean };
+
+export interface NativeConfig {
+  publishableKey: string;
+  apiUrl: string | null;
+  appId: string | null;
+  requireDeviceAuthentication: boolean;
+  testing: { allowSoftwareKeys: boolean; autoApprove: boolean };
+}
+
+/** The Swift / Kotlin module `AuthonWallet`. Tokens go in per call; nothing secret comes out. */
+export interface AuthonWalletNativeModule {
+  configure(id: string, config: NativeConfig): Promise<NativeResult<null>>;
+  release(id: string): Promise<NativeResult<null>>;
+  appConfig(id: string): Promise<NativeResult<unknown>>;
+  capabilities(id: string): Promise<NativeResult<unknown>>;
+  status(id: string, token: string): Promise<NativeResult<unknown>>;
+  create(id: string, token: string): Promise<NativeResult<unknown>>;
+  accounts(id: string, token: string, start: number, count: number, chain: string): Promise<NativeResult<unknown>>;
+  signMessage(
+    id: string,
+    token: string,
+    kind: 'text' | 'raw',
+    message: string,
+    account: number,
+    address: string | null,
+  ): Promise<NativeResult<unknown>>;
+  signTypedData(id: string, token: string, typedDataJson: string, account: number, address: string | null): Promise<NativeResult<unknown>>;
+  signTransaction(id: string, token: string, transactionJson: string, account: number, address: string | null): Promise<NativeResult<unknown>>;
+  signChainTransaction(id: string, token: string, chain: string, account: number, address: string, payloadJson: string): Promise<NativeResult<unknown>>;
+  protect(id: string, token: string): Promise<NativeResult<unknown>>;
+  upgradeBackup(id: string, token: string): Promise<NativeResult<unknown>>;
+  restore(id: string, token: string, reset: boolean): Promise<NativeResult<unknown>>;
+  revokeDevice(id: string, token: string, deviceId: string): Promise<NativeResult<unknown>>;
+}
+
+let override: AuthonWalletNativeModule | null | undefined;
+
+export function getNativeModule(): AuthonWalletNativeModule | null {
+  if (override !== undefined) return override;
+  return requireOptionalNativeModule<AuthonWalletNativeModule>('AuthonWallet');
+}
+
+/** Tests only: replaces the native module (pass undefined to restore). */
+export function setNativeModuleForTesting(module: AuthonWalletNativeModule | null | undefined): void {
+  override = module;
+}