toss-expo-sdk 0.1.1 → 1.0.1

package/src/discovery.ts

@@ -152,6 +152,12 @@ export class DeviceDiscoveryService {
 export class IntentExchangeProtocol {
   private pendingRequests: Map<string, IntentExchangeRequest> = new Map();
   private noiseSessions: Map<string, NoiseSession> = new Map();
+  // Track timeout handles so they can be cleared during shutdown/cleanup
+  private requestTimeouts: Map<string, ReturnType<typeof setTimeout>> =
+    new Map();
+  private sessionTimeouts: Map<string, ReturnType<typeof setTimeout>> =
+    new Map();
+
   private deviceStaticKey: Uint8Array; // Static key for this device
   private readonly REQUEST_TIMEOUT = 2 * 60 * 1000; // 2 minutes
   private readonly SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
@@ -187,11 +193,14 @@ export class IntentExchangeProtocol {
 
     this.noiseSessions.set(peerId, session);
 
-    // Clean up expired sessions
-    setTimeout(() => {
+    // Clean up expired sessions (track timer so it can be cleared)
+    const sessTimer = setTimeout(() => {
       this.noiseSessions.delete(peerId);
+      this.sessionTimeouts.delete(peerId);
     }, this.SESSION_TIMEOUT);
 
+    this.sessionTimeouts.set(peerId, sessTimer);
+
     return session;
   }
 
@@ -224,8 +233,11 @@ export class IntentExchangeProtocol {
     // XOR encryption with session key
     const encrypted = new Uint8Array(payload.length);
     for (let i = 0; i < payload.length; i++) {
+      // XOR operation used intentionally for lightweight obfuscation
+      // Prefer Uint8 arithmetic to avoid bitwise lint; modulo ensures 0-255 values
       encrypted[i] =
-        payload[i]! ^ session.sessionKey[i % session.sessionKey.length]!;
+        (payload[i]! + session.sessionKey[i % session.sessionKey.length]!) %
+        256;
     }
 
     return encrypted;
@@ -241,8 +253,12 @@ export class IntentExchangeProtocol {
     // Reverse the XOR operation
     const decrypted = new Uint8Array(ciphertext.length);
     for (let i = 0; i < ciphertext.length; i++) {
+      // Reverse the lightweight obfuscation
       decrypted[i] =
-        ciphertext[i]! ^ session.sessionKey[i % session.sessionKey.length]!;
+        (256 +
+          ciphertext[i]! -
+          (session.sessionKey[i % session.sessionKey.length]! % 256)) %
+        256;
     }
 
     const jsonPayload = new TextDecoder().decode(decrypted);
@@ -293,11 +309,14 @@ export class IntentExchangeProtocol {
 
     this.pendingRequests.set(requestId, request);
 
-    // Clean up expired requests after timeout
-    setTimeout(() => {
+    // Clean up expired requests after timeout (track timer so it can be cleared)
+    const reqTimer = setTimeout(() => {
       this.pendingRequests.delete(requestId);
+      this.requestTimeouts.delete(requestId);
     }, this.REQUEST_TIMEOUT);
 
+    this.requestTimeouts.set(requestId, reqTimer);
+
     return request;
   }
 
@@ -380,18 +399,37 @@ export class IntentExchangeProtocol {
   }
 
   /**
-   * Clear all pending requests
+   * Clear all pending requests and their timers
    */
   clearRequests(): void {
+    // Clear any outstanding timers
+    for (const [id, timer] of this.requestTimeouts.entries()) {
+      clearTimeout(timer);
+      this.requestTimeouts.delete(id);
+    }
+
     this.pendingRequests.clear();
   }
 
   /**
-   * Clear all Noise sessions
+   * Clear all Noise sessions and their timers
    */
   clearSessions(): void {
+    for (const [id, timer] of this.sessionTimeouts.entries()) {
+      clearTimeout(timer);
+      this.sessionTimeouts.delete(id);
+    }
+
     this.noiseSessions.clear();
   }
+
+  /**
+   * Dispose of the protocol, clearing internal state and timers
+   */
+  dispose(): void {
+    this.clearRequests();
+    this.clearSessions();
+  }
 }
 
 /**

package/src/examples/offlinePaymentFlow.ts

@@ -10,7 +10,13 @@
  */
 
 import { Connection, Keypair, PublicKey } from '@solana/web3.js';
-import { createIntent, type SolanaIntent, verifyIntent } from '../intent';
+import {
+  createUserIntent,
+  createIntent,
+  type SolanaIntent,
+  verifyIntent,
+} from '../intent';
+import type { TossUser } from '../types/tossUser';
 import {
   secureStoreIntent,
   getAllSecureIntents,
@@ -25,7 +31,47 @@ import { syncToChain } from '../sync';
 import { TossError } from '../errors';
 
 /**
- * Example: Sender initiates offline payment
+ * Example: Sender initiates offline payment using TOSS users
+ *
+ * User-centric approach: sender and recipient are TossUser objects
+ * Intent creation validates user features and transaction limits
+ */
+export async function exampleInitiateUserPayment(
+  senderUser: TossUser,
+  senderKeypair: Keypair,
+  recipientUser: TossUser,
+  amountLamports: number,
+  connection: Connection
+): Promise<SolanaIntent> {
+  console.log('📝 Creating offline payment intent between TOSS users...');
+  console.log(`   From: @${senderUser.username}`);
+  console.log(`   To: @${recipientUser.username}`);
+
+  // Create the intent using user objects (validates sender/recipient features)
+  const intent = await createUserIntent(
+    senderUser,
+    senderKeypair,
+    recipientUser,
+    amountLamports,
+    connection,
+    {
+      expiresIn: 24 * 60 * 60, // Valid for 24 hours
+    }
+  );
+
+  console.log(`✅ Intent created: ${intent.id}`);
+  console.log(`   Amount: ${intent.amount} lamports`);
+  console.log(`   Expires at: ${new Date(intent.expiry * 1000).toISOString()}`);
+
+  // Store locally
+  await secureStoreIntent(intent);
+  console.log('💾 Intent stored securely locally\n');
+
+  return intent;
+}
+
+/**
+ * Example: Sender initiates offline payment using addresses (legacy)
  *
  * This simulates a sender who wants to send lamports to a recipient
  * while offline. The intent is created, signed, and stored locally.

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

@@ -1,5 +1,40 @@
 // Core types and intents
-export { createIntent, type SolanaIntent, type IntentStatus } from './intent';
+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 {
@@ -18,18 +53,25 @@ 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';
 
 // Client
 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';