@sip-protocol/react-native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RECTOR Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# @sip-protocol/react-native
+
+React Native SDK for Shielded Intents Protocol - privacy on iOS/Android.
+
+## Installation
+
+```bash
+npm install @sip-protocol/react-native @sip-protocol/sdk
+
+# Required peer dependencies
+npm install react react-native
+
+# Optional: For secure key storage (recommended for production)
+npm install react-native-keychain
+
+# Optional: For clipboard functionality
+npm install @react-native-clipboard/clipboard
+```
+
+## Features
+
+- **Mobile-optimized hooks** for stealth addresses, transfers, and payment scanning
+- **Secure key storage** via iOS Keychain and Android Keystore
+- **Biometric authentication** support for key access
+- **Native clipboard** integration
+- **Same API** as `@sip-protocol/react` with mobile-specific enhancements
+
+## Quick Start
+
+```tsx
+import {
+  useStealthAddress,
+  useStealthTransfer,
+  useScanPayments,
+  SecureStorage,
+} from '@sip-protocol/react-native'
+
+function ReceiveScreen() {
+  const {
+    metaAddress,
+    stealthAddress,
+    copyToClipboard,
+    saveToKeychain,
+  } = useStealthAddress('solana', {
+    autoSave: true,
+    requireBiometrics: true,
+  })
+
+  return (
+    <View>
+      <Text>Share this address:</Text>
+      <Text selectable>{metaAddress}</Text>
+
+      <TouchableOpacity onPress={copyToClipboard}>
+        <Text>Copy to Clipboard</Text>
+      </TouchableOpacity>
+
+      <TouchableOpacity onPress={saveToKeychain}>
+        <Text>Save to Keychain</Text>
+      </TouchableOpacity>
+    </View>
+  )
+}
+```
+
+## Hooks
+
+### useStealthAddress
+
+Generate and manage stealth addresses with secure storage.
+
+```tsx
+const {
+  metaAddress,        // Encoded meta-address for sharing
+  stealthAddress,     // One-time stealth address
+  spendingPrivateKey, // For claiming (handle securely!)
+  viewingPrivateKey,  // For scanning
+  isGenerating,       // Loading state
+  error,              // Error if any
+  regenerate,         // Generate new stealth address
+  copyToClipboard,    // Copy to native clipboard
+  saveToKeychain,     // Save keys securely
+  loadFromKeychain,   // Load keys from storage
+} = useStealthAddress('solana', {
+  autoSave: false,         // Auto-save on generation
+  requireBiometrics: true, // Require FaceID/TouchID
+  walletId: 'main',        // Storage identifier
+})
+```
+
+### useStealthTransfer
+
+Execute private SPL token transfers.
+
+```tsx
+const {
+  transfer,
+  status,    // 'idle' | 'preparing' | 'signing' | 'sending' | 'confirming' | 'success' | 'error'
+  error,
+  isLoading,
+  reset,
+} = useStealthTransfer({
+  connection,
+  wallet: walletAdapter,
+})
+
+// Send private payment
+const result = await transfer({
+  recipientMetaAddress: 'sip:solana:...',
+  amount: 1000000n, // 1 USDC
+  mint: USDC_MINT,
+})
+
+if (result.success) {
+  Alert.alert('Success', `Sent to ${result.stealthAddress}`)
+}
+```
+
+### useScanPayments
+
+Scan for incoming private payments.
+
+```tsx
+const {
+  payments,   // Array of received payments
+  isScanning,
+  scan,       // (viewingKey, spendingPubKey) => Promise<void>
+  claim,      // (signature, spendingKey, destination) => Promise<string>
+  claimAll,   // (spendingKey, destination) => Promise<string[]>
+  clear,
+} = useScanPayments({
+  connection,
+  provider: heliusProvider, // Optional, recommended for efficiency
+})
+
+// Scan for payments
+await scan(viewingPrivateKey, spendingPublicKey)
+
+// Claim a payment
+await claim(payment.signature, spendingPrivateKey, myWalletAddress)
+```
+
+## Secure Storage
+
+The `SecureStorage` API provides platform-native secure storage:
+
+- **iOS**: Keychain with optional biometric protection
+- **Android**: Keystore with optional biometric protection
+
+```tsx
+import { SecureStorage } from '@sip-protocol/react-native'
+
+// Store viewing key
+await SecureStorage.setViewingKey('wallet-1', viewingKey, {
+  requireBiometrics: true,
+})
+
+// Retrieve with biometric prompt
+const key = await SecureStorage.getViewingKey('wallet-1', {
+  requireBiometrics: true,
+})
+
+// Check biometrics support
+const { available, biometryType } = await SecureStorage.getSupportedBiometrics()
+// biometryType: 'FaceID' | 'TouchID' | 'Fingerprint' | 'None'
+
+// Clear all keys on logout
+await SecureStorage.clearAll()
+```
+
+## Platform Requirements
+
+- iOS 13.0+
+- Android API 23+
+- React Native 0.71+
+
+## Security Considerations
+
+1. **Always use biometrics** for spending key access in production
+2. **Never log private keys** - use `SecureStorage` for persistence
+3. **Clear keys on logout** - call `SecureStorage.clearAll()`
+4. **Use auto-lock** - keys are protected by device lock state
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,442 @@
+export { Asset, ChainId, HexString, PrivacyLevel } from '@sip-protocol/types';
+
+/**
+ * useStealthAddress - Mobile-optimized stealth address hook
+ *
+ * React Native version with secure storage and native clipboard support.
+ *
+ * @example
+ * ```tsx
+ * import { useStealthAddress } from '@sip-protocol/react-native'
+ *
+ * function ReceiveScreen() {
+ *   const {
+ *     metaAddress,
+ *     stealthAddress,
+ *     isGenerating,
+ *     regenerate,
+ *     copyToClipboard,
+ *     saveToKeychain,
+ *   } = useStealthAddress('solana')
+ *
+ *   return (
+ *     <View>
+ *       <Text>Share: {metaAddress}</Text>
+ *       <TouchableOpacity onPress={copyToClipboard}>
+ *         <Text>Copy</Text>
+ *       </TouchableOpacity>
+ *       <TouchableOpacity onPress={saveToKeychain}>
+ *         <Text>Save Securely</Text>
+ *       </TouchableOpacity>
+ *     </View>
+ *   )
+ * }
+ * ```
+ */
+/**
+ * Supported chain IDs (matches @sip-protocol/types ChainId)
+ */
+type SupportedChainId = 'ethereum' | 'solana' | 'near' | 'bitcoin' | 'polygon' | 'arbitrum' | 'optimism' | 'base' | 'bsc' | 'avalanche' | 'cosmos' | 'aptos' | 'sui' | 'polkadot' | 'tezos';
+/**
+ * Options for useStealthAddress hook
+ */
+interface UseStealthAddressOptions {
+    /** Auto-save to secure storage on generation */
+    autoSave?: boolean;
+    /** Require biometrics to access stored keys */
+    requireBiometrics?: boolean;
+    /** Wallet identifier for storage (default: 'default') */
+    walletId?: string;
+}
+/**
+ * Return type for useStealthAddress hook
+ */
+interface UseStealthAddressReturn {
+    /** Encoded meta-address for sharing */
+    metaAddress: string | null;
+    /** One-time stealth address */
+    stealthAddress: string | null;
+    /** Spending private key (for claiming) */
+    spendingPrivateKey: string | null;
+    /** Viewing private key (for scanning) */
+    viewingPrivateKey: string | null;
+    /** Whether generation is in progress */
+    isGenerating: boolean;
+    /** Error if any occurred */
+    error: Error | null;
+    /** Generate a new stealth address */
+    regenerate: () => void;
+    /** Copy stealth address to clipboard */
+    copyToClipboard: () => Promise<boolean>;
+    /** Save keys to secure storage */
+    saveToKeychain: () => Promise<boolean>;
+    /** Load keys from secure storage */
+    loadFromKeychain: () => Promise<boolean>;
+    /** Clear error state */
+    clearError: () => void;
+}
+/**
+ * Mobile-optimized stealth address hook
+ *
+ * @param chain - Target blockchain
+ * @param options - Hook options
+ */
+declare function useStealthAddress(chain: SupportedChainId, options?: UseStealthAddressOptions): UseStealthAddressReturn;
+
+/**
+ * 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>
+ *   )
+ * }
+ * ```
+ */
+/**
+ * Wallet adapter interface for mobile wallets
+ */
+interface MobileWalletAdapter {
+    publicKey: {
+        toBase58(): string;
+    } | null;
+    signTransaction: <T>(transaction: T) => Promise<T>;
+    signAllTransactions?: <T>(transactions: T[]) => Promise<T[]>;
+}
+/**
+ * Transfer status enum
+ */
+type TransferStatus = 'idle' | 'preparing' | 'signing' | 'sending' | 'confirming' | 'success' | 'error';
+/**
+ * Parameters for stealth transfer
+ */
+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
+ */
+interface TransferResult {
+    success: boolean;
+    signature?: string;
+    stealthAddress?: string;
+    error?: Error;
+}
+/**
+ * Connection interface (subset of @solana/web3.js Connection)
+ */
+interface SolanaConnection$1 {
+    confirmTransaction(signature: string, commitment?: string): Promise<{
+        value: {
+            err: unknown;
+        };
+    }>;
+}
+/**
+ * Parameters for useStealthTransfer hook
+ */
+interface UseStealthTransferParams {
+    /** Solana connection */
+    connection: SolanaConnection$1;
+    /** Wallet adapter */
+    wallet: MobileWalletAdapter;
+}
+/**
+ * Return type for useStealthTransfer hook
+ */
+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
+ */
+declare function useStealthTransfer(params: UseStealthTransferParams): UseStealthTransferReturn;
+/**
+ * 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
+ */
+declare function getAssociatedTokenAddress(mint: string, owner: string): Promise<string>;
+
+/**
+ * useScanPayments - Mobile-optimized payment scanning hook
+ *
+ * Scans for incoming stealth payments using viewing key.
+ *
+ * @example
+ * ```tsx
+ * import { useScanPayments } from '@sip-protocol/react-native'
+ *
+ * function InboxScreen() {
+ *   const { payments, isScanning, scan, claim } = useScanPayments({
+ *     connection,
+ *     provider: heliusProvider,
+ *   })
+ *
+ *   useEffect(() => {
+ *     // Load keys from keychain and scan
+ *     loadKeysAndScan()
+ *   }, [])
+ *
+ *   return (
+ *     <FlatList
+ *       data={payments}
+ *       renderItem={({ item }) => (
+ *         <PaymentCard
+ *           payment={item}
+ *           onClaim={() => claim(item.signature)}
+ *         />
+ *       )}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+/**
+ * Solana connection interface (subset of @solana/web3.js Connection)
+ */
+interface SolanaConnection {
+    getAccountInfo(publicKey: unknown): Promise<unknown>;
+    getSignaturesForAddress(address: unknown, options?: unknown): Promise<unknown[]>;
+    getTransaction(signature: string, options?: unknown): Promise<unknown>;
+}
+/**
+ * Scanned payment info
+ */
+interface ScannedPayment {
+    /** Transaction signature */
+    signature: string;
+    /** Stealth address that received the payment */
+    stealthAddress: string;
+    /** Ephemeral public key */
+    ephemeralPublicKey: string;
+    /** Token mint address */
+    mint: string;
+    /** Amount in smallest units */
+    amount: bigint;
+    /** Block timestamp */
+    timestamp: number;
+    /** Whether this payment has been claimed */
+    claimed: boolean;
+}
+/**
+ * Scan status
+ */
+type ScanStatus = 'idle' | 'scanning' | 'claiming' | 'error';
+/**
+ * Hook parameters
+ */
+interface UseScanPaymentsParams {
+    /** Solana connection */
+    connection: SolanaConnection;
+    /** RPC provider (Helius recommended) */
+    provider?: unknown;
+}
+/**
+ * Hook return type
+ */
+interface UseScanPaymentsReturn {
+    /** Scanned payments */
+    payments: ScannedPayment[];
+    /** Current status */
+    status: ScanStatus;
+    /** Error if any */
+    error: Error | null;
+    /** Whether scanning is in progress */
+    isScanning: boolean;
+    /** Scan for payments */
+    scan: (viewingPrivateKey: string, spendingPublicKey: string) => Promise<void>;
+    /** Claim a specific payment */
+    claim: (signature: string, spendingPrivateKey: string, destinationAddress: string) => Promise<string | null>;
+    /** Claim all unclaimed payments */
+    claimAll: (spendingPrivateKey: string, destinationAddress: string) => Promise<string[]>;
+    /** Clear payments */
+    clear: () => void;
+}
+/**
+ * Mobile payment scanning hook
+ */
+declare function useScanPayments(params: UseScanPaymentsParams): UseScanPaymentsReturn;
+
+/**
+ * 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
+ */
+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';
+}
+/**
+ * Key prefixes for different key types
+ */
+declare const KEY_PREFIXES: {
+    readonly spending: "sip:spending:";
+    readonly viewing: "sip:viewing:";
+    readonly ephemeral: "sip:ephemeral:";
+    readonly meta: "sip:meta:";
+};
+type KeyType = keyof typeof KEY_PREFIXES;
+/**
+ * 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
+ */
+declare function setKey(type: KeyType, identifier: string, value: string, options?: SecureStorageOptions): Promise<boolean>;
+/**
+ * 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
+ */
+declare function getKey(type: KeyType, identifier: string, options?: SecureStorageOptions): Promise<string | null>;
+/**
+ * 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
+ */
+declare function deleteKey(type: KeyType, identifier: string, options?: SecureStorageOptions): Promise<boolean>;
+/**
+ * Clear all stored keys
+ *
+ * @param options - Storage options
+ */
+declare function clearAll(options?: SecureStorageOptions): Promise<boolean>;
+/**
+ * Check if biometrics are available on this device
+ *
+ * @returns Biometrics support info
+ */
+declare function getSupportedBiometrics(): Promise<{
+    available: boolean;
+    biometryType: 'FaceID' | 'TouchID' | 'Fingerprint' | 'None';
+}>;
+/**
+ * Check if secure storage is available
+ */
+declare function isAvailable(): boolean;
+/**
+ * SecureStorage API
+ *
+ * Unified API for secure key storage on mobile devices.
+ */
+declare const SecureStorage: {
+    readonly setKey: typeof setKey;
+    readonly getKey: typeof getKey;
+    readonly deleteKey: typeof deleteKey;
+    readonly clearAll: typeof clearAll;
+    readonly setViewingKey: (identifier: string, key: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly getViewingKey: (identifier: string, options?: SecureStorageOptions) => Promise<string | null>;
+    readonly deleteViewingKey: (identifier: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly setSpendingKey: (identifier: string, key: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly getSpendingKey: (identifier: string, options?: SecureStorageOptions) => Promise<string | null>;
+    readonly deleteSpendingKey: (identifier: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly setMetaAddress: (identifier: string, meta: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly getMetaAddress: (identifier: string, options?: SecureStorageOptions) => Promise<string | null>;
+    readonly deleteMetaAddress: (identifier: string, options?: SecureStorageOptions) => Promise<boolean>;
+    readonly getSupportedBiometrics: typeof getSupportedBiometrics;
+    readonly isAvailable: typeof isAvailable;
+};
+
+/**
+ * Clipboard Utilities for React Native
+ *
+ * Provides cross-platform clipboard access with fallback support.
+ */
+/**
+ * Copy text to clipboard
+ *
+ * @param text - Text to copy
+ * @returns true if successful
+ */
+declare function copyToClipboard(text: string): Promise<boolean>;
+/**
+ * Read text from clipboard
+ *
+ * @returns Clipboard contents or empty string
+ */
+declare function readFromClipboard(): Promise<string>;
+/**
+ * Check if clipboard is available
+ */
+declare function isClipboardAvailable(): boolean;
+
+export { type KeyType, type MobileWalletAdapter, type ScanStatus, type ScannedPayment, SecureStorage, type SecureStorageOptions, type TransferParams, type TransferResult, type TransferStatus, type UseScanPaymentsParams, type UseScanPaymentsReturn, type UseStealthAddressOptions, type UseStealthAddressReturn, type UseStealthTransferParams, type UseStealthTransferReturn, copyToClipboard, getAssociatedTokenAddress, isClipboardAvailable, readFromClipboard, useScanPayments, useStealthAddress, useStealthTransfer };