toss-expo-sdk 0.1.2 → 1.0.1

package/src/hooks/useOfflineBLETransactions.ts

@@ -0,0 +1,438 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Device } from 'react-native-ble-plx';
+import { Connection } from '@solana/web3.js';
+import type { SolanaIntent } from '../intent';
+import type {
+  OfflineTransaction,
+  NonceAccountCacheEntry,
+} from '../types/nonceAccount';
+import type { TossUser } from '../types/tossUser';
+import { BLETransactionHandler } from '../client/BLETransactionHandler';
+import { NonceAccountManager } from '../client/NonceAccountManager';
+import { AuthService } from '../services/authService';
+
+/**
+ * State for BLE transaction transmission
+ */
+export interface BLETransmissionState {
+  isTransmitting: boolean;
+  progress: {
+    sentFragments: number;
+    totalFragments: number;
+    messageId?: string;
+  };
+  error?: string;
+  lastSent?: {
+    messageId: string;
+    timestamp: number;
+  };
+}
+
+/**
+ * State for offline transaction preparation
+ */
+export interface OfflineTransactionState {
+  isPreparing: boolean;
+  transaction?: OfflineTransaction;
+  error?: string;
+  isReady: boolean;
+}
+
+/**
+ * useOfflineTransaction Hook
+ * Manages offline transaction creation with nonce accounts
+ * Handles biometric protection and secure storage
+ */
+export function useOfflineTransaction(user: TossUser, connection: Connection) {
+  const [state, setState] = useState<OfflineTransactionState>({
+    isPreparing: false,
+    isReady: false,
+  });
+  const nonceManagerRef = useRef<NonceAccountManager | null>(null);
+
+  // Initialize nonce manager
+  useEffect(() => {
+    nonceManagerRef.current = new NonceAccountManager(connection);
+
+    // Cleanup expired cache periodically
+    const interval = setInterval(
+      () => {
+        nonceManagerRef.current?.cleanupExpiredCache();
+      },
+      5 * 60 * 1000
+    ); // Every 5 minutes
+
+    return () => clearInterval(interval);
+  }, [connection]);
+
+  /**
+   * Create offline transaction with nonce account
+   * Requires biometric verification if enabled
+   */
+  const createOfflineTransaction = useCallback(
+    async (
+      instructions: any[], // TransactionInstruction[]
+      metadata?: { description?: string; tags?: string[] }
+    ): Promise<OfflineTransaction | null> => {
+      if (!user.nonceAccount) {
+        setState((prev) => ({
+          ...prev,
+          error: 'User does not have nonce account configured',
+        }));
+        return null;
+      }
+
+      setState((prev) => ({
+        ...prev,
+        isPreparing: true,
+        error: undefined,
+      }));
+
+      try {
+        // Verify nonce account access (requires biometric if enabled)
+        if (user.security.nonceAccountRequiresBiometric) {
+          const hasAccess = await AuthService.verifyNonceAccountAccess(
+            user.userId
+          );
+          if (!hasAccess) {
+            throw new Error('Biometric verification failed');
+          }
+        }
+
+        // Get cached nonce account or retrieve from storage
+        const nonceManager = nonceManagerRef.current!;
+        let nonceAccountData = nonceManager.getCachedNonceAccount(user.userId);
+
+        let nonceAccountInfo: NonceAccountCacheEntry | null = null;
+        if (nonceAccountData) {
+          nonceAccountInfo = nonceAccountData;
+        } else {
+          const retrievedInfo = await nonceManager.getNonceAccountSecure(
+            user.userId
+          );
+          if (retrievedInfo) {
+            nonceAccountInfo = nonceManager.getCachedNonceAccount(user.userId);
+          }
+        }
+
+        if (!nonceAccountInfo) {
+          throw new Error('Failed to retrieve nonce account information');
+        }
+
+        // Validate nonce account
+        if (!nonceManager.isNonceAccountValid(nonceAccountInfo.accountInfo)) {
+          throw new Error('Nonce account is no longer valid');
+        }
+
+        // Prepare offline transaction
+        const transaction = await nonceManager.prepareOfflineTransaction(
+          user,
+          instructions,
+          nonceAccountInfo.accountInfo
+        );
+
+        transaction.metadata = metadata || {};
+
+        setState((prev) => ({
+          ...prev,
+          transaction,
+          isReady: true,
+          isPreparing: false,
+        }));
+
+        return transaction;
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        setState((prev) => ({
+          ...prev,
+          error: errorMessage,
+          isPreparing: false,
+          isReady: false,
+        }));
+        return null;
+      }
+    },
+    [user]
+  );
+
+  /**
+   * Clear current offline transaction
+   */
+  const clearTransaction = useCallback(() => {
+    setState({
+      isPreparing: false,
+      isReady: false,
+    });
+  }, []);
+
+  return {
+    ...state,
+    createOfflineTransaction,
+    clearTransaction,
+    nonceManager: nonceManagerRef.current,
+  };
+}
+
+/**
+ * useBLETransactionTransmission Hook
+ * Handles secure BLE transmission of fragmented transactions
+ * with Noise Protocol encryption
+ */
+export function useBLETransactionTransmission(
+  platform: 'android' | 'ios' = 'android'
+) {
+  const [state, setState] = useState<BLETransmissionState>({
+    isTransmitting: false,
+    progress: {
+      sentFragments: 0,
+      totalFragments: 0,
+    },
+  });
+
+  const bleHandlerRef = useRef(new BLETransactionHandler(platform));
+
+  /**
+   * Send transaction over BLE with fragmentation
+   */
+  const sendTransactionBLE = useCallback(
+    async (
+      device: Device,
+      transaction: OfflineTransaction | SolanaIntent,
+      sendFn: (
+        deviceId: string,
+        characteristicUUID: string,
+        data: Buffer
+      ) => Promise<void>,
+      noiseEncryptFn?: (data: Uint8Array) => Promise<any>,
+      isIntent: boolean = false
+    ): Promise<boolean> => {
+      setState((prev) => ({
+        ...prev,
+        isTransmitting: true,
+        error: undefined,
+      }));
+
+      try {
+        const bleHandler = bleHandlerRef.current;
+        const result = await bleHandler.sendFragmentedTransactionBLE(
+          device,
+          transaction,
+          sendFn,
+          noiseEncryptFn,
+          isIntent
+        );
+
+        if (!result.success) {
+          const failedCount = result.failedFragments.length;
+          throw new Error(
+            `Failed to send ${failedCount} fragment(s): ${result.failedFragments.join(', ')}`
+          );
+        }
+
+        setState((prev) => ({
+          ...prev,
+          isTransmitting: false,
+          progress: {
+            sentFragments: result.sentFragments,
+            totalFragments:
+              result.sentFragments + result.failedFragments.length,
+            messageId: result.messageId,
+          },
+          lastSent: {
+            messageId: result.messageId,
+            timestamp: Date.now(),
+          },
+        }));
+
+        return true;
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        setState((prev) => ({
+          ...prev,
+          isTransmitting: false,
+          error: errorMessage,
+        }));
+        return false;
+      }
+    },
+    []
+  );
+
+  /**
+   * Receive fragmented transaction
+   */
+  const receiveTransactionFragment = useCallback(
+    async (
+      fragment: any, // BLEFragment
+      noiseDecryptFn?: (encrypted: any) => Promise<Uint8Array>
+    ): Promise<{
+      complete: boolean;
+      transaction?: OfflineTransaction | SolanaIntent;
+      progress: { received: number; total: number };
+    }> => {
+      try {
+        const bleHandler = bleHandlerRef.current;
+        const result = await bleHandler.receiveFragmentedMessage(
+          fragment,
+          noiseDecryptFn
+        );
+
+        setState((prev) => ({
+          ...prev,
+          progress: {
+            sentFragments: result.progress.received,
+            totalFragments: result.progress.total,
+            messageId: fragment.messageId,
+          },
+        }));
+
+        return result;
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        setState((prev) => ({
+          ...prev,
+          error: errorMessage,
+        }));
+
+        return {
+          complete: false,
+          progress: { received: 0, total: 0 },
+        };
+      }
+    },
+    []
+  );
+
+  const getMTUConfig = useCallback(() => {
+    return bleHandlerRef.current.getMTUConfig();
+  }, []);
+
+  const setMTUConfig = useCallback((config: Partial<any>) => {
+    bleHandlerRef.current.setMTUConfig(config);
+  }, []);
+
+  return {
+    ...state,
+    sendTransactionBLE,
+    receiveTransactionFragment,
+    getMTUConfig,
+    setMTUConfig,
+  };
+}
+
+/**
+ * useNonceAccountManagement Hook
+ * Manages nonce account lifecycle: creation, renewal, revocation
+ */
+export function useNonceAccountManagement(
+  user: TossUser,
+  connection: Connection
+) {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | undefined>();
+  const nonceManagerRef = useRef(new NonceAccountManager(connection));
+
+  /**
+   * Create nonce account with biometric protection
+   */
+  const createNonceAccount = useCallback(
+    async (userKeypair: any) => {
+      setIsLoading(true);
+      setError(undefined);
+
+      try {
+        const updatedUser = await AuthService.createSecureNonceAccount(
+          user,
+          connection,
+          userKeypair
+        );
+
+        return updatedUser;
+      } catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        setError(errorMessage);
+        return null;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [user, connection]
+  );
+
+  /**
+   * Renew nonce account (refresh from blockchain)
+   */
+  const renewNonceAccount = useCallback(async () => {
+    if (!user.nonceAccount) {
+      setError('No nonce account to renew');
+      return null;
+    }
+
+    setIsLoading(true);
+    setError(undefined);
+
+    try {
+      const updated = await nonceManagerRef.current.renewNonceAccount(
+        user.userId,
+        user.nonceAccount.address
+      );
+
+      return updated;
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      setError(errorMessage);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [user.userId, user.nonceAccount]);
+
+  /**
+   * Revoke nonce account
+   */
+  const revokeNonceAccount = useCallback(async () => {
+    setIsLoading(true);
+    setError(undefined);
+
+    try {
+      const updatedUser = await AuthService.revokeNonceAccount(
+        user.userId,
+        user
+      );
+
+      return updatedUser;
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : String(err);
+      setError(errorMessage);
+      return null;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [user]);
+
+  const isNonceAccountValid = useCallback(() => {
+    if (!user.nonceAccount) {
+      return false;
+    }
+
+    const cached = nonceManagerRef.current.getCachedNonceAccount(user.userId);
+    if (cached) {
+      return nonceManagerRef.current.isNonceAccountValid(cached.accountInfo);
+    }
+
+    return user.nonceAccount.status === 'active';
+  }, [user.userId, user.nonceAccount]);
+
+  return {
+    isLoading,
+    error,
+    createNonceAccount,
+    renewNonceAccount,
+    revokeNonceAccount,
+    isNonceAccountValid,
+    hasNonceAccount: !!user.nonceAccount,
+  };
+}

package/src/index.tsx

@@ -3,10 +3,39 @@ export {
   createIntent,
   createUserIntent,
   createSignedIntent,
+  createOfflineIntent,
   type SolanaIntent,
   type IntentStatus,
 } from './intent';
 
+// Nonce Account Management (for offline transactions)
+export { NonceAccountManager } from './client/NonceAccountManager';
+export type {
+  NonceAccountInfo,
+  NonceAccountCacheEntry,
+  CreateNonceAccountOptions,
+  OfflineTransaction,
+} from './types/nonceAccount';
+
+// BLE Transaction Handling (fragmentation & Noise encryption)
+export { BLETransactionHandler } from './client/BLETransactionHandler';
+export type {
+  BLEFragment,
+  EncryptedBLEMessage,
+  BLEMTUConfig,
+} from './client/BLETransactionHandler';
+
+// Custom Hooks for Offline BLE Transactions
+export {
+  useOfflineTransaction,
+  useBLETransactionTransmission,
+  useNonceAccountManagement,
+} from './hooks/useOfflineBLETransactions';
+export type {
+  BLETransmissionState,
+  OfflineTransactionState,
+} from './hooks/useOfflineBLETransactions';
+
 // Intent management
 export {
   verifyIntentSignature,
@@ -24,8 +53,15 @@ export {
   clearPendingIntents,
 } from './storage';
 
-// Transport methods
-export { startTossScan, requestBLEPermissions } from './ble';
+// Transport methods (enhanced with fragmentation)
+export {
+  startTossScan,
+  requestBLEPermissions,
+  sendOfflineTransactionFragmented,
+  receiveOfflineTransactionFragment,
+  getBLEMTUConfig,
+  setBLEMTUConfig,
+} from './ble';
 export { initNFC, readNFCUser, writeUserToNFC, writeIntentToNFC } from './nfc';
 export { QRScanner } from './qr';
 
@@ -34,10 +70,8 @@ export { TossClient, type TossConfig } from './client/TossClient';
 export type { TossUser } from './types/tossUser';
 export { WalletProvider, useWallet } from './contexts/WalletContext';
 
-// Create client instance
-import { TossClient } from './client/TossClient';
-export const createClient = TossClient.createClient;
-
+// Authentication Service (enhanced with nonce accounts)
+export { AuthService } from './services/authService';
 // Sync and settlement
 export { syncToChain, checkSyncStatus, type SyncResult } from './sync';
 

package/src/intent.ts

@@ -5,6 +5,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { sign } from 'tweetnacl';
 import nacl from 'tweetnacl';
 import type { TossUser, TossUserContext } from './types/tossUser';
+import type { OfflineTransaction } from './types/nonceAccount';
 import {
   encryptForArciumInternal,
   type ArciumEncryptedOutput,
@@ -18,6 +19,7 @@ export type IntentStatus = 'pending' | 'settled' | 'failed' | 'expired';
 
 /**
  * Core type for an offline intent following TOSS specification
+ * Enhanced with durable nonce account support
  */
 export interface SolanaIntent {
   // Core fields
@@ -43,6 +45,12 @@ export interface SolanaIntent {
   serialized?: string; // Optional: Serialized transaction
   nonceAccount?: string; // Optional: Public key of the nonce account
   nonceAuth?: string; // Optional: Public key authorized to use the nonce
+  nonceAccountAddress?: string; // Durable nonce account address (from nonce account)
+  nonceAccountAuth?: string; // Authority for durable nonce account
+
+  // Offline transaction support
+  offlineTransaction?: OfflineTransaction; // Associated offline transaction
+  requiresBiometric?: boolean; // Requires biometric to sign/execute
 
   // Privacy features
   encrypted?: ArciumEncryptedOutput; // Optional encrypted payload
@@ -143,6 +151,8 @@ export const nonceManager = new NonceManager();
 /**
  * Creates a signed intent between two TOSS users (User-centric API)
  * Recommended for application developers - validates user wallets
+ *
+ * GAP #8 FIX: Requires biometric authentication for sensitive transactions
  */
 export async function createUserIntent(
   senderUser: TossUser,
@@ -152,6 +162,29 @@ export async function createUserIntent(
   connection: Connection,
   options: CreateIntentOptions = {}
 ): Promise<SolanaIntent> {
+  // GAP #8 FIX: Require biometric verification if enabled
+  if (senderUser.security?.biometricEnabled) {
+    try {
+      const LocalAuthentication = await import('expo-local-authentication');
+      const compatible = await LocalAuthentication.default.hasHardwareAsync();
+      if (compatible) {
+        const authenticated =
+          await LocalAuthentication.default.authenticateAsync({
+            disableDeviceFallback: false,
+          });
+
+        if (!authenticated.success) {
+          throw new Error('Biometric authentication failed');
+        }
+      }
+    } catch (error) {
+      console.warn(
+        'Biometric verification not available, proceeding without',
+        error
+      );
+    }
+  }
+
   // Verify sender's keypair matches their wallet
   if (
     senderKeypair.publicKey.toBase58() !==
@@ -414,3 +447,136 @@ export function updateIntentStatus(
     updatedAt: Math.floor(Date.now() / 1000),
   };
 }
+/**
+ * Creates an offline intent with durable nonce account support
+ * Enables replay-protected offline transactions using nonce accounts
+ * Requires biometric authentication for enhanced security
+ */
+export async function createOfflineIntent(
+  senderUser: TossUser,
+  senderKeypair: Keypair,
+  recipientUser: TossUser,
+  amount: number,
+  nonceAccountInfo: any, // NonceAccountInfo from NonceAccountManager
+  connection: Connection,
+  options: CreateIntentOptions = {}
+): Promise<SolanaIntent> {
+  // Verify sender has nonce account enabled
+  if (
+    !senderUser.nonceAccount ||
+    !senderUser.tossFeatures.offlineTransactionsEnabled
+  ) {
+    throw new Error('Offline transactions not enabled for this user');
+  }
+
+  // Verify sender's keypair matches their wallet
+  if (
+    senderKeypair.publicKey.toBase58() !==
+    senderUser.wallet.publicKey.toBase58()
+  ) {
+    throw new Error('Sender keypair does not match user wallet');
+  }
+
+  // Verify both users can transact
+  if (!senderUser.tossFeatures.canSend) {
+    throw new Error('Sender account is not enabled for sending');
+  }
+  if (!recipientUser.tossFeatures.canReceive) {
+    throw new Error('Recipient account is not enabled for receiving');
+  }
+
+  // Verify transaction amount is within limits
+  if (amount > senderUser.tossFeatures.maxTransactionAmount) {
+    throw new Error(
+      `Transaction amount exceeds limit of ${senderUser.tossFeatures.maxTransactionAmount} lamports`
+    );
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const defaultExpiry = 24 * 60 * 60; // 24 hours default
+
+  // Get latest blockhash for nonce account
+  const { blockhash } = await connection.getLatestBlockhash();
+
+  // Prepare user contexts
+  const senderCtx: TossUserContext = {
+    userId: senderUser.userId,
+    username: senderUser.username,
+    wallet: {
+      publicKey: senderUser.wallet.publicKey,
+      isVerified: senderUser.wallet.isVerified,
+      createdAt: senderUser.wallet.createdAt,
+    },
+    status: senderUser.status,
+    deviceId: senderUser.device.id,
+    sessionId: uuidv4(),
+  };
+
+  const recipientCtx: TossUserContext = {
+    userId: recipientUser.userId,
+    username: recipientUser.username,
+    wallet: {
+      publicKey: recipientUser.wallet.publicKey,
+      isVerified: recipientUser.wallet.isVerified,
+      createdAt: recipientUser.wallet.createdAt,
+    },
+    status: recipientUser.status,
+    deviceId: recipientUser.device.id,
+    sessionId: uuidv4(),
+  };
+
+  // Create base intent with nonce account support
+  const baseIntent: Omit<SolanaIntent, 'signature'> = {
+    id: uuidv4(),
+    from: senderKeypair.publicKey.toBase58(),
+    to: recipientUser.wallet.publicKey.toBase58(),
+    fromUser: senderCtx,
+    toUser: recipientCtx,
+    amount,
+    nonce: nonceAccountInfo.currentNonce,
+    expiry: now + (options.expiresIn || defaultExpiry),
+    blockhash,
+    feePayer: senderKeypair.publicKey.toBase58(),
+    status: 'pending',
+    createdAt: now,
+    updatedAt: now,
+    // Nonce account support
+    nonceAccountAddress: nonceAccountInfo.address,
+    nonceAccountAuth: nonceAccountInfo.authorizedSigner,
+    requiresBiometric: senderUser.security.nonceAccountRequiresBiometric,
+    // Backward compatibility
+    nonceAccount: nonceAccountInfo.address,
+    nonceAuth: nonceAccountInfo.authorizedSigner,
+  };
+
+  // Sign the intent
+  const signature = sign(
+    Buffer.from(JSON.stringify(baseIntent)),
+    senderKeypair.secretKey
+  );
+
+  const intent: SolanaIntent = {
+    ...baseIntent,
+    signature: bs58.encode(signature),
+  };
+
+  // If private transaction, encrypt the intent data
+  if (options.privateTransaction) {
+    if (!options.mxeProgramId) {
+      throw new Error('MXE Program ID is required for private transactions');
+    }
+    if (!options.provider) {
+      throw new Error('Provider is required for private transactions');
+    }
+
+    const plaintextValues: bigint[] = [BigInt(amount)];
+
+    intent.encrypted = await encryptForArciumInternal(
+      options.mxeProgramId,
+      plaintextValues,
+      options.provider
+    );
+  }
+
+  return intent;
+}