feat(wallet): block UI on network mismatch with a11y overlay and settings link

Author: AustineSamuel

frontend/src/app/layout.tsx

@@ -2,8 +2,10 @@ import type { Metadata, Viewport } from "next";
 import { headers } from "next/headers";
 
 import "./globals.css";
+import { AnalyticsScript } from "@/components/analytics-script";
 import { ThemeProvider } from "@/components/theme-provider";
 import { Toaster } from "@/components/ui/toaster";
+import { WalletProvider, NetworkMismatchModal } from "@/features/wallet";
 import { inter, ibmPlexMono } from "@/lib/fonts";
 
 export const viewport: Viewport = {

frontend/src/components/settings/settings-panel.tsx

@@ -7,6 +7,7 @@ import { Card, CardContent, CardHeader, CardTitle, CardDescription } from '@/com
 import { Input } from '@/components/ui/input'
 import { useSettings } from '@/hooks/use-settings'
 import { useWallet } from '@/hooks/use-wallet'
+import { SETTINGS_NETWORK_SECTION_ID } from '@/features/wallet/constants'
 import { getContracts } from '@/lib/network-manifest'
 import { validateRpcUrl, PUBLIC_RPC, STATUS_PAGES, type AppSettings } from '@/lib/settings-store'
 import type { Network } from '@/lib/network-manifest'
@@ -15,14 +16,15 @@ const NETWORKS: Network[] = ['testnet', 'public']
 
 export function SettingsPanel() {
   const { settings, update, reset } = useSettings()
-  const { disconnect } = useWallet()
+  const { disconnect, setAppNetwork } = useWallet()
   const [advancedOpen, setAdvancedOpen] = useState(false)
   const [rpcInput, setRpcInput] = useState(settings.customRpcUrl ?? '')
   const [rpcError, setRpcError] = useState<string | null>(null)
   const [isPending, startTransition] = useTransition()
 
   function handleNetworkChange(network: Network) {
     update('network', network)
+    setAppNetwork(network === 'public' ? 'mainnet' : 'testnet')
     // Pull fresh contract manifests for the new network
     startTransition(() => {
       getContracts(network) // re-reads registry; triggers any dependent queries
@@ -58,7 +60,7 @@ export function SettingsPanel() {
   return (
     <div className="space-y-6 max-w-xl">
       {/* Network */}
-      <Card>
+      <Card id={SETTINGS_NETWORK_SECTION_ID} tabIndex={-1}>
         <CardHeader>
           <CardTitle>Network</CardTitle>
           <CardDescription>

frontend/src/components/ui/dialog.tsx

@@ -31,10 +31,15 @@ DialogOverlay.displayName = DialogPrimitive.Overlay.displayName
 
 const DialogContent = React.forwardRef<
   React.ElementRef<typeof DialogPrimitive.Content>,
-  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
->(({ className, children, ...props }, ref) => (
+  React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & {
+    /** When true, omit the default close (X) control — for blocking flows */
+    hideCloseButton?: boolean
+    /** Merged onto the overlay (e.g. higher z-index for full-screen blocking) */
+    overlayClassName?: string
+  }
+>(({ className, children, hideCloseButton = false, overlayClassName, ...props }, ref) => (
   <DialogPortal>
-    <DialogOverlay />
+    <DialogOverlay className={overlayClassName} />
     <DialogPrimitive.Content
       ref={ref}
       className={cn(
@@ -55,10 +60,12 @@ const DialogContent = React.forwardRef<
       {...props}
     >
       {children}
-      <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground min-h-[44px] min-w-[44px] flex items-center justify-center">
-        <X className="h-4 w-4" />
-        <span className="sr-only">Close</span>
-      </DialogPrimitive.Close>
+      {!hideCloseButton && (
+        <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground min-h-[44px] min-w-[44px] flex items-center justify-center">
+          <X className="h-4 w-4" />
+          <span className="sr-only">Close</span>
+        </DialogPrimitive.Close>
+      )}
     </DialogPrimitive.Content>
   </DialogPortal>
 ))

frontend/src/config/networkManifest.ts

@@ -52,7 +52,21 @@ export function getManifest(network: AppNetwork): NetworkManifest {
   return NETWORK_MANIFESTS[network]
 }
 
-/** Maps a wallet-reported network passphrase to our AppNetwork key. */
+/**
+ * Maps the exact network passphrase string returned by the wallet (via
+ * `StellarWalletsKit.getNetwork()`) to our `AppNetwork` key.
+ *
+ * Comparison is **case-sensitive, full-string equality** against each manifest’s
+ * `networkPassphrase` (Stellar’s canonical strings, e.g. Test SDF Network).
+ *
+ * **Custom RPC:** Changing the Soroban/Horizon RPC in Settings does not change
+ * the wallet passphrase; mismatch detection is driven only by what the wallet
+ * reports for the active network.
+ *
+ * **Unknown / private networks:** If the passphrase is not one of our three
+ * manifests, this returns `null`. Callers should treat that as “wallet network
+ * not supported by this app” (see `computeNetworkMismatch` in wallet utils).
+ */
 export function passphraseToAppNetwork(passphrase: string): AppNetwork | null {
   for (const [key, manifest] of Object.entries(NETWORK_MANIFESTS)) {
     if (manifest.networkPassphrase === passphrase) return key as AppNetwork

frontend/src/features/wallet/NETWORK_MISMATCH.md

@@ -0,0 +1,31 @@
+# Wallet vs app network mismatch
+
+## What we compare
+
+1. **App network** — `WalletContext` state (`AppNetwork`: `testnet` | `mainnet` | `futurenet`), persisted under `niffyinsure:appNetwork` and passed into `StellarWalletsKit.init` / `setNetwork`.
+2. **Wallet network** — The `network` string from `StellarWalletsKit.getNetwork()` (Stellar network passphrase), mapped with `passphraseToAppNetwork()` in `src/config/networkManifest.ts`.
+
+We re-fetch the wallet passphrase on connect, reconnect, app network changes, successful `signTransaction`, and on `KitEventType.STATE_UPDATED` when an address is present so extension network switches are picked up quickly.
+
+## When the blocking overlay shows
+
+The full-screen overlay is shown only on routes that are **not** read-only (see `isReadOnlyWalletInteractionPath` in `utils/networkMismatch.ts`): excluded paths include `/`, `/docs` (and subpaths), `/privacy`, and `/support`, with optional locale prefixes (`/en`, `/es`).
+
+`computeNetworkMismatch` returns true when:
+
+- The wallet is **connected**, and
+- The last `getNetwork()` call **succeeded** (`resolution.status === 'ok'`), and
+- Either the passphrase did **not** match any manifest (`mappedNetwork === null`), or `mappedNetwork !== appNetwork`.
+
+## Edge cases
+
+| Situation | Behavior |
+|-----------|----------|
+| Custom Soroban RPC in Settings | Does not affect passphrase comparison; only the wallet’s reported passphrase matters. |
+| Wallet on a private / unknown chain | Passphrase does not match manifests → `mappedNetwork === null` → mismatch overlay (when on a wallet-required route). |
+| `getNetwork()` throws or fails | Resolution stays non-`ok` → overlay hidden (we do not block on unknown read failure). |
+| Settings “Network” (testnet / mainnet) | `SettingsPanel` calls `setAppNetwork` so the kit and app passphrase stay aligned with the same control users reach via “Switch Network”. The Network card uses `SETTINGS_NETWORK_SECTION_ID` (`settings-network`) so `/settings#settings-network` scrolls/focuses the right block. |
+
+## Accessibility
+
+The overlay uses a Radix `Dialog` with `role="alertdialog"`, `aria-modal`, labelled title/description, and an `aria-live="assertive"` region so assistive tech announces the mismatch when the dialog opens.

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

@@ -0,0 +1,75 @@
+/**
+ * @jest-environment jsdom
+ */
+import { render, screen, waitFor } from '@testing-library/react'
+import React from 'react'
+
+import {
+  NetworkMismatchOverlayView,
+  buildMismatchCopy,
+} from '@/features/wallet/components/NetworkMismatchModal'
+
+jest.mock('@/i18n/navigation', () => ({
+  Link: ({
+    href,
+    children,
+    ...rest
+  }: React.AnchorHTMLAttributes<HTMLAnchorElement>) => (
+    <a href={href} {...rest}>
+      {children}
+    </a>
+  ),
+}))
+
+describe('buildMismatchCopy', () => {
+  it('describes standard mismatch', () => {
+    const copy = buildMismatchCopy('mainnet', { status: 'ok', mappedNetwork: 'testnet' })
+    expect(copy.announcement).toContain('Mainnet')
+    expect(copy.announcement).toContain('Testnet')
+  })
+
+  it('describes unsupported wallet passphrase', () => {
+    const copy = buildMismatchCopy('mainnet', { status: 'ok', mappedNetwork: null })
+    expect(copy.title).toContain('Unsupported')
+    expect(copy.announcement).toMatch(/unsupported|expect/i)
+  })
+})
+
+describe('NetworkMismatchOverlayView', () => {
+  const base = {
+    appNetwork: 'mainnet' as const,
+    resolution: { status: 'ok' as const, mappedNetwork: 'testnet' as const },
+    switchNetworkHref: '/settings#settings-network',
+  }
+
+  it('does not render alert dialog when closed', () => {
+    const { container } = render(<NetworkMismatchOverlayView open={false} {...base} />)
+    expect(container.querySelector('[role="alertdialog"]')).toBeNull()
+  })
+
+  it('renders blocking overlay and Switch Network when open', () => {
+    render(<NetworkMismatchOverlayView open {...base} />)
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: /switch network/i })).toHaveAttribute(
+      'href',
+      '/settings#settings-network',
+    )
+  })
+
+  it('dismisses alert dialog when open flips to false', async () => {
+    const { rerender } = render(<NetworkMismatchOverlayView open {...base} />)
+    expect(screen.getByRole('alertdialog')).toBeInTheDocument()
+
+    rerender(<NetworkMismatchOverlayView open={false} {...base} />)
+    await waitFor(() => {
+      expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument()
+    })
+  })
+
+  it('exposes assertive live region for screen reader announcement', () => {
+    render(<NetworkMismatchOverlayView open {...base} />)
+    const live = document.querySelector('[aria-live="assertive"]')
+    expect(live).toBeTruthy()
+    expect(live?.textContent?.length).toBeGreaterThan(10)
+  })
+})

frontend/src/features/wallet/__tests__/networkMismatch.test.ts

@@ -0,0 +1,86 @@
+import { passphraseToAppNetwork } from '@/config/networkManifest'
+import {
+  computeNetworkMismatch,
+  isReadOnlyWalletInteractionPath,
+  stripLocalePrefix,
+} from '@/features/wallet/utils/networkMismatch'
+
+describe('stripLocalePrefix', () => {
+  it('removes optional locale segment', () => {
+    expect(stripLocalePrefix('/es/quote')).toBe('/quote')
+    expect(stripLocalePrefix('/en/docs/voting')).toBe('/docs/voting')
+    expect(stripLocalePrefix('/es')).toBe('/')
+  })
+
+  it('leaves default-locale paths unchanged', () => {
+    expect(stripLocalePrefix('/quote')).toBe('/quote')
+    expect(stripLocalePrefix('/')).toBe('/')
+  })
+})
+
+describe('isReadOnlyWalletInteractionPath', () => {
+  it('treats landing, docs, privacy, support as read-only', () => {
+    expect(isReadOnlyWalletInteractionPath('/')).toBe(true)
+    expect(isReadOnlyWalletInteractionPath('/docs')).toBe(true)
+    expect(isReadOnlyWalletInteractionPath('/docs/voting')).toBe(true)
+    expect(isReadOnlyWalletInteractionPath('/privacy')).toBe(true)
+    expect(isReadOnlyWalletInteractionPath('/support')).toBe(true)
+  })
+
+  it('treats wallet-interaction routes as not read-only', () => {
+    expect(isReadOnlyWalletInteractionPath('/quote')).toBe(false)
+    expect(isReadOnlyWalletInteractionPath('/settings')).toBe(false)
+    expect(isReadOnlyWalletInteractionPath('/dashboard')).toBe(false)
+  })
+
+  it('respects locale prefix', () => {
+    expect(isReadOnlyWalletInteractionPath('/es')).toBe(true)
+    expect(isReadOnlyWalletInteractionPath('/es/docs/contracts')).toBe(true)
+    expect(isReadOnlyWalletInteractionPath('/es/quote')).toBe(false)
+  })
+})
+
+describe('computeNetworkMismatch', () => {
+  it('is false when disconnected or resolution not ok', () => {
+    expect(
+      computeNetworkMismatch('disconnected', 'mainnet', { status: 'ok', mappedNetwork: 'testnet' }),
+    ).toBe(false)
+    expect(
+      computeNetworkMismatch('connected', 'mainnet', { status: 'idle' }),
+    ).toBe(false)
+    expect(
+      computeNetworkMismatch('connected', 'mainnet', { status: 'error' }),
+    ).toBe(false)
+  })
+
+  it('is true when mapped network differs from app network', () => {
+    expect(
+      computeNetworkMismatch('connected', 'mainnet', { status: 'ok', mappedNetwork: 'testnet' }),
+    ).toBe(true)
+  })
+
+  it('is false when networks match', () => {
+    expect(
+      computeNetworkMismatch('connected', 'testnet', { status: 'ok', mappedNetwork: 'testnet' }),
+    ).toBe(false)
+  })
+
+  it('is true when passphrase is unknown (unmapped)', () => {
+    expect(
+      computeNetworkMismatch('connected', 'mainnet', { status: 'ok', mappedNetwork: null }),
+    ).toBe(true)
+  })
+})
+
+describe('passphraseToAppNetwork', () => {
+  it('maps known Stellar passphrases', () => {
+    expect(passphraseToAppNetwork('Test SDF Network ; September 2015')).toBe('testnet')
+    expect(
+      passphraseToAppNetwork('Public Global Stellar Network ; September 2015'),
+    ).toBe('mainnet')
+  })
+
+  it('returns null for unknown passphrases', () => {
+    expect(passphraseToAppNetwork('Private Custom Network')).toBeNull()
+  })
+})