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

package/src/types.ts

@@ -0,0 +1,171 @@
+/** Names and shapes follow `@authon/js` (WalletClient) so web and app code read the same. */
+
+export type Hex = `0x${string}`;
+
+export interface EmbeddedWalletDevice {
+  id: string;
+  label: string | null;
+  createdAt: string | null;
+  lastUsedAt: string | null;
+  /** This app install. */
+  current: boolean;
+}
+
+export interface EmbeddedWallet {
+  /** Account 0 (m/44'/60'/0'/0/0), the same address the web wallet shows for this user. */
+  address: string;
+  /**
+   * True once the wallet has a passkey backup (`protect()`). An unprotected wallet exists only
+   * as this install's device share plus the server share: deleting the app or losing the device
+   * makes it unrecoverable. Do not let users receive funds until `protected` is true.
+   */
+  protected: boolean;
+  /** True when the server has a wallet but this install holds no device share (call `restore()`). */
+  needsRestore: boolean;
+  /** A legacy backup without a passkey public key; call `upgradeBackup()` on a device that holds the wallet. */
+  backupUpgradeRecommended: boolean;
+  devices: EmbeddedWalletDevice[];
+}
+
+/** Chains whose account addresses the wallet derives from the same seed (NATIVE.md section 11). */
+export type WalletChain = 'evm' | 'tron' | 'xrp' | 'bitcoin' | 'bitcoin-testnet' | 'solana';
+
+/**
+ * One HD account. EVM: `m/44'/60'/0'/0/{index}` (account 0 is `EmbeddedWallet.address`); other chains
+ * use their standard paths (TRON `m/44'/195'/n'/0/0`, XRP `m/44'/144'/n'/0/0`, Bitcoin
+ * `m/84'/0'/n'/0/0`, Bitcoin testnet `m/84'/1'/n'/0/0`, Solana `m/44'/501'/n'/0'`).
+ */
+export interface WalletAccount {
+  index: number;
+  path: string;
+  address: string;
+  /** Set when `getAccounts` was asked for a chain. */
+  chain?: WalletChain;
+  /** Public key (hex) when the chain needs it to build a transaction (XRP SigningPubKey). */
+  publicKey?: string;
+}
+
+/** `signChainTransaction` input (NATIVE.md section 12). The app builds the unsigned transaction. */
+export interface WalletChainSignRequest {
+  chain: Exclude<WalletChain, 'evm'>;
+  /** Account index (default 0). */
+  account?: number;
+  /** The account's address on `chain`, from getAccounts. Signing fails (ADDRESS_MISMATCH) if it differs. */
+  address: string;
+  /**
+   * Chain-specific unsigned transaction: Solana `{ message }` (base64 Message, legacy or v0),
+   * TRON `{ rawDataHex }`, Bitcoin `{ psbt }` (base64), XRP `{ txBlobHex }` (encodeForSigning output).
+   */
+  payload: Record<string, unknown>;
+}
+
+/** Signs with another account of the same wallet. Omitted or 0 = the wallet address. */
+export interface WalletSignOptions {
+  account?: number;
+}
+
+/** A personal_sign payload: UTF-8 text, or raw bytes as 0x hex. */
+export type WalletMessage = string | { raw: string };
+
+export interface TypedDataPayload {
+  domain: Record<string, unknown>;
+  types: Record<string, Array<{ name: string; type: string }>>;
+  primaryType: string;
+  message: Record<string, unknown>;
+}
+
+export interface WalletTransactionRequest {
+  to?: string;
+  from?: string;
+  value?: string | number | bigint;
+  data?: string;
+  nonce?: string | number;
+  gas?: string | number | bigint;
+  gasLimit?: string | number | bigint;
+  gasPrice?: string | number | bigint;
+  maxFeePerGas?: string | number | bigint;
+  maxPriorityFeePerGas?: string | number | bigint;
+  chainId?: string | number;
+  type?: string | number;
+  accessList?: Array<{ address: string; storageKeys: string[] }>;
+}
+
+export type WalletChangeListener = (wallet: EmbeddedWallet | null) => void;
+
+/** `GET /v1/wallet/app-config` for this app (public, no session needed). */
+export interface WalletAppConfig {
+  projectId: string | null;
+  /** The app is registered for the project (bundle ID / package name). */
+  allowed: boolean;
+  /** An Authon administrator approved the registration; passkey backup and restore need it. */
+  approved: boolean;
+  enabled: boolean;
+  chainIds: number[];
+  /** Project setting: show the native approval UI before every signature. */
+  confirmSigning: boolean;
+  /** Passkey relying party (`wallet.authon.dev`). */
+  rpId: string;
+  minFrameProtocol: number | null;
+}
+
+export type CapabilityStatus = 'available' | 'unavailable' | 'unknown';
+
+export interface CapabilityCheck {
+  status: CapabilityStatus;
+  /** Reason code (see the README table); null when available. */
+  reason: string | null;
+}
+
+/** `capabilities()`: can this device and app use the wallet? Asked before sign-in, no session. */
+export interface WalletCapabilities {
+  /** unavailable if any check is unavailable, else unknown if any is unknown, else available. */
+  ready: CapabilityStatus;
+  /** App registration and approval (APP_NOT_REGISTERED, APP_SIGNATURE_MISMATCH, APP_NOT_APPROVED, NETWORK_ERROR, API_ERROR). */
+  app: CapabilityCheck;
+  /** Embedded wallet enabled for the project (WALLET_DISABLED, NETWORK_ERROR). */
+  wallet: CapabilityCheck;
+  /** Hardware-protected key storage (HARDWARE_KEYSTORE_UNAVAILABLE, SIMULATOR, CHECK_FAILED). */
+  secureStorage: CapabilityCheck;
+  /** A device passcode / biometrics is set (DEVICE_LOCK_NOT_SET, CHECK_FAILED). */
+  deviceLock: CapabilityCheck;
+  /** Passkey PRF backup, static OS/API support only (OS_UNSUPPORTED, PASSKEY_API_UNAVAILABLE, PRF_PROVIDER_UNVERIFIED). */
+  passkeyBackup: CapabilityCheck;
+  /** X-Request-Id of the app-config response. */
+  diagnosticId: string | null;
+}
+
+export interface EIP1193RequestArguments {
+  method: string;
+  params?: unknown[] | Record<string, unknown>;
+}
+
+export interface EIP1193Provider {
+  request(args: EIP1193RequestArguments): Promise<unknown>;
+}
+
+export type TokenGetter = () => Promise<string | null | undefined> | string | null | undefined;
+
+export interface AuthonWalletOptions {
+  publishableKey: string;
+  /** Defaults to https://api.authon.dev. */
+  apiUrl?: string;
+  /**
+   * Returns the current Authon session (access) token, refreshed when needed. Called before
+   * every wallet call; the token is handed to the native wallet for that call only.
+   */
+  getToken: TokenGetter;
+  /**
+   * The app as registered in the Authon console: `TEAMID.bundleId` on iOS, the package name on
+   * Android. Detected when omitted (iOS: from the keychain access group; Android: package name).
+   */
+  appId?: string | { ios?: string; android?: string };
+  /** Also require Face ID / Touch ID / device credential (iOS) or BiometricPrompt (Android) before each signature. */
+  requireDeviceAuthentication?: boolean;
+  /**
+   * TEST ONLY. Refused by the native module outside debug builds.
+   * - `allowSoftwareKeys`: software device keys when there is no Secure Enclave / StrongBox / TEE
+   *   (simulator, emulator).
+   * - `autoApprove`: approve every signature without UI, for automated smoke tests.
+   */
+  testing?: { allowSoftwareKeys?: boolean; autoApprove?: boolean };
+}

