test(wallet): add tests for wallet auto-reconnect and document security (#222)

Author: milah-247

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',
+      }));
+    });
+  });
+});