feat(mobile): pick a city for each multi-hop end; hide split tunneling where nothing can be bought

Multi-hop entry/exit pickers were country-only — tapping a country
selected it and closed, with no way into its cities. They now drill in
like the single-hop picker: a hop pick is a location id (`DE` or
`DE:Nuremberg`, so previously-stored bare country codes keep working),
Country rows carry the gateway IPs they cover, and those are passed to
selectHops as entryIps/exitIps. The hop card names the pinned city —
without it the card read "Germany" whether you chose the country or one
city, making the pick invisible. An impossible pair (e.g. the same
one-node city at both ends) gets a message naming the knob to loosen
instead of a raw selectHops error.

Split tunneling is now hidden entirely for a non-premium user who cannot
buy anything — iOS store builds, where PURCHASE_UI_PLATFORMS excludes the
platform structurally. Showing a locked paid feature with no purchase
path is the guideline 3.1.1 upsell surface that got a previous build
rejected; the section ignored that flag and rendered "upgrade to route
only the traffic you choose". Premium users still see it on iOS, since
that follows tier, not platform.

Also: requestPermission now rejects on the iOS Simulator with "VPN
tunnels are not supported on the iOS Simulator" (compile-time guard, so
the device build is untouched). The Simulator has no NetworkExtension VPN
subsystem, so the generic "VPN permission is required" left a tester
hunting for a consent dialog that can never appear.

Author: TheTrunk

clients/mobile/App.tsx