package/src/useAuthonWallet.ts

@@ -0,0 +1,103 @@
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { getAuthonContext } from './authonContext';
+import { AuthonWalletClient } from './client';
+import { AuthonWalletError } from './errors';
+import type { AuthonWalletOptions, EmbeddedWallet, TokenGetter } from './types';
+
+export interface UseAuthonWalletOptions extends Omit<AuthonWalletOptions, 'getToken'> {
+  /** Defaults to the session of the surrounding `<AuthonProvider>` from @authon/react-native. */
+  getToken?: TokenGetter;
+}
+
+export interface UseAuthonWalletResult {
+  /** The client; call ensure(), signMessage(), protect() etc. on it. */
+  wallet: AuthonWalletClient;
+  /** The signed-in user's wallet, null when signed out or before it is created. */
+  current: EmbeddedWallet | null;
+  /** False until the first status check finished (or while signed out and the auth SDK is loading). */
+  isLoaded: boolean;
+  error: AuthonWalletError | null;
+  /** Reloads `current`. */
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Wallet of the signed-in user. Inside `<AuthonProvider>` (@authon/react-native) the session token
+ * comes from the provider and the wallet follows sign-in and sign-out; elsewhere pass `getToken`.
+ * The client is recreated only when publishableKey, apiUrl or appId change.
+ */
+export function useAuthonWallet(options: UseAuthonWalletOptions): UseAuthonWalletResult {
+  const session = useContext(getAuthonContext());
+  const latest = useRef({ options, session });
+  latest.current = { options, session };
+
+  if (!options.getToken && !session) {
+    throw new AuthonWalletError(
+      'NOT_CONFIGURED',
+      'useAuthonWallet needs getToken, or must be used inside <AuthonProvider> from @authon/react-native',
+    );
+  }
+
+  const appIdKey = typeof options.appId === 'string' ? options.appId : JSON.stringify(options.appId ?? null);
+  const testingKey = JSON.stringify(options.testing ?? null);
+  const wallet = useMemo(
+    () =>
+      new AuthonWalletClient({
+        ...latest.current.options,
+        getToken: async () => {
+          const { options: o, session: s } = latest.current;
+          if (o.getToken) return o.getToken();
+          if (!s?.isSignedIn) return null;
+          const token = s.getToken?.();
+          if (token) return token;
+          return (await s.client?.refreshToken?.())?.accessToken ?? null;
+        },
+      }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [options.publishableKey, options.apiUrl, appIdKey, options.requireDeviceAuthentication, testingKey],
+  );
+  // dispose() only resets the client, so this is safe under StrictMode's double effects.
+  useEffect(() => () => wallet.dispose(), [wallet]);
+
+  const [current, setCurrent] = useState<EmbeddedWallet | null>(null);
+  const [isLoaded, setLoaded] = useState(false);
+  const [error, setError] = useState<AuthonWalletError | null>(null);
+
+  useEffect(() => wallet.onChange(setCurrent), [wallet]);
+
+  const signedIn = options.getToken ? true : session?.isSignedIn === true;
+  const sessionUser = options.getToken ? null : session?.userId ?? null;
+  const authLoaded = options.getToken ? true : session?.isLoaded !== false;
+
+  const lastUser = useRef<string | null | undefined>(undefined);
+
+  const refresh = useCallback(async () => {
+    try {
+      setCurrent(await wallet.get());
+      setError(null);
+    } catch (e) {
+      setError(e instanceof AuthonWalletError ? e : new AuthonWalletError('UNKNOWN', String(e)));
+    } finally {
+      setLoaded(true);
+    }
+  }, [wallet]);
+
+  useEffect(() => {
+    if (!authLoaded) return;
+    if (!signedIn) {
+      wallet.dispose();
+      lastUser.current = undefined;
+      setCurrent(null);
+      setError(null);
+      setLoaded(true);
+      return;
+    }
+    // Another user signed in: drop the previous user's cached accounts and in-flight calls.
+    if (lastUser.current !== undefined && lastUser.current !== sessionUser) wallet.dispose();
+    lastUser.current = sessionUser;
+    setLoaded(false);
+    void refresh();
+  }, [authLoaded, signedIn, sessionUser, refresh, wallet]);
+
+  return { wallet, current, isLoaded, error, refresh };
+}