@sip-protocol/react-native 0.1.0

package/src/hooks/use-stealth-transfer.ts

@@ -0,0 +1,252 @@
+/**
+ * useStealthTransfer - Mobile-optimized private transfer hook
+ *
+ * Handles shielded SPL token transfers on Solana from mobile devices.
+ *
+ * @example
+ * ```tsx
+ * import { useStealthTransfer } from '@sip-protocol/react-native'
+ *
+ * function SendScreen() {
+ *   const { transfer, status, error, isLoading } = useStealthTransfer({
+ *     connection,
+ *     wallet: walletAdapter,
+ *   })
+ *
+ *   const handleSend = async () => {
+ *     const result = await transfer({
+ *       recipientMetaAddress: 'sip:solana:...',
+ *       amount: 1000000n, // 1 USDC
+ *       mint: USDC_MINT,
+ *     })
+ *     if (result.success) {
+ *       Alert.alert('Success', 'Payment sent privately!')
+ *     }
+ *   }
+ *
+ *   return (
+ *     <TouchableOpacity onPress={handleSend} disabled={isLoading}>
+ *       <Text>{isLoading ? 'Sending...' : 'Send Private Payment'}</Text>
+ *     </TouchableOpacity>
+ *   )
+ * }
+ * ```
+ */
+
+import { useState, useCallback } from 'react'
+
+/**
+ * Wallet adapter interface for mobile wallets
+ */
+export interface MobileWalletAdapter {
+  publicKey: { toBase58(): string } | null
+  signTransaction: <T>(transaction: T) => Promise<T>
+  signAllTransactions?: <T>(transactions: T[]) => Promise<T[]>
+}
+
+/**
+ * Transfer status enum
+ */
+export type TransferStatus =
+  | 'idle'
+  | 'preparing'
+  | 'signing'
+  | 'sending'
+  | 'confirming'
+  | 'success'
+  | 'error'
+
+/**
+ * Parameters for stealth transfer
+ */
+export interface TransferParams {
+  /** Recipient's stealth meta-address */
+  recipientMetaAddress: string
+  /** Amount in smallest units */
+  amount: bigint
+  /** SPL token mint address */
+  mint: string
+}
+
+/**
+ * Result of stealth transfer
+ */
+export interface TransferResult {
+  success: boolean
+  signature?: string
+  stealthAddress?: string
+  error?: Error
+}
+
+/**
+ * Connection interface (subset of @solana/web3.js Connection)
+ */
+export interface SolanaConnection {
+  confirmTransaction(
+    signature: string,
+    commitment?: string
+  ): Promise<{ value: { err: unknown } }>
+}
+
+/**
+ * Parameters for useStealthTransfer hook
+ */
+export interface UseStealthTransferParams {
+  /** Solana connection */
+  connection: SolanaConnection
+  /** Wallet adapter */
+  wallet: MobileWalletAdapter
+}
+
+/**
+ * Return type for useStealthTransfer hook
+ */
+export interface UseStealthTransferReturn {
+  /** Execute a private transfer */
+  transfer: (params: TransferParams) => Promise<TransferResult>
+  /** Current transfer status */
+  status: TransferStatus
+  /** Error if any occurred */
+  error: Error | null
+  /** Whether a transfer is in progress */
+  isLoading: boolean
+  /** Reset the hook state */
+  reset: () => void
+}
+
+/**
+ * Mobile-optimized stealth transfer hook
+ *
+ * @param params - Hook parameters
+ */
+export function useStealthTransfer(
+  params: UseStealthTransferParams
+): UseStealthTransferReturn {
+  const { connection, wallet } = params
+
+  const [status, setStatus] = useState<TransferStatus>('idle')
+  const [error, setError] = useState<Error | null>(null)
+
+  const transfer = useCallback(
+    async (transferParams: TransferParams): Promise<TransferResult> => {
+      const { recipientMetaAddress, amount, mint } = transferParams
+
+      // Validate wallet connected
+      if (!wallet.publicKey) {
+        const err = new Error('Wallet not connected')
+        setError(err)
+        setStatus('error')
+        return { success: false, error: err }
+      }
+
+      try {
+        setStatus('preparing')
+        setError(null)
+
+        // Dynamic import SDK functions to avoid bundling issues
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const sdk: any = await import('@sip-protocol/sdk')
+
+        // Check if sendPrivateSPLTransfer is available
+        if (!sdk.sendPrivateSPLTransfer) {
+          throw new Error(
+            'sendPrivateSPLTransfer not available. Install @sip-protocol/sdk with Solana support.'
+          )
+        }
+
+        const sendPrivateSPLTransfer = sdk.sendPrivateSPLTransfer as (params: {
+          connection: unknown
+          sender: unknown
+          senderTokenAccount: unknown
+          recipientMetaAddress: string
+          mint: unknown
+          amount: bigint
+          signTransaction: unknown
+        }) => Promise<{ signature: string; stealthAddress: string }>
+
+        // Dynamic import Solana libraries
+        const { PublicKey } = await import('@solana/web3.js')
+        const { getAssociatedTokenAddress } = await import('@solana/spl-token')
+
+        // Get sender's token account
+        const mintPubkey = new PublicKey(mint)
+        const senderTokenAccount = await getAssociatedTokenAddress(
+          mintPubkey,
+          new PublicKey(wallet.publicKey.toBase58())
+        )
+
+        setStatus('signing')
+
+        // Execute private transfer
+        const result = await sendPrivateSPLTransfer({
+          connection,
+          sender: new PublicKey(wallet.publicKey.toBase58()),
+          senderTokenAccount,
+          recipientMetaAddress,
+          mint: mintPubkey,
+          amount,
+          signTransaction: wallet.signTransaction,
+        })
+
+        setStatus('confirming')
+
+        // Wait for confirmation
+        const confirmation = await connection.confirmTransaction(
+          result.signature,
+          'confirmed'
+        )
+
+        if (confirmation.value.err) {
+          throw new Error(`Transaction failed: ${confirmation.value.err}`)
+        }
+
+        setStatus('success')
+        setError(null)
+
+        return {
+          success: true,
+          signature: result.signature,
+          stealthAddress: result.stealthAddress,
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Transfer failed')
+        setError(error)
+        setStatus('error')
+        return { success: false, error }
+      }
+    },
+    [connection, wallet]
+  )
+
+  const reset = useCallback(() => {
+    setStatus('idle')
+    setError(null)
+  }, [])
+
+  return {
+    transfer,
+    status,
+    error,
+    isLoading: status !== 'idle' && status !== 'success' && status !== 'error',
+    reset,
+  }
+}
+
+/**
+ * Get associated token address helper
+ *
+ * Dynamically imports from @solana/spl-token
+ *
+ * @param mint - Token mint address string
+ * @param owner - Owner address string
+ * @returns Associated token address
+ */
+export async function getAssociatedTokenAddress(
+  mint: string,
+  owner: string
+): Promise<string> {
+  const { PublicKey } = await import('@solana/web3.js')
+  const { getAssociatedTokenAddress: getATA } = await import('@solana/spl-token')
+  const ata = await getATA(new PublicKey(mint), new PublicKey(owner))
+  return ata.toBase58()
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+/**
+ * @sip-protocol/react-native
+ *
+ * React Native SDK for Shielded Intents Protocol - privacy on iOS/Android.
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   useStealthAddress,
+ *   useStealthTransfer,
+ *   useScanPayments,
+ *   SecureStorage,
+ * } from '@sip-protocol/react-native'
+ *
+ * function PrivacyWallet() {
+ *   const { metaAddress, saveToKeychain } = useStealthAddress('solana', {
+ *     autoSave: true,
+ *     requireBiometrics: true,
+ *   })
+ *
+ *   return <Text>Your private address: {metaAddress}</Text>
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Hooks
+export {
+  // Stealth address generation
+  useStealthAddress,
+  type UseStealthAddressOptions,
+  type UseStealthAddressReturn,
+  // Private transfers
+  useStealthTransfer,
+  type MobileWalletAdapter,
+  type TransferStatus,
+  type TransferParams,
+  type TransferResult,
+  type UseStealthTransferParams,
+  type UseStealthTransferReturn,
+  getAssociatedTokenAddress,
+  // Payment scanning
+  useScanPayments,
+  type ScannedPayment,
+  type ScanStatus,
+  type UseScanPaymentsParams,
+  type UseScanPaymentsReturn,
+} from './hooks'
+
+// Secure Storage (Keychain/Keystore)
+export { SecureStorage, type SecureStorageOptions, type KeyType } from './storage'
+
+// Utilities
+export { copyToClipboard, readFromClipboard, isClipboardAvailable } from './utils'
+
+// Re-export core types for convenience
+export type { ChainId, Asset, HexString, PrivacyLevel } from '@sip-protocol/types'

package/src/storage/index.ts

@@ -0,0 +1 @@
+export { SecureStorage, type SecureStorageOptions, type KeyType } from './secure-storage'

package/src/storage/secure-storage.ts

@@ -0,0 +1,395 @@
+/**
+ * Secure Key Storage for React Native
+ *
+ * Provides secure storage for private keys using native platform capabilities:
+ * - iOS: Keychain with biometric protection
+ * - Android: Keystore with biometric protection
+ *
+ * Falls back to in-memory storage if react-native-keychain is not available.
+ *
+ * @example
+ * ```typescript
+ * import { SecureStorage } from '@sip-protocol/react-native'
+ *
+ * // Store viewing key
+ * await SecureStorage.setViewingKey('my-wallet', viewingPrivateKey)
+ *
+ * // Retrieve with biometric prompt
+ * const key = await SecureStorage.getViewingKey('my-wallet')
+ *
+ * // Clear on logout
+ * await SecureStorage.clearAll()
+ * ```
+ */
+
+/**
+ * Storage options for secure key storage
+ */
+export interface SecureStorageOptions {
+  /** Key identifier/service name */
+  service?: string
+  /** Require biometric authentication to access */
+  requireBiometrics?: boolean
+  /** iOS: Accessibility level */
+  accessible?: 'whenUnlocked' | 'afterFirstUnlock' | 'always'
+  /** Storage backend to use */
+  backend?: 'keychain' | 'memory'
+}
+
+/**
+ * Default service name for SIP keys
+ */
+const DEFAULT_SERVICE = 'com.sip-protocol.keys'
+
+/**
+ * Key prefixes for different key types
+ */
+const KEY_PREFIXES = {
+  spending: 'sip:spending:',
+  viewing: 'sip:viewing:',
+  ephemeral: 'sip:ephemeral:',
+  meta: 'sip:meta:',
+} as const
+
+type KeyType = keyof typeof KEY_PREFIXES
+
+/**
+ * In-memory fallback storage (for testing or when keychain unavailable)
+ */
+const memoryStorage = new Map<string, string>()
+
+/**
+ * Keychain module interface (subset of react-native-keychain)
+ * Defined locally to avoid requiring type declarations at build time
+ */
+interface KeychainModule {
+  ACCESSIBLE: {
+    WHEN_UNLOCKED: number
+    AFTER_FIRST_UNLOCK: number
+    ALWAYS: number
+    WHEN_UNLOCKED_THIS_DEVICE_ONLY: number
+  }
+  ACCESS_CONTROL: {
+    BIOMETRY_CURRENT_SET: number
+  }
+  AUTHENTICATION_TYPE: {
+    BIOMETRICS: number
+  }
+  setGenericPassword(
+    username: string,
+    password: string,
+    options?: {
+      service?: string
+      accessible?: number
+      accessControl?: number
+      authenticationType?: number
+    }
+  ): Promise<boolean | { service: string; storage: string }>
+  getGenericPassword(options?: {
+    service?: string
+    authenticationPrompt?: {
+      title: string
+      subtitle?: string
+      description?: string
+      cancel?: string
+    }
+  }): Promise<false | { username: string; password: string; service: string; storage: string }>
+  resetGenericPassword(options?: { service?: string }): Promise<boolean>
+  getSupportedBiometryType(): Promise<string | null>
+}
+
+/**
+ * Check if react-native-keychain is available
+ */
+let Keychain: KeychainModule | null = null
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+  Keychain = require('react-native-keychain') as KeychainModule
+} catch {
+  // Keychain not available, will use memory fallback
+}
+
+/**
+ * Get the appropriate storage backend
+ */
+function getBackend(options?: SecureStorageOptions): 'keychain' | 'memory' {
+  if (options?.backend) {
+    return options.backend
+  }
+  return Keychain ? 'keychain' : 'memory'
+}
+
+/**
+ * Build the full key name for storage
+ */
+function buildKeyName(type: KeyType, identifier: string): string {
+  return `${KEY_PREFIXES[type]}${identifier}`
+}
+
+/**
+ * Store a key securely
+ *
+ * @param type - Type of key (spending, viewing, ephemeral, meta)
+ * @param identifier - Unique identifier (e.g., wallet address)
+ * @param value - Key value (hex string)
+ * @param options - Storage options
+ */
+async function setKey(
+  type: KeyType,
+  identifier: string,
+  value: string,
+  options?: SecureStorageOptions
+): Promise<boolean> {
+  const keyName = buildKeyName(type, identifier)
+  const backend = getBackend(options)
+
+  if (backend === 'memory') {
+    memoryStorage.set(keyName, value)
+    return true
+  }
+
+  if (!Keychain) {
+    throw new Error(
+      'react-native-keychain is required for secure storage. ' +
+      'Install it or use backend: "memory" for testing.'
+    )
+  }
+
+  const service = options?.service ?? DEFAULT_SERVICE
+
+  // Build keychain options
+  const keychainOptions: {
+    service?: string
+    accessible?: number
+    accessControl?: number
+    authenticationType?: number
+  } = {
+    service,
+    accessible: mapAccessible(options?.accessible),
+  }
+
+  // Add biometric authentication if requested
+  if (options?.requireBiometrics) {
+    keychainOptions.accessControl = Keychain.ACCESS_CONTROL.BIOMETRY_CURRENT_SET
+    keychainOptions.authenticationType =
+      Keychain.AUTHENTICATION_TYPE.BIOMETRICS
+  }
+
+  const result = await Keychain.setGenericPassword(
+    keyName,
+    value,
+    keychainOptions
+  )
+
+  return !!result
+}
+
+/**
+ * Retrieve a key from secure storage
+ *
+ * @param type - Type of key (spending, viewing, ephemeral, meta)
+ * @param identifier - Unique identifier (e.g., wallet address)
+ * @param options - Storage options
+ * @returns Key value or null if not found
+ */
+async function getKey(
+  type: KeyType,
+  identifier: string,
+  options?: SecureStorageOptions
+): Promise<string | null> {
+  const keyName = buildKeyName(type, identifier)
+  const backend = getBackend(options)
+
+  if (backend === 'memory') {
+    return memoryStorage.get(keyName) ?? null
+  }
+
+  if (!Keychain) {
+    throw new Error(
+      'react-native-keychain is required for secure storage. ' +
+      'Install it or use backend: "memory" for testing.'
+    )
+  }
+
+  const service = options?.service ?? DEFAULT_SERVICE
+
+  const keychainOptions: {
+    service?: string
+    authenticationPrompt?: {
+      title: string
+      subtitle?: string
+      description?: string
+      cancel?: string
+    }
+  } = {
+    service,
+  }
+
+  // Add biometric prompt if required
+  if (options?.requireBiometrics) {
+    keychainOptions.authenticationPrompt = {
+      title: 'Authenticate to access key',
+      subtitle: 'SIP Protocol requires authentication',
+      description: 'Use biometrics to unlock your private keys',
+      cancel: 'Cancel',
+    }
+  }
+
+  const result = await Keychain.getGenericPassword(keychainOptions)
+
+  if (!result) {
+    return null
+  }
+
+  // Verify we got the right key
+  if (result.username !== keyName) {
+    return null
+  }
+
+  return result.password
+}
+
+/**
+ * Delete a key from secure storage
+ *
+ * @param type - Type of key (spending, viewing, ephemeral, meta)
+ * @param identifier - Unique identifier (e.g., wallet address)
+ * @param options - Storage options
+ */
+async function deleteKey(
+  type: KeyType,
+  identifier: string,
+  options?: SecureStorageOptions
+): Promise<boolean> {
+  const keyName = buildKeyName(type, identifier)
+  const backend = getBackend(options)
+
+  if (backend === 'memory') {
+    return memoryStorage.delete(keyName)
+  }
+
+  if (!Keychain) {
+    throw new Error('react-native-keychain is required for secure storage.')
+  }
+
+  const service = options?.service ?? DEFAULT_SERVICE
+
+  return await Keychain.resetGenericPassword({ service })
+}
+
+/**
+ * Clear all stored keys
+ *
+ * @param options - Storage options
+ */
+async function clearAll(options?: SecureStorageOptions): Promise<boolean> {
+  const backend = getBackend(options)
+
+  if (backend === 'memory') {
+    memoryStorage.clear()
+    return true
+  }
+
+  if (!Keychain) {
+    throw new Error('react-native-keychain is required for secure storage.')
+  }
+
+  const service = options?.service ?? DEFAULT_SERVICE
+
+  return await Keychain.resetGenericPassword({ service })
+}
+
+/**
+ * Map our accessibility levels to keychain constants
+ */
+function mapAccessible(
+  level?: 'whenUnlocked' | 'afterFirstUnlock' | 'always'
+): number | undefined {
+  if (!Keychain) return undefined
+
+  switch (level) {
+    case 'whenUnlocked':
+      return Keychain.ACCESSIBLE.WHEN_UNLOCKED
+    case 'afterFirstUnlock':
+      return Keychain.ACCESSIBLE.AFTER_FIRST_UNLOCK
+    case 'always':
+      return Keychain.ACCESSIBLE.ALWAYS
+    default:
+      return Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY
+  }
+}
+
+/**
+ * Check if biometrics are available on this device
+ *
+ * @returns Biometrics support info
+ */
+async function getSupportedBiometrics(): Promise<{
+  available: boolean
+  biometryType: 'FaceID' | 'TouchID' | 'Fingerprint' | 'None'
+}> {
+  if (!Keychain) {
+    return { available: false, biometryType: 'None' }
+  }
+
+  const biometryType = await Keychain.getSupportedBiometryType()
+
+  if (!biometryType) {
+    return { available: false, biometryType: 'None' }
+  }
+
+  return {
+    available: true,
+    biometryType: biometryType as 'FaceID' | 'TouchID' | 'Fingerprint',
+  }
+}
+
+/**
+ * Check if secure storage is available
+ */
+function isAvailable(): boolean {
+  return !!Keychain
+}
+
+/**
+ * SecureStorage API
+ *
+ * Unified API for secure key storage on mobile devices.
+ */
+export const SecureStorage = {
+  // Key operations
+  setKey,
+  getKey,
+  deleteKey,
+  clearAll,
+
+  // Convenience methods for viewing keys
+  setViewingKey: (identifier: string, key: string, options?: SecureStorageOptions) =>
+    setKey('viewing', identifier, key, options),
+  getViewingKey: (identifier: string, options?: SecureStorageOptions) =>
+    getKey('viewing', identifier, options),
+  deleteViewingKey: (identifier: string, options?: SecureStorageOptions) =>
+    deleteKey('viewing', identifier, options),
+
+  // Convenience methods for spending keys
+  setSpendingKey: (identifier: string, key: string, options?: SecureStorageOptions) =>
+    setKey('spending', identifier, key, options),
+  getSpendingKey: (identifier: string, options?: SecureStorageOptions) =>
+    getKey('spending', identifier, options),
+  deleteSpendingKey: (identifier: string, options?: SecureStorageOptions) =>
+    deleteKey('spending', identifier, options),
+
+  // Convenience methods for meta addresses
+  setMetaAddress: (identifier: string, meta: string, options?: SecureStorageOptions) =>
+    setKey('meta', identifier, meta, options),
+  getMetaAddress: (identifier: string, options?: SecureStorageOptions) =>
+    getKey('meta', identifier, options),
+  deleteMetaAddress: (identifier: string, options?: SecureStorageOptions) =>
+    deleteKey('meta', identifier, options),
+
+  // Biometrics support
+  getSupportedBiometrics,
+  isAvailable,
+} as const
+
+export type { KeyType }