vpn/netstate: allow enabling the gateway client offline

Soften the no-IPv4-uplink gates on both platforms from a hard error to a
warning: on Linux setupGatewayRoutes proceeds with an empty exemption
table (the route monitor copies the default in when one appears), on
Windows EnableClientRoutes no longer refuses at index4 == 0 (the /1
routes are TUN-bound, marking is a no-op until the watcher re-binds).
An offline boot with a persisted ClientEnabled now self-heals instead
of failing Init.

Author: pymq

vpn/netstate/manager_windows.go

@@ -4,7 +4,6 @@ package netstate
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"sync"
 	"sync/atomic"
@@ -192,23 +191,21 @@ func (m *Manager) onNetworkChange() {
 
 // EnableClientRoutes installs the gateway client routes on the TUN (the
 // default-route capture plus the IPv6 fail-closed fence). Idempotent: a
-// second call while routes are installed is a no-op. It refuses while no
-// IPv4 uplink is known (marking could not exempt libp2p traffic — routing
-// loop); the condition is self-healing (the watcher re-binds sockets when
-// connectivity appears), so that is "try again once online", not a permanent
-// failure. IPv6 is not required: the tunnel is IPv4-only and gateway mode
-// fences IPv6.
+// second call while routes are installed is a no-op. Offline enable is
+// allowed with a warning: the /1 routes are bound to the TUN LUID and need
+// no uplink, marking with index 0 is a no-op, and the watcher re-binds
+// registered sockets once connectivity appears — the gateway self-heals
+// without a re-enable. IPv6 is not required: the tunnel is IPv4-only and
+// gateway mode fences IPv6.
 func (m *Manager) EnableClientRoutes(tunIfName string) error {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
 	if m.routeState != nil {
 		return nil
 	}
-	// TODO(gateway-offline-start): soften this gate to a warning so gateway
-	// client mode can be enabled/booted offline and self-heal when connectivity appears
 	if m.index4.Load() == 0 {
-		return errors.New("cannot enable VPN gateway: no active network connection (no IPv4 default route)")
+		logger.Warnf("gateway client enabled with no IPv4 uplink; internet will flow when network appears")
 	}
 
 	state, err := m.setupGatewayRoutes(tunIfName)

vpn/netstate/routes_linux.go

@@ -102,12 +102,14 @@ func (m *Manager) setupGatewayRoutes(tunIfName string) (*routeState, error) {
 		return nil, fmt.Errorf("get default routes: %w", err)
 	}
 	if len(origDefaults) == 0 {
-		// TODO(gateway-offline-start): soften to a warning and proceed with an
-		// empty exemption table — the route monitor below already re-syncs it
-		// when a default appears (DHCP), so an offline boot with a persisted
-		// ClientEnabled would self-heal instead of failing Init. Needs a
-		// reconcile-from-empty verification + doc updates
-		return nil, fmt.Errorf("no IPv4 default route present, cannot configure VPN gateway")
+		// Offline enable is allowed: proceed with an empty exemption table. The
+		// route monitor (alive since Manager.Start) copies the default into
+		// tableID once one appears (DHCP), so an offline boot with a persisted
+		// ClientEnabled self-heals instead of failing Init. Until that reconcile
+		// (≤ one monitor tick) marked libp2p sockets fall through to the TUN
+		// default — a routing loop, but with no uplink there is no traffic to
+		// leak, only a connect delay.
+		logger.Warnf("gateway client enabled with no IPv4 uplink; internet will flow when network appears")
 	}
 
 	state := &routeState{

vpn/netstate/sockmark_windows.go

@@ -74,8 +74,10 @@ func (m *Manager) ControlFunc() func(network, address string, c syscall.RawConn)
 // index is unknown — the option simply stays
 // unset. rebind=true (uplink change) always writes, because writing 0 is the
 // documented way to clear a stale binding (the socket falls back to regular
-// routing, which is safe: with no uplink there is nothing to leak to, and
-// EnableClientRoutes refuses to enable the gateway while offline).
+// routing, which is safe: with no uplink there is no traffic at all, and once
+// one appears the watcher re-binds the registry within the debounce window —
+// the brief unmarked-libp2p loop into the TUN in between is the accepted
+// offline-enable transient).
 //
 // Returns the Control-level error (dead socket — eviction signal for the
 // registry) separately from setsockopt errors (live socket, wrong option —

vpn/netstate/vpn_hostnet_integration_test.go

@@ -338,6 +338,80 @@ func TestGatewayHostNetRoutesStalenessReconcileV6(t *testing.T) {
 	assertRoutesApplied(t)
 }
 
+// ---- R6: offline enable proceeds and self-heals when a default appears ----
+//
+// Enabling the gateway client with NO IPv4 default route must succeed (warn +
+// empty exemption table) with the TUN default and the v6 fence installed, and
+// the monitor must copy the host default into tableID once one appears — the
+// §8.4 offline-boot self-heal. We simulate "offline" by removing the host's
+// real IPv4 defaults and restoring them afterwards; while they are gone the
+// host's v4 egress is the TUN black hole, which is within this suite's risk
+// profile (every routes test black-holes egress mid-flight anyway).
+func TestGatewayHostNetRoutesOfflineEnableSelfHeals(t *testing.T) {
+	verifyNoLeaks(t)
+	requireRoot(t)
+	// A default is required not by the enable under test (that is the point)
+	// but as material: we snapshot the real defaults to remove and re-add.
+	requireDefaultRoute(t)
+	setupDummyTun(t)
+
+	origDefaults, err := getDefaultRoutes()
+	require.NoError(t, err)
+	require.NotEmpty(t, origDefaults)
+	for i := range origDefaults {
+		r := origDefaults[i]
+		require.NoError(t, netlink.RouteDel(&r), "remove host default %v", r)
+	}
+	t.Cleanup(func() {
+		// RouteReplace, not RouteAdd: the mid-test re-add below leaves one of
+		// them already present on the success path.
+		for i := range origDefaults {
+			r := origDefaults[i]
+			_ = netlink.RouteReplace(&r)
+		}
+	})
+
+	before := snapshotNet(t)
+
+	// See R4 for why Start + cancel are needed here.
+	mgr := NewManager()
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+	require.NoError(t, mgr.Start(ctx))
+	require.NoError(t, mgr.EnableClientRoutes(testTunIf),
+		"offline enable must proceed with a warning, not fail")
+	t.Cleanup(func() { _ = mgr.DisableClientRoutes() })
+	require.True(t, mgr.ClientRoutesActive())
+
+	// Offline shape: TUN default captured, exemption table empty (nothing to
+	// exempt yet). assertRoutesApplied is not usable here — it requires a
+	// non-empty exemption table.
+	main := cmdOut(t, "ip", "-4", "route", "show")
+	require.Contains(t, main, "dev "+testTunIf, "TUN default must be installed even offline")
+	require.Empty(t, strings.TrimSpace(routeTableDump(t, tableID)),
+		"the v4 exemption table must start empty when enabled offline")
+
+	// The network comes back: restore one real default in the main table.
+	restored := origDefaults[0]
+	require.NoError(t, netlink.RouteReplace(&restored))
+
+	require.Eventually(t, func() bool {
+		return strings.Contains(routeTableDump(t, tableID), "default")
+	}, 5*time.Second, 100*time.Millisecond,
+		"the monitor must copy the appeared host default into the awl exemption table")
+
+	// The reconcile must have left the TUN default and the IPv6 fence alone.
+	assertRoutesApplied(t)
+
+	require.NoError(t, mgr.DisableClientRoutes())
+	require.False(t, mgr.ClientRoutesActive())
+
+	// Back out the mid-test re-add so the state is comparable with the
+	// "no defaults" snapshot; teardown must have removed everything else.
+	require.NoError(t, netlink.RouteDel(&restored))
+	require.Equal(t, before, snapshotNet(t), "teardown must restore the exact pre-setup routing state")
+}
+
 // ---------------------------------------------------------------------------
 // assertions
 // ---------------------------------------------------------------------------

vpn/netstate/vpn_hostnet_windows_integration_test.go

@@ -94,18 +94,20 @@ func requireAdmin(t *testing.T) {
 	}
 }
 
-// startManager runs Manager.Start with a test-scoped context, so the client
-// tests pass the IPv4-uplink gate in EnableClientRoutes the same way
-// production does. The watch goroutine dies on the context cancel registered
-// here; verifyNoLeaks (registered before this, so running after) sees it gone.
-// Skips when the host is offline — the gate would legitimately refuse.
+// startManager runs Manager.Start with a test-scoped context, populating the
+// uplink indexes the same way production does. The watch goroutine dies on
+// the context cancel registered here; verifyNoLeaks (registered before this,
+// so running after) sees it gone. Skips when the host is offline: enabling
+// offline is allowed (warn + self-heal), but the tests below assert against
+// a real uplink index (e.g. MarkerRebind), which an offline runner cannot
+// provide.
 func startManager(t *testing.T, mgr *Manager) {
 	t.Helper()
 	ctx, cancel := context.WithCancel(context.Background())
 	t.Cleanup(cancel)
 	require.NoError(t, mgr.Start(ctx))
 	if mgr.index4.Load() == 0 {
-		t.Skip("no IPv4 uplink on this host; EnableClientRoutes refuses while offline")
+		t.Skip("no IPv4 uplink on this host; these tests assert against a real uplink index")
 	}
 }