Merge pull request #298 from dev-fatima-24/issue-#222

Frontend — Wallet session persistence: reconnect on page reload without re-prompting

Author: jhayniffy

frontend/src/features/wallet/WALLET_SECURITY.md

@@ -0,0 +1,12 @@
+# Wallet Security and Persistence
+
+## Storing Public Keys vs Private Keys
+In the interest of user experience, our application persists the wallet session using `localStorage` to attempt silent auto-reconnects on page reloads.
+
+**Important Security Implications:**
+1. **Never Store Secrets:** We only persist the `walletType` and the `publicKey` (Stellar Address) in localStorage. 
+2. **Never** store seed phrases, private keys, or signed transactions in local storage or sessionStorage, as these are vulnerable to XSS (Cross-Site Scripting) attacks.
+3. **Public Nature of Addresses:** A public key is not secret. Storing it in localStorage merely indicates which account the user was last trying to connect with.
+4. **Validation on Reconnect:** During silent reconnect (`app mount`), the app queries the wallet extension or kit for the active address. We explicitly validate that the returned address matches the persisted public key. If there is a mismatch (e.g., the user switched accounts in their wallet extension), the session is cleared to prevent impersonation bugs.
+
+By enforcing these constraints, we ensure a smooth UX without compromising the user's private keys or allowing incorrect application states.

frontend/src/features/wallet/__tests__/WalletContextAutoReconnect.test.tsx

@@ -0,0 +1,116 @@
+import React from 'react';
+import { render, act, waitFor } from '@testing-library/react';
+import { StellarWalletsKit } from '@creit.tech/stellar-wallets-kit';
+import { WalletProvider, useWalletContext } from '../context/WalletContext';
+import { toast } from '@/components/ui/use-toast';
+
+// Mock dependencies
+jest.mock('@creit.tech/stellar-wallets-kit', () => ({
+  StellarWalletsKit: {
+    init: jest.fn(),
+    on: jest.fn(),
+    setWallet: jest.fn(),
+    getAddress: jest.fn(),
+    getNetwork: jest.fn(),
+    setNetwork: jest.fn(),
+    disconnect: jest.fn(),
+    signTransaction: jest.fn(),
+  },
+  Networks: { PUBLIC: 'public', TESTNET: 'testnet', FUTURENET: 'futurenet' },
+  KitEventType: { STATE_UPDATED: 'state_updated', DISCONNECT: 'disconnect' },
+}));
+
+jest.mock('@creit.tech/stellar-wallets-kit/modules/freighter', () => ({
+  FreighterModule: jest.fn(),
+  FREIGHTER_ID: 'freighter',
+}));
+
+jest.mock('@creit.tech/stellar-wallets-kit/modules/xbull', () => ({
+  xBullModule: jest.fn(),
+  XBULL_ID: 'xbull',
+}));
+
+jest.mock('@/components/ui/use-toast', () => ({
+  toast: jest.fn(),
+}));
+
+const LS_WALLET_SESSION = 'niffyinsur-wallet-session-v1';
+
+const TestComponent = () => {
+  const { address, activeWalletId, connectionStatus } = useWalletContext();
+  return (
+    <div>
+      <div data-testid="address">{address || 'none'}</div>
+      <div data-testid="wallet-id">{activeWalletId || 'none'}</div>
+      <div data-testid="status">{connectionStatus}</div>
+    </div>
+  );
+};
+
+describe('WalletContext Auto-Reconnect', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    jest.clearAllMocks();
+    (StellarWalletsKit.getNetwork as jest.Mock).mockResolvedValue({ network: 'testnet' });
+  });
+
+  it('silently reconnects when valid session exists', async () => {
+    const session = { walletId: 'freighter', publicKey: 'GBXYZ...' };
+    localStorage.setItem(LS_WALLET_SESSION, JSON.stringify(session));
+    
+    (StellarWalletsKit.getAddress as jest.Mock).mockResolvedValue({ address: 'GBXYZ...' });
+
+    const { getByTestId } = render(
+      <WalletProvider>
+        <TestComponent />
+      </WalletProvider>
+    );
+
+    await waitFor(() => {
+      expect(getByTestId('status').textContent).toBe('connected');
+      expect(getByTestId('address').textContent).toBe('GBXYZ...');
+      expect(getByTestId('wallet-id').textContent).toBe('freighter');
+    });
+
+    expect(StellarWalletsKit.setWallet).toHaveBeenCalledWith('freighter');
+  });
+
+  it('clears session when public keys mismatch', async () => {
+    // Session is for GBXYZ, but adapter returns GB123
+    const session = { walletId: 'xbull', publicKey: 'GBXYZ...' };
+    localStorage.setItem(LS_WALLET_SESSION, JSON.stringify(session));
+    
+    (StellarWalletsKit.getAddress as jest.Mock).mockResolvedValue({ address: 'GB123...' });
+
+    const { getByTestId } = render(
+      <WalletProvider>
+        <TestComponent />
+      </WalletProvider>
+    );
+
+    await waitFor(() => {
+      expect(localStorage.getItem(LS_WALLET_SESSION)).toBeNull();
+      expect(getByTestId('status').textContent).toBe('disconnected');
+    });
+  });
+
+  it('shows non-blocking banner (toast) when reconnect fails', async () => {
+    const session = { walletId: 'freighter', publicKey: 'GBXYZ...' };
+    localStorage.setItem(LS_WALLET_SESSION, JSON.stringify(session));
+    
+    (StellarWalletsKit.getAddress as jest.Mock).mockRejectedValue(new Error('Locked'));
+
+    render(
+      <WalletProvider>
+        <TestComponent />
+      </WalletProvider>
+    );
+
+    await waitFor(() => {
+      expect(toast).toHaveBeenCalledWith(expect.objectContaining({
+        title: 'Reconnect failed',
+        variant: 'default',
+      }));
+    });
+  });
+});

frontend/src/features/wallet/context/WalletContext.tsx

@@ -47,6 +47,12 @@ const WalletContext = createContext<WalletContextValue | null>(null)
 
 const LS_WALLET_KEY = 'niffyinsure:lastWalletId'
 const LS_NETWORK_KEY = 'niffyinsure:appNetwork'
+const LS_WALLET_SESSION = 'niffyinsur-wallet-session-v1'
+
+interface WalletSession {
+  walletId: WalletId;
+  publicKey: string;
+}
 
 function kitNetworkFor(app: AppNetwork): Networks {
   if (app === 'mainnet') return Networks.PUBLIC
@@ -94,6 +100,7 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
           setActiveWalletId(null)
           setWalletNetwork(null)
           setWalletNetworkResolution({ status: 'idle' })
+          localStorage.removeItem(LS_WALLET_SESSION)
         }
       } catch {
         setAddress(null)
@@ -106,28 +113,48 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
       setActiveWalletId(null)
       setWalletNetwork(null)
       setWalletNetworkResolution({ status: 'idle' })
+      localStorage.removeItem(LS_WALLET_SESSION)
     })
 
-    // Auto-reconnect last wallet
-    const lastWallet = localStorage.getItem(LS_WALLET_KEY) as WalletId | null
-    if (lastWallet) {
-      reconnect(lastWallet)
+    // Auto-reconnect last wallet (Silent reconnect on app mount)
+    const sessionRaw = localStorage.getItem(LS_WALLET_SESSION)
+    if (sessionRaw) {
+      try {
+        const session = JSON.parse(sessionRaw) as WalletSession
+        reconnect(session)
+      } catch {
+        localStorage.removeItem(LS_WALLET_SESSION)
+      }
     }
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
-  async function reconnect(walletId: WalletId) {
+  async function reconnect(session: WalletSession) {
     try {
-      StellarWalletsKit.setWallet(walletId)
+      StellarWalletsKit.setWallet(session.walletId)
       const { address: addr } = await StellarWalletsKit.getAddress()
+      
       if (addr) {
+        // Validate reconnected public key matches stored value (Requirement: clear if mismatched)
+        if (addr !== session.publicKey) {
+          console.warn('Wallet address mismatch during reconnect. Clearing session.')
+          localStorage.removeItem(LS_WALLET_SESSION)
+          return
+        }
+
         setAddress(addr)
-        setActiveWalletId(walletId)
+        setActiveWalletId(session.walletId)
         setConnectionStatus('connected')
         await refreshWalletNetwork()
       }
-    } catch {
-      // Silent — wallet may not be unlocked yet
+    } catch (err) {
+      // Failed to reconnect (extension locked or unavailable)
+      // Requirement: show a non-blocking banner if it fails.
+      toast({
+        title: 'Reconnect failed',
+        description: 'Unable to auto-reconnect to your wallet. Please unlock your extension or connect manually.',
+        variant: 'default', // non-blocking (not 'destructive' if we want it subtle)
+      })
     }
   }
 
@@ -148,11 +175,21 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
     try {
       StellarWalletsKit.setWallet(walletId)
       const { address: addr } = await StellarWalletsKit.getAddress()
-      setAddress(addr ?? null)
-      setActiveWalletId(walletId)
-      setConnectionStatus('connected')
-      localStorage.setItem(LS_WALLET_KEY, walletId)
-      await refreshWalletNetwork()
+      
+      if (addr) {
+        setAddress(addr)
+        setActiveWalletId(walletId)
+        setConnectionStatus('connected')
+        
+        // Save session data (Requirement: {walletType, publicKey})
+        // SECURITY NOTE: We only store the public key. Never store private keys or seed phrases in localStorage.
+        localStorage.setItem(LS_WALLET_SESSION, JSON.stringify({
+          walletId,
+          publicKey: addr
+        }))
+        
+        await refreshWalletNetwork()
+      }
     } catch (err: unknown) {
       setWalletNetworkResolution({ status: 'idle' })
       setConnectionStatus('error')
@@ -173,7 +210,7 @@ export function WalletProvider({ children }: { children: React.ReactNode }) {
     setActiveWalletId(null)
     setWalletNetwork(null)
     setWalletNetworkResolution({ status: 'idle' })
-    localStorage.removeItem(LS_WALLET_KEY)
+    localStorage.removeItem(LS_WALLET_SESSION)
   }, [])
 
   const signTransaction = useCallback(async (xdr: string): Promise<string> => {