@@ -112,8 +112,9 @@ function App(): React.JSX.Element {
           ) : route === 'entry' ? (
             <CountryPickerScreen
               countries={vpn.countries}
-              selectedCode={vpn.entry?.code ?? null}
-              onSelect={(code) => void vpn.selectEntryCountry(code)}
+              locations={vpn.locations}
+              selectedCode={vpn.entry?.id ?? null}
+              onSelect={(id) => void vpn.selectEntryCountry(id)}
               onSelectAuto={() => void vpn.selectEntryCountry(null)}
               onClose={() => setRoute('connect')}
               onRefresh={() => vpn.refresh()}
@@ -124,8 +125,9 @@ function App(): React.JSX.Element {
           ) : route === 'exit' ? (
             <CountryPickerScreen
               countries={vpn.countries}
-              selectedCode={vpn.exit?.code ?? null}
-              onSelect={(code) => void vpn.selectExitCountry(code)}
+              locations={vpn.locations}
+              selectedCode={vpn.exit?.id ?? null}
+              onSelect={(id) => void vpn.selectExitCountry(id)}
               onSelectAuto={() => void vpn.selectExitCountry(null)}
               onClose={() => setRoute('connect')}
               onRefresh={() => vpn.refresh()}
@@ -148,6 +150,7 @@ function App(): React.JSX.Element {
               onClose={() => setRoute('connect')}
               onOpenUpgrade={flags.inAppUpgrade ? () => setRoute('upgrade') : undefined}
               onOpenPrivacy={() => setRoute('privacy')}
+              canUpgrade={flags.inAppUpgrade}
             />
           ) : (
             <ConnectScreen

clients/mobile/ios/CumulusTunnel/CumulusTunnelModule.swift

@@ -241,6 +241,20 @@ final class CumulusTunnelModule: RCTEventEmitter {
         // "VPN permission is required to connect." Give it a minimal valid
         // provider protocol so the save is accepted and the prompt appears; the
         // real connect overwrites it with the full tunnel config.
+        #if targetEnvironment(simulator)
+        // The Simulator has no NetworkExtension VPN subsystem: saving a manager
+        // always fails and iOS never shows the consent prompt, so the generic
+        // "VPN permission is required" left a tester hunting for a dialog that
+        // cannot appear. Say what is actually true. Compile-time guard, so the
+        // shipped device build is untouched (docs/16 Stage F: packet-tunnel
+        // extensions do not run on the Simulator).
+        reject(
+            "E_SIMULATOR",
+            "VPN tunnels are not supported on the iOS Simulator — run on a real device to connect.",
+            nil
+        )
+        return
+        #else
         loadOrCreateManager { [weak self] mgr, _ in
             guard let self, let mgr else { resolve(false); return }
             if mgr.protocolConfiguration == nil {
@@ -253,6 +267,7 @@ final class CumulusTunnelModule: RCTEventEmitter {
             mgr.isEnabled = true
             mgr.saveToPreferences { err in resolve(err == nil) }
         }
+        #endif
     }
 
     // solvePow(publicKeyB64, bits): Promise<String>

clients/mobile/src/components/SplitTunnelingSection.tsx

@@ -38,9 +38,25 @@ interface Props {
   readonly killSwitch: boolean;
   /** True while a session exists — changes then apply on the next connect. */
   readonly locked: boolean;
+  /**
+   * Whether this build may show purchase/upsell surfaces at all
+   * (`flags.inAppUpgrade`; structurally false on iOS — see lib/flags).
+   *
+   * A non-premium user who CANNOT buy anything must not be shown a locked
+   * paid feature: on the App Store that is a 3.1.1 upsell surface with no IAP
+   * behind it, which is what got a previous build rejected. Settings hides the
+   * whole section in that case; this guard makes the component itself safe if
+   * it is ever rendered directly.
+   */
+  readonly canUpgrade: boolean;
 }
 
-export function SplitTunnelingSection({ tier, killSwitch, locked }: Props): React.JSX.Element {
+export function SplitTunnelingSection({
+  tier,
+  killSwitch,
+  locked,
+  canUpgrade,
+}: Props): React.JSX.Element | null {
   const [policy, setPolicy] = useState<SplitPolicy>(EMPTY_POLICY);
   const [draft, setDraft] = useState('');
   const [inputError, setInputError] = useState<string | null>(null);
@@ -110,6 +126,13 @@ export function SplitTunnelingSection({ tier, killSwitch, locked }: Props): Reac
   // (docs/17 §4.5) — with both on, the kill switch wins at connect time.
   const iosConflict = Platform.OS === 'ios' && killSwitch && active;
 
+  // Nothing to offer and nothing to sell: render nothing rather than advertise
+  // a locked paid feature (see `canUpgrade`). Placed after the hooks so hook
+  // order stays stable across renders.
+  if (!premium && !canUpgrade) {
+    return null;
+  }
+
   return (
     <View style={styles.card}>
       <View style={styles.modes} accessibilityRole="radiogroup">

clients/mobile/src/lib/gateways.ts

@@ -33,8 +33,15 @@ export interface Country {
   readonly city: string;
   /** Number of reachable gateways in this country. */
   readonly nodeCount: number;
-  /** Best (lowest-load) gateway — the one we enroll at. */
+  /** Best gateway in this row (see `bestOf`) — the one we enroll at. */
   readonly best: GatewayInfo;
+  /**
+   * Every gateway IP this row covers. Multi-hop passes these to core's
+   * `selectHops` as `entryIps`/`exitIps`, so picking a CITY pins that hop to
+   * the city's nodes instead of letting load ordering choose anywhere in the
+   * country (docs/11).
+   */
+  readonly ips: readonly string[];
   /** Round-trip latency in ms to `best`, or null if not yet measured. */
   readonly latencyMs: number | null;
 }
@@ -229,6 +236,7 @@ export function groupByCountry(
       city: localityOf(best.city, code),
       nodeCount: list.length,
       best,
+      ips: list.map((g) => g.ip),
       latencyMs: latency ?? null,
     });
   }
@@ -274,6 +282,7 @@ export function groupByLocation(
       city: localityOf(best.city, code),
       nodeCount: list.length,
       best,
+      ips: list.map((g) => g.ip),
       latencyMs: latencyByIp[best.ip] ?? null,
     });
   }

clients/mobile/src/screens/ConnectScreen.tsx

@@ -399,6 +399,14 @@ function HopButton({
           {country?.name ?? 'Auto'}
         </Text>
       </View>
+      {/* Name the city when this hop is pinned to one (a location id carries
+          `cc:city`). Without it a city pick is invisible: the card would read
+          "Germany" whether you chose the whole country or Nuremberg. */}
+      {country && country.id.includes(':') && country.city ? (
+        <Text style={styles.hopCity} numberOfLines={1}>
+          {country.city}
+        </Text>
+      ) : null}
     </Pressable>
   );
 }
@@ -645,6 +653,7 @@ const styles = StyleSheet.create({
   },
   hopMain: { flexDirection: 'row', alignItems: 'center', gap: 6, marginTop: 4 },
   hopFlag: { fontSize: 18 },
+  hopCity: { color: color.inkDim, fontSize: 11.5, marginTop: 2 },
   hopName: { flex: 1, color: color.ink, fontSize: 14, fontWeight: '600' },
   tradeoff: { color: color.inkMuted, fontSize: 12, lineHeight: 17, marginTop: space.xs },
   locBtn: {

clients/mobile/src/screens/SettingsScreen.tsx

@@ -33,13 +33,16 @@ interface Props {
   readonly onOpenUpgrade?: (() => void) | undefined;
   /** Re-open the 5.4 data disclosure (also shown as a first-run gate). */
   readonly onOpenPrivacy: () => void;
+  /** Whether this build may show purchase/upsell surfaces (`flags.inAppUpgrade`). */
+  readonly canUpgrade: boolean;
 }
 
 export function SettingsScreen({
   vpn,
   onClose,
   onOpenUpgrade,
   onOpenPrivacy,
+  canUpgrade,
 }: Props): React.JSX.Element {
   const premium = vpn.tier === 'premium';
   const expiry = formatExpiry(vpn.paidUntil);
@@ -136,9 +139,21 @@ export function SettingsScreen({
         />
 
         {/* Split tunneling (docs/17) — premium, applied when a tunnel is built,
-            like the transport/routing toggles above. */}
-        <Text style={styles.section}>Split tunneling</Text>
-        <SplitTunnelingSection tier={vpn.tier} killSwitch={vpn.killSwitch} locked={locked} />
+            like the transport/routing toggles above. Hidden entirely for a
+            non-premium user who has no way to buy (iOS store builds): showing a
+            locked paid feature with no purchase path is the 3.1.1 upsell
+            surface that got a previous build rejected. */}
+        {(premium || canUpgrade) && (
+          <>
+            <Text style={styles.section}>Split tunneling</Text>
+            <SplitTunnelingSection
+              tier={vpn.tier}
+              killSwitch={vpn.killSwitch}
+              locked={locked}
+              canUpgrade={canUpgrade}
+            />
+          </>
+        )}
 
         <Text style={styles.section}>Privacy &amp; support</Text>
         <Pressable

clients/mobile/src/state/useVpn.ts

@@ -229,9 +229,11 @@ export interface VpnActions {
   /** Switch transport mode (Auto vs Stealth); persisted. Applies on next connect. */
   setTransportMode(mode: TransportMode): Promise<void>;
   /** Pick the multi-hop entry country (`null` = auto-pick nearest); persisted. */
-  selectEntryCountry(code: string | null): Promise<void>;
+  /** Pick the multi-hop ENTRY: a location id (`DE` or `DE:Frankfurt`), null = auto. */
+  selectEntryCountry(id: string | null): Promise<void>;
   /** Pick the multi-hop exit country (`null` = auto-pick); persisted. */
-  selectExitCountry(code: string | null): Promise<void>;
+  /** Pick the multi-hop EXIT: a location id (`DE` or `DE:Frankfurt`), null = auto. */
+  selectExitCountry(id: string | null): Promise<void>;
   /** Toggle the kill switch (persisted). Applies on the next connect. */
   setKillSwitch(enabled: boolean): Promise<void>;
   /** Toggle multi-hop node diversity (persisted). Applies on the next connect. */
@@ -371,13 +373,22 @@ export function useVpn(): VpnModel & VpnActions {
     [locations, selectedCode],
   );
 
+  // A hop pick is a LOCATION id: `DE` (whole country) or `DE:Frankfurt` (one
+  // city). Look in the city rows first, then fall back to the country row —
+  // which is also what makes previously-stored bare country codes keep working.
   const entry = useMemo<Country | null>(
-    () => countries.find((c) => c.code === entryCode) ?? null,
-    [countries, entryCode],
+    () =>
+      locations.find((l) => l.id === entryCode) ??
+      countries.find((c) => c.code === entryCode) ??
+      null,
+    [countries, locations, entryCode],
   );
   const exit = useMemo<Country | null>(
-    () => countries.find((c) => c.code === exitCode) ?? null,
-    [countries, exitCode],
+    () =>
+      locations.find((l) => l.id === exitCode) ??
+      countries.find((c) => c.code === exitCode) ??
+      null,
+    [countries, locations, exitCode],
   );
   const multihop = isMultihop(routeStyle);
 
@@ -814,7 +825,19 @@ export function useVpn(): VpnModel & VpnActions {
       // without it the native backend throws (Android: GoBackend BackendException).
       // Ask once — no-op if already granted (VpnService.prepare()==null).
       if (!(await CumulusTunnel.isPrepared())) {
-        const granted = await CumulusTunnel.requestPermission();
+        // requestPermission REJECTS with a specific reason on platforms that
+        // can never grant it (the iOS Simulator has no VPN subsystem, so no
+        // consent dialog can appear); surface that instead of the generic line,
+        // which otherwise sends a tester looking for a prompt that will never
+        // come.
+        let granted = false;
+        try {
+          granted = await CumulusTunnel.requestPermission();
+        } catch (e) {
+          setState('error');
+          setError(e instanceof Error ? e.message : 'VPN permission is required to connect.');
+          return;
+        }
         if (!granted) {
           setState('error');
           setError('VPN permission is required to connect.');
@@ -837,8 +860,11 @@ export function useVpn(): VpnModel & VpnActions {
           transportMode,
           tier: tierRef.current,
           gateways: availableGateways(),
-          entryCountry: entryCode ?? autoEntry ?? null,
-          exitCountry: exitCode,
+          entryCountry: entry?.code ?? autoEntry ?? null,
+          exitCountry: exit?.code ?? null,
+          // City-level pins: only when the user picked a specific city row.
+          entryIps: entry && entry.id.includes(':') ? entry.ips : null,
+          exitIps: exit && exit.id.includes(':') ? exit.ips : null,
           gatewayIpRef,
           setEnrollment,
           killSwitch,
@@ -1122,14 +1148,14 @@ export function useVpn(): VpnModel & VpnActions {
     await saveTransportMode(mode);
   }, []);
 
-  const selectEntryCountry = useCallback(async (code: string | null): Promise<void> => {
-    setEntryCode(code);
-    await saveEntryCountry(code);
+  const selectEntryCountry = useCallback(async (id: string | null): Promise<void> => {
+    setEntryCode(id);
+    await saveEntryCountry(id);
   }, []);
 
-  const selectExitCountry = useCallback(async (code: string | null): Promise<void> => {
-    setExitCode(code);
-    await saveExitCountry(code);
+  const selectExitCountry = useCallback(async (id: string | null): Promise<void> => {
+    setExitCode(id);
+    await saveExitCountry(id);
   }, []);
 
   const setKillSwitch = useCallback(async (enabled: boolean): Promise<void> => {
@@ -1337,6 +1363,10 @@ async function connectMultihop(args: {
   gateways: readonly GatewayInfo[];
   entryCountry: string | null;
   exitCountry: string | null;
+  /** Gateway IPs of the chosen ENTRY city, or null for "anywhere in country". */
+  entryIps: readonly string[] | null;
+  /** Gateway IPs of the chosen EXIT city, or null. */
+  exitIps: readonly string[] | null;
   gatewayIpRef: { current: string | null };
   setEnrollment: (r: EnrollResponse) => void;
   killSwitch: boolean;
@@ -1350,6 +1380,8 @@ async function connectMultihop(args: {
     gateways,
     entryCountry,
     exitCountry,
+    entryIps,
+    exitIps,
     gatewayIpRef,
     setEnrollment,
     killSwitch,
@@ -1365,9 +1397,22 @@ async function connectMultihop(args: {
     hops = selectHops(gateways, routeStyle, {
       ...(entryCountry ? { entryCountry } : {}),
       ...(exitCountry ? { exitCountry } : {}),
+      ...(entryIps ? { entryIps } : {}),
+      ...(exitIps ? { exitIps } : {}),
       ...(requireDistinctSubnet ? { requireDistinctSubnet: true } : {}),
     });
   } catch (e) {
+    // Pinning cities narrows each hop to a handful of nodes, so an impossible
+    // pair is a normal outcome (one city, one node, used for both ends) rather
+    // than a fault. Say which knob to loosen instead of surfacing a raw
+    // selectHops error.
+    if (entryIps || exitIps) {
+      throw new Error(
+        requireDistinctSubnet
+          ? 'No route between those cities. Pick a different city, choose the whole country instead, or turn off Node diversity in Settings.'
+          : 'No route between those cities — they may share the only available node. Pick a different city, or choose the whole country instead.',
+      );
+    }
     if (requireDistinctSubnet) {
       // Name where the setting actually lives — it is no longer on this screen,
       // so "turn off Node diversity" alone would send the user hunting.