Merge remote-tracking branch 'origin/main' into refactor/migrate-profiles-to-go

Conflict resolutions:

- client/android/profile_manager.go: kept the thin adapter over client/mobile.
  The exported surface matches what main had (main's profileEmail was private
  and now lives in the shared package).

- client/ios/NetBirdSDK/login.go: took main's version. Its
  DirectUpdateOrCreateConfig supersedes the branch's GetConfig overlay for
  preserving the profile name and keys, and it also handles the tvOS App Group
  sandbox where atomic writes are blocked. Keeping main's version also retains
  Auth.Stop() and its cancellable context.

Follow-up from the merge: main's client/android/profile_state.go duplicated the
shared client/mobile implementation, so it and its test are removed and
login.go now calls mobile.ReadProfileEmail / mobile.WriteProfileEmail.
profile_prefs.go goes through the shared ProfilePrefs instead of reaching into
the removed serviceMgr field.

client/android/client.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"os"
 	"slices"
+	"strings"
 	"sync"
 	"time"
 
@@ -14,6 +15,7 @@ import (
 
 	log "github.com/sirupsen/logrus"
 
+	nbAnonymize "github.com/netbirdio/netbird/client/anonymize"
 	"github.com/netbirdio/netbird/client/iface/device"
 	"github.com/netbirdio/netbird/client/internal"
 	"github.com/netbirdio/netbird/client/internal/debug"
@@ -24,6 +26,8 @@ import (
 	"github.com/netbirdio/netbird/client/internal/routemanager"
 	"github.com/netbirdio/netbird/client/internal/stdnet"
 	"github.com/netbirdio/netbird/client/net"
+	"github.com/netbirdio/netbird/client/netstate"
+	"github.com/netbirdio/netbird/client/netsweep"
 	"github.com/netbirdio/netbird/client/system"
 	"github.com/netbirdio/netbird/formatter"
 	"github.com/netbirdio/netbird/route"
@@ -31,10 +35,12 @@ import (
 	types "github.com/netbirdio/netbird/upload-server/types"
 )
 
-// ConnectionListener export internal Listener for mobile
-type ConnectionListener interface {
-	peer.Listener
-}
+// AnonymizeLevelDefault and AnonymizeLevelStrict are the accepted
+// anonymizeLevel values for DebugBundle.
+const (
+	AnonymizeLevelDefault = nbAnonymize.LevelDefaultString
+	AnonymizeLevelStrict  = nbAnonymize.LevelStrictString
+)
 
 // TunAdapter export internal TunAdapter for mobile
 type TunAdapter interface {
@@ -56,6 +62,12 @@ type DnsReadyListener interface {
 	dns.ReadyListener
 }
 
+// TunSettings is a snapshot of the settings the TUN device is rebuilt with
+type TunSettings struct {
+	Routes        string
+	SearchDomains string
+}
+
 func init() {
 	formatter.SetLogcatFormatter(log.StandardLogger())
 }
@@ -70,18 +82,46 @@ type Client struct {
 	deviceName            string
 	uiVersion             string
 	networkChangeListener listener.NetworkChangeListener
+	// netState outlives engine restarts: it mirrors the OS connectivity, not
+	// the engine lifecycle. Run and RunWithoutLogin inject it into each new
+	// ConnectClient, which distributes it to every reconnection loop.
+	netState *netstate.State
+
+	// sweeper also outlives engine restarts; NotifyNetworkChange sweeps it.
+	sweeper *netsweep.Sweeper
 
 	stateMu       sync.RWMutex
 	connectClient *internal.ConnectClient
 	config        *profilemanager.Config
 	cacheDir      string
+	// Identifies the running profile for the SSO login hint; see profile_state.go.
+	cfgPath string
+
+	stateChangeMu    sync.Mutex
+	stateChangeSubID string
+	eventSub         *peer.EventSubscription
+	// Closed to stop the watch goroutines from delivering buffered items to a
+	// listener that has been removed or replaced. See stopStateChangeWatchLocked.
+	stateChangeDone chan struct{}
+
+	// Latched "the server wants an interactive login": survives the engine
+	// restarts that replace the run loop's context state. See Client.Status.
+	// Guarded by loginRequiredMu together with loginCleared, which counts
+	// clears so a stale observation cannot re-latch over one.
+	loginRequiredMu sync.Mutex
+	loginRequired   bool
+	loginCleared    uint64
+
+	extendMu     sync.Mutex
+	extendCancel context.CancelFunc
 }
 
-func (c *Client) setState(cfg *profilemanager.Config, cacheDir string, cc *internal.ConnectClient) {
+func (c *Client) setState(cfg *profilemanager.Config, cacheDir string, cfgPath string, cc *internal.ConnectClient) {
 	c.stateMu.Lock()
 	defer c.stateMu.Unlock()
 	c.config = cfg
 	c.cacheDir = cacheDir
+	c.cfgPath = cfgPath
 	c.connectClient = cc
 }
 
@@ -91,6 +131,16 @@ func (c *Client) stateSnapshot() (*profilemanager.Config, string, *internal.Conn
 	return c.config, c.cacheDir, c.connectClient
 }
 
+// authSnapshot returns the config together with the path it was loaded from, in
+// one lock: the path identifies the profile whose account email backs the login
+// hint, so reading it separately could pair one profile's config with another's
+// hint when a profile switch lands in between.
+func (c *Client) authSnapshot() (*profilemanager.Config, string, *internal.ConnectClient) {
+	c.stateMu.RLock()
+	defer c.stateMu.RUnlock()
+	return c.config, c.cfgPath, c.connectClient
+}
+
 func (c *Client) getConnectClient() *internal.ConnectClient {
 	c.stateMu.RLock()
 	defer c.stateMu.RUnlock()
@@ -102,6 +152,7 @@ func NewClient(androidSDKVersion int, deviceName string, uiVersion string, tunAd
 	execWorkaround(androidSDKVersion)
 
 	net.SetAndroidProtectSocketFn(tunAdapter.ProtectSocket)
+	system.SetIFaceDiscover(iFaceDiscover)
 	return &Client{
 		deviceName:            deviceName,
 		uiVersion:             uiVersion,
@@ -110,6 +161,8 @@ func NewClient(androidSDKVersion int, deviceName string, uiVersion string, tunAd
 		recorder:              peer.NewRecorder(""),
 		ctxCancelLock:         &sync.Mutex{},
 		networkChangeListener: networkChangeListener,
+		netState:              netstate.New(),
+		sweeper:               netsweep.New(),
 	}
 }
 
@@ -143,16 +196,22 @@ func (c *Client) Run(platformFiles PlatformFiles, urlOpener URLOpener, isAndroid
 	defer c.ctxCancel()
 	c.ctxCancelLock.Unlock()
 
-	auth := NewAuthWithConfig(ctx, cfg)
+	auth := NewAuthWithConfig(ctx, cfg, cfgFile)
 	err = auth.login(urlOpener, isAndroidTV)
 	if err != nil {
 		return err
 	}
-
 	// todo do not throw error in case of cancelled context
 	ctx = internal.CtxInitState(ctx)
-	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder)
-	c.setState(cfg, cacheDir, connectClient)
+	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder,
+		internal.WithNetworkState(c.netState), internal.WithSweeper(c.sweeper))
+	c.setState(cfg, cacheDir, cfgFile, connectClient)
+	// This path runs the interactive SSO flow, so reaching here means the peer
+	// is authenticated again — release the latch Status() reports from. Clear
+	// only once the fresh connect client is installed: until then Status()
+	// still reads the previous run's context state, which holds the NeedsLogin
+	// that prompted this login, and would re-latch what was just cleared.
+	c.clearLoginRequired()
 	return connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile, cacheDir)
 }
 
@@ -186,8 +245,9 @@ func (c *Client) RunWithoutLogin(platformFiles PlatformFiles, dns *DNSList, dnsR
 
 	// todo do not throw error in case of cancelled context
 	ctx = internal.CtxInitState(ctx)
-	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder)
-	c.setState(cfg, cacheDir, connectClient)
+	connectClient := internal.NewConnectClient(ctx, cfg, c.recorder,
+		internal.WithNetworkState(c.netState), internal.WithSweeper(c.sweeper))
+	c.setState(cfg, cacheDir, cfgFile, connectClient)
 	return connectClient.RunOnAndroid(c.tunAdapter, c.iFaceDiscover, c.networkChangeListener, slices.Clone(dns.items), dnsReadyListener, stateFile, cacheDir)
 }
 
@@ -216,9 +276,47 @@ func (c *Client) RenewTun(fd int) error {
 	return e.RenewTun(fd)
 }
 
+func (c *Client) GetTunSettings() (*TunSettings, error) {
+	cc := c.getConnectClient()
+	if cc == nil {
+		return nil, fmt.Errorf("engine not running")
+	}
+
+	e := cc.Engine()
+	if e == nil {
+		return nil, fmt.Errorf("engine not initialized")
+	}
+
+	routes, searchDomains := e.TunSettings()
+	return &TunSettings{
+		Routes:        strings.Join(routes, ";"),
+		SearchDomains: strings.Join(searchDomains, ";"),
+	}, nil
+}
+
+// SetNetworkAvailable feeds OS-reported network availability into the client.
+// While unavailable, the internal reconnect loops suspend their attempts and
+// the connection listener reports NoNetwork instead of Connecting; when
+// availability returns, the loops resume immediately with a fresh backoff.
+func (c *Client) SetNetworkAvailable(available bool) {
+	c.netState.Set(available)
+	c.recorder.SetNetworkAvailable(available)
+}
+
+// NotifyNetworkChange marks the management, signal and relay connections
+// stale after the OS switched networks and schedules a sweep that cuts
+// whatever has not redialed on the new network by then. The engine and the
+// TUN device stay untouched.
+func (c *Client) NotifyNetworkChange() {
+	c.sweeper.MarkNetworkChange()
+	log.Infof("network change: connections marked stale")
+}
+
 // DebugBundle generates a debug bundle, uploads it, and returns the upload key.
-// It works both with and without a running engine.
-func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool) (string, error) {
+// It works both with and without a running engine. anonymizeLevel is "default"
+// or "strict"; strict also anonymizes internal IP ranges, peer names, and
+// WireGuard public keys, and implies anonymize.
+func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool, anonymizeLevel string) (string, error) {
 	cfg, cacheDir, cc := c.stateSnapshot()
 
 	// If the engine hasn't been started, load config from disk
@@ -237,6 +335,7 @@ func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool) (strin
 		InternalConfig: cfg,
 		StatusRecorder: c.recorder,
 		TempDir:        cacheDir,
+		StatePath:      platformFiles.StateFilePath(),
 	}
 
 	if cc != nil {
@@ -247,6 +346,9 @@ func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool) (strin
 		deps.SyncResponse = resp
 
 		if e := cc.Engine(); e != nil {
+			deps.RefreshStatus = func() {
+				e.RunHealthProbes(context.Background(), true)
+			}
 			if cm := e.GetClientMetrics(); cm != nil {
 				deps.ClientMetrics = cm
 			}
@@ -257,6 +359,7 @@ func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool) (strin
 		deps,
 		debug.BundleConfig{
 			Anonymize:         anonymize,
+			AnonymizeLevel:    nbAnonymize.ParseLevel(anonymizeLevel),
 			IncludeSystemInfo: true,
 		},
 	)
@@ -274,7 +377,7 @@ func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool) (strin
 	uploadCtx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
 	defer cancel()
 
-	key, err := debug.UploadDebugBundle(uploadCtx, types.DefaultBundleURL, cfg.ManagementURL.String(), path)
+	key, err := debug.UploadDebugBundle(uploadCtx, types.DefaultBundleURL, cfg.ManagementURL.String(), path, false)
 	if err != nil {
 		return "", fmt.Errorf("upload debug bundle: %w", err)
 	}
@@ -296,6 +399,13 @@ func (c *Client) SetInfoLogLevel() {
 // PeersList return with the list of the PeerInfos
 func (c *Client) PeersList() *PeerInfoArray {
 
+	// The recorder only caches transfer counters and handshake times; nothing
+	// refreshes them on its own, so without this they read as zero. The desktop
+	// daemon does the same before serving a full peer status.
+	if err := c.recorder.RefreshWireGuardStats(); err != nil {
+		log.Debugf("failed to refresh WireGuard stats: %v", err)
+	}
+
 	fullStatus := c.recorder.GetFullStatus()
 
 	peerInfos := make([]PeerInfo, len(fullStatus.Peers))
@@ -306,6 +416,20 @@ func (c *Client) PeersList() *PeerInfoArray {
 			FQDN:       p.FQDN,
 			ConnStatus: int(p.ConnStatus),
 			Routes:     PeerRoutes{routes: maps.Keys(p.GetRoutes())},
+
+			PubKey:                     p.PubKey,
+			Latency:                    formatDuration(p.Latency),
+			LatencyMs:                  p.Latency.Milliseconds(),
+			BytesRx:                    p.BytesRx,
+			BytesTx:                    p.BytesTx,
+			ConnStatusUpdate:           formatTime(p.ConnStatusUpdate),
+			Relayed:                    p.Relayed,
+			RosenpassEnabled:           p.RosenpassEnabled,
+			LastWireguardHandshake:     formatTime(p.LastWireguardHandshake),
+			LocalIceCandidateType:      p.LocalIceCandidateType,
+			RemoteIceCandidateType:     p.RemoteIceCandidateType,
+			LocalIceCandidateEndpoint:  p.LocalIceCandidateEndpoint,
+			RemoteIceCandidateEndpoint: p.RemoteIceCandidateEndpoint,
 		}
 		peerInfos[n] = pi
 	}
@@ -428,7 +552,11 @@ func (c *Client) OnUpdatedHostDNS(list *DNSList) error {
 
 // SetConnectionListener set the network connection listener
 func (c *Client) SetConnectionListener(listener ConnectionListener) {
-	c.recorder.SetConnectionListener(listener)
+	if listener == nil {
+		c.recorder.RemoveConnectionListener()
+		return
+	}
+	c.recorder.SetConnectionListener(connectionListenerAdapter{listener})
 }
 
 // RemoveConnectionListener remove connection listener
@@ -436,10 +564,6 @@ func (c *Client) RemoveConnectionListener() {
 	c.recorder.RemoveConnectionListener()
 }
 
-func (c *Client) toggleRoute(command routeCommand) error {
-	return command.toggleRoute()
-}
-
 func (c *Client) getRouteManager() (routemanager.Manager, error) {
 	client := c.getConnectClient()
 	if client == nil {
@@ -459,22 +583,22 @@ func (c *Client) getRouteManager() (routemanager.Manager, error) {
 	return manager, nil
 }
 
-func (c *Client) SelectRoute(route string) error {
+func (c *Client) SelectRoute(id string) error {
 	manager, err := c.getRouteManager()
 	if err != nil {
 		return err
 	}
 
-	return c.toggleRoute(selectRouteCommand{route: route, manager: manager})
+	return manager.SelectRoutes([]route.NetID{route.NetID(id)}, true)
 }
 
-func (c *Client) DeselectRoute(route string) error {
+func (c *Client) DeselectRoute(id string) error {
 	manager, err := c.getRouteManager()
 	if err != nil {
 		return err
 	}
 
-	return c.toggleRoute(deselectRouteCommand{route: route, manager: manager})
+	return manager.DeselectRoutes([]route.NetID{route.NetID(id)})
 }
 
 // getNetworkDomainsFromRoute extracts domains from a route and enriches each domain
@@ -509,3 +633,28 @@ func exportEnvList(list *EnvList) {
 		}
 	}
 }
+
+// formatDuration renders a duration for display, trimming the fractional part
+// to two digits so latencies read as "12.34ms" rather than "12.345678ms".
+func formatDuration(d time.Duration) string {
+	ds := d.String()
+	dotIndex := strings.Index(ds, ".")
+	if dotIndex == -1 {
+		return ds
+	}
+
+	endIndex := min(dotIndex+3, len(ds))
+
+	// Skip the remaining digits so only the unit suffix is appended back.
+	unitStart := endIndex
+	for unitStart < len(ds) && ds[unitStart] >= '0' && ds[unitStart] <= '9' {
+		unitStart++
+	}
+	return ds[:endIndex] + ds[unitStart:]
+}
+
+// formatTime renders a timestamp in UTC using a fixed layout. The zero time is
+// passed through as-is so the UI can recognise it and show "never" instead.
+func formatTime(t time.Time) string {
+	return t.UTC().Format("2006-01-02 15:04:05")
+}

client/android/connection_listener.go

@@ -0,0 +1,41 @@
+//go:build android
+
+package android
+
+import (
+	"github.com/netbirdio/netbird/client/internal/peer"
+)
+
+// Client state values delivered via ConnectionListener.OnStateChanged,
+// re-exported as basic constants so gomobile emits them into the generated
+// Java bindings. They mirror peer.ClientState*: append-only, never reorder.
+const (
+	ClientStateDisconnected  = int(peer.ClientStateDisconnected)
+	ClientStateConnected     = int(peer.ClientStateConnected)
+	ClientStateConnecting    = int(peer.ClientStateConnecting)
+	ClientStateDisconnecting = int(peer.ClientStateDisconnecting)
+	ClientStateNoNetwork     = int(peer.ClientStateNoNetwork)
+)
+
+// ConnectionListener export internal Listener for mobile. It mirrors
+// peer.Listener with OnStateChanged taking a plain int (one of the
+// ClientState* constants), because gomobile cannot bind named types.
+type ConnectionListener interface {
+	OnStateChanged(state int)
+	OnConnected()
+	OnDisconnected()
+	OnConnecting()
+	OnDisconnecting()
+	OnAddressChanged(string, string)
+	OnPeersListChanged(int)
+}
+
+// connectionListenerAdapter adapts the gomobile-facing ConnectionListener to
+// peer.Listener, converting the typed state to the int the binding carries.
+type connectionListenerAdapter struct {
+	ConnectionListener
+}
+
+func (a connectionListenerAdapter) OnStateChanged(state peer.ClientState) {
+	a.ConnectionListener.OnStateChanged(int(state))
+}

client/android/env_list.go

@@ -10,7 +10,7 @@ var (
 	EnvKeyNBForceRelay = peer.EnvKeyNBForceRelay
 
 	// EnvKeyNBLazyConn Exported for Android java client to configure lazy connection
-	EnvKeyNBLazyConn = lazyconn.EnvEnableLazyConn
+	EnvKeyNBLazyConn = lazyconn.EnvLazyConn
 
 	// EnvKeyNBInactivityThreshold Exported for Android java client to configure connection inactivity threshold
 	EnvKeyNBInactivityThreshold = lazyconn.EnvInactivityThreshold

client/android/login.go

@@ -4,8 +4,11 @@ import (
 	"context"
 	"fmt"
 
+	log "github.com/sirupsen/logrus"
+
 	"github.com/netbirdio/netbird/client/internal/auth"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
+	"github.com/netbirdio/netbird/client/mobile"
 	"github.com/netbirdio/netbird/client/system"
 )
 
@@ -36,12 +39,20 @@ type Auth struct {
 }
 
 // NewAuth instantiate Auth struct and validate the management URL
+//
+// The configuration at cfgPath is reused when one is already there, and only created when it is
+// not. Building a fresh in-memory config unconditionally gives the client a new WireGuard key on
+// every call: the peer registers under that key, the key is written out, and any peer registered by
+// an earlier call is orphaned on the server. It also breaks a client that enrols and then runs from
+// the persisted config, because the identity it registered is not the one it runs with — the
+// management stream rejects it with "no peer auth method provided".
 func NewAuth(cfgPath string, mgmURL string) (*Auth, error) {
 	inputCfg := profilemanager.ConfigInput{
+		ConfigPath:    cfgPath,
 		ManagementURL: mgmURL,
 	}
 
-	cfg, err := profilemanager.CreateInMemoryConfig(inputCfg)
+	cfg, err := profilemanager.UpdateOrCreateConfig(inputCfg)
 	if err != nil {
 		return nil, err
 	}
@@ -53,11 +64,14 @@ func NewAuth(cfgPath string, mgmURL string) (*Auth, error) {
 	}, nil
 }
 
-// NewAuthWithConfig instantiate Auth based on existing config
-func NewAuthWithConfig(ctx context.Context, config *profilemanager.Config) *Auth {
+// NewAuthWithConfig instantiate Auth based on existing config. cfgPath is the
+// file the config was loaded from; it identifies the profile whose account email
+// backs the login_hint.
+func NewAuthWithConfig(ctx context.Context, config *profilemanager.Config, cfgPath string) *Auth {
 	return &Auth{
-		ctx:    ctx,
-		config: config,
+		ctx:     ctx,
+		config:  config,
+		cfgPath: cfgPath,
 	}
 }
 
@@ -150,12 +164,14 @@ func (a *Auth) login(urlOpener URLOpener, isAndroidTV bool) error {
 	}
 
 	jwtToken := ""
+	email := ""
 	if needsLogin {
 		tokenInfo, err := a.foregroundGetTokenInfo(authClient, urlOpener, isAndroidTV)
 		if err != nil {
 			return fmt.Errorf("interactive sso login failed: %v", err)
 		}
 		jwtToken = tokenInfo.GetTokenToUse()
+		email = tokenInfo.Email
 	}
 
 	err, _ = authClient.Login(a.ctx, "", jwtToken)
@@ -163,27 +179,62 @@ func (a *Auth) login(urlOpener URLOpener, isAndroidTV bool) error {
 		return fmt.Errorf("login failed: %v", err)
 	}
 
+	// Stored after Login, not before: a rejected token must not leave a hint
+	// pointing at an account that cannot be used.
+	if email != "" && a.cfgPath != "" {
+		if err := mobile.WriteProfileEmail(a.cfgPath, email); err != nil {
+			log.Warnf("failed to store profile account email: %v", err)
+		}
+	}
+
 	go urlOpener.OnLoginSuccess()
 
 	return nil
 }
 
 func (a *Auth) foregroundGetTokenInfo(authClient *auth.Auth, urlOpener URLOpener, isAndroidTV bool) (*auth.TokenInfo, error) {
-	oAuthFlow, err := authClient.GetOAuthFlow(a.ctx, isAndroidTV)
+	oAuthFlow, err := authClient.GetOAuthFlow(a.ctx, isAndroidTV, profileLoginHint(a.cfgPath))
 	if err != nil {
 		return nil, fmt.Errorf("failed to get OAuth flow: %v", err)
 	}
 
-	flowInfo, err := oAuthFlow.RequestAuthInfo(context.TODO())
+	return runOAuthFlow(a.ctx, oAuthFlow, urlOpener, nil)
+}
+
+// profileLoginHint returns the stored account email for the profile at cfgPath.
+// An empty hint is deliberate, not a fallback: a fresh profile leaves the
+// choice to the IdP. Switching accounts is done by switching or removing
+// profiles, not by logging out — logout keeps the email.
+func profileLoginHint(cfgPath string) string {
+	if cfgPath == "" {
+		return ""
+	}
+	return mobile.ReadProfileEmail(cfgPath)
+}
+
+// runOAuthFlow drives an already acquired OAuth flow to a token: requests the
+// flow info, presents the verification URL through the opener and waits for
+// the browser round-trip. Open is called synchronously — it is what marks the
+// surface as opened on the client side, and a fast token's OnLoginSuccess is
+// a no-op until it has, so the dismissal would be dropped rather than
+// delayed. Openers must therefore not block: they post their UI work and
+// return. onWaiting, when set, runs after the URL is shown, right before the
+// blocking wait.
+func runOAuthFlow(ctx context.Context, flow auth.OAuthFlow, urlOpener URLOpener, onWaiting func()) (*auth.TokenInfo, error) {
+	flowInfo, err := flow.RequestAuthInfo(ctx)
 	if err != nil {
-		return nil, fmt.Errorf("getting a request OAuth flow info failed: %v", err)
+		return nil, fmt.Errorf("request auth info: %w", err)
 	}
 
-	go urlOpener.Open(flowInfo.VerificationURIComplete, flowInfo.UserCode)
+	urlOpener.Open(flowInfo.VerificationURIComplete, flowInfo.UserCode)
 
-	tokenInfo, err := oAuthFlow.WaitToken(a.ctx, flowInfo)
+	if onWaiting != nil {
+		onWaiting()
+	}
+
+	tokenInfo, err := flow.WaitToken(ctx, flowInfo)
 	if err != nil {
-		return nil, fmt.Errorf("waiting for browser login failed: %v", err)
+		return nil, fmt.Errorf("wait for token: %w", err)
 	}
 
 	return &tokenInfo, nil

client/android/login_test.go

@@ -0,0 +1,51 @@
+package android
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// NewAuth must reuse the configuration already at cfgPath rather than building a fresh one.
+//
+// Creating a new in-memory config on every call gives the client a new WireGuard private key each
+// time. The peer registers under that key and the key is written out, so a peer registered by an
+// earlier call is orphaned on the server — a client that enrols twice leaves two entries and owns
+// neither. It also breaks enrol-then-run: RunWithoutLogin reloads the configuration from disk, so
+// the identity that registered is not the identity that runs, and the management stream rejects it
+// with "no peer auth method provided, please use a setup key or interactive SSO login".
+func TestNewAuth_ReusesPersistedIdentity(t *testing.T) {
+	cfgPath := filepath.Join(t.TempDir(), "config.json")
+
+	first, err := NewAuth(cfgPath, "https://api.example.com:443")
+	if err != nil {
+		t.Fatalf("first NewAuth: %v", err)
+	}
+	if first.config.PrivateKey == "" {
+		t.Fatal("first NewAuth produced no private key")
+	}
+
+	second, err := NewAuth(cfgPath, "https://api.example.com:443")
+	if err != nil {
+		t.Fatalf("second NewAuth: %v", err)
+	}
+
+	if second.config.PrivateKey != first.config.PrivateKey {
+		t.Errorf("private key changed between calls: a second enrolment would orphan the peer registered by the first")
+	}
+}
+
+// A missing configuration is still created, so a first enrolment works unchanged.
+func TestNewAuth_CreatesConfigWhenAbsent(t *testing.T) {
+	cfgPath := filepath.Join(t.TempDir(), "config.json")
+
+	auth, err := NewAuth(cfgPath, "https://api.example.com:443")
+	if err != nil {
+		t.Fatalf("NewAuth: %v", err)
+	}
+	if auth.config == nil || auth.config.PrivateKey == "" {
+		t.Fatal("NewAuth did not create a usable configuration")
+	}
+	if auth.cfgPath != cfgPath {
+		t.Errorf("cfgPath = %q, want %q", auth.cfgPath, cfgPath)
+	}
+}

client/android/peer_notifier.go

@@ -12,12 +12,30 @@ const (
 )
 
 // PeerInfo describe information about the peers. It designed for the UI usage
+//
+// The fields below ConnStatus back the peer detail screen. Durations and times
+// are pre-formatted into strings so the UI does not have to know Go's layouts;
+// Latency is additionally exposed as LatencyMs for colour coding.
 type PeerInfo struct {
 	IP         string
 	IPv6       string
 	FQDN       string
 	ConnStatus int
 	Routes     PeerRoutes
+
+	PubKey                     string
+	Latency                    string
+	LatencyMs                  int64
+	BytesRx                    int64
+	BytesTx                    int64
+	ConnStatusUpdate           string
+	Relayed                    bool
+	RosenpassEnabled           bool
+	LastWireguardHandshake     string
+	LocalIceCandidateType      string
+	RemoteIceCandidateType     string
+	LocalIceCandidateEndpoint  string
+	RemoteIceCandidateEndpoint string
 }
 
 func (p *PeerInfo) GetPeerRoutes() *PeerRoutes {

client/android/profile_prefs.go

@@ -0,0 +1,37 @@
+//go:build android
+
+package android
+
+import (
+	"fmt"
+
+	"github.com/netbirdio/netbird/client/internal/profilemanager"
+)
+
+type prefsStore interface {
+	Get(namespace string, v any) (bool, error)
+	Put(namespace string, v any) error
+}
+
+type profilePrefs struct {
+	prefs *profilemanager.Prefs
+}
+
+func newProfilePrefs(configDir, profileID string) (*profilePrefs, error) {
+	if configDir == "" || profileID == "" {
+		return nil, fmt.Errorf("profile prefs require a config dir and profile ID")
+	}
+	prefs, err := NewProfileManager(configDir).impl.ProfilePrefs(profileID)
+	if err != nil {
+		return nil, err
+	}
+	return &profilePrefs{prefs: prefs}, nil
+}
+
+func (p *profilePrefs) Get(namespace string, v any) (bool, error) {
+	return p.prefs.Get(namespace, v)
+}
+
+func (p *profilePrefs) Put(namespace string, v any) error {
+	return p.prefs.Put(namespace, v)
+}

client/android/route_command.go

@@ -1,70 +0,0 @@
-//go:build android
-
-package android
-
-import (
-	"fmt"
-
-	log "github.com/sirupsen/logrus"
-	"golang.org/x/exp/maps"
-
-	"github.com/netbirdio/netbird/client/internal/routemanager"
-	"github.com/netbirdio/netbird/route"
-)
-
-func executeRouteToggle(id string, manager routemanager.Manager,
-	operationName string,
-	routeOperation func(routes []route.NetID, allRoutes []route.NetID) error) error {
-	netID := route.NetID(id)
-	routes := []route.NetID{netID}
-
-	routesMap := manager.GetClientRoutesWithNetID()
-	routes = route.ExpandV6ExitPairs(routes, routesMap)
-
-	log.Debugf("%s with ids: %v", operationName, routes)
-
-	if err := routeOperation(routes, maps.Keys(routesMap)); err != nil {
-		log.Debugf("error when %s: %s", operationName, err)
-		return fmt.Errorf("error %s: %w", operationName, err)
-	}
-
-	manager.TriggerSelection(manager.GetClientRoutes())
-
-	return nil
-}
-
-type routeCommand interface {
-	toggleRoute() error
-}
-
-type selectRouteCommand struct {
-	route   string
-	manager routemanager.Manager
-}
-
-func (s selectRouteCommand) toggleRoute() error {
-	routeSelector := s.manager.GetRouteSelector()
-	if routeSelector == nil {
-		return fmt.Errorf("no route selector available")
-	}
-
-	routeOperation := func(routes []route.NetID, allRoutes []route.NetID) error {
-		return routeSelector.SelectRoutes(routes, true, allRoutes)
-	}
-
-	return executeRouteToggle(s.route, s.manager, "selecting route", routeOperation)
-}
-
-type deselectRouteCommand struct {
-	route   string
-	manager routemanager.Manager
-}
-
-func (d deselectRouteCommand) toggleRoute() error {
-	routeSelector := d.manager.GetRouteSelector()
-	if routeSelector == nil {
-		return fmt.Errorf("no route selector available")
-	}
-
-	return executeRouteToggle(d.route, d.manager, "deselecting route", routeSelector.DeselectRoutes)
-}

client/android/session.go

@@ -0,0 +1,312 @@
+//go:build android
+
+package android
+
+import (
+	"context"
+	"fmt"
+
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/internal"
+	"github.com/netbirdio/netbird/client/internal/auth"
+	"github.com/netbirdio/netbird/client/internal/auth/sessionwatch"
+	"github.com/netbirdio/netbird/client/internal/peer"
+	cProto "github.com/netbirdio/netbird/client/proto"
+)
+
+// StateChangeListener receives client state notifications.
+//
+// OnStateChanged is a payload-free wake-up whenever the state snapshot
+// changed: connection state, the run-loop status label (e.g. NeedsLogin) or
+// the session deadline. It mirrors the daemon's SubscribeStatus stream
+// trigger — on each signal the consumer pulls the fresh values via
+// Status() / SessionExpiresAtUnix().
+//
+// OnSessionExpiring forwards the engine's session-expiry warnings, fired at
+// sessionwatch.WarningLead before the deadline and again at FinalWarningLead
+// (finalWarning true). The second one is suppressed when the user dismissed
+// the first via DismissSessionWarning. The daemon turns the same events into
+// its tray notification.
+type StateChangeListener interface {
+	OnStateChanged()
+	OnSessionExpiring(expiresAtUnix int64, leadMinutes int64, finalWarning bool)
+}
+
+// Status returns the connect run-loop's status label — the same value the
+// desktop daemon serves in StatusResponse.Status. "NeedsLogin" means the
+// management server rejected the peer and an interactive login is required.
+//
+// The label is latched: the run loop keeps its status in a per-run context
+// state, which a restart replaces with a fresh Idle one, so an engine restart
+// (network change, always-on) would otherwise erase the fact that the peer
+// still needs to log in. Only a successful interactive login or extend clears
+// it — see clearLoginRequired.
+func (c *Client) Status() string {
+	latched, generation := c.loginRequiredState()
+	if latched {
+		return string(internal.StatusNeedsLogin)
+	}
+	cc := c.getConnectClient()
+	if cc == nil {
+		return string(internal.StatusIdle)
+	}
+	status := cc.Status()
+	if status == internal.StatusNeedsLogin {
+		c.latchLoginRequired(generation)
+	}
+	return string(status)
+}
+
+func (c *Client) loginRequiredState() (bool, uint64) {
+	c.loginRequiredMu.Lock()
+	defer c.loginRequiredMu.Unlock()
+	return c.loginRequired, c.loginCleared
+}
+
+// latchLoginRequired records a NeedsLogin observation, unless a clear landed
+// while the caller was reading the run loop's status: cc.Status() is read
+// outside the lock, so a login or extend completing in that window would
+// otherwise be undone by this stale observation, stranding the UI on
+// "login required" over a healthy session.
+func (c *Client) latchLoginRequired(observedGeneration uint64) {
+	c.loginRequiredMu.Lock()
+	defer c.loginRequiredMu.Unlock()
+	if c.loginCleared != observedGeneration {
+		return
+	}
+	c.loginRequired = true
+}
+
+// clearLoginRequired releases the latch after a successful interactive login
+// or session extend, and invalidates any observation already in flight.
+func (c *Client) clearLoginRequired() {
+	c.loginRequiredMu.Lock()
+	defer c.loginRequiredMu.Unlock()
+	c.loginRequired = false
+	c.loginCleared++
+}
+
+// SessionExpiresAtUnix returns the SSO session deadline as unix seconds, or 0
+// when no deadline is known (not SSO-registered, expiry disabled, or the
+// engine has not received one yet). A past value means the session expired.
+// Mirror of StatusResponse.sessionExpiresAt on the desktop daemon.
+func (c *Client) SessionExpiresAtUnix() int64 {
+	deadline := c.recorder.GetSessionExpiresAt()
+	if deadline.IsZero() {
+		return 0
+	}
+	return deadline.Unix()
+}
+
+// SetStateChangeListener registers the state notification listener.
+// Replaces any previously registered listener; remove it with
+// RemoveStateChangeListener.
+func (c *Client) SetStateChangeListener(listener StateChangeListener) {
+	c.stateChangeMu.Lock()
+	defer c.stateChangeMu.Unlock()
+	c.stopStateChangeWatchLocked()
+	if listener == nil {
+		return
+	}
+
+	// Both subscriptions are buffered (one pending tick, ten pending events),
+	// so unsubscribing is not enough to stop callbacks: the loops would drain
+	// what is already queued and deliver it to a listener the caller has
+	// already removed or replaced. Gate every callback on this registration's
+	// own signal, which is closed before unsubscribing.
+	done := make(chan struct{})
+	c.stateChangeDone = done
+
+	id, ch := c.recorder.SubscribeToStateChanges()
+	c.stateChangeSubID = id
+	// The channel is closed by UnsubscribeFromStateChanges, which ends the
+	// goroutine. Ticks are coalesced (buffer of one), so a burst of changes
+	// wakes the listener once.
+	go func() {
+		for range ch {
+			select {
+			case <-done:
+				return
+			default:
+			}
+			listener.OnStateChanged()
+		}
+	}()
+
+	c.eventSub = c.recorder.SubscribeToEvents()
+	go watchSessionWarnings(c.eventSub, listener, done)
+}
+
+// RemoveStateChangeListener unregisters the state notification listener.
+func (c *Client) RemoveStateChangeListener() {
+	c.stateChangeMu.Lock()
+	defer c.stateChangeMu.Unlock()
+	c.stopStateChangeWatchLocked()
+}
+
+// DismissSessionWarning records the user's "Dismiss" on the first expiry
+// warning and suppresses the final one for the current deadline. A refreshed
+// deadline re-arms both. No-op while the engine is not running.
+func (c *Client) DismissSessionWarning() {
+	cc := c.getConnectClient()
+	if cc == nil {
+		return
+	}
+	engine := cc.Engine()
+	if engine == nil {
+		return
+	}
+	engine.DismissSessionWarning()
+}
+
+// ExtendAuthSession runs the interactive SSO flow to obtain a fresh JWT and
+// asks the management server to extend the session deadline. The tunnel is
+// untouched: no resync, no reconnect. Async; the result arrives on the
+// listener. Mirror of the daemon's RequestExtendAuthSession /
+// WaitExtendAuthSession RPC pair, with URLOpener playing the "UI opens the
+// browser" role.
+//
+// Only one flow may be in flight: the PKCE step binds a fixed loopback port,
+// so a second concurrent flow would fail on that bind. Call
+// CancelExtendAuthSession when the user abandons the browser.
+func (c *Client) ExtendAuthSession(urlOpener URLOpener, isAndroidTV bool, resultListener ErrListener) {
+	ctx, err := c.beginExtend()
+	if err != nil {
+		resultListener.OnError(err)
+		return
+	}
+
+	go func() {
+		defer c.endExtend()
+		if err := c.extendAuthSession(ctx, urlOpener, isAndroidTV); err != nil {
+			resultListener.OnError(err)
+			return
+		}
+		resultListener.OnSuccess()
+	}()
+}
+
+// CancelExtendAuthSession aborts an in-flight ExtendAuthSession. The tunnel is
+// left alone — unlike the login flow, which cancels the whole client context
+// by stopping the engine. Without this the abandoned PKCE wait keeps its
+// loopback port for the full flow timeout and blocks every later attempt.
+// No-op when no flow is running.
+func (c *Client) CancelExtendAuthSession() {
+	c.extendMu.Lock()
+	defer c.extendMu.Unlock()
+	if c.extendCancel != nil {
+		c.extendCancel()
+	}
+}
+
+func (c *Client) stopStateChangeWatchLocked() {
+	// Signal first, unsubscribe second: closing the channels only stops new
+	// items, and the loops would still hand whatever is buffered to a listener
+	// that is no longer registered.
+	if c.stateChangeDone != nil {
+		close(c.stateChangeDone)
+		c.stateChangeDone = nil
+	}
+	if c.stateChangeSubID != "" {
+		c.recorder.UnsubscribeFromStateChanges(c.stateChangeSubID)
+		c.stateChangeSubID = ""
+	}
+	if c.eventSub != nil {
+		// Closes the channel, which ends watchSessionWarnings.
+		c.recorder.UnsubscribeFromEvents(c.eventSub)
+		c.eventSub = nil
+	}
+}
+
+// watchSessionWarnings forwards the engine's session-expiry warnings to the
+// listener. The event stream also carries unrelated traffic — network-map
+// updates on every sync, DNS and route errors — so everything but an
+// AUTHENTICATION event carrying the session-warning marker is dropped. Exits
+// when the subscription is closed by UnsubscribeFromEvents, or earlier when
+// done is closed — the stream buffers up to ten events, and a deregistered
+// listener must not receive the ones already queued.
+func watchSessionWarnings(sub *peer.EventSubscription, listener StateChangeListener, done <-chan struct{}) {
+	for ev := range sub.Events() {
+		select {
+		case <-done:
+			return
+		default:
+		}
+		if ev.GetCategory() != cProto.SystemEvent_AUTHENTICATION {
+			continue
+		}
+		meta := ev.GetMetadata()
+		if meta[sessionwatch.MetaSessionWarning] != "true" {
+			// Other AUTHENTICATION events exist (e.g. a deadline rejected as
+			// out of range); they carry no warning marker.
+			continue
+		}
+		deadline, err := sessionwatch.ParseExpiresAt(meta[sessionwatch.MetaSessionExpiresAt])
+		if err != nil {
+			log.Warnf("session warning event with unparsable deadline: %v", err)
+			continue
+		}
+		lead, err := sessionwatch.ParseLeadMinutes(meta[sessionwatch.MetaSessionLeadMinutes])
+		if err != nil {
+			// Informational only — the deadline above is what drives the UI.
+			lead = 0
+		}
+		listener.OnSessionExpiring(deadline.Unix(), int64(lead),
+			meta[sessionwatch.MetaSessionFinal] == "true")
+	}
+}
+
+func (c *Client) beginExtend() (context.Context, error) {
+	c.extendMu.Lock()
+	defer c.extendMu.Unlock()
+	if c.extendCancel != nil {
+		return nil, fmt.Errorf("session extend already in progress")
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	c.extendCancel = cancel
+	return ctx, nil
+}
+
+func (c *Client) endExtend() {
+	c.extendMu.Lock()
+	defer c.extendMu.Unlock()
+	if c.extendCancel != nil {
+		c.extendCancel()
+		c.extendCancel = nil
+	}
+}
+
+func (c *Client) extendAuthSession(ctx context.Context, urlOpener URLOpener, isAndroidTV bool) error {
+	cfg, cfgPath, cc := c.authSnapshot()
+	if cfg == nil || cc == nil {
+		return fmt.Errorf("engine is not running")
+	}
+	engine := cc.Engine()
+	if engine == nil {
+		return fmt.Errorf("engine is not initialized")
+	}
+
+	authClient, err := auth.NewAuth(ctx, cfg.PrivateKey, cfg.ManagementURL, cfg)
+	if err != nil {
+		return fmt.Errorf("failed to create auth client: %v", err)
+	}
+	defer authClient.Close()
+
+	// Passing the config path makes the flow pick up the login_hint: an extend
+	// renews the session of the account already signed in, so it must not stop to
+	// offer a choice.
+	a := NewAuthWithConfig(ctx, cfg, cfgPath)
+	tokenInfo, err := a.foregroundGetTokenInfo(authClient, urlOpener, isAndroidTV)
+	if err != nil {
+		return fmt.Errorf("interactive sso login failed: %v", err)
+	}
+
+	if _, err := engine.ExtendAuthSession(ctx, tokenInfo.GetTokenToUse()); err != nil {
+		return err
+	}
+	c.clearLoginRequired()
+
+	go urlOpener.OnLoginSuccess()
+	return nil
+}

client/android/ssh_client.go

@@ -0,0 +1,649 @@
+//go:build android
+
+package android
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+	gossh "golang.org/x/crypto/ssh"
+
+	"github.com/netbirdio/netbird/client/internal"
+	"github.com/netbirdio/netbird/client/internal/auth"
+	"github.com/netbirdio/netbird/client/internal/profilemanager"
+	nbssh "github.com/netbirdio/netbird/client/ssh"
+	"github.com/netbirdio/netbird/client/ssh/detection"
+)
+
+const (
+	sshDialTimeout      = 30 * time.Second
+	sshDetectionTimeout = 5 * time.Second
+)
+
+// PasswordRequiredMarker tells Java to prompt for a password and retry. It is
+// a string because gomobile flattens errors to their message, so a sentinel
+// value would not survive the binding.
+const PasswordRequiredMarker = "netbird-ssh-password-required"
+
+// HostKeyUnknownMarker tells Java to show the fingerprint and, on confirmation,
+// retry with TrustHostKey set. The presented fingerprint is appended after the
+// marker so the prompt can display it and the retry can guard against a key
+// that changed between the two connects. Only regular (non-NetBird) servers
+// reach this: NetBird peers verify against the registry.
+const HostKeyUnknownMarker = "netbird-ssh-hostkey-unknown"
+
+var (
+	errPasswordRequired = errors.New(PasswordRequiredMarker)
+	errClientClosed     = errors.New("ssh client closed")
+)
+
+// errHostKeyUnknown carries the presented fingerprint so Connect can build the
+// marker message the Java side parses.
+type errHostKeyUnknown struct {
+	fingerprint string
+}
+
+func (e *errHostKeyUnknown) Error() string {
+	return HostKeyUnknownMarker + ":" + e.fingerprint
+}
+
+// SSHTerminalListener receives SSH session events. It is implemented in Java.
+//
+// All callbacks are invoked from goroutines and may run concurrently with each
+// other; the implementation must be safe to call from any thread.
+type SSHTerminalListener interface {
+	OnConnected()
+	OnData(data []byte)
+	OnClose(reason string)
+	OnError(message string)
+}
+
+// SSHClient is a NetBird-aware SSH client exposed to Java via gomobile.
+//
+// It dials through the running NetBird tunnel and runs a standard SSH session
+// on top with PTY enabled. Host-key verification uses the NetBird-provided
+// peer SSH host keys, identical to the desktop client.
+type SSHClient struct {
+	nb        *Client
+	mu        sync.Mutex
+	listener  SSHTerminalListener
+	urlOpener URLOpener
+
+	sshClient *gossh.Client
+	session   *gossh.Session
+	stdin     io.WriteCloser
+	closed    bool
+
+	// gen identifies the current connection attempt. Connect and Close bump it,
+	// so an in-flight dial or a reader left over from a previous connection
+	// finds itself stale and stays silent instead of publishing OnConnected or
+	// OnClose for a connection the caller already abandoned.
+	gen        uint64
+	dialCancel context.CancelFunc
+
+	// knownHostsConfigDir and knownHostsProfile locate the TOFU store for
+	// regular SSH servers in the profile's preferences. Java supplies them,
+	// since an overlay IP is a different host under a different profile. Empty
+	// until set: without them a regular server cannot be verified and Connect
+	// refuses one.
+	knownHostsConfigDir string
+	knownHostsProfile   string
+	// trustHostKey carries the fingerprint the user confirmed on a previous
+	// attempt, so the retry accepts exactly that key and persists it.
+	trustHostKey string
+}
+
+// NewSSHClient creates a new SSH client bound to the running NetBird Client.
+func NewSSHClient(c *Client) *SSHClient {
+	return &SSHClient{nb: c}
+}
+
+// SetListener registers the Java listener. Must be called before Connect to
+// receive any events.
+func (s *SSHClient) SetListener(l SSHTerminalListener) {
+	s.mu.Lock()
+	s.listener = l
+	s.mu.Unlock()
+}
+
+// SetURLOpener registers the Java URL opener used to display the device-code
+// authorization page in a Custom Tabs window when the target peer requires
+// JWT authentication. Must be set before Connect to be effective.
+func (s *SSHClient) SetURLOpener(opener URLOpener) {
+	s.mu.Lock()
+	s.urlOpener = opener
+	s.mu.Unlock()
+}
+
+// SetKnownHostsStore points the TOFU host-key store at a profile's preferences.
+// Must be set before connecting to a regular SSH server; without it such a
+// server cannot be verified and Connect refuses one.
+func (s *SSHClient) SetKnownHostsStore(configDir, profileID string) {
+	s.mu.Lock()
+	s.knownHostsConfigDir = configDir
+	s.knownHostsProfile = profileID
+	s.mu.Unlock()
+}
+
+// TrustHostKey records the fingerprint the user confirmed for a regular server,
+// so the next Connect accepts that exact key and adds it to the known-hosts
+// store. Passing a fingerprint that no longer matches makes the connect fail
+// rather than trust a key that changed since the prompt.
+func (s *SSHClient) TrustHostKey(fingerprint string) {
+	s.mu.Lock()
+	s.trustHostKey = fingerprint
+	s.mu.Unlock()
+}
+
+// Connect dials the SSH server through the NetBird tunnel and performs the
+// SSH handshake. It auto-detects the server type via SSH banner inspection
+// and selects the appropriate authentication path:
+//
+//   - NetBird-SSH server requiring JWT: launches the OAuth 2.0 device-code
+//     flow, opens the verification URL through the registered URLOpener, and
+//     uses the resulting token as the SSH password. Host-key verification
+//     uses the NetBird peer registry.
+//   - NetBird-SSH server without JWT: authenticates with the NetBird SSH
+//     private key. Host-key verification uses the NetBird peer registry.
+//   - Regular SSH server (e.g. OpenSSH): authenticates with the NetBird key
+//     first (so a user-installed NetBird public key works), then falls back
+//     to the supplied password if non-empty. Host-key verification is
+//     trust-on-first-use against the per-profile known-hosts store.
+//
+// The password parameter is only consulted for regular SSH servers.
+func (s *SSHClient) Connect(host string, port int, user, password string) error {
+	if port < 1 || port > 65535 {
+		return fmt.Errorf("invalid port: %d", port)
+	}
+
+	cfg, cfgPath, cc := s.nb.authSnapshot()
+	if cc == nil {
+		return errors.New("netbird client not running")
+	}
+	if cfg == nil {
+		return errors.New("netbird config not loaded")
+	}
+	engine := cc.Engine()
+	if engine == nil {
+		return errors.New("netbird engine not available")
+	}
+
+	s.mu.Lock()
+	s.gen++
+	gen := s.gen
+	s.mu.Unlock()
+
+	serverType := detectServerType(host, port)
+	log.Debugf("SSH server type: %s", serverType)
+
+	authMethods, hostKeyCallback, err := s.buildAuth(cfg, cfgPath, engine, serverType, password)
+	if err != nil {
+		return err
+	}
+
+	clientConfig := &gossh.ClientConfig{
+		User:            user,
+		Auth:            authMethods,
+		HostKeyCallback: hostKeyCallback,
+		Timeout:         sshDialTimeout,
+	}
+	err = s.dialAndHandshake(gen, host, port, clientConfig)
+
+	// An unknown host key is a prompt, not a failure: return the marker intact
+	// (rootCause would unwrap it) so Java can show the fingerprint and retry.
+	var unknownHost *errHostKeyUnknown
+	if errors.As(err, &unknownHost) {
+		return errors.New(unknownHost.Error())
+	}
+
+	// A regular server may still accept a password, so let the caller ask for
+	// one instead of failing. NetBird servers never use a password, so a
+	// failure there is genuine.
+	if err != nil && serverType != detection.ServerTypeNetBirdJWT &&
+		serverType != detection.ServerTypeNetBirdNoJWT && isAuthFailure(err) &&
+		passwordCouldHelp(err, password != "") {
+		return errPasswordRequired
+	}
+	if err != nil {
+		return rootCause(err)
+	}
+	return nil
+}
+
+// StartSession requests a PTY and starts an interactive shell. Output from
+// the session is forwarded to the listener via OnData.
+func (s *SSHClient) StartSession(cols, rows int) error {
+	err := s.startSession(cols, rows)
+	if err != nil {
+		log.Infof("SSH: start session failed: %v", err)
+		return rootCause(err)
+	}
+	return nil
+}
+
+// Write sends data to the SSH session stdin.
+func (s *SSHClient) Write(data []byte) error {
+	s.mu.Lock()
+	stdin := s.stdin
+	s.mu.Unlock()
+	if stdin == nil {
+		return errors.New("ssh session not started")
+	}
+	if _, err := stdin.Write(data); err != nil {
+		return fmt.Errorf("write stdin: %w", err)
+	}
+	return nil
+}
+
+// Resize updates the PTY window size.
+func (s *SSHClient) Resize(cols, rows int) error {
+	s.mu.Lock()
+	session := s.session
+	s.mu.Unlock()
+	if session == nil {
+		return errors.New("ssh session not started")
+	}
+	return session.WindowChange(rows, cols)
+}
+
+// Reset makes a closed client usable for another Connect: Close leaves the
+// one-shot guard set, and clearing it lets the same client back a reconnect.
+func (s *SSHClient) Reset() {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.closed = false
+}
+
+// Close terminates the SSH session and underlying connection. Safe to call
+// multiple times.
+func (s *SSHClient) Close() error {
+	s.mu.Lock()
+	s.gen++
+	if s.dialCancel != nil {
+		s.dialCancel()
+		s.dialCancel = nil
+	}
+	sshClient := s.sshClient
+	session := s.session
+	stdin := s.stdin
+	s.sshClient = nil
+	s.session = nil
+	s.stdin = nil
+	notify := !s.closed
+	s.closed = true
+	listener := s.listener
+	s.mu.Unlock()
+
+	if stdin != nil {
+		if err := stdin.Close(); err != nil {
+			log.Debugf("ssh: stdin close: %v", err)
+		}
+	}
+	if session != nil {
+		if err := session.Close(); err != nil && !errors.Is(err, io.EOF) {
+			log.Debugf("ssh: session close: %v", err)
+		}
+	}
+	var firstErr error
+	if sshClient != nil {
+		if err := sshClient.Close(); err != nil {
+			firstErr = err
+		}
+	}
+	if notify && listener != nil {
+		listener.OnClose("closed by client")
+	}
+	return firstErr
+}
+
+func (s *SSHClient) startSession(cols, rows int) error {
+	log.Debugf("SSH: starting session %dx%d", cols, rows)
+	s.mu.Lock()
+	sshClient := s.sshClient
+	gen := s.gen
+	s.mu.Unlock()
+
+	if sshClient == nil {
+		return errors.New("ssh client not connected")
+	}
+
+	pty, err := nbssh.StartPTYSession(sshClient, cols, rows)
+	if err != nil {
+		return err
+	}
+
+	s.mu.Lock()
+	if gen != s.gen {
+		s.mu.Unlock()
+		closeQuiet(pty.Session, "stale session")
+		return errClientClosed
+	}
+	s.session = pty.Session
+	s.stdin = pty.Stdin
+	s.mu.Unlock()
+
+	readerDone := make(chan string, 2)
+	go func() { readerDone <- s.readLoop(pty.Stdout, "stdout") }()
+	go func() { readerDone <- s.readLoop(pty.Stderr, "stderr") }()
+	go func() {
+		reason := <-readerDone
+		if second := <-readerDone; reason == "" {
+			reason = second
+		}
+		s.notifyClose(gen, reason)
+	}()
+	log.Debug("SSH: session started, shell running")
+	return nil
+}
+
+func (s *SSHClient) buildAuth(cfg *profilemanager.Config, cfgPath string, engine *internal.Engine,
+	serverType detection.ServerType, password string) ([]gossh.AuthMethod, gossh.HostKeyCallback, error) {
+
+	switch serverType {
+	case detection.ServerTypeNetBirdJWT:
+		token, err := s.requestJWTToken(cfg, cfgPath)
+		if err != nil {
+			return nil, nil, fmt.Errorf("jwt: %w", err)
+		}
+		auths := []gossh.AuthMethod{gossh.Password(token)}
+		return auths, nbssh.CreateHostKeyCallback(nbssh.PeerKeyLookup(engine.GetPeerSSHKey)), nil
+
+	case detection.ServerTypeNetBirdNoJWT:
+		if cfg.SSHKey == "" {
+			return nil, nil, errors.New("no NetBird SSH key available")
+		}
+		signer, err := gossh.ParsePrivateKey([]byte(cfg.SSHKey))
+		if err != nil {
+			return nil, nil, fmt.Errorf("parse netbird ssh key: %w", err)
+		}
+		auths := []gossh.AuthMethod{gossh.PublicKeys(signer)}
+		return auths, nbssh.CreateHostKeyCallback(nbssh.PeerKeyLookup(engine.GetPeerSSHKey)), nil
+
+	case detection.ServerTypeRegular:
+		var auths []gossh.AuthMethod
+		if cfg.SSHKey != "" {
+			if signer, err := gossh.ParsePrivateKey([]byte(cfg.SSHKey)); err == nil {
+				auths = append(auths, gossh.PublicKeys(signer))
+			} else {
+				log.Debugf("ssh: parse netbird key for regular auth: %v", err)
+			}
+		}
+		if password != "" {
+			pw := password
+			auths = append(auths, gossh.Password(pw))
+			auths = append(auths, gossh.KeyboardInteractive(func(_, _ string, questions []string, _ []bool) ([]string, error) {
+				answers := make([]string, len(questions))
+				for i := range questions {
+					answers[i] = pw
+				}
+				return answers, nil
+			}))
+		}
+		if len(auths) == 0 {
+			// Nothing to offer at all: ask for a password rather than failing,
+			// so the caller can retry once the user supplies one.
+			return nil, nil, errPasswordRequired
+		}
+		callback, err := s.tofuHostKeyCallback()
+		if err != nil {
+			return nil, nil, err
+		}
+		return auths, callback, nil
+
+	default:
+		return nil, nil, fmt.Errorf("unsupported SSH server type: %v", serverType)
+	}
+}
+
+// tofuHostKeyCallback verifies a regular server's host key against the
+// per-profile known-hosts store. An unknown host returns errHostKeyUnknown so
+// Java can show the fingerprint and, once confirmed, retry with the key
+// trusted; a changed key is rejected outright, as OpenSSH does. When the user
+// has confirmed a fingerprint, the callback accepts exactly that key and
+// appends it to the store.
+func (s *SSHClient) tofuHostKeyCallback() (gossh.HostKeyCallback, error) {
+	s.mu.Lock()
+	configDir := s.knownHostsConfigDir
+	profileID := s.knownHostsProfile
+	trusted := s.trustHostKey
+	s.mu.Unlock()
+
+	if configDir == "" || profileID == "" {
+		return nil, errors.New("no known-hosts store configured for regular SSH")
+	}
+
+	store, err := openKnownHostsStore(configDir, profileID)
+	if err != nil {
+		return nil, fmt.Errorf("load known-hosts store: %w", err)
+	}
+
+	return func(hostname string, remote net.Addr, key gossh.PublicKey) error {
+		verdict, err := store.verify(hostname, remote, key)
+		if err != nil {
+			return err
+		}
+		if verdict == hostKeyMatched {
+			return nil
+		}
+		if verdict == hostKeyChanged {
+			return fmt.Errorf("SSH host key changed for %s (possible attack)", hostname)
+		}
+
+		fingerprint := gossh.FingerprintSHA256(key)
+		if trusted == "" {
+			return &errHostKeyUnknown{fingerprint: fingerprint}
+		}
+		if trusted != fingerprint {
+			return fmt.Errorf("SSH host key changed since it was confirmed for %s", hostname)
+		}
+		if err := store.append(hostname, remote, key); err != nil {
+			return fmt.Errorf("persist trusted host key: %w", err)
+		}
+		// The confirmation is spent: now that the key is stored, a later
+		// reconnect must verify against the file, not re-accept this fingerprint.
+		s.mu.Lock()
+		s.trustHostKey = ""
+		s.mu.Unlock()
+		return nil
+	}, nil
+}
+
+func (s *SSHClient) requestJWTToken(cfg *profilemanager.Config, cfgPath string) (string, error) {
+	s.mu.Lock()
+	urlOpener := s.urlOpener
+	s.mu.Unlock()
+	if urlOpener == nil {
+		return "", errors.New("URL opener not configured for JWT auth")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	defer cancel()
+
+	flow, err := auth.NewOAuthFlow(ctx, cfg, false, true, profileLoginHint(cfgPath))
+	if err != nil {
+		return "", fmt.Errorf("create oauth flow: %w", err)
+	}
+
+	// The status callback covers the browser round-trip, which would
+	// otherwise leave the terminal blank.
+	tokenInfo, err := runOAuthFlow(ctx, flow, urlOpener, func() {
+		s.notifyStatus("Waiting for browser authentication...")
+	})
+	if err != nil {
+		return "", err
+	}
+
+	token := tokenInfo.GetTokenToUse()
+	if token == "" {
+		return "", errors.New("empty token returned by IdP")
+	}
+
+	// Tells the client the browser round-trip is over so it can dismiss the
+	// surface it opened, the same way the login and session-extend flows do.
+	// Without it the Custom Tab stays in front of the terminal even though the
+	// token has already been collected.
+	urlOpener.OnLoginSuccess()
+
+	return token, nil
+}
+
+func (s *SSHClient) dialAndHandshake(gen uint64, host string, port int, clientConfig *gossh.ClientConfig) error {
+	addr := net.JoinHostPort(host, strconv.Itoa(port))
+	ctx, cancel := context.WithTimeout(context.Background(), sshDialTimeout)
+	defer cancel()
+
+	s.mu.Lock()
+	if gen != s.gen {
+		s.mu.Unlock()
+		return errClientClosed
+	}
+	s.dialCancel = cancel
+	s.mu.Unlock()
+
+	var dialer net.Dialer
+	conn, err := dialer.DialContext(ctx, "tcp", addr)
+	if err != nil {
+		return fmt.Errorf("dial %s: %w", addr, err)
+	}
+
+	client, err := nbssh.Handshake(ctx, conn, addr, clientConfig)
+	if err != nil {
+		return err
+	}
+
+	s.mu.Lock()
+	if gen != s.gen {
+		s.mu.Unlock()
+		closeQuiet(client, "stale ssh client")
+		return errClientClosed
+	}
+	s.sshClient = client
+	listener := s.listener
+	s.mu.Unlock()
+
+	if listener != nil {
+		listener.OnConnected()
+	}
+	return nil
+}
+
+func (s *SSHClient) readLoop(r io.Reader, name string) string {
+	buf := make([]byte, 4096)
+	for {
+		n, err := r.Read(buf)
+		if n > 0 {
+			s.mu.Lock()
+			listener := s.listener
+			s.mu.Unlock()
+			if listener != nil {
+				chunk := make([]byte, n)
+				copy(chunk, buf[:n])
+				listener.OnData(chunk)
+			}
+		}
+		if err != nil {
+			// EOF is a normal shell exit, so report it without a reason.
+			if errors.Is(err, io.EOF) {
+				return ""
+			}
+			log.Debugf("ssh %s read: %v", name, err)
+			return rootCause(err).Error()
+		}
+	}
+}
+
+// notifyStatus writes a progress line to the terminal through the normal
+// output path, so long steps are visible while nothing else is arriving.
+func (s *SSHClient) notifyStatus(text string) {
+	s.mu.Lock()
+	listener := s.listener
+	s.mu.Unlock()
+	if listener != nil {
+		listener.OnData([]byte("\r\n\x1b[33m" + text + "\x1b[0m\r\n"))
+	}
+}
+
+func (s *SSHClient) notifyClose(gen uint64, reason string) {
+	s.mu.Lock()
+	if gen != s.gen || s.closed {
+		s.mu.Unlock()
+		return
+	}
+	s.closed = true
+	listener := s.listener
+	s.mu.Unlock()
+	if listener != nil {
+		listener.OnClose(reason)
+	}
+}
+
+func closeQuiet(c io.Closer, label string) {
+	if c == nil {
+		return
+	}
+	if err := c.Close(); err != nil && !errors.Is(err, io.EOF) {
+		log.Debugf("ssh: close %s: %v", label, err)
+	}
+}
+
+func detectServerType(host string, port int) detection.ServerType {
+	ctx, cancel := context.WithTimeout(context.Background(), sshDetectionTimeout)
+	defer cancel()
+
+	dialer := &net.Dialer{}
+	serverType, err := detection.DetectSSHServerType(ctx, dialer, host, port)
+	if err != nil {
+		log.Debugf("ssh: server detection failed: %v (assuming regular SSH)", err)
+		return detection.ServerTypeRegular
+	}
+	return serverType
+}
+
+// rootCause returns the innermost error of a %w chain, so the terminal shows
+// "i/o timeout" rather than every layer that added context on the way up.
+func rootCause(err error) error {
+	for {
+		// A joined error has no single root, so keep it as-is.
+		if _, ok := err.(interface{ Unwrap() []error }); ok {
+			return err
+		}
+		next := errors.Unwrap(err)
+		if next == nil {
+			return err
+		}
+		err = next
+	}
+}
+
+// isAuthFailure distinguishes credential rejection from dial, timeout and
+// host-key errors, which retrying with a password would not fix.
+func isAuthFailure(err error) bool {
+	if errors.Is(err, errPasswordRequired) {
+		return true
+	}
+	var partial *gossh.PartialSuccessError
+	if errors.As(err, &partial) {
+		return true
+	}
+	return strings.Contains(err.Error(), "unable to authenticate")
+}
+
+// passwordCouldHelp reports whether prompting for a password again can change
+// the outcome. gossh lists a method under "attempted methods" only when the
+// server offered it, so a supplied password that was never attempted means the
+// server does not accept passwords and the real error should surface instead.
+func passwordCouldHelp(err error, passwordOffered bool) bool {
+	if !passwordOffered {
+		return true
+	}
+	msg := err.Error()
+	return strings.Contains(msg, "password") || strings.Contains(msg, "keyboard-interactive")
+}

client/android/ssh_known_hosts.go

@@ -0,0 +1,168 @@
+//go:build android
+
+package android
+
+import (
+	"bytes"
+	"net"
+	"strconv"
+	"strings"
+	"sync"
+
+	gossh "golang.org/x/crypto/ssh"
+	"golang.org/x/crypto/ssh/knownhosts"
+)
+
+const knownHostsNamespace = "ssh"
+
+const (
+	hostKeyUnknown hostKeyVerdict = iota
+	hostKeyMatched
+	hostKeyChanged
+)
+
+var knownHostsMu sync.Mutex
+
+type hostKeyVerdict uint8
+
+type knownHostsSection struct {
+	KnownHosts []string `json:"knownHosts"`
+}
+
+type knownHostsStore struct {
+	prefs prefsStore
+}
+
+// RemoveKnownHost deletes every known-hosts entry for host:port from the
+// profile's store, so a host trusted for a session that is being deleted does
+// not linger. Java calls this only once no session targets that host, so a
+// shared host stays trusted. A missing entry is not an error: the goal state
+// is "absent".
+func RemoveKnownHost(configDir, profileID, host string, port int) error {
+	store, err := openKnownHostsStore(configDir, profileID)
+	if err != nil {
+		return err
+	}
+	return store.removeHost(host, port)
+}
+
+func openKnownHostsStore(configDir, profileID string) (*knownHostsStore, error) {
+	prefs, err := newProfilePrefs(configDir, profileID)
+	if err != nil {
+		return nil, err
+	}
+	return &knownHostsStore{prefs: prefs}, nil
+}
+
+func (st *knownHostsStore) verify(hostname string, remote net.Addr, key gossh.PublicKey) (hostKeyVerdict, error) {
+	lines, err := st.lines()
+	if err != nil {
+		return hostKeyUnknown, err
+	}
+	targets := knownHostsTargets(hostname, remote)
+
+	verdict := hostKeyUnknown
+	for _, line := range lines {
+		pubKey, ok := knownHostsLineKey(line, targets)
+		if !ok {
+			continue
+		}
+		if pubKey.Type() == key.Type() && bytes.Equal(pubKey.Marshal(), key.Marshal()) {
+			return hostKeyMatched, nil
+		}
+		verdict = hostKeyChanged
+	}
+	return verdict, nil
+}
+
+func (st *knownHostsStore) append(hostname string, remote net.Addr, key gossh.PublicKey) error {
+	line := knownhosts.Line(knownHostsTargets(hostname, remote), key)
+
+	knownHostsMu.Lock()
+	defer knownHostsMu.Unlock()
+
+	lines, err := st.lines()
+	if err != nil {
+		return err
+	}
+	return st.prefs.Put(knownHostsNamespace, knownHostsSection{KnownHosts: append(lines, line)})
+}
+
+func (st *knownHostsStore) removeHost(host string, port int) error {
+	target := knownhosts.Normalize(net.JoinHostPort(host, strconv.Itoa(port)))
+
+	knownHostsMu.Lock()
+	defer knownHostsMu.Unlock()
+
+	lines, err := st.lines()
+	if err != nil {
+		return err
+	}
+	kept := make([]string, 0, len(lines))
+	for _, line := range lines {
+		if knownHostsLineMatches(line, target) {
+			continue
+		}
+		kept = append(kept, line)
+	}
+	if len(kept) == len(lines) {
+		return nil
+	}
+	return st.prefs.Put(knownHostsNamespace, knownHostsSection{KnownHosts: kept})
+}
+
+func (st *knownHostsStore) lines() ([]string, error) {
+	var section knownHostsSection
+	if _, err := st.prefs.Get(knownHostsNamespace, &section); err != nil {
+		return nil, err
+	}
+	return section.KnownHosts, nil
+}
+
+func knownHostsTargets(hostname string, remote net.Addr) []string {
+	targets := []string{knownhosts.Normalize(hostname)}
+	if remote != nil {
+		if normalized := knownhosts.Normalize(remote.String()); normalized != targets[0] {
+			targets = append(targets, normalized)
+		}
+	}
+	return targets
+}
+
+func knownHostsLineKey(line string, targets []string) (gossh.PublicKey, bool) {
+	trimmed := strings.TrimSpace(line)
+	if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+		return nil, false
+	}
+	_, hosts, pubKey, _, _, err := gossh.ParseKnownHosts([]byte(trimmed))
+	if err != nil {
+		return nil, false
+	}
+	for _, host := range hosts {
+		for _, target := range targets {
+			if host == target {
+				return pubKey, true
+			}
+		}
+	}
+	return nil, false
+}
+
+// knownHostsLineMatches reports whether a known-hosts line's address list
+// contains the normalized target. Comment and blank lines never match.
+func knownHostsLineMatches(line, target string) bool {
+	trimmed := strings.TrimSpace(line)
+	if trimmed == "" || strings.HasPrefix(trimmed, "#") {
+		return false
+	}
+	fields := strings.Fields(trimmed)
+	if len(fields) == 0 {
+		return false
+	}
+	for _, addr := range strings.Split(fields[0], ",") {
+		if addr == target {
+			return true
+		}
+	}
+	return false
+}

client/android/ssh_sessions.go

@@ -0,0 +1,104 @@
+//go:build android
+
+package android
+
+const (
+	sshSessionsNamespace = "ssh-sessions"
+	maxStoredSSHSessions = 50
+)
+
+type sshSessionRecord struct {
+	ID   string `json:"id"`
+	Host string `json:"host"`
+	Port int    `json:"port"`
+	User string `json:"user"`
+}
+
+type sshSessionsSection struct {
+	Sessions []sshSessionRecord `json:"sessions"`
+}
+
+// SSHSessionEntry is one stored SSH session, without any credential.
+type SSHSessionEntry struct {
+	ID   string
+	Host string
+	Port int
+	User string
+}
+
+// SSHSessionArray wraps stored SSH sessions for gomobile compatibility.
+type SSHSessionArray struct {
+	items []*SSHSessionEntry
+}
+
+// NewSSHSessionArray creates an empty session array to fill via Add.
+func NewSSHSessionArray() *SSHSessionArray {
+	return &SSHSessionArray{}
+}
+
+// Add appends a session entry, oldest first.
+func (a *SSHSessionArray) Add(id, host string, port int, user string) {
+	a.items = append(a.items, &SSHSessionEntry{ID: id, Host: host, Port: port, User: user})
+}
+
+// Length returns the number of entries.
+func (a *SSHSessionArray) Length() int {
+	return len(a.items)
+}
+
+// Get returns the entry at index i, or nil when out of range.
+func (a *SSHSessionArray) Get(i int) *SSHSessionEntry {
+	if i < 0 || i >= len(a.items) {
+		return nil
+	}
+	return a.items[i]
+}
+
+// SSHSessionStore reads and writes a profile's stored SSH sessions.
+type SSHSessionStore struct {
+	prefs prefsStore
+}
+
+// NewSSHSessionStore opens the session store of the given profile.
+func NewSSHSessionStore(configDir, profileID string) (*SSHSessionStore, error) {
+	prefs, err := newProfilePrefs(configDir, profileID)
+	if err != nil {
+		return nil, err
+	}
+	return &SSHSessionStore{prefs: prefs}, nil
+}
+
+// Load returns the stored sessions, oldest first.
+func (s *SSHSessionStore) Load() (*SSHSessionArray, error) {
+	var section sshSessionsSection
+	if _, err := s.prefs.Get(sshSessionsNamespace, &section); err != nil {
+		return nil, err
+	}
+
+	out := NewSSHSessionArray()
+	for _, record := range section.Sessions {
+		if record.ID == "" || record.Host == "" {
+			continue
+		}
+		out.Add(record.ID, record.Host, record.Port, record.User)
+	}
+	return out, nil
+}
+
+// Save replaces the stored sessions, keeping only the newest entries when the
+// list exceeds the storage cap.
+func (s *SSHSessionStore) Save(sessions *SSHSessionArray) error {
+	var items []*SSHSessionEntry
+	if sessions != nil {
+		items = sessions.items
+	}
+	if len(items) > maxStoredSSHSessions {
+		items = items[len(items)-maxStoredSSHSessions:]
+	}
+
+	records := make([]sshSessionRecord, 0, len(items))
+	for _, item := range items {
+		records = append(records, sshSessionRecord{ID: item.ID, Host: item.Host, Port: item.Port, User: item.User})
+	}
+	return s.prefs.Put(sshSessionsNamespace, sshSessionsSection{Sessions: records})
+}

client/anonymize/anonymize.go

@@ -2,6 +2,7 @@ package anonymize
 
 import (
 	"crypto/rand"
+	"encoding/base64"
 	"fmt"
 	"math/big"
 	"net"
@@ -15,13 +16,88 @@ import (
 
 const anonTLD = ".domain"
 
+// Level selects how much the anonymizer redacts. Levels are ordered: a higher
+// level redacts strictly more. On the wire (protos, flags) levels travel as
+// their string form.
+type Level int
+
+const (
+	// LevelDefault anonymizes public IP addresses, IPv6 ULA, domains, and MAC
+	// addresses. Internal IPv4 ranges (RFC 1918, CGNAT, link-local) are
+	// preserved so support can reason about the real topology.
+	LevelDefault Level = iota
+	// LevelStrict additionally anonymizes internal IP ranges, peer names, and
+	// WireGuard public keys.
+	LevelStrict
+)
+
+// LevelDefaultString and LevelStrictString are the wire forms of the levels,
+// for boundaries that pass levels as strings (flags, protos, mobile bindings).
+const (
+	LevelDefaultString = "default"
+	LevelStrictString  = "strict"
+)
+
+// ParseLevel maps s to a Level. Empty means LevelDefault; anything
+// unrecognized maps to LevelStrict so an unknown request never yields less
+// anonymization than intended.
+func ParseLevel(s string) Level {
+	switch strings.ToLower(s) {
+	case "", LevelDefaultString:
+		return LevelDefault
+	default:
+		return LevelStrict
+	}
+}
+
+// String returns the wire form of the level: "default" or "strict".
+func (l Level) String() string {
+	if l >= LevelStrict {
+		return LevelStrictString
+	}
+	return LevelDefaultString
+}
+
+// protectedDomains are NetBird-operated suffixes that stay recognizable in an
+// anonymized bundle. At LevelStrict the labels in front of them (the peer
+// name) are still replaced, except under netbird.io, which only hosts
+// NetBird infrastructure (api, signal, flow), never peer names.
+var protectedDomains = []string{"netbird.io", "netbird.selfhosted", "netbird.cloud", "netbird.stage"}
+
+const infraDomain = "netbird.io"
+
+var (
+	macColonRegex = regexp.MustCompile(`\b[0-9a-fA-F]{2}(?::[0-9a-fA-F]{2}){5}\b`)
+	macDashRegex  = regexp.MustCompile(`\b[0-9a-fA-F]{2}(?:-[0-9a-fA-F]{2}){5}\b`)
+	wgKeyRegex    = regexp.MustCompile(`\b[A-Za-z0-9+/]{43}=`)
+)
+
 type Anonymizer struct {
 	ipAnonymizer     map[netip.Addr]netip.Addr
 	domainAnonymizer map[string]string
-	currentAnonIPv4  netip.Addr
-	currentAnonIPv6  netip.Addr
-	startAnonIPv4    netip.Addr
-	startAnonIPv6    netip.Addr
+	// domainOrder caches the keys of domainAnonymizer sorted longest-first
+	// for AnonymizeString; it is rebuilt when the map gains entries.
+	domainOrder     []string
+	labelAnonymizer map[string]string
+	labelAnonymized map[string]struct{}
+	labelCounter    uint32
+	macAnonymizer   map[string]string
+	macCounter      uint32
+	wgKeyAnonymizer map[string]string
+	wgKeyAnonymized map[string]struct{}
+	currentAnonIPv4 netip.Addr
+	currentAnonIPv6 netip.Addr
+	startAnonIPv4   netip.Addr
+	startAnonIPv6   netip.Addr
+
+	// LevelStrict also anonymizes internal ranges (RFC 1918, CGNAT,
+	// link-local), replacing them from the dedicated internal pools below so
+	// a reader can still tell an internal address from a public one.
+	level                   Level
+	currentAnonInternalIPv4 netip.Addr
+	currentAnonInternalIPv6 netip.Addr
+	startAnonInternalIPv4   netip.Addr
+	startAnonInternalIPv6   netip.Addr
 
 	domainKeyRegex *regexp.Regexp
 }
@@ -32,25 +108,50 @@ func DefaultAddresses() (netip.Addr, netip.Addr) {
 	return netip.AddrFrom4([4]byte{198, 51, 100, 0}), netip.MustParseAddr("2001:db8:ffff::")
 }
 
+// InternalAddresses returns the pool starts used in strict mode for internal
+// ranges. Both are reserved ranges that cannot collide with real addressing:
+// 198.18.0.0 (RFC 2544 benchmarking), 2001:db8:1:: (RFC 3849 documentation).
+func InternalAddresses() (netip.Addr, netip.Addr) {
+	return netip.AddrFrom4([4]byte{198, 18, 0, 0}), netip.MustParseAddr("2001:db8:1::")
+}
+
 func NewAnonymizer(startIPv4, startIPv6 netip.Addr) *Anonymizer {
+	internalIPv4, internalIPv6 := InternalAddresses()
 	return &Anonymizer{
 		ipAnonymizer:     map[netip.Addr]netip.Addr{},
 		domainAnonymizer: map[string]string{},
+		labelAnonymizer:  map[string]string{},
+		labelAnonymized:  map[string]struct{}{},
+		macAnonymizer:    map[string]string{},
+		wgKeyAnonymizer:  map[string]string{},
+		wgKeyAnonymized:  map[string]struct{}{},
 		currentAnonIPv4:  startIPv4,
 		currentAnonIPv6:  startIPv6,
 		startAnonIPv4:    startIPv4,
 		startAnonIPv6:    startIPv6,
 
+		level:                   LevelDefault,
+		currentAnonInternalIPv4: internalIPv4,
+		currentAnonInternalIPv6: internalIPv6,
+		startAnonInternalIPv4:   internalIPv4,
+		startAnonInternalIPv6:   internalIPv6,
+
 		domainKeyRegex: regexp.MustCompile(`\bdomain=([^\s,:"]+)`),
 	}
 }
 
+// SetLevel selects the anonymization level. The zero value of a new
+// Anonymizer is LevelDefault.
+func (a *Anonymizer) SetLevel(level Level) {
+	a.level = level
+}
+
 func (a *Anonymizer) AnonymizeIP(ip netip.Addr) netip.Addr {
+	// Normalize 4-in-6 addresses so ::ffff:192.168.1.1 classifies and maps
+	// like 192.168.1.1.
+	ip = ip.Unmap()
+
 	if ip.IsLoopback() ||
-		ip.IsLinkLocalUnicast() ||
-		ip.IsLinkLocalMulticast() ||
-		ip.IsInterfaceLocalMulticast() ||
-		(ip.Is4() && ip.IsPrivate()) ||
 		ip.IsUnspecified() ||
 		ip.IsMulticast() ||
 		isWellKnown(ip) ||
@@ -59,18 +160,100 @@ func (a *Anonymizer) AnonymizeIP(ip netip.Addr) netip.Addr {
 		return ip
 	}
 
+	if isInternal(ip) && a.level < LevelStrict {
+		return ip
+	}
+
 	if _, ok := a.ipAnonymizer[ip]; !ok {
-		if ip.Is4() {
-			a.ipAnonymizer[ip] = a.currentAnonIPv4
-			a.currentAnonIPv4 = a.currentAnonIPv4.Next()
-		} else {
-			a.ipAnonymizer[ip] = a.currentAnonIPv6
-			a.currentAnonIPv6 = a.currentAnonIPv6.Next()
-		}
+		a.ipAnonymizer[ip] = a.nextAnonIP(ip)
 	}
 	return a.ipAnonymizer[ip]
 }
 
+func (a *Anonymizer) nextAnonIP(ip netip.Addr) netip.Addr {
+	// At the strict level, internal addresses (including IPv6 ULA, matched
+	// by IsPrivate) come from the internal pools so they remain recognizable
+	// as internal without disclosing the real values.
+	if a.level >= LevelStrict && (isInternal(ip) || ip.IsPrivate()) {
+		if ip.Is4() {
+			anon := a.currentAnonInternalIPv4
+			a.currentAnonInternalIPv4 = a.currentAnonInternalIPv4.Next()
+			return anon
+		}
+		anon := a.currentAnonInternalIPv6
+		a.currentAnonInternalIPv6 = a.currentAnonInternalIPv6.Next()
+		return anon
+	}
+
+	if ip.Is4() {
+		anon := a.currentAnonIPv4
+		a.currentAnonIPv4 = a.currentAnonIPv4.Next()
+		return anon
+	}
+	anon := a.currentAnonIPv6
+	a.currentAnonIPv6 = a.currentAnonIPv6.Next()
+	return anon
+}
+
+// AnonymizeMAC replaces a MAC address with a consistent placeholder from the
+// locally administered range starting at 02:00:00:00:00:01, at every
+// anonymization level. Broadcast, multicast, all-zero, and already assigned
+// placeholder addresses are preserved. The colon and dash spellings of the
+// same address share one placeholder; the output keeps the input's separator.
+func (a *Anonymizer) AnonymizeMAC(mac string) string {
+	hw, err := net.ParseMAC(mac)
+	if err != nil || len(hw) != 6 {
+		return mac
+	}
+
+	if isWellKnownMAC(hw) || a.isAnonymizedMAC(hw) {
+		return mac
+	}
+
+	key := hw.String()
+	anon, ok := a.macAnonymizer[key]
+	if !ok {
+		a.macCounter++
+		anon = fmt.Sprintf("02:00:00:%02x:%02x:%02x", byte(a.macCounter>>16), byte(a.macCounter>>8), byte(a.macCounter))
+		a.macAnonymizer[key] = anon
+	}
+
+	if strings.Contains(mac, "-") {
+		anon = strings.ReplaceAll(anon, ":", "-")
+	}
+	return anon
+}
+
+// isAnonymizedMAC reports whether hw is a placeholder this anonymizer already
+// handed out, so a second pass over anonymized output leaves it unchanged.
+func (a *Anonymizer) isAnonymizedMAC(hw net.HardwareAddr) bool {
+	if hw[0] != 0x02 || hw[1] != 0 || hw[2] != 0 {
+		return false
+	}
+	value := uint32(hw[3])<<16 | uint32(hw[4])<<8 | uint32(hw[5])
+	return value <= a.macCounter
+}
+
+// AnonymizeWGKey replaces a WireGuard public key with a consistent random
+// placeholder of the same shape. Keys are only anonymized at LevelStrict;
+// placeholders already handed out pass through unchanged.
+func (a *Anonymizer) AnonymizeWGKey(key string) string {
+	if a.level < LevelStrict || !looksLikeWGKey(key) {
+		return key
+	}
+	if _, ok := a.wgKeyAnonymized[key]; ok {
+		return key
+	}
+
+	anon, ok := a.wgKeyAnonymizer[key]
+	if !ok {
+		anon = generateAnonymousKey()
+		a.wgKeyAnonymizer[key] = anon
+		a.wgKeyAnonymized[anon] = struct{}{}
+	}
+	return anon
+}
+
 func (a *Anonymizer) AnonymizeUDPAddr(addr net.UDPAddr) net.UDPAddr {
 	// Convert IP to netip.Addr
 	ip, ok := netip.AddrFromSlice(addr.IP)
@@ -89,12 +272,12 @@ func (a *Anonymizer) AnonymizeUDPAddr(addr net.UDPAddr) net.UDPAddr {
 
 // isInAnonymizedRange checks if an IP is within the range of already assigned anonymized IPs
 func (a *Anonymizer) isInAnonymizedRange(ip netip.Addr) bool {
-	if ip.Is4() && ip.Compare(a.startAnonIPv4) >= 0 && ip.Compare(a.currentAnonIPv4) <= 0 {
-		return true
-	} else if !ip.Is4() && ip.Compare(a.startAnonIPv6) >= 0 && ip.Compare(a.currentAnonIPv6) <= 0 {
-		return true
+	if ip.Is4() {
+		return inPoolRange(ip, a.startAnonIPv4, a.currentAnonIPv4) ||
+			inPoolRange(ip, a.startAnonInternalIPv4, a.currentAnonInternalIPv4)
 	}
-	return false
+	return inPoolRange(ip, a.startAnonIPv6, a.currentAnonIPv6) ||
+		inPoolRange(ip, a.startAnonInternalIPv6, a.currentAnonInternalIPv6)
 }
 
 func (a *Anonymizer) AnonymizeIPString(ip string) string {
@@ -118,14 +301,23 @@ func (a *Anonymizer) AnonymizeDomain(domain string) string {
 		baseDomain = domain[:len(domain)-1]
 	}
 
-	if strings.HasSuffix(baseDomain, "netbird.io") ||
-		strings.HasSuffix(baseDomain, "netbird.selfhosted") ||
-		strings.HasSuffix(baseDomain, "netbird.cloud") ||
-		strings.HasSuffix(baseDomain, "netbird.stage") ||
-		strings.HasSuffix(baseDomain, anonTLD) {
+	if strings.HasSuffix(baseDomain, anonTLD) {
 		return domain
 	}
 
+	// A reverse zone names an address prefix, so it follows the address rules,
+	// which also keeps its digit labels intact.
+	if zone, ok := a.anonymizeReverseZone(baseDomain); ok {
+		return withTrailingDot(zone, hasDot)
+	}
+
+	if suffix := protectedSuffix(baseDomain); suffix != "" {
+		if a.level < LevelStrict || baseDomain == suffix || suffix == infraDomain {
+			return domain
+		}
+		return withTrailingDot(a.anonymizePeerName(baseDomain, suffix), hasDot)
+	}
+
 	parts := strings.Split(baseDomain, ".")
 	if len(parts) < 2 {
 		return domain
@@ -141,12 +333,53 @@ func (a *Anonymizer) AnonymizeDomain(domain string) string {
 	}
 
 	result := strings.Replace(baseDomain, baseForLookup, anonymized, 1)
-	if hasDot {
-		result += "."
+	if a.level >= LevelStrict && len(parts) > 2 {
+		prefix := strings.TrimSuffix(baseDomain, "."+baseForLookup)
+		result = a.anonymizeLabels(prefix, "host") + "." + anonymized
+		// The full mapping feeds AnonymizeString so seeded FQDNs are caught
+		// in log lines as a whole, labels included.
+		a.domainAnonymizer[baseDomain] = result
+	}
+	return withTrailingDot(result, hasDot)
+}
+
+// anonymizePeerName replaces the labels in front of a protected suffix with
+// numbered peer placeholders, keeping the suffix, and records the full
+// mapping for string replacement in logs. The numbering keeps a peer
+// recognizable across the whole bundle without disclosing its name.
+func (a *Anonymizer) anonymizePeerName(baseDomain, suffix string) string {
+	prefix := strings.TrimSuffix(baseDomain, "."+suffix)
+	result := a.anonymizeLabels(prefix, "peer") + "." + suffix
+	if result != baseDomain {
+		a.domainAnonymizer[baseDomain] = result
 	}
 	return result
 }
 
+// anonymizeLabels replaces each dot-separated label with a consistent
+// numbered placeholder ("<placeholder>-<n>"). Wildcard labels and
+// placeholders already handed out pass through unchanged.
+func (a *Anonymizer) anonymizeLabels(prefix, placeholder string) string {
+	labels := strings.Split(prefix, ".")
+	for i, label := range labels {
+		if label == "*" {
+			continue
+		}
+		if _, ok := a.labelAnonymized[label]; ok {
+			continue
+		}
+		anon, ok := a.labelAnonymizer[label]
+		if !ok {
+			a.labelCounter++
+			anon = fmt.Sprintf("%s-%d", placeholder, a.labelCounter)
+			a.labelAnonymizer[label] = anon
+			a.labelAnonymized[anon] = struct{}{}
+		}
+		labels[i] = anon
+	}
+	return strings.Join(labels, ".")
+}
+
 func (a *Anonymizer) AnonymizeURI(uri string) string {
 	u, err := url.Parse(uri)
 	if err != nil {
@@ -178,17 +411,75 @@ func (a *Anonymizer) AnonymizeString(str string) string {
 	ipv4Regex := regexp.MustCompile(`\b(?:[0-9]{1,3}\.){3}[0-9]{1,3}\b`)
 	ipv6Regex := regexp.MustCompile(`\b([0-9a-fA-F:]+:+[0-9a-fA-F]{0,4})(?:%[0-9a-zA-Z]+)?(?:\/[0-9]{1,3})?(?::[0-9]{1,5})?\b`)
 
+	// Reverse zones go first and are then held out of the passes below: their
+	// labels are digits, which the address patterns would otherwise consume.
+	str, restoreZones := a.replaceReverseZones(str)
+
 	str = ipv4Regex.ReplaceAllStringFunc(str, a.AnonymizeIPString)
 	str = ipv6Regex.ReplaceAllStringFunc(str, a.AnonymizeIPString)
 
-	for domain, anonDomain := range a.domainAnonymizer {
-		str = strings.ReplaceAll(str, domain, anonDomain)
+	for _, domain := range a.sortedDomains() {
+		str = strings.ReplaceAll(str, domain, a.domainAnonymizer[domain])
 	}
 
 	str = a.AnonymizeSchemeURI(str)
 	str = a.AnonymizeDNSLogLine(str)
 
-	return str
+	// MAC handling runs after the IP passes so preserved IPv6 addresses are
+	// already out of the way; the separator guard skips matches embedded in a
+	// longer colon- or dash-separated sequence (such as an IPv6 tail).
+	str = a.anonymizeMACsInString(str, macColonRegex, ':')
+	str = a.anonymizeMACsInString(str, macDashRegex, '-')
+
+	if a.level >= LevelStrict {
+		str = wgKeyRegex.ReplaceAllStringFunc(str, a.AnonymizeWGKey)
+	}
+
+	return restoreZones(str)
+}
+
+// sortedDomains returns the domain mappings longest-first, so a full-FQDN
+// mapping (strict level) is applied before the base-domain mapping it
+// contains. The order is rebuilt only when domainAnonymizer has grown.
+func (a *Anonymizer) sortedDomains() []string {
+	if len(a.domainOrder) == len(a.domainAnonymizer) {
+		return a.domainOrder
+	}
+
+	a.domainOrder = a.domainOrder[:0]
+	for domain := range a.domainAnonymizer {
+		a.domainOrder = append(a.domainOrder, domain)
+	}
+	slices.SortFunc(a.domainOrder, func(x, y string) int {
+		if d := len(y) - len(x); d != 0 {
+			return d
+		}
+		return strings.Compare(x, y)
+	})
+	return a.domainOrder
+}
+
+// anonymizeMACsInString replaces MAC addresses matched by re, skipping
+// matches that directly adjoin another sep so a six-group run inside a longer
+// separated sequence is left alone.
+func (a *Anonymizer) anonymizeMACsInString(str string, re *regexp.Regexp, sep byte) string {
+	matches := re.FindAllStringIndex(str, -1)
+	if len(matches) == 0 {
+		return str
+	}
+
+	var b strings.Builder
+	last := 0
+	for _, m := range matches {
+		if (m[0] > 0 && str[m[0]-1] == sep) || (m[1] < len(str) && str[m[1]] == sep) {
+			continue
+		}
+		b.WriteString(str[last:m[0]])
+		b.WriteString(a.AnonymizeMAC(str[m[0]:m[1]]))
+		last = m[1]
+	}
+	b.WriteString(str[last:])
+	return b.String()
 }
 
 // AnonymizeSchemeURI finds and anonymizes URIs with ws, wss, rel, rels, stun, stuns, turn, and turns schemes.
@@ -239,10 +530,79 @@ func isWellKnown(addr netip.Addr) bool {
 		"128.0.0.0", "8000::", // 2nd split subnet for default routes
 	}
 
-	if slices.Contains(wellKnown, addr.String()) {
+	return slices.Contains(wellKnown, addr.String())
+}
+
+// isInternal reports whether ip identifies a host only within the local
+// network: IPv4 private (RFC 1918), CGNAT (RFC 6598), and link-local (v4 and
+// v6). These are preserved at the default level so support can reason about
+// the real topology, and replaced from the internal pools at the strict
+// level. IPv6 ULA is deliberately not internal: its random global ID uniquely
+// fingerprints the network, so it is anonymized at every level.
+func isInternal(ip netip.Addr) bool {
+	return (ip.Is4() && ip.IsPrivate()) ||
+		ip.IsLinkLocalUnicast() ||
+		isCGNAT(ip)
+}
+
+func inPoolRange(ip, start, current netip.Addr) bool {
+	return ip.Compare(start) >= 0 && ip.Compare(current) <= 0
+}
+
+// isWellKnownMAC reports whether hw carries no stable host identity: all-zero
+// or a group address (broadcast and multicast).
+func isWellKnownMAC(hw net.HardwareAddr) bool {
+	if hw[0]&1 == 1 {
 		return true
 	}
+	for _, b := range hw {
+		if b != 0 {
+			return false
+		}
+	}
+	return true
+}
 
+// looksLikeWGKey reports whether s has the shape of a WireGuard key:
+// 44 base64 characters decoding to 32 bytes.
+func looksLikeWGKey(s string) bool {
+	if len(s) != 44 || s[43] != '=' {
+		return false
+	}
+	decoded, err := base64.StdEncoding.DecodeString(s)
+	return err == nil && len(decoded) == 32
+}
+
+func generateAnonymousKey() string {
+	buf := make([]byte, 32)
+	if _, err := rand.Read(buf); err != nil {
+		return strings.Repeat("A", 43) + "="
+	}
+	return base64.StdEncoding.EncodeToString(buf)
+}
+
+// protectedSuffix returns the protected NetBird suffix baseDomain ends with,
+// or empty. The match is label-anchored so an unrelated domain that merely
+// ends in the same characters is not preserved.
+func protectedSuffix(baseDomain string) string {
+	for _, d := range protectedDomains {
+		if baseDomain == d || strings.HasSuffix(baseDomain, "."+d) {
+			return d
+		}
+	}
+	return ""
+}
+
+func withTrailingDot(domain string, hasDot bool) string {
+	if hasDot {
+		return domain + "."
+	}
+	return domain
+}
+
+// isCGNAT reports whether addr is in 100.64.0.0/10 (RFC 6598), the range
+// NetBird assigns overlay peer addresses from.
+func isCGNAT(addr netip.Addr) bool {
 	cgnatRangeStart := netip.AddrFrom4([4]byte{100, 64, 0, 0})
 	cgnatRange := netip.PrefixFrom(cgnatRangeStart, 10)
 

client/anonymize/anonymize_test.go

@@ -1,8 +1,11 @@
 package anonymize_test
 
 import (
+	"bytes"
+	"encoding/base64"
 	"net/netip"
 	"regexp"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -44,6 +47,301 @@ func TestAnonymizeIP(t *testing.T) {
 	}
 }
 
+func TestParseLevel(t *testing.T) {
+	tests := []struct {
+		input  string
+		expect anonymize.Level
+	}{
+		{"", anonymize.LevelDefault},
+		{"default", anonymize.LevelDefault},
+		{"DEFAULT", anonymize.LevelDefault},
+		{"strict", anonymize.LevelStrict},
+		{"STRICT", anonymize.LevelStrict},
+		// Unknown values must never yield less anonymization than requested.
+		{"garbage", anonymize.LevelStrict},
+	}
+
+	for _, tc := range tests {
+		t.Run("input="+tc.input, func(t *testing.T) {
+			assert.Equal(t, tc.expect, anonymize.ParseLevel(tc.input), "parsed level should match")
+		})
+	}
+}
+
+func TestAnonymizeIP_DefaultLevelInternalRanges(t *testing.T) {
+	anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+
+	tests := []struct {
+		name   string
+		ip     string
+		expect string
+	}{
+		{"RFC1918 10/8", "10.1.2.3", "10.1.2.3"},
+		{"RFC1918 172.16/12", "172.16.5.5", "172.16.5.5"},
+		{"RFC1918 192.168/16", "192.168.1.1", "192.168.1.1"},
+		{"CGNAT", "100.64.0.5", "100.64.0.5"},
+		{"IPv4 link-local", "169.254.1.1", "169.254.1.1"},
+		{"IPv6 link-local", "fe80::1", "fe80::1"},
+		// ULA is anonymized even at the default level: its random global ID
+		// uniquely fingerprints the network, unlike shared RFC 1918 space.
+		{"IPv6 ULA", "fd12:3456:789a::1", "2001:db8:ffff::"},
+		// 4-in-6 addresses classify like their unmapped IPv4 form.
+		{"4-in-6 RFC1918", "::ffff:192.168.1.1", "192.168.1.1"},
+		{"4-in-6 CGNAT", "::ffff:100.64.0.5", "100.64.0.5"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := anonymizer.AnonymizeIP(netip.MustParseAddr(tc.ip))
+			assert.Equal(t, tc.expect, result.String(), "default level should preserve internal ranges except ULA")
+		})
+	}
+}
+
+func TestAnonymizeIP_StrictLevel(t *testing.T) {
+	anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+	anonymizer.SetLevel(anonymize.LevelStrict)
+
+	// Order matters: internal pool addresses are assigned sequentially.
+	tests := []struct {
+		name   string
+		ip     string
+		expect string
+	}{
+		{"RFC1918 192.168/16", "192.168.1.1", "198.18.0.0"},
+		{"Second RFC1918", "192.168.1.2", "198.18.0.1"},
+		{"Repeated RFC1918", "192.168.1.1", "198.18.0.0"},
+		{"RFC1918 10/8", "10.1.2.3", "198.18.0.2"},
+		{"RFC1918 172.16/12", "172.16.5.5", "198.18.0.3"},
+		{"CGNAT", "100.64.0.5", "198.18.0.4"},
+		{"IPv4 link-local", "169.254.1.1", "198.18.0.5"},
+		{"Public IPv4 uses public pool", "1.2.3.4", "198.51.100.0"},
+		{"IPv6 link-local", "fe80::1", "2001:db8:1::"},
+		{"IPv6 ULA", "fd12:3456:789a::1", "2001:db8:1::1"},
+		{"Public IPv6 uses public pool", "2607:f8b0:4005:805::200e", "2001:db8:ffff::"},
+		{"Loopback IPv4", "127.0.0.1", "127.0.0.1"},
+		{"Loopback IPv6", "::1", "::1"},
+		{"Unspecified", "0.0.0.0", "0.0.0.0"},
+		{"Multicast", "224.0.0.251", "224.0.0.251"},
+		{"Well known resolver", "8.8.8.8", "8.8.8.8"},
+		{"Well known split marker", "128.0.0.0", "128.0.0.0"},
+		{"In internal pool range", "198.18.0.3", "198.18.0.3"},
+		{"In public pool range", "198.51.100.0", "198.51.100.0"},
+		{"4-in-6 repeated RFC1918", "::ffff:192.168.1.1", "198.18.0.0"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := anonymizer.AnonymizeIP(netip.MustParseAddr(tc.ip))
+			assert.Equal(t, tc.expect, result.String(), "strict level should replace internal ranges from the internal pools")
+		})
+	}
+}
+
+func TestAnonymizeString_StrictInternalIPs(t *testing.T) {
+	anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+	anonymizer.SetLevel(anonymize.LevelStrict)
+
+	input := "route 10.20.30.0/24 via 192.168.1.1 dev eth0 src 100.64.0.7"
+	firstPass := anonymizer.AnonymizeString(input)
+	secondPass := anonymizer.AnonymizeString(firstPass)
+
+	assert.NotContains(t, firstPass, "10.20.30.0", "private network address should be anonymized")
+	assert.NotContains(t, firstPass, "192.168.1.1", "private gateway should be anonymized")
+	assert.NotContains(t, firstPass, "100.64.0.7", "CGNAT address should be anonymized")
+	assert.Contains(t, firstPass, "/24", "prefix length should be preserved")
+	assert.Equal(t, firstPass, secondPass, "second pass should not further anonymize the string")
+}
+
+func TestAnonymizeMAC(t *testing.T) {
+	anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+
+	first := anonymizer.AnonymizeMAC("aa:bb:cc:dd:ee:0f")
+	assert.Equal(t, "02:00:00:00:00:01", first, "first MAC should get the first placeholder")
+	assert.Equal(t, first, anonymizer.AnonymizeMAC("aa:bb:cc:dd:ee:0f"), "repeated MAC should map to the same placeholder")
+	assert.Equal(t, first, anonymizer.AnonymizeMAC("AA:BB:CC:DD:EE:0F"), "case should not affect the mapping")
+	assert.Equal(t, "02-00-00-00-00-01", anonymizer.AnonymizeMAC("AA-BB-CC-DD-EE-0F"), "dash form should keep its separator but share the mapping")
+
+	second := anonymizer.AnonymizeMAC("10:22:33:44:55:66")
+	assert.Equal(t, "02:00:00:00:00:02", second, "second distinct MAC should get the next placeholder")
+
+	tests := []struct {
+		name string
+		mac  string
+	}{
+		{"Broadcast", "ff:ff:ff:ff:ff:ff"},
+		{"IPv4 multicast", "01:00:5e:00:00:fb"},
+		{"IPv6 multicast", "33:33:00:00:00:01"},
+		{"All zero", "00:00:00:00:00:00"},
+		{"Assigned placeholder", "02:00:00:00:00:01"},
+		{"Invalid", "not-a-mac"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.Equal(t, tc.mac, anonymizer.AnonymizeMAC(tc.mac), "should be preserved")
+		})
+	}
+}
+
+func TestAnonymizeString_MACAddresses(t *testing.T) {
+	anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+
+	tests := []struct {
+		name   string
+		input  string
+		expect string
+	}{
+		{
+			name:   "nftables ether rule",
+			input:  "ether saddr aa:bb:cc:dd:ee:ff drop",
+			expect: "ether saddr 02:00:00:00:00:01 drop",
+		},
+		{
+			name:   "Windows dash form",
+			input:  "Physical Address : AA-BB-CC-DD-EE-FF",
+			expect: "Physical Address : 02-00-00-00-00-01",
+		},
+		{
+			name:   "IPv6 address tail is not treated as MAC",
+			input:  "addr fe80:0:11:22:33:44:55:66 scope link",
+			expect: "addr fe80:0:11:22:33:44:55:66 scope link",
+		},
+		{
+			name:   "broadcast MAC preserved",
+			input:  "dst ff:ff:ff:ff:ff:ff type ARP",
+			expect: "dst ff:ff:ff:ff:ff:ff type ARP",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			result := anonymizer.AnonymizeString(tc.input)
+			assert.Equal(t, tc.expect, result, "MAC addresses should be anonymized at every level")
+			assert.Equal(t, result, anonymizer.AnonymizeString(result), "second pass should not change the result")
+		})
+	}
+}
+
+func TestAnonymizeWGKey(t *testing.T) {
+	key := base64.StdEncoding.EncodeToString(bytes.Repeat([]byte{0x42}, 32))
+
+	t.Run("default level preserves keys", func(t *testing.T) {
+		anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+		assert.Equal(t, key, anonymizer.AnonymizeWGKey(key), "default level should not touch WireGuard keys")
+	})
+
+	t.Run("strict level replaces keys", func(t *testing.T) {
+		anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+		anonymizer.SetLevel(anonymize.LevelStrict)
+
+		anon := anonymizer.AnonymizeWGKey(key)
+		assert.NotEqual(t, key, anon, "strict level should replace the key")
+		assert.Regexp(t, `^[A-Za-z0-9+/]{43}=$`, anon, "placeholder should keep the WireGuard key shape")
+		assert.Equal(t, anon, anonymizer.AnonymizeWGKey(key), "repeated key should map to the same placeholder")
+		assert.Equal(t, anon, anonymizer.AnonymizeWGKey(anon), "an assigned placeholder should pass through unchanged")
+
+		assert.Equal(t, "not-a-key", anonymizer.AnonymizeWGKey("not-a-key"), "non-key values should be preserved")
+	})
+}
+
+func TestAnonymizeString_WGKeys(t *testing.T) {
+	key := base64.StdEncoding.EncodeToString(bytes.Repeat([]byte{0x42}, 32))
+	input := "peer " + key + " handshake completed"
+
+	t.Run("default level preserves keys", func(t *testing.T) {
+		anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+		assert.Equal(t, input, anonymizer.AnonymizeString(input), "default level should not touch WireGuard keys in strings")
+	})
+
+	t.Run("strict level replaces keys", func(t *testing.T) {
+		anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+		anonymizer.SetLevel(anonymize.LevelStrict)
+
+		firstPass := anonymizer.AnonymizeString(input)
+		assert.NotContains(t, firstPass, key, "the key should not survive strict anonymization")
+		assert.Equal(t, anonymizer.AnonymizeWGKey(key), extractKey(t, firstPass), "string replacement should be consistent with AnonymizeWGKey")
+		assert.Equal(t, firstPass, anonymizer.AnonymizeString(firstPass), "second pass should not change the result")
+	})
+}
+
+func extractKey(t *testing.T, logLine string) string {
+	t.Helper()
+	fields := strings.Fields(logLine)
+	require.Len(t, fields, 4, "log line should keep its structure")
+	return fields[1]
+}
+
+func TestAnonymizeDomain_StrictLevel(t *testing.T) {
+	anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+	anonymizer.SetLevel(anonymize.LevelStrict)
+
+	t.Run("netbird peer name", func(t *testing.T) {
+		result := anonymizer.AnonymizeDomain("my-laptop.netbird.cloud")
+		assert.Regexp(t, `^peer-\d+\.netbird\.cloud$`, result, "peer name should be anonymized, suffix kept")
+		assert.NotContains(t, result, "my-laptop", "the peer name should not survive")
+		assert.Equal(t, result, anonymizer.AnonymizeDomain("my-laptop.netbird.cloud"), "repeated domain should map consistently")
+		assert.Equal(t, result, anonymizer.AnonymizeDomain(result), "an anonymized domain should pass through unchanged")
+	})
+
+	t.Run("bare netbird domain", func(t *testing.T) {
+		assert.Equal(t, "netbird.cloud", anonymizer.AnonymizeDomain("netbird.cloud"), "the bare protected suffix should be preserved")
+	})
+
+	t.Run("netbird infrastructure preserved", func(t *testing.T) {
+		assert.Equal(t, "api.netbird.io", anonymizer.AnonymizeDomain("api.netbird.io"),
+			"netbird.io hosts infrastructure, not peer names, and should stay readable")
+	})
+
+	t.Run("leading labels of other domains", func(t *testing.T) {
+		result := anonymizer.AnonymizeDomain("host1.corp.example.com")
+		assert.Regexp(t, `^host-\d+\.host-\d+\.anon-[a-zA-Z0-9]+\.domain$`, result, "every label should be anonymized")
+		for _, label := range []string{"host1", "corp", "example"} {
+			assert.NotContains(t, result, label, "no original label should survive")
+		}
+		assert.Equal(t, result, anonymizer.AnonymizeDomain("host1.corp.example.com"), "repeated domain should map consistently")
+	})
+
+	t.Run("same label maps consistently across domains", func(t *testing.T) {
+		first := anonymizer.AnonymizeDomain("shared.one.com")
+		second := anonymizer.AnonymizeDomain("shared.two.com")
+		assert.Equal(t, strings.Split(first, ".")[0], strings.Split(second, ".")[0], "the shared host label should get one placeholder")
+	})
+
+	t.Run("wildcard label preserved", func(t *testing.T) {
+		result := anonymizer.AnonymizeDomain("*.example.com")
+		assert.Regexp(t, `^\*\.anon-[a-zA-Z0-9]+\.domain$`, result, "the wildcard label should stay a wildcard")
+	})
+}
+
+func TestAnonymizeDomain_DefaultLevelKeepsPeerNames(t *testing.T) {
+	anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+
+	assert.Equal(t, "my-laptop.netbird.cloud", anonymizer.AnonymizeDomain("my-laptop.netbird.cloud"),
+		"default level should preserve netbird FQDNs including the peer name")
+	assert.Regexp(t, `^sub\.anon-[a-zA-Z0-9]+\.domain$`, anonymizer.AnonymizeDomain("sub.example.com"),
+		"default level should keep subdomain labels")
+}
+
+func TestAnonymizeString_StrictPeerNames(t *testing.T) {
+	anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
+	anonymizer.SetLevel(anonymize.LevelStrict)
+
+	// Seed like the bundle generator does from the status: base first, then
+	// the full FQDN, so replacement must prefer the longer mapping.
+	anonBase := anonymizer.AnonymizeDomain("example.com")
+	anonPeer := anonymizer.AnonymizeDomain("peer1.netbird.cloud")
+	anonHost := anonymizer.AnonymizeDomain("host1.example.com")
+
+	logLine := "connected to peer1.netbird.cloud via host1.example.com endpoint"
+	firstPass := anonymizer.AnonymizeString(logLine)
+	assert.NotContains(t, firstPass, "peer1", "the peer name should not survive in logs")
+	assert.NotContains(t, firstPass, "host1", "the host label should not survive in logs")
+	assert.Contains(t, firstPass, anonPeer, "the seeded peer mapping should be applied")
+	assert.Contains(t, firstPass, anonHost, "the seeded host mapping should be applied, not just the base mapping")
+	assert.NotContains(t, firstPass, "host1."+anonBase, "the base mapping must not preempt the longer FQDN mapping")
+	assert.Equal(t, firstPass, anonymizer.AnonymizeString(firstPass), "second pass should not change the result")
+}
+
 func TestAnonymizeDNSLogLine(t *testing.T) {
 	anonymizer := anonymize.NewAnonymizer(netip.Addr{}, netip.Addr{})
 	tests := []struct {

client/anonymize/reverse_zone.go

@@ -0,0 +1,174 @@
+package anonymize
+
+import (
+	"encoding/hex"
+	"net/netip"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+const (
+	reverseZoneSuffixV4 = ".in-addr.arpa"
+	reverseZoneSuffixV6 = ".ip6.arpa"
+
+	v6Nibbles = 32
+	v4Octets  = 4
+)
+
+// reverseZoneRegexes match a reverse zone or a full reverse name in free text.
+// They are applied before the address passes of AnonymizeString, whose IPv4
+// pattern would otherwise consume the digit labels of a zone and replace parts
+// of it with unrelated addresses.
+var reverseZoneRegexes = []*regexp.Regexp{
+	regexp.MustCompile(`(?:[0-9]{1,3}\.){1,4}in-addr\.arpa\b`),
+	regexp.MustCompile(`(?:[0-9a-fA-F]\.){1,32}ip6\.arpa\b`),
+}
+
+// anonymizeReverseZone maps a reverse zone to the zone of the anonymized form
+// of the prefix it encodes, so it follows the address rules rather than the
+// domain ones: the zone of an address that is preserved is preserved too, and
+// the zone of one that is replaced names the replacement. This keeps a reverse
+// zone recognizable as such, and consistent with the addresses it belongs to
+// elsewhere in the same output. It reports false for anything that is not a
+// reverse zone.
+func (a *Anonymizer) anonymizeReverseZone(domain string) (string, bool) {
+	prefix, labelCount, suffix, ok := parseReverseZone(domain)
+	if !ok {
+		return "", false
+	}
+
+	anonymized := a.AnonymizeIP(prefix)
+	if anonymized == prefix {
+		return domain, true
+	}
+
+	return reverseZoneName(anonymized, labelCount) + suffix, true
+}
+
+// replaceReverseZones anonymizes every reverse zone in str and swaps each one
+// for a placeholder, returning a function that puts the anonymized zones back.
+// The placeholders carry no dots, digits or colons, so no later pass matches
+// them.
+func (a *Anonymizer) replaceReverseZones(str string) (string, func(string) string) {
+	var zones []string
+
+	for _, re := range reverseZoneRegexes {
+		str = re.ReplaceAllStringFunc(str, func(match string) string {
+			zone, ok := a.anonymizeReverseZone(match)
+			if !ok {
+				return match
+			}
+
+			zones = append(zones, zone)
+			return reverseZonePlaceholder(len(zones) - 1)
+		})
+	}
+
+	if len(zones) == 0 {
+		return str, func(s string) string { return s }
+	}
+
+	return str, func(s string) string {
+		for i, zone := range zones {
+			s = strings.ReplaceAll(s, reverseZonePlaceholder(i), zone)
+		}
+		return s
+	}
+}
+
+func reverseZonePlaceholder(index int) string {
+	return "\x00reversezone" + strconv.Itoa(index) + "\x00"
+}
+
+// parseReverseZone turns a reverse zone into the address of the prefix its
+// labels spell backwards, padding the absent low-order part with zeroes, and
+// returns the label count and zone suffix so the name can be rebuilt.
+func parseReverseZone(domain string) (netip.Addr, int, string, bool) {
+	lower := strings.ToLower(domain)
+
+	switch {
+	case strings.HasSuffix(lower, reverseZoneSuffixV4):
+		labels := strings.Split(strings.TrimSuffix(lower, reverseZoneSuffixV4), ".")
+		addr, ok := reverseZoneAddrV4(labels)
+		return addr, len(labels), reverseZoneSuffixV4, ok
+	case strings.HasSuffix(lower, reverseZoneSuffixV6):
+		labels := strings.Split(strings.TrimSuffix(lower, reverseZoneSuffixV6), ".")
+		addr, ok := reverseZoneAddrV6(labels)
+		return addr, len(labels), reverseZoneSuffixV6, ok
+	default:
+		return netip.Addr{}, 0, "", false
+	}
+}
+
+func reverseZoneAddrV4(labels []string) (netip.Addr, bool) {
+	if len(labels) == 0 || len(labels) > v4Octets {
+		return netip.Addr{}, false
+	}
+
+	var octets [v4Octets]byte
+	for i, label := range labels {
+		octet, err := strconv.ParseUint(label, 10, 8)
+		if err != nil {
+			return netip.Addr{}, false
+		}
+		octets[len(labels)-1-i] = byte(octet)
+	}
+
+	return netip.AddrFrom4(octets), true
+}
+
+func reverseZoneAddrV6(labels []string) (netip.Addr, bool) {
+	if len(labels) == 0 || len(labels) > v6Nibbles {
+		return netip.Addr{}, false
+	}
+
+	nibbles := make([]byte, 0, v6Nibbles)
+	for i := len(labels) - 1; i >= 0; i-- {
+		if len(labels[i]) != 1 || !isHexDigit(labels[i][0]) {
+			return netip.Addr{}, false
+		}
+		nibbles = append(nibbles, labels[i][0])
+	}
+	for len(nibbles) < v6Nibbles {
+		nibbles = append(nibbles, '0')
+	}
+
+	var groups []string
+	for i := 0; i < len(nibbles); i += 4 {
+		groups = append(groups, string(nibbles[i:i+4]))
+	}
+
+	addr, err := netip.ParseAddr(strings.Join(groups, ":"))
+	if err != nil {
+		return netip.Addr{}, false
+	}
+
+	return addr, true
+}
+
+// reverseZoneName spells the first labelCount labels of addr backwards, the
+// inverse of parseReverseZone, without the zone suffix.
+func reverseZoneName(addr netip.Addr, labelCount int) string {
+	labels := make([]string, 0, labelCount)
+
+	if addr.Is4() {
+		octets := addr.As4()
+		for i := labelCount - 1; i >= 0; i-- {
+			labels = append(labels, strconv.Itoa(int(octets[i])))
+		}
+		return strings.Join(labels, ".")
+	}
+
+	address := addr.As16()
+	nibbles := hex.EncodeToString(address[:])
+	for i := labelCount - 1; i >= 0; i-- {
+		labels = append(labels, string(nibbles[i]))
+	}
+
+	return strings.Join(labels, ".")
+}
+
+func isHexDigit(c byte) bool {
+	return c >= '0' && c <= '9' || c >= 'a' && c <= 'f' || c >= 'A' && c <= 'F'
+}

client/anonymize/reverse_zone_test.go

@@ -0,0 +1,171 @@
+package anonymize
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func newLeveledAnonymizer(level Level) *Anonymizer {
+	a := NewAnonymizer(DefaultAddresses())
+	a.SetLevel(level)
+	return a
+}
+
+// TestAnonymizeDomainReverseZone covers reverse zones going through the address
+// rules instead of the domain ones, so a zone stays a zone and an address that
+// is preserved keeps the zone that names it.
+func TestAnonymizeDomainReverseZone(t *testing.T) {
+	// 100.64.0.0/10 is the overlay range, which is CGNAT: preserved at the
+	// default level and replaced from the internal pool at the strict one
+	const overlayZone = "64.100.in-addr.arpa"
+
+	t.Run("overlay zone preserved at the default level", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+		assert.Equal(t, overlayZone, a.AnonymizeDomain(overlayZone), "should keep the zone of a preserved address")
+	})
+
+	t.Run("private zone preserved at the default level", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+		assert.Equal(t, "168.192.in-addr.arpa", a.AnonymizeDomain("168.192.in-addr.arpa"), "should keep the zone of a private address")
+	})
+
+	t.Run("overlay zone replaced at the strict level", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelStrict)
+
+		got := a.AnonymizeDomain(overlayZone)
+		require.True(t, strings.HasSuffix(got, reverseZoneSuffixV4), "should stay a reverse zone, got %q", got)
+		assert.NotEqual(t, overlayZone, got, "should replace the encoded prefix")
+		assert.Len(t, strings.Split(strings.TrimSuffix(got, reverseZoneSuffixV4), "."), 2,
+			"should keep the label count, got %q", got)
+	})
+
+	t.Run("public zone replaced at the default level", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+
+		got := a.AnonymizeDomain("113.0.203.in-addr.arpa")
+		require.True(t, strings.HasSuffix(got, reverseZoneSuffixV4), "should stay a reverse zone, got %q", got)
+		assert.NotEqual(t, "113.0.203.in-addr.arpa", got, "should replace a public prefix")
+	})
+
+	t.Run("zone of an address keeps that address mapping", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+
+		anonymizedAddr := a.AnonymizeIPString("203.0.113.7")
+		got := a.AnonymizeDomain("7.113.0.203.in-addr.arpa")
+
+		octets := strings.Split(anonymizedAddr, ".")
+		want := octets[3] + "." + octets[2] + "." + octets[1] + "." + octets[0] + reverseZoneSuffixV4
+		assert.Equal(t, want, got, "should name the same replacement as the address itself")
+	})
+
+	t.Run("ipv6 nibble labels stay single digits", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+
+		zone := "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.0.0.0" + reverseZoneSuffixV6
+		got := a.AnonymizeDomain(zone)
+
+		require.True(t, strings.HasSuffix(got, reverseZoneSuffixV6), "should stay a reverse zone, got %q", got)
+		labels := strings.Split(strings.TrimSuffix(got, reverseZoneSuffixV6), ".")
+		assert.Len(t, labels, 28, "should keep every nibble label, got %q", got)
+		for _, label := range labels {
+			assert.Len(t, label, 1, "nibble label %q should stay a single digit", label)
+		}
+	})
+
+	t.Run("trailing dot is kept", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+		assert.Equal(t, "64.100.in-addr.arpa.", a.AnonymizeDomain("64.100.in-addr.arpa."), "should keep the trailing dot")
+	})
+
+	t.Run("a domain that only looks like a zone is anonymized as a domain", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+
+		got := a.AnonymizeDomain("not-a-zone.in-addr.arpa")
+		assert.NotContains(t, got, "in-addr.arpa", "should fall back to domain anonymization")
+	})
+}
+
+// TestAnonymizeStringReverseZone verifies that a zone inside free text, such as
+// a DNS log line, is not chewed up by the address passes. The IPv4 pattern
+// matches any run of dotted digits, which a reverse zone is made of.
+func TestAnonymizeStringReverseZone(t *testing.T) {
+	t.Run("ipv6 zone survives the address passes", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+
+		zone := "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.0.0.0" + reverseZoneSuffixV6
+		got := a.AnonymizeString("question: domain=" + zone + " type=PTR")
+
+		assert.Contains(t, got, "type=PTR", "should keep the rest of the line")
+		assert.NotContains(t, got, "198.51.100", "should not rewrite nibble labels as an address")
+
+		labels := strings.Split(strings.TrimSuffix(strings.TrimPrefix(got, "question: domain="), reverseZoneSuffixV6+" type=PTR"), ".")
+		assert.Len(t, labels, 28, "should keep every nibble label, got %q", got)
+	})
+
+	t.Run("preserved ipv4 zone is untouched", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+
+		line := "reverse zone 64.100.in-addr.arpa registered"
+		assert.Equal(t, line, a.AnonymizeString(line), "should keep the zone of a preserved address")
+	})
+
+	t.Run("public ipv4 zone is replaced consistently", func(t *testing.T) {
+		a := newLeveledAnonymizer(LevelDefault)
+
+		got := a.AnonymizeString("zone 113.0.203.in-addr.arpa and address 203.0.113.7")
+		assert.NotContains(t, got, "113.0.203.in-addr.arpa", "should replace the zone")
+		assert.NotContains(t, got, "203.0.113.7", "should replace the address")
+		assert.Contains(t, got, reverseZoneSuffixV4, "should keep the zone suffix")
+	})
+}
+
+func TestParseReverseZone(t *testing.T) {
+	tests := []struct {
+		name   string
+		zone   string
+		addr   string
+		labels int
+	}{
+		{name: "v4 two labels", zone: "0.100" + reverseZoneSuffixV4, addr: "100.0.0.0", labels: 2},
+		{name: "v4 three labels", zone: "1.168.192" + reverseZoneSuffixV4, addr: "192.168.1.0", labels: 3},
+		{name: "v4 full address", zone: "7.113.0.203" + reverseZoneSuffixV4, addr: "203.0.113.7", labels: 4},
+		{
+			name:   "v6 prefix",
+			zone:   "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.2.0.0.0" + reverseZoneSuffixV6,
+			addr:   "2::",
+			labels: 28,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			addr, labels, suffix, ok := parseReverseZone(tc.zone)
+			require.True(t, ok, "should decode the reverse zone")
+			assert.Equal(t, tc.addr, addr.String(), "should decode to the encoded prefix")
+			assert.Equal(t, tc.labels, labels, "should count the labels")
+			assert.Equal(t, tc.zone, reverseZoneName(addr, labels)+suffix, "should re-encode to the original zone")
+		})
+	}
+}
+
+func TestParseReverseZoneRejectsNonZones(t *testing.T) {
+	tests := []string{
+		"example.com",
+		"in-addr.arpa",
+		"x.100" + reverseZoneSuffixV4,
+		"256" + reverseZoneSuffixV4,
+		"1.2.3.4.5" + reverseZoneSuffixV4,
+		"ab" + reverseZoneSuffixV6,
+		"g" + reverseZoneSuffixV6,
+	}
+
+	for _, zone := range tests {
+		t.Run(zone, func(t *testing.T) {
+			_, _, _, ok := parseReverseZone(zone)
+			assert.False(t, ok, "should reject %q", zone)
+		})
+	}
+}

client/cmd/daemon_error.go

@@ -0,0 +1,66 @@
+package cmd
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	gstatus "google.golang.org/grpc/status"
+
+	"github.com/netbirdio/netbird/client/internal/ipcauth"
+)
+
+// daemonCallError prepares a daemon error for display. A refusal the daemon
+// raised because the operation needs root/administrator is already guidance
+// written for the user, so it is surfaced on its own instead of buried under the
+// gRPC envelope and the name of the RPC that hit it. Anything else is wrapped
+// with context as usual.
+func daemonCallError(context string, err error) error {
+	if guidance, ok := privilegeGuidance(err); ok {
+		return errors.New(guidance)
+	}
+	return fmt.Errorf("%s: %w", context, err)
+}
+
+// privilegeGuidance renders the daemon's privilege refusal as a summary and the
+// command that performs the operation with the privileges it needs. It reports
+// false for any other error.
+func privilegeGuidance(err error) (string, bool) {
+	info, ok := privilegeErrorInfo(err)
+	if !ok {
+		return "", false
+	}
+
+	summary := info.GetMetadata()[ipcauth.ErrorMetaSummary]
+	command := info.GetMetadata()[ipcauth.ErrorMetaCommand]
+	if summary == "" {
+		// Detail without a summary: fall back to the status message, which
+		// carries the same text.
+		summary = strings.TrimSpace(gstatus.Convert(err).Message())
+	}
+	if command == "" {
+		return summary, true
+	}
+
+	return fmt.Sprintf("%s\n\n    %s\n", summary, command), true
+}
+
+// privilegeErrorInfo returns the daemon's privilege-refusal detail, if the error
+// carries one.
+func privilegeErrorInfo(err error) (*errdetails.ErrorInfo, bool) {
+	if err == nil {
+		return nil, false
+	}
+
+	for _, detail := range gstatus.Convert(err).Details() {
+		info, ok := detail.(*errdetails.ErrorInfo)
+		if !ok {
+			continue
+		}
+		if info.GetReason() == ipcauth.ErrorReasonPrivilegeRequired && info.GetDomain() == ipcauth.ErrorDomain {
+			return info, true
+		}
+	}
+	return nil, false
+}

client/cmd/debug.go

@@ -27,10 +27,11 @@ import (
 const errCloseConnection = "Failed to close connection: %v"
 
 var (
-	logFileCount        uint32
-	systemInfoFlag      bool
-	uploadBundleFlag    bool
-	uploadBundleURLFlag string
+	logFileCount             uint32
+	systemInfoFlag           bool
+	uploadBundleFlag         bool
+	uploadBundleURLFlag      string
+	uploadBundleInsecureFlag bool
 )
 
 var debugCmd = &cobra.Command{
@@ -130,7 +131,7 @@ func debugConfigDump(cmd *cobra.Command, _ []string) error {
 
 	client := proto.NewDaemonServiceClient(conn)
 	resp, err := client.GetConfig(cmd.Context(), &proto.GetConfigRequest{
-		ProfileName: activeProf.Name,
+		ProfileName: string(activeProf.ID),
 		Username:    currUser.Username,
 	})
 	if err != nil {
@@ -155,6 +156,11 @@ func debugConfigDump(cmd *cobra.Command, _ []string) error {
 // request. Returns an error if the RPC fails or if the daemon reports
 // an upload failure reason.
 func debugBundle(cmd *cobra.Command, _ []string) error {
+	anonymizeEnabled, anonymizeLevel, err := effectiveAnonymize()
+	if err != nil {
+		return err
+	}
+
 	conn, err := getClient(cmd)
 	if err != nil {
 		return err
@@ -167,17 +173,19 @@ func debugBundle(cmd *cobra.Command, _ []string) error {
 
 	client := proto.NewDaemonServiceClient(conn)
 	request := &proto.DebugBundleRequest{
-		Anonymize:    anonymizeFlag,
-		SystemInfo:   systemInfoFlag,
-		LogFileCount: logFileCount,
-		CliVersion:   version.NetbirdVersion(),
+		Anonymize:      anonymizeEnabled,
+		AnonymizeLevel: anonymizeLevel.String(),
+		SystemInfo:     systemInfoFlag,
+		LogFileCount:   logFileCount,
+		CliVersion:     version.NetbirdVersion(),
 	}
 	if uploadBundleFlag {
 		request.UploadURL = uploadBundleURLFlag
+		request.UploadInsecure = uploadBundleInsecureFlag
 	}
 	resp, err := client.DebugBundle(cmd.Context(), request)
 	if err != nil {
-		return fmt.Errorf("failed to bundle debug: %v", status.Convert(err).Message())
+		return daemonCallError("bundle debug", err)
 	}
 	cmd.Printf("Local file:\n%s\n", resp.GetPath())
 
@@ -227,6 +235,11 @@ func runForDuration(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("invalid duration format: %v", err)
 	}
 
+	anonymizeEnabled, anonymizeLevel, err := effectiveAnonymize()
+	if err != nil {
+		return err
+	}
+
 	conn, err := getClient(cmd)
 	if err != nil {
 		return err
@@ -366,17 +379,19 @@ func runForDuration(cmd *cobra.Command, args []string) error {
 	cmd.Println("Creating debug bundle...")
 
 	request := &proto.DebugBundleRequest{
-		Anonymize:    anonymizeFlag,
-		SystemInfo:   systemInfoFlag,
-		LogFileCount: logFileCount,
-		CliVersion:   version.NetbirdVersion(),
+		Anonymize:      anonymizeEnabled,
+		AnonymizeLevel: anonymizeLevel.String(),
+		SystemInfo:     systemInfoFlag,
+		LogFileCount:   logFileCount,
+		CliVersion:     version.NetbirdVersion(),
 	}
 	if uploadBundleFlag {
 		request.UploadURL = uploadBundleURLFlag
+		request.UploadInsecure = uploadBundleInsecureFlag
 	}
 	resp, err := client.DebugBundle(cmd.Context(), request)
 	if err != nil {
-		return fmt.Errorf("failed to bundle debug: %v", status.Convert(err).Message())
+		return daemonCallError("bundle debug", err)
 	}
 
 	if needsRestoreUp {
@@ -524,10 +539,12 @@ func init() {
 	debugBundleCmd.Flags().BoolVarP(&systemInfoFlag, "system-info", "S", true, "Adds system information to the debug bundle")
 	debugBundleCmd.Flags().BoolVarP(&uploadBundleFlag, "upload-bundle", "U", false, "Uploads the debug bundle to a server")
 	debugBundleCmd.Flags().StringVar(&uploadBundleURLFlag, "upload-bundle-url", types.DefaultBundleURL, "Service URL to get an URL to upload the debug bundle")
+	debugBundleCmd.Flags().BoolVar(&uploadBundleInsecureFlag, "upload-bundle-insecure", false, "Allow uploading to an http or untrusted-TLS upload server (self-hosted); requires root")
 
 	forCmd.Flags().Uint32VarP(&logFileCount, "log-file-count", "C", 1, "Number of rotated log files to include in debug bundle")
 	forCmd.Flags().BoolVarP(&systemInfoFlag, "system-info", "S", true, "Adds system information to the debug bundle")
 	forCmd.Flags().BoolVarP(&uploadBundleFlag, "upload-bundle", "U", false, "Uploads the debug bundle to a server")
 	forCmd.Flags().StringVar(&uploadBundleURLFlag, "upload-bundle-url", types.DefaultBundleURL, "Service URL to get an URL to upload the debug bundle")
+	forCmd.Flags().BoolVar(&uploadBundleInsecureFlag, "upload-bundle-insecure", false, "Allow uploading to an http or untrusted-TLS upload server (self-hosted); requires root")
 	forCmd.Flags().Bool("capture", false, "Capture packets during the debug duration and include in bundle")
 }

client/cmd/login.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"os"
 	"os/user"
-	"runtime"
 	"strings"
 
 	log "github.com/sirupsen/logrus"
@@ -17,16 +16,26 @@ import (
 	"github.com/netbirdio/netbird/client/internal"
 	"github.com/netbirdio/netbird/client/internal/auth"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
+	nbnet "github.com/netbirdio/netbird/client/net"
 	"github.com/netbirdio/netbird/client/proto"
+	"github.com/netbirdio/netbird/client/server"
 	"github.com/netbirdio/netbird/client/system"
 	"github.com/netbirdio/netbird/util"
 )
 
+// extendSessionFlag drives the `netbird login --extend` flow: refresh the
+// SSO session expiry on the management server without tearing down the
+// tunnel. Mutually exclusive with setup-key login (a setup-key cannot
+// refresh an SSO-tracked peer — see auth.errSetupKeyOnSSOExpiredPeer).
+var extendSessionFlag bool
+
 func init() {
 	loginCmd.PersistentFlags().BoolVar(&noBrowser, noBrowserFlag, false, noBrowserDesc)
 	loginCmd.PersistentFlags().BoolVar(&showQR, showQRFlag, false, showQRDesc)
 	loginCmd.PersistentFlags().StringVar(&profileName, profileNameFlag, "", profileNameDesc)
 	loginCmd.PersistentFlags().StringVarP(&configPath, "config", "c", "", "(DEPRECATED) Netbird config file location")
+	loginCmd.PersistentFlags().BoolVar(&extendSessionFlag, "extend", false,
+		"refresh the SSO session expiry without tearing down the tunnel (requires an active connection)")
 }
 
 var loginCmd = &cobra.Command{
@@ -61,6 +70,16 @@ var loginCmd = &cobra.Command{
 			return err
 		}
 
+		if extendSessionFlag {
+			if providedSetupKey != "" {
+				return fmt.Errorf("--extend cannot be combined with a setup key; setup keys can only enrol new peers")
+			}
+			if err := doExtendSession(ctx, cmd); err != nil {
+				return fmt.Errorf("extend session failed: %v", err)
+			}
+			return nil
+		}
+
 		// workaround to run without service
 		if util.FindFirstLogPath(logFiles) == "" {
 			if err := doForegroundLogin(ctx, cmd, providedSetupKey, activeProf); err != nil {
@@ -101,7 +120,7 @@ func doDaemonLogin(ctx context.Context, cmd *cobra.Command, providedSetupKey str
 	loginRequest := proto.LoginRequest{
 		SetupKey:            providedSetupKey,
 		ManagementUrl:       managementURL,
-		IsUnixDesktopClient: isUnixRunningDesktop(),
+		IsUnixDesktopClient: util.HasGraphicalSession(),
 		Hostname:            hostName,
 		DnsLabels:           dnsLabelsReq,
 		ProfileName:         &handle,
@@ -152,6 +171,66 @@ func doDaemonLogin(ctx context.Context, cmd *cobra.Command, providedSetupKey str
 	return nil
 }
 
+// doExtendSession drives the daemon's RequestExtendAuthSession /
+// WaitExtendAuthSession pair. The user is sent through a regular SSO flow
+// (browser + verification URL) and the resulting JWT is forwarded to the
+// management server's ExtendAuthSession RPC. The tunnel stays up
+// throughout — no Down/Up, no network-map resync.
+func doExtendSession(ctx context.Context, cmd *cobra.Command) error {
+	conn, err := DialClientGRPCServer(ctx, daemonAddr)
+	if err != nil {
+		//nolint
+		return fmt.Errorf("failed to connect to daemon error: %v\n"+
+			"If the daemon is not running please run: "+
+			"\nnetbird service install \nnetbird service start\n", err)
+	}
+	defer conn.Close()
+
+	client := proto.NewDaemonServiceClient(conn)
+
+	// the CLI runs in the user's session, the daemon does not: tell it what we can see
+	req := &proto.RequestExtendAuthSessionRequest{HasGraphicalSession: util.HasGraphicalSession()}
+	// Pre-fill the IdP login hint from the active profile so the user
+	// doesn't have to retype their email. Best-effort: we still proceed
+	// without a hint if the lookup fails.
+	pm := profilemanager.NewProfileManager()
+	if active, perr := pm.GetActiveProfile(); perr == nil {
+		if profState, sperr := pm.GetProfileState(active.ID); sperr == nil && profState.Email != "" {
+			req.Hint = &profState.Email
+		}
+	}
+
+	startResp, err := client.RequestExtendAuthSession(ctx, req)
+	if err != nil {
+		return fmt.Errorf("start extend session: %v", err)
+	}
+
+	uri := startResp.GetVerificationURIComplete()
+	if uri == "" {
+		uri = startResp.GetVerificationURI()
+	}
+	openURL(cmd, uri, startResp.GetUserCode(), noBrowser, showQR)
+
+	waitResp, err := client.WaitExtendAuthSession(ctx, &proto.WaitExtendAuthSessionRequest{
+		DeviceCode: startResp.GetDeviceCode(),
+		UserCode:   startResp.GetUserCode(),
+	})
+	if err != nil {
+		return fmt.Errorf("wait for extend session: %v", err)
+	}
+
+	if ts := waitResp.GetSessionExpiresAt(); ts.IsValid() && !ts.AsTime().IsZero() {
+		deadline := ts.AsTime().Local()
+		cmd.Printf("Session extended. New expiry: %s\n", deadline.Format("2006-01-02 15:04:05 MST"))
+	} else {
+		// Management reported the peer is not eligible (e.g. login
+		// expiration disabled on the account). Surface that fact
+		// instead of pretending the call succeeded.
+		cmd.Println("Session extension call completed, but the management server did not return a new deadline (peer may not be SSO-tracked or login expiration is disabled).")
+	}
+	return nil
+}
+
 func getActiveProfile(ctx context.Context, pm *profilemanager.ProfileManager, profileName string, username string) (*profilemanager.Profile, error) {
 	// switch profile if provided
 
@@ -254,6 +333,14 @@ func doForegroundLogin(ctx context.Context, cmd *cobra.Command, setupKey string,
 		return fmt.Errorf("read config file %s: %v", configFilePath, err)
 	}
 
+	// Mirror runInForegroundMode: recover residual state (DNS, firewall,
+	// ssh config, legacy routing) from a previous unclean shutdown and
+	// enable advanced routing before dialing management.
+	if err := server.RestoreResidualState(ctx, profilemanager.NewServiceManager(configFilePath).GetStatePath()); err != nil {
+		log.Warnf("failed to restore residual state: %v", err)
+	}
+	nbnet.Init()
+
 	err = foregroundLogin(ctx, cmd, config, setupKey, activeProf.ID)
 	if err != nil {
 		return fmt.Errorf("foreground login failed: %v", err)
@@ -321,7 +408,7 @@ func foregroundGetTokenInfo(ctx context.Context, cmd *cobra.Command, config *pro
 		hint = profileState.Email
 	}
 
-	oAuthFlow, err := auth.NewOAuthFlow(ctx, config, isUnixRunningDesktop(), false, hint)
+	oAuthFlow, err := auth.NewOAuthFlow(ctx, config, util.HasGraphicalSession(), false, hint)
 	if err != nil {
 		return nil, err
 	}
@@ -371,14 +458,6 @@ func openURL(cmd *cobra.Command, verificationURIComplete, userCode string, noBro
 	}
 }
 
-// isUnixRunningDesktop checks if a Linux OS is running desktop environment
-func isUnixRunningDesktop() bool {
-	if runtime.GOOS != "linux" && runtime.GOOS != "freebsd" {
-		return false
-	}
-	return os.Getenv("DESKTOP_SESSION") != "" || os.Getenv("XDG_CURRENT_DESKTOP") != ""
-}
-
 func setEnvAndFlags(cmd *cobra.Command) error {
 	SetFlagsFromEnvVars(rootCmd)
 

client/cmd/logout.go

@@ -46,7 +46,7 @@ var logoutCmd = &cobra.Command{
 		}
 
 		if _, err := daemonClient.Logout(ctx, req); err != nil {
-			return fmt.Errorf("deregister: %v", err)
+			return daemonCallError("deregister", err)
 		}
 
 		cmd.Println("Deregistered successfully")

client/cmd/root.go

@@ -20,8 +20,8 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 	"google.golang.org/grpc"
-	"google.golang.org/grpc/credentials/insecure"
 
+	"github.com/netbirdio/netbird/client/anonymize"
 	daddr "github.com/netbirdio/netbird/client/internal/daemonaddr"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
 )
@@ -70,13 +70,16 @@ var (
 	autoConnectDisabled     bool
 	extraIFaceBlackList     []string
 	anonymizeFlag           bool
+	anonymizeLevelFlag      string
 	dnsRouteInterval        time.Duration
-	lazyConnEnabled         bool
-	mtu                     uint16
-	profilesDisabled        bool
-	updateSettingsDisabled  bool
-	captureEnabled          bool
-	networksDisabled        bool
+	// lazyConnEnabled is the parse target for the deprecated --enable-lazy-connection
+	// flag. The flag is inert; the value is no longer read (use NB_LAZY_CONN instead).
+	lazyConnEnabled        bool
+	mtu                    uint16
+	profilesDisabled       bool
+	updateSettingsDisabled bool
+	captureEnabled         bool
+	networksDisabled       bool
 
 	rootCmd = &cobra.Command{
 		Use:          "netbird",
@@ -89,6 +92,7 @@ var (
 			// Don't resolve for service commands — they create the socket, not connect to it.
 			if !isServiceCmd(cmd) {
 				daemonAddr = daddr.ResolveUnixDaemonAddr(daemonAddr)
+				daemonAddr = daddr.ResolveDaemonAddr(daemonAddr)
 			}
 			return nil
 		},
@@ -141,10 +145,10 @@ func init() {
 
 	defaultDaemonAddr := "unix:///var/run/netbird.sock"
 	if runtime.GOOS == "windows" {
-		defaultDaemonAddr = "tcp://127.0.0.1:41731"
+		defaultDaemonAddr = daddr.WindowsPipeAddr
 	}
 
-	rootCmd.PersistentFlags().StringVar(&daemonAddr, "daemon-addr", defaultDaemonAddr, "Daemon service address to serve CLI requests [unix|tcp]://[path|host:port]")
+	rootCmd.PersistentFlags().StringVar(&daemonAddr, "daemon-addr", defaultDaemonAddr, "Daemon service address to serve CLI requests [unix|tcp|npipe]://[path|host:port|name]")
 	rootCmd.PersistentFlags().StringVarP(&managementURL, "management-url", "m", "", fmt.Sprintf("Management Service URL [http|https]://[host]:[port] (default \"%s\")", profilemanager.DefaultManagementURL))
 	rootCmd.PersistentFlags().StringVar(&adminURL, "admin-url", "", fmt.Sprintf("Admin Panel URL [http|https]://[host]:[port] (default \"%s\")", profilemanager.DefaultAdminURL))
 	rootCmd.PersistentFlags().StringVarP(&logLevel, "log-level", "l", "info", "sets NetBird log level")
@@ -154,7 +158,8 @@ func init() {
 	rootCmd.MarkFlagsMutuallyExclusive("setup-key", "setup-key-file")
 	rootCmd.PersistentFlags().StringVar(&preSharedKey, preSharedKeyFlag, "", "Sets WireGuard PreSharedKey property. If set, then only peers that have the same key can communicate.")
 	rootCmd.PersistentFlags().StringVarP(&hostName, "hostname", "n", "", "Sets a custom hostname for the device")
-	rootCmd.PersistentFlags().BoolVarP(&anonymizeFlag, "anonymize", "A", false, "anonymize IP addresses and non-netbird.io domains in logs and status output")
+	rootCmd.PersistentFlags().BoolVarP(&anonymizeFlag, "anonymize", "A", false, "anonymize public IP addresses, MAC addresses, and non-netbird.io domains in logs and status output; private, CGNAT, and link-local IP ranges are kept (see --anonymize-level strict)")
+	rootCmd.PersistentFlags().StringVar(&anonymizeLevelFlag, "anonymize-level", "", "anonymization level: \"default\" or \"strict\"; strict also anonymizes private, CGNAT, and link-local IP ranges, peer names, and WireGuard public keys. Setting this flag implies --anonymize")
 	rootCmd.PersistentFlags().StringVarP(&configPath, "config", "c", profilemanager.DefaultConfigPath, "Overrides the default profile file location")
 
 	rootCmd.AddCommand(upCmd)
@@ -210,7 +215,8 @@ func init() {
 	upCmd.PersistentFlags().BoolVar(&rosenpassEnabled, enableRosenpassFlag, false, "[Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.")
 	upCmd.PersistentFlags().BoolVar(&rosenpassPermissive, rosenpassPermissiveFlag, false, "[Experimental] Enable Rosenpass in permissive mode to allow this peer to accept WireGuard connections without requiring Rosenpass functionality from peers that do not have Rosenpass enabled.")
 	upCmd.PersistentFlags().BoolVar(&autoConnectDisabled, disableAutoConnectFlag, false, "Disables auto-connect feature. If enabled, then the client won't connect automatically when the service starts.")
-	upCmd.PersistentFlags().BoolVar(&lazyConnEnabled, enableLazyConnectionFlag, false, "[Experimental] Enable the lazy connection feature. If enabled, the client will establish connections on-demand. Note: this setting may be overridden by management configuration.")
+	upCmd.PersistentFlags().BoolVar(&lazyConnEnabled, enableLazyConnectionFlag, false, "Deprecated: no longer used. Lazy connections are controlled by the server and the NB_LAZY_CONN environment variable.")
+	_ = upCmd.PersistentFlags().MarkDeprecated(enableLazyConnectionFlag, "no longer used; lazy connections are controlled by the server and the NB_LAZY_CONN environment variable")
 
 }
 
@@ -266,12 +272,10 @@ func DialClientGRPCServer(ctx context.Context, addr string) (*grpc.ClientConn, e
 	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
 	defer cancel()
 
-	return grpc.DialContext(
-		ctx,
-		strings.TrimPrefix(addr, "tcp://"),
-		grpc.WithTransportCredentials(insecure.NewCredentials()),
-		grpc.WithBlock(),
-	)
+	target, opts := daddr.DialTarget(addr)
+	opts = append(opts, grpc.WithBlock())
+
+	return grpc.DialContext(ctx, target, opts...)
 }
 
 // WithBackOff execute function in backoff cycle.
@@ -292,6 +296,19 @@ var CLIBackOffSettings = &backoff.ExponentialBackOff{
 	Clock:               backoff.SystemClock,
 }
 
+// effectiveAnonymize resolves the --anonymize and --anonymize-level flags:
+// setting a level implies anonymization, and an invalid level is rejected.
+func effectiveAnonymize() (bool, anonymize.Level, error) {
+	if anonymizeLevelFlag == "" {
+		return anonymizeFlag, anonymize.LevelDefault, nil
+	}
+	level := anonymize.ParseLevel(anonymizeLevelFlag)
+	if !strings.EqualFold(anonymizeLevelFlag, level.String()) {
+		return false, anonymize.LevelDefault, fmt.Errorf("invalid anonymize level %q: use %q or %q", anonymizeLevelFlag, anonymize.LevelDefault.String(), anonymize.LevelStrict.String())
+	}
+	return true, level, nil
+}
+
 func getSetupKey() (string, error) {
 	if setupKeyPath != "" && setupKey == "" {
 		return getSetupKeyFromFile(setupKeyPath)

client/cmd/service.go

@@ -5,6 +5,7 @@ package cmd
 import (
 	"context"
 	"fmt"
+	"net/http"
 	"runtime"
 	"strings"
 	"sync"
@@ -22,15 +23,26 @@ var serviceCmd = &cobra.Command{
 	Short: "Manage the NetBird daemon service",
 }
 
+const defaultJSONSocket = "unix:///var/run/netbird-http.sock"
+
 var (
-	serviceName    string
-	serviceEnvVars []string
+	serviceName      string
+	serviceEnvVars   []string
+	jsonSocket       string
+	enableJSONSocket bool
 )
 
 type program struct {
-	ctx              context.Context
-	cancel           context.CancelFunc
-	serv             *grpc.Server
+	ctx      context.Context
+	cancel   context.CancelFunc
+	serv     *grpc.Server
+	jsonServ *http.Server
+	// jsonClient is the gateway's own connection to the daemon. It is held so
+	// shutting the gateway down also closes it: nothing else references it once
+	// the handlers are registered, so its transport goroutines would otherwise
+	// outlive the server.
+	jsonClient       *grpc.ClientConn
+	jsonServMu       sync.Mutex
 	serverInstance   *server.Server
 	serverInstanceMu sync.Mutex
 }
@@ -46,6 +58,8 @@ func init() {
 	serviceCmd.PersistentFlags().BoolVar(&updateSettingsDisabled, "disable-update-settings", false, "Disables update settings feature. If enabled, the client will not be able to change or edit any settings. To persist this setting, use: netbird service install --disable-update-settings")
 	serviceCmd.PersistentFlags().BoolVar(&captureEnabled, "enable-capture", false, "Enables packet capture via 'netbird debug capture'. To persist, use: netbird service install --enable-capture")
 	serviceCmd.PersistentFlags().BoolVar(&networksDisabled, "disable-networks", false, "Disables network selection. If enabled, the client will not allow listing, selecting, or deselecting networks. To persist, use: netbird service install --disable-networks")
+	serviceCmd.PersistentFlags().BoolVar(&enableJSONSocket, "enable-json-socket", false, "Enables the HTTP/JSON API socket served by grpc-gateway. To persist, use: netbird service install --enable-json-socket")
+	serviceCmd.PersistentFlags().StringVar(&jsonSocket, "json-socket", defaultJSONSocket, "HTTP/JSON API socket address [unix|tcp]://[path|host:port]. Requires --enable-json-socket to serve. To persist, use: netbird service install --enable-json-socket --json-socket")
 
 	rootCmd.PersistentFlags().StringVarP(&serviceName, "service", "s", defaultServiceName, "Netbird system service name")
 	serviceEnvDesc := `Sets extra environment variables for the service. ` +

client/cmd/service_controller.go

@@ -5,9 +5,7 @@ package cmd
 import (
 	"context"
 	"fmt"
-	"net"
-	"os"
-	"strings"
+	"runtime"
 	"time"
 
 	"github.com/kardianos/service"
@@ -16,69 +14,157 @@ import (
 	"github.com/spf13/cobra"
 	"google.golang.org/grpc"
 
+	"github.com/netbirdio/netbird/client/internal/daemonaddr"
+	"github.com/netbirdio/netbird/client/internal/ipcauth"
 	"github.com/netbirdio/netbird/client/proto"
 	"github.com/netbirdio/netbird/client/server"
 	"github.com/netbirdio/netbird/client/system"
 	"github.com/netbirdio/netbird/util"
 )
 
+func validateJSONSocketFlags() error {
+	if serviceCmd.PersistentFlags().Changed("json-socket") && !enableJSONSocket {
+		return fmt.Errorf("--json-socket requires --enable-json-socket to configure the daemon JSON gateway")
+	}
+	return nil
+}
+
+// daemonServerOptions installs the transport credentials that expose each
+// caller's kernel-authenticated identity to the handlers, which is what lets
+// the daemon require root/administrator for privileged operations.
+//
+// The handshake exchanges no bytes, so older CLI and UI binaries still
+// interoperate. Callers on a TCP socket carry no identity at all: the daemon
+// keeps serving them, and the privileged operations deny them, so a warning is
+// logged to make the loss of functionality visible.
+func daemonServerOptions(network string) []grpc.ServerOption {
+	if network == "tcp" {
+		log.Warnf("daemon is listening on TCP (%s): callers carry no verifiable identity over TCP, "+
+			"so privileged operations (SSH root login, SSH auth, enabling the SSH server, management URL changes, "+
+			"deregistration) will be denied. Use a unix socket, or npipe:// on Windows", daemonAddr)
+		return nil
+	}
+
+	creds := ipcauth.NewTransportCredentials() //nolint:staticcheck
+	if creds == nil {                          //nolint:staticcheck // nil only on platforms without a peer-identity primitive
+		log.Warnf("daemon IPC has no peer-identity primitive on %s: privileged operations will be denied", runtime.GOOS)
+		return nil
+	}
+
+	return []grpc.ServerOption{grpc.Creds(creds)}
+}
+
 func (p *program) Start(svc service.Service) error {
 	// Start should not block. Do the actual work async.
 	log.Info("starting NetBird service") //nolint
 
+	if err := validateJSONSocketFlags(); err != nil {
+		return err
+	}
+
 	// Collect static system and platform information
 	system.UpdateStaticInfoAsync()
 
-	// in any case, even if configuration does not exists we run daemon to serve CLI gRPC API.
-	p.serv = grpc.NewServer()
-
-	split := strings.Split(daemonAddr, "://")
-	switch split[0] {
-	case "unix":
-		// cleanup failed close
-		stat, err := os.Stat(split[1])
-		if err == nil && !stat.IsDir() {
-			if err := os.Remove(split[1]); err != nil {
-				log.Debugf("remove socket file: %v", err)
-			}
-		}
-	case "tcp":
-	default:
-		return fmt.Errorf("unsupported daemon address protocol: %v", split[0])
+	// A daemon installed before named-pipe support has the loopback TCP address
+	// persisted. Move it to the named pipe so an upgraded daemon can identify
+	// its callers instead of silently serving an unauthenticated socket.
+	if migrated, ok := daemonaddr.MigrateLegacy(daemonAddr); ok {
+		log.Infof("daemon address %q predates named-pipe support, listening on %q so callers can be identified", daemonAddr, migrated)
+		daemonAddr = migrated
 	}
 
-	listen, err := net.Listen(split[0], split[1])
+	network, _, err := parseListenAddress(daemonAddr)
 	if err != nil {
-		return fmt.Errorf("listen daemon interface: %w", err)
+		return fmt.Errorf("parse daemon address: %w", err)
 	}
+
+	// in any case, even if configuration does not exists we run daemon to serve CLI gRPC API.
+	p.serv = grpc.NewServer(daemonServerOptions(network)...)
+
+	daemonListener, jsonListener, err := listenDaemonSockets()
+	if err != nil {
+		return err
+	}
+
 	go func() {
-		defer listen.Close()
-
-		if split[0] == "unix" {
-			if err := os.Chmod(split[1], 0666); err != nil {
-				log.Errorf("failed setting daemon permissions: %v", split[1])
-				return
-			}
-		}
-
-		serverInstance := server.New(p.ctx, util.FindFirstLogPath(logFiles), configPath, profilesDisabled, updateSettingsDisabled, captureEnabled, networksDisabled)
-		if err := serverInstance.Start(); err != nil {
-			log.Fatalf("failed to start daemon: %v", err)
-		}
-		proto.RegisterDaemonServiceServer(p.serv, serverInstance)
-
-		p.serverInstanceMu.Lock()
-		p.serverInstance = serverInstance
-		p.serverInstanceMu.Unlock()
-
-		log.Printf("started daemon server: %v", split[1])
-		if err := p.serv.Serve(listen); err != nil {
-			log.Errorf("failed to serve daemon requests: %v", err)
+		// Fatal here rather than inside serve, so serve's deferred listener
+		// closes run before the process exits.
+		if err := p.serve(daemonListener, jsonListener); err != nil {
+			log.Fatalf("failed to %v", err)
 		}
 	}()
 	return nil
 }
 
+// listenDaemonSockets opens the daemon control socket and, when it is enabled, the
+// JSON gateway socket. The control socket is closed again if the second one fails,
+// so a failed start leaves nothing listening. The returned JSON listener is nil
+// when the socket is disabled.
+func listenDaemonSockets() (*socketListener, *socketListener, error) {
+	daemonListener, err := listenOnAddress(daemonAddr)
+	if err != nil {
+		return nil, nil, fmt.Errorf("listen daemon interface: %w", err)
+	}
+
+	if !enableJSONSocket {
+		removeStaleUnixSocketForAddress(jsonSocket)
+		return daemonListener, nil, nil
+	}
+
+	jsonListener, err := listenOnAddress(jsonSocket)
+	if err != nil {
+		if cerr := daemonListener.Close(); cerr != nil {
+			log.Debugf("close daemon listener: %v", cerr)
+		}
+		return nil, nil, fmt.Errorf("listen daemon JSON interface: %w", err)
+	}
+
+	return daemonListener, jsonListener, nil
+}
+
+// serve brings up the daemon server on an already-open control socket and blocks
+// until it stops. jsonListener is nil when the JSON socket is disabled. A returned
+// error means the daemon cannot run at all and the caller is expected to exit; the
+// failures it recovers from on its own are logged here.
+func (p *program) serve(daemonListener, jsonListener *socketListener) error {
+	defer daemonListener.Close()
+	if jsonListener != nil {
+		defer jsonListener.Close()
+	}
+
+	// chmodUnixSocket is a no-op for a nil listener and for a non-unix one.
+	if err := daemonListener.chmodUnixSocket("daemon"); err != nil {
+		log.Error(err)
+		return nil
+	}
+	if err := jsonListener.chmodUnixSocket("daemon JSON"); err != nil {
+		log.Error(err)
+		return nil
+	}
+
+	serverInstance := server.New(p.ctx, util.FindFirstLogPath(logFiles), configPath, profilesDisabled, updateSettingsDisabled, captureEnabled, networksDisabled)
+	if err := serverInstance.Start(); err != nil {
+		return fmt.Errorf("start daemon: %w", err)
+	}
+	proto.RegisterDaemonServiceServer(p.serv, serverInstance)
+
+	p.serverInstanceMu.Lock()
+	p.serverInstance = serverInstance
+	p.serverInstanceMu.Unlock()
+
+	if jsonListener == nil {
+		log.Debug("daemon JSON socket disabled")
+	} else if err := p.startJSONGateway(jsonListener, daemonAddr); err != nil {
+		return fmt.Errorf("start daemon JSON server: %w", err)
+	}
+
+	log.Printf("started daemon server: %v", daemonListener.address)
+	if err := p.serv.Serve(daemonListener.Listener); err != nil {
+		log.Errorf("failed to serve daemon requests: %v", err)
+	}
+	return nil
+}
+
 func (p *program) Stop(srv service.Service) error {
 	p.serverInstanceMu.Lock()
 	if p.serverInstance != nil {
@@ -92,6 +178,25 @@ func (p *program) Stop(srv service.Service) error {
 
 	p.cancel()
 
+	p.jsonServMu.Lock()
+	jsonServ, jsonClient := p.jsonServ, p.jsonClient
+	p.jsonServMu.Unlock()
+	if jsonClient != nil {
+		if err := jsonClient.Close(); err != nil {
+			log.Debugf("close daemon JSON gateway client: %v", err)
+		}
+	}
+	if jsonServ != nil {
+		shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 2*time.Second)
+		if err := jsonServ.Shutdown(shutdownCtx); err != nil {
+			log.Errorf("failed to stop daemon JSON server gracefully: %v", err)
+			if err := jsonServ.Close(); err != nil {
+				log.Errorf("failed to close daemon JSON server: %v", err)
+			}
+		}
+		shutdownCancel()
+	}
+
 	if p.serv != nil {
 		p.serv.Stop()
 	}
@@ -148,6 +253,9 @@ var runCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
+		if err := validateJSONSocketFlags(); err != nil {
+			return err
+		}
 
 		return s.Run()
 	},
@@ -162,6 +270,9 @@ var startCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
+		if err := validateJSONSocketFlags(); err != nil {
+			return err
+		}
 
 		if err := s.Start(); err != nil {
 			return fmt.Errorf("start service: %w", err)
@@ -198,6 +309,9 @@ var restartCmd = &cobra.Command{
 		if err != nil {
 			return err
 		}
+		if err := validateJSONSocketFlags(); err != nil {
+			return err
+		}
 
 		if err := s.Restart(); err != nil {
 			return fmt.Errorf("restart service: %w", err)

client/cmd/service_installer.go

@@ -67,6 +67,10 @@ func buildServiceArguments() []string {
 		args = append(args, "--disable-networks")
 	}
 
+	if enableJSONSocket {
+		args = append(args, "--enable-json-socket", "--json-socket", jsonSocket)
+	}
+
 	return args
 }
 
@@ -106,6 +110,10 @@ func configurePlatformSpecificSettings(svcConfig *service.Config) error {
 
 // Create fully configured service config for install/reconfigure
 func createServiceConfigForInstall() (*service.Config, error) {
+	if err := validateJSONSocketFlags(); err != nil {
+		return nil, err
+	}
+
 	svcConfig, err := newSVCConfig()
 	if err != nil {
 		return nil, fmt.Errorf("create service config: %w", err)

client/cmd/service_json_gateway.go

@@ -0,0 +1,150 @@
+//go:build !ios && !android
+
+package cmd
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
+	log "github.com/sirupsen/logrus"
+	"google.golang.org/grpc"
+
+	"github.com/netbirdio/netbird/client/internal/daemonaddr"
+	"github.com/netbirdio/netbird/client/internal/ipcauth"
+	"github.com/netbirdio/netbird/client/proto"
+)
+
+// jsonPeerIdentity is the context key under which the connecting HTTP client's
+// identity is stashed for the lifetime of its connection.
+type jsonPeerIdentity struct{}
+
+// jsonPeerIdentityValue pairs the identity with whether it could be read at
+// all, so an unreadable identity is forwarded as "unknown" rather than omitted.
+type jsonPeerIdentityValue struct {
+	id    ipcauth.Identity
+	known bool
+}
+
+// jsonConnContext reads the identity of the client connecting to the JSON
+// socket and stashes it on the connection's context. The gateway re-dials the
+// daemon in-process, so the daemon would otherwise see every JSON request as
+// coming from the daemon itself.
+func jsonConnContext(ctx context.Context, c net.Conn) context.Context {
+	value := jsonPeerIdentityValue{}
+	id, err := ipcauth.ConnIdentity(c)
+	if err != nil {
+		log.Warnf("json gateway: cannot read HTTP client identity, privileged operations will be denied for this connection: %v", err)
+	} else {
+		value.id = id
+		value.known = true
+	}
+	return context.WithValue(ctx, jsonPeerIdentity{}, value)
+}
+
+// forwardIdentity stamps the HTTP client's identity onto every call the gateway
+// makes to the daemon.
+//
+// It is an interceptor on the gateway's client connection rather than a
+// runtime.WithMetadata annotator because grpc-gateway skips annotators when no
+// request header maps to metadata, which an HTTP/1.0 request with no Host header
+// over a unix socket achieves. The daemon would then receive no marker, see its own
+// identity as the transport peer, and authorize the request as the daemon itself.
+// An interceptor runs for every RPC whatever the request looked like.
+func forwardIdentity(ctx context.Context) context.Context {
+	value, ok := ctx.Value(jsonPeerIdentity{}).(jsonPeerIdentityValue)
+	if !ok {
+		// No ConnContext ran for this request, so forward an unknown identity:
+		// the daemon must not mistake its own identity for the client's.
+		return ipcauth.WithForwardedIdentity(ctx, ipcauth.Identity{}, false)
+	}
+	return ipcauth.WithForwardedIdentity(ctx, value.id, value.known)
+}
+
+func forwardIdentityUnary(ctx context.Context, method string, req, reply any, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
+	return invoker(forwardIdentity(ctx), method, req, reply, cc, opts...)
+}
+
+func forwardIdentityStream(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, streamer grpc.Streamer, opts ...grpc.CallOption) (grpc.ClientStream, error) {
+	return streamer(forwardIdentity(ctx), desc, cc, method, opts...)
+}
+
+// reservedHeaderWarning limits the dropped-header warning to the first occurrence.
+var reservedHeaderWarning sync.Once
+
+// jsonIncomingHeaderMatcher keeps an HTTP client from supplying the metadata the
+// gateway uses to forward its identity. grpc-gateway turns "Grpc-Metadata-<key>"
+// headers into gRPC metadata and joins them ahead of what its annotators add, so
+// without this filter a JSON client could send its own x-netbird-fwd-uid and the
+// daemon would authorize that instead of the client's real identity.
+func jsonIncomingHeaderMatcher(key string) (string, bool) {
+	mapped, ok := runtime.DefaultHeaderMatcher(key)
+	if !ok {
+		return "", false
+	}
+	if ipcauth.IsReservedForwardKey(mapped) {
+		// Warn once: any client can send these on every request, so warning each
+		// time hands it a way to fill the log. The rest are debug-level.
+		reservedHeaderWarning.Do(func() {
+			log.Warnf("json gateway: dropping reserved header %q from a request: only the gateway may set the caller's identity", key)
+		})
+		log.Debugf("json gateway: dropping reserved header %q", key)
+		return "", false
+	}
+	return mapped, true
+}
+
+func (p *program) startJSONGateway(jsonListener *socketListener, daemonEndpoint string) error {
+	if jsonListener.network == "tcp" {
+		log.Warnf("daemon JSON socket is listening on TCP (%s): callers carry no verifiable identity over TCP, "+
+			"so privileged operations will be denied for JSON clients", jsonListener.address)
+	}
+
+	mux := runtime.NewServeMux(runtime.WithIncomingHeaderMatcher(jsonIncomingHeaderMatcher))
+
+	// grpc.NewClient does not connect until the first request, so registering
+	// the handler here cannot block daemon startup.
+	target, opts := daemonaddr.DialTarget(daemonEndpoint)
+	opts = append(opts,
+		grpc.WithChainUnaryInterceptor(forwardIdentityUnary),
+		grpc.WithChainStreamInterceptor(forwardIdentityStream),
+	)
+	conn, err := grpc.NewClient(target, opts...)
+	if err != nil {
+		return fmt.Errorf("create daemon client for JSON gateway: %w", err)
+	}
+	if err := proto.RegisterDaemonServiceHandler(p.ctx, mux, conn); err != nil {
+		if cerr := conn.Close(); cerr != nil {
+			log.Debugf("close daemon client after failed JSON gateway registration: %v", cerr)
+		}
+		return err
+	}
+
+	jsonServer := &http.Server{
+		Handler:           mux,
+		ReadHeaderTimeout: 5 * time.Second,
+		BaseContext: func(net.Listener) context.Context {
+			return p.ctx
+		},
+		ConnContext: jsonConnContext,
+	}
+
+	p.jsonServMu.Lock()
+	p.jsonServ = jsonServer
+	p.jsonClient = conn
+	p.jsonServMu.Unlock()
+
+	go func() {
+		log.Printf("started daemon JSON server: %v", jsonListener.address)
+		if err := jsonServer.Serve(jsonListener.Listener); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			log.Errorf("failed to serve daemon JSON requests: %v", err)
+		}
+	}()
+
+	return nil
+}

client/cmd/service_json_gateway_test.go

@@ -0,0 +1,261 @@
+//go:build !windows && !ios && !android
+
+package cmd
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/metadata"
+	"google.golang.org/grpc/peer"
+
+	"github.com/netbirdio/netbird/client/internal/ipcauth"
+)
+
+// The JSON gateway runs inside the daemon and re-dials it locally, so every JSON
+// request reaches a handler with the daemon's own identity as the transport peer.
+// The gateway therefore forwards its HTTP client's identity as metadata, and the
+// daemon authorizes that instead of itself. These tests drive the real wiring
+// (jsonConnContext, forwardIdentity, jsonIncomingHeaderMatcher) and check the
+// identity a handler would end up authorizing.
+
+// daemonSideCtx is what a handler sees for a gateway-relayed call. The transport
+// peer must be this process's own identity: the gateway is the daemon, so the two
+// cannot differ, and hardcoding root here instead would describe a state that
+// never occurs.
+func daemonSideCtx(t *testing.T, md metadata.MD) context.Context {
+	t.Helper()
+	self, err := ipcauth.CurrentProcessIdentity()
+	if err != nil {
+		t.Skipf("cannot read this process's identity: %v", err)
+	}
+	ctx := peer.NewContext(context.Background(), &peer.Peer{
+		AuthInfo: ipcauth.AuthInfo{
+			CommonAuthInfo: credentials.CommonAuthInfo{SecurityLevel: credentials.NoSecurity},
+			Identity:       self,
+		},
+	})
+	return metadata.NewIncomingContext(ctx, md)
+}
+
+// gatewayMetadata reproduces what the daemon receives for a JSON request: the
+// mux annotates the context from the request's headers, then the interceptor on the
+// gateway's client connection stamps the caller's identity. The order matters,
+// since the interceptor must win over anything a header put there.
+func gatewayMetadata(t *testing.T, req *http.Request, ctx context.Context) metadata.MD {
+	t.Helper()
+	mux := runtime.NewServeMux(runtime.WithIncomingHeaderMatcher(jsonIncomingHeaderMatcher))
+	annotated, err := runtime.AnnotateContext(ctx, mux, req,
+		"/daemon.DaemonService/SetConfig",
+		runtime.WithHTTPPathPattern("/daemon.DaemonService/SetConfig"))
+	if err != nil {
+		t.Fatalf("annotate: %v", err)
+	}
+
+	md, ok := metadata.FromOutgoingContext(forwardIdentity(annotated))
+	if !ok {
+		t.Fatal("the interceptor produced no metadata")
+	}
+	return md
+}
+
+// clientCtx is the connection context jsonConnContext would have produced for an
+// HTTP client whose identity the gateway could read.
+func clientCtx(id ipcauth.Identity, known bool) context.Context {
+	return context.WithValue(context.Background(), jsonPeerIdentity{},
+		jsonPeerIdentityValue{id: id, known: known})
+}
+
+// An HTTP client must not be able to name its own identity. grpc-gateway turns
+// Grpc-Metadata-<key> headers into gRPC metadata, so without the header filter and
+// the interceptor overwriting the reserved keys, this request would authorize as
+// uid 0.
+func TestJSONGateway_ForgedIdentityHeaderIsDropped(t *testing.T) {
+	req, err := http.NewRequest(http.MethodPost, "http://localhost/daemon.DaemonService/SetConfig", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Grpc-Metadata-X-Netbird-Fwd-Uid", "0")
+	req.Header.Set("Grpc-Metadata-X-Netbird-Fwd-Gid", "0")
+	req.Header.Set("Grpc-Metadata-X-Netbird-Fwd", "1")
+	req.Header.Set("Grpc-Metadata-X-Netbird-Fwd-Sid", "S-1-5-18")
+
+	caller := ipcauth.Identity{UID: 31000, GID: 31000}
+	md := gatewayMetadata(t, req, clientCtx(caller, true))
+
+	id, ok := ipcauth.CallerIdentity(daemonSideCtx(t, md))
+	if !ok {
+		t.Fatal("the forwarded identity should be usable")
+	}
+	if id.IsPrivileged() {
+		t.Errorf("forged header was believed: authorized as %v", id)
+	}
+	if id.UID != caller.UID {
+		t.Errorf("authorized as uid %d, want the real client %d", id.UID, caller.UID)
+	}
+}
+
+// A request with no headers at all (HTTP/1.0 needs no Host, and a unix socket
+// yields no host:port) makes grpc-gateway produce no metadata whatsoever and skip
+// its annotators: "if len(pairs) == 0 { return ctx, nil, nil }" in
+// runtime/context.go. That is why the identity is stamped by an interceptor
+// instead. This is the case that previously reached the gate as the daemon itself.
+func TestJSONGateway_HeaderlessRequestIsStillMarkedForwarded(t *testing.T) {
+	req, err := http.NewRequest(http.MethodPost, "http://localhost/daemon.DaemonService/SetConfig", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header = http.Header{}
+	req.Host = ""
+
+	caller := ipcauth.Identity{UID: 31000, GID: 31000}
+	ctx := clientCtx(caller, true)
+
+	// Pin the skip path itself: if grpc-gateway ever produced a pair here, this
+	// test would still pass below while no longer covering what it was written for.
+	mux := runtime.NewServeMux(runtime.WithIncomingHeaderMatcher(jsonIncomingHeaderMatcher))
+	annotated, err := runtime.AnnotateContext(ctx, mux, req,
+		"/daemon.DaemonService/SetConfig",
+		runtime.WithHTTPPathPattern("/daemon.DaemonService/SetConfig"))
+	if err != nil {
+		t.Fatalf("annotate: %v", err)
+	}
+	if md, ok := metadata.FromOutgoingContext(annotated); ok {
+		t.Fatalf("grpc-gateway produced metadata %v for a headerless request; "+
+			"this test no longer covers the annotator-skip path", md)
+	}
+
+	md := gatewayMetadata(t, req, ctx)
+
+	id, ok := ipcauth.CallerIdentity(daemonSideCtx(t, md))
+	if !ok {
+		t.Fatal("the forwarded identity should be usable")
+	}
+	if id.UID != caller.UID || id.IsPrivileged() {
+		t.Errorf("authorized as %v, want the real client uid %d", id, caller.UID)
+	}
+}
+
+// When the gateway cannot read its client's identity (a TCP JSON socket, say) it
+// forwards the marker alone. The daemon must then report "unidentified" so the
+// privileged operations refuse, rather than falling back to the gateway's own
+// identity.
+func TestJSONGateway_UnreadableClientIdentityIsUnidentified(t *testing.T) {
+	req, err := http.NewRequest(http.MethodPost, "http://localhost/daemon.DaemonService/SetConfig", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	md := gatewayMetadata(t, req, clientCtx(ipcauth.Identity{}, false))
+
+	if id, ok := ipcauth.CallerIdentity(daemonSideCtx(t, md)); ok {
+		t.Errorf("a request with no client identity was authorized as %v", id)
+	}
+}
+
+// A request that never passed through jsonConnContext (no stashed identity) must
+// also come out unidentified rather than as the daemon.
+func TestJSONGateway_MissingConnContextIsUnidentified(t *testing.T) {
+	req, err := http.NewRequest(http.MethodPost, "http://localhost/daemon.DaemonService/SetConfig", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	md := gatewayMetadata(t, req, context.Background())
+
+	if id, ok := ipcauth.CallerIdentity(daemonSideCtx(t, md)); ok {
+		t.Errorf("a request with no connection context was authorized as %v", id)
+	}
+}
+
+// End to end over a real unix socket: the gateway reads the connecting client's
+// identity from the socket itself, so a client cannot present anything else.
+func TestJSONGateway_IdentityComesFromTheSocket(t *testing.T) {
+	mux := runtime.NewServeMux(runtime.WithIncomingHeaderMatcher(jsonIncomingHeaderMatcher))
+
+	type observed struct {
+		md metadata.MD
+	}
+	seen := make(chan observed, 1)
+
+	srv := &http.Server{
+		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			ctx, err := runtime.AnnotateContext(r.Context(), mux, r,
+				"/daemon.DaemonService/SetConfig",
+				runtime.WithHTTPPathPattern("/daemon.DaemonService/SetConfig"))
+			if err != nil {
+				t.Errorf("annotate: %v", err)
+				return
+			}
+			md, _ := metadata.FromOutgoingContext(forwardIdentity(ctx))
+			seen <- observed{md: md}
+			w.WriteHeader(http.StatusOK)
+		}),
+		ReadHeaderTimeout: 5 * time.Second,
+		ConnContext:       jsonConnContext,
+	}
+
+	sock := filepath.Join(t.TempDir(), "http.sock")
+	ln, err := net.Listen("unix", sock)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := srv.Close(); err != nil {
+			t.Logf("close server: %v", err)
+		}
+	})
+	go func() {
+		if err := srv.Serve(ln); err != nil && err != http.ErrServerClosed {
+			t.Logf("serve: %v", err)
+		}
+	}()
+
+	conn, err := net.Dial("unix", sock)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := conn.Close(); err != nil {
+			t.Logf("close conn: %v", err)
+		}
+	})
+
+	// Forge the identity headers on the wire as well.
+	request := "POST /daemon.DaemonService/SetConfig HTTP/1.1\r\n" +
+		"Host: localhost\r\n" +
+		"Grpc-Metadata-X-Netbird-Fwd: 1\r\n" +
+		"Grpc-Metadata-X-Netbird-Fwd-Uid: 0\r\n" +
+		"Content-Length: 0\r\n\r\n"
+	if _, err := conn.Write([]byte(request)); err != nil {
+		t.Fatal(err)
+	}
+
+	select {
+	case got := <-seen:
+		self, err := ipcauth.CurrentProcessIdentity()
+		if err != nil {
+			t.Skipf("cannot read this process's identity: %v", err)
+		}
+		// The socket peer is this test process, so that is the identity the
+		// gateway must forward, not the uid 0 the request asked for.
+		if uids := got.md.Get("x-netbird-fwd-uid"); len(uids) != 1 {
+			t.Fatalf("x-netbird-fwd-uid = %v, want exactly the gateway's own value", uids)
+		}
+		id, ok := ipcauth.CallerIdentity(daemonSideCtx(t, got.md))
+		if !ok {
+			t.Fatal("the forwarded identity should be usable")
+		}
+		if id.UID != self.UID {
+			t.Errorf("authorized as uid %d, want the socket peer %d", id.UID, self.UID)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("the gateway never handled the request")
+	}
+}

client/cmd/service_json_socket_test.go

@@ -0,0 +1,176 @@
+//go:build !ios && !android
+
+package cmd
+
+import (
+	"net"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func preserveJSONSocketTestState(t *testing.T) {
+	t.Helper()
+
+	origJSONSocket := jsonSocket
+	origEnableJSONSocket := enableJSONSocket
+	origChanged := map[string]bool{}
+	serviceCmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+		origChanged[flag.Name] = flag.Changed
+	})
+
+	t.Cleanup(func() {
+		jsonSocket = origJSONSocket
+		enableJSONSocket = origEnableJSONSocket
+		serviceCmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+			flag.Changed = origChanged[flag.Name]
+		})
+	})
+}
+
+func TestJSONSocketFlagsArePositiveEnableOnly(t *testing.T) {
+	assert.NotNil(t, serviceCmd.PersistentFlags().Lookup("enable-json-socket"))
+	assert.NotNil(t, serviceCmd.PersistentFlags().Lookup("json-socket"))
+	assert.Nil(t, serviceCmd.PersistentFlags().Lookup("disable-json-socket"))
+	assert.Equal(t, "false", serviceCmd.PersistentFlags().Lookup("enable-json-socket").DefValue)
+}
+
+func TestBuildServiceArgumentsDefaultDisablesJSONSocket(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	enableJSONSocket = false
+	jsonSocket = "tcp://127.0.0.1:8080"
+
+	args := buildServiceArguments()
+
+	assert.NotContains(t, args, "--enable-json-socket")
+	assert.NotContains(t, args, "--json-socket")
+}
+
+func TestBuildServiceArgumentsIncludesJSONSocketWhenEnabled(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	enableJSONSocket = true
+	jsonSocket = "tcp://127.0.0.1:8080"
+
+	args := buildServiceArguments()
+
+	enableIndex := indexOfArg(args, "--enable-json-socket")
+	jsonIndex := indexOfArg(args, "--json-socket")
+	require.NotEqual(t, -1, enableIndex)
+	require.NotEqual(t, -1, jsonIndex)
+	require.Less(t, enableIndex, jsonIndex)
+	require.Less(t, jsonIndex+1, len(args))
+	assert.Equal(t, "tcp://127.0.0.1:8080", args[jsonIndex+1])
+}
+
+func TestJSONSocketWithoutEnableValidation(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	enableJSONSocket = false
+	require.NoError(t, serviceCmd.PersistentFlags().Set("json-socket", "tcp://127.0.0.1:8080"))
+
+	err := validateJSONSocketFlags()
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "--enable-json-socket")
+}
+
+func TestJSONSocketWithEnableValidation(t *testing.T) {
+	preserveJSONSocketTestState(t)
+
+	require.NoError(t, serviceCmd.PersistentFlags().Set("enable-json-socket", "true"))
+	require.NoError(t, serviceCmd.PersistentFlags().Set("json-socket", "tcp://127.0.0.1:8080"))
+
+	assert.NoError(t, validateJSONSocketFlags())
+}
+
+func TestJSONSocketServiceParamsPersistEnableAndAddress(t *testing.T) {
+	preserveJSONSocketTestState(t)
+	serviceCmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+		flag.Changed = false
+	})
+
+	enableJSONSocket = true
+	jsonSocket = "tcp://127.0.0.1:8080"
+
+	params := currentServiceParams()
+	require.True(t, params.EnableJSONSocket)
+	require.Equal(t, "tcp://127.0.0.1:8080", params.JSONSocket)
+
+	enableJSONSocket = false
+	jsonSocket = defaultJSONSocket
+	applyServiceParams(testServiceEnvCommand(), params)
+
+	assert.True(t, enableJSONSocket)
+	assert.Equal(t, "tcp://127.0.0.1:8080", jsonSocket)
+}
+
+func TestRemoveStaleUnixSocketDoesNotRemoveRegularFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "netbird-http.sock")
+	require.NoError(t, os.WriteFile(path, []byte("not a socket"), 0600))
+
+	removeStaleUnixSocket(path)
+
+	data, err := os.ReadFile(path)
+	require.NoError(t, err)
+	assert.Equal(t, []byte("not a socket"), data)
+}
+
+func TestRemoveStaleUnixSocketRemovesSocket(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("unix sockets are not available on Windows")
+	}
+
+	path := filepath.Join(t.TempDir(), "netbird-http.sock")
+	addr := &net.UnixAddr{Name: path, Net: "unix"}
+	listener, err := net.ListenUnix("unix", addr)
+	require.NoError(t, err)
+	listener.SetUnlinkOnClose(false)
+	require.NoError(t, listener.Close())
+
+	_, err = os.Lstat(path)
+	require.NoError(t, err, "test setup must leave a stale Unix socket path")
+
+	removeStaleUnixSocket(path)
+
+	_, err = os.Lstat(path)
+	assert.True(t, os.IsNotExist(err), "expected stale Unix socket to be removed, got %v", err)
+}
+
+func TestRemoveStaleUnixSocketDoesNotRemoveLiveSocket(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("unix sockets are not available on Windows")
+	}
+
+	path := filepath.Join(t.TempDir(), "netbird-http.sock")
+	listener, err := net.Listen("unix", path)
+	require.NoError(t, err)
+	defer listener.Close()
+
+	removeStaleUnixSocket(path)
+
+	_, err = os.Lstat(path)
+	assert.NoError(t, err, "expected live Unix socket to be preserved")
+}
+
+func testServiceEnvCommand() *cobra.Command {
+	cmd := &cobra.Command{}
+	cmd.Flags().StringSlice("service-env", nil, "")
+	return cmd
+}
+
+func indexOfArg(args []string, arg string) int {
+	for i, candidate := range args {
+		if candidate == arg {
+			return i
+		}
+	}
+	return -1
+}

client/cmd/service_params.go

@@ -13,6 +13,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/netbirdio/netbird/client/configs"
+	"github.com/netbirdio/netbird/client/internal/daemonaddr"
 	"github.com/netbirdio/netbird/util"
 )
 
@@ -23,6 +24,7 @@ const serviceParamsFile = "service.json"
 type serviceParams struct {
 	LogLevel              string            `json:"log_level"`
 	DaemonAddr            string            `json:"daemon_addr"`
+	JSONSocket            string            `json:"json_socket"`
 	ManagementURL         string            `json:"management_url,omitempty"`
 	ConfigPath            string            `json:"config_path,omitempty"`
 	LogFiles              []string          `json:"log_files,omitempty"`
@@ -30,6 +32,7 @@ type serviceParams struct {
 	DisableUpdateSettings bool              `json:"disable_update_settings,omitempty"`
 	EnableCapture         bool              `json:"enable_capture,omitempty"`
 	DisableNetworks       bool              `json:"disable_networks,omitempty"`
+	EnableJSONSocket      bool              `json:"enable_json_socket,omitempty"`
 	ServiceEnvVars        map[string]string `json:"service_env_vars,omitempty"`
 }
 
@@ -75,6 +78,7 @@ func currentServiceParams() *serviceParams {
 	params := &serviceParams{
 		LogLevel:              logLevel,
 		DaemonAddr:            daemonAddr,
+		JSONSocket:            jsonSocket,
 		ManagementURL:         managementURL,
 		ConfigPath:            configPath,
 		LogFiles:              logFiles,
@@ -82,6 +86,7 @@ func currentServiceParams() *serviceParams {
 		DisableUpdateSettings: updateSettingsDisabled,
 		EnableCapture:         captureEnabled,
 		DisableNetworks:       networksDisabled,
+		EnableJSONSocket:      enableJSONSocket,
 	}
 
 	if len(serviceEnvVars) > 0 {
@@ -113,15 +118,29 @@ func applyServiceParams(cmd *cobra.Command, params *serviceParams) {
 		return
 	}
 
-	// For fields with non-empty defaults (log-level, daemon-addr), keep the
-	// != "" guard so that an older service.json missing the field doesn't
-	// clobber the default with an empty string.
+	// For fields with non-empty defaults, keep the != "" guard so that an older
+	// service.json missing the field doesn't clobber the default with an empty string.
 	if !rootCmd.PersistentFlags().Changed("log-level") && params.LogLevel != "" {
 		logLevel = params.LogLevel
 	}
 
 	if !rootCmd.PersistentFlags().Changed("daemon-addr") && params.DaemonAddr != "" {
 		daemonAddr = params.DaemonAddr
+		// An install that predates named-pipe support has the loopback TCP
+		// address saved. Callers carry no identity over TCP, so move it to the
+		// pipe instead of restoring a socket the daemon cannot authorize on.
+		if migrated, ok := daemonaddr.MigrateLegacy(daemonAddr); ok {
+			cmd.Printf("Moving the saved daemon address from %s to %s so the daemon can identify its callers\n", daemonAddr, migrated)
+			daemonAddr = migrated
+		}
+	}
+
+	if !serviceCmd.PersistentFlags().Changed("json-socket") && params.JSONSocket != "" {
+		jsonSocket = params.JSONSocket
+	}
+
+	if !serviceCmd.PersistentFlags().Changed("enable-json-socket") {
+		enableJSONSocket = params.EnableJSONSocket
 	}
 
 	// For optional fields where empty means "use default", always apply so

client/cmd/service_params_test.go

@@ -41,6 +41,8 @@ func TestSaveAndLoadServiceParams(t *testing.T) {
 	params := &serviceParams{
 		LogLevel:              "debug",
 		DaemonAddr:            "unix:///var/run/netbird.sock",
+		JSONSocket:            "tcp://127.0.0.1:8080",
+		EnableJSONSocket:      true,
 		ManagementURL:         "https://my.server.com",
 		ConfigPath:            "/etc/netbird/config.json",
 		LogFiles:              []string{"/var/log/netbird/client.log", "console"},
@@ -63,6 +65,8 @@ func TestSaveAndLoadServiceParams(t *testing.T) {
 
 	assert.Equal(t, params.LogLevel, loaded.LogLevel)
 	assert.Equal(t, params.DaemonAddr, loaded.DaemonAddr)
+	assert.Equal(t, params.JSONSocket, loaded.JSONSocket)
+	assert.Equal(t, params.EnableJSONSocket, loaded.EnableJSONSocket)
 	assert.Equal(t, params.ManagementURL, loaded.ManagementURL)
 	assert.Equal(t, params.ConfigPath, loaded.ConfigPath)
 	assert.Equal(t, params.LogFiles, loaded.LogFiles)
@@ -101,6 +105,8 @@ func TestLoadServiceParams_InvalidJSON(t *testing.T) {
 func TestCurrentServiceParams(t *testing.T) {
 	origLogLevel := logLevel
 	origDaemonAddr := daemonAddr
+	origJSONSocket := jsonSocket
+	origEnableJSONSocket := enableJSONSocket
 	origManagementURL := managementURL
 	origConfigPath := configPath
 	origLogFiles := logFiles
@@ -110,6 +116,8 @@ func TestCurrentServiceParams(t *testing.T) {
 	t.Cleanup(func() {
 		logLevel = origLogLevel
 		daemonAddr = origDaemonAddr
+		jsonSocket = origJSONSocket
+		enableJSONSocket = origEnableJSONSocket
 		managementURL = origManagementURL
 		configPath = origConfigPath
 		logFiles = origLogFiles
@@ -120,6 +128,8 @@ func TestCurrentServiceParams(t *testing.T) {
 
 	logLevel = "trace"
 	daemonAddr = "tcp://127.0.0.1:9999"
+	jsonSocket = "tcp://127.0.0.1:8080"
+	enableJSONSocket = true
 	managementURL = "https://mgmt.example.com"
 	configPath = "/tmp/test-config.json"
 	logFiles = []string{"/tmp/test.log"}
@@ -131,6 +141,8 @@ func TestCurrentServiceParams(t *testing.T) {
 
 	assert.Equal(t, "trace", params.LogLevel)
 	assert.Equal(t, "tcp://127.0.0.1:9999", params.DaemonAddr)
+	assert.Equal(t, "tcp://127.0.0.1:8080", params.JSONSocket)
+	assert.True(t, params.EnableJSONSocket)
 	assert.Equal(t, "https://mgmt.example.com", params.ManagementURL)
 	assert.Equal(t, "/tmp/test-config.json", params.ConfigPath)
 	assert.Equal(t, []string{"/tmp/test.log"}, params.LogFiles)
@@ -142,6 +154,8 @@ func TestCurrentServiceParams(t *testing.T) {
 func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	origLogLevel := logLevel
 	origDaemonAddr := daemonAddr
+	origJSONSocket := jsonSocket
+	origEnableJSONSocket := enableJSONSocket
 	origManagementURL := managementURL
 	origConfigPath := configPath
 	origLogFiles := logFiles
@@ -151,6 +165,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	t.Cleanup(func() {
 		logLevel = origLogLevel
 		daemonAddr = origDaemonAddr
+		jsonSocket = origJSONSocket
+		enableJSONSocket = origEnableJSONSocket
 		managementURL = origManagementURL
 		configPath = origConfigPath
 		logFiles = origLogFiles
@@ -162,6 +178,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	// Reset all flags to defaults.
 	logLevel = "info"
 	daemonAddr = "unix:///var/run/netbird.sock"
+	jsonSocket = defaultJSONSocket
+	enableJSONSocket = false
 	managementURL = ""
 	configPath = "/etc/netbird/config.json"
 	logFiles = []string{"/var/log/netbird/client.log"}
@@ -184,6 +202,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 	saved := &serviceParams{
 		LogLevel:              "debug",
 		DaemonAddr:            "tcp://127.0.0.1:5555",
+		JSONSocket:            "tcp://127.0.0.1:8080",
+		EnableJSONSocket:      true,
 		ManagementURL:         "https://saved.example.com",
 		ConfigPath:            "/saved/config.json",
 		LogFiles:              []string{"/saved/client.log"},
@@ -201,6 +221,8 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 
 	// All other fields were not Changed, so they should use saved values.
 	assert.Equal(t, "tcp://127.0.0.1:5555", daemonAddr)
+	assert.Equal(t, "tcp://127.0.0.1:8080", jsonSocket)
+	assert.True(t, enableJSONSocket)
 	assert.Equal(t, "https://saved.example.com", managementURL)
 	assert.Equal(t, "/saved/config.json", configPath)
 	assert.Equal(t, []string{"/saved/client.log"}, logFiles)
@@ -212,14 +234,17 @@ func TestApplyServiceParams_OnlyUnchangedFlags(t *testing.T) {
 func TestApplyServiceParams_BooleanRevertToFalse(t *testing.T) {
 	origProfilesDisabled := profilesDisabled
 	origUpdateSettingsDisabled := updateSettingsDisabled
+	origEnableJSONSocket := enableJSONSocket
 	t.Cleanup(func() {
 		profilesDisabled = origProfilesDisabled
 		updateSettingsDisabled = origUpdateSettingsDisabled
+		enableJSONSocket = origEnableJSONSocket
 	})
 
 	// Simulate current state where booleans are true (e.g. set by previous install).
 	profilesDisabled = true
 	updateSettingsDisabled = true
+	enableJSONSocket = true
 
 	// Reset Changed state so flags appear unset.
 	serviceCmd.PersistentFlags().VisitAll(func(f *pflag.Flag) {
@@ -238,6 +263,7 @@ func TestApplyServiceParams_BooleanRevertToFalse(t *testing.T) {
 
 	assert.False(t, profilesDisabled, "saved false should override current true")
 	assert.False(t, updateSettingsDisabled, "saved false should override current true")
+	assert.False(t, enableJSONSocket, "saved false should override current true")
 }
 
 func TestApplyServiceParams_ClearManagementURL(t *testing.T) {
@@ -530,6 +556,7 @@ func fieldToGlobalVar(field string) string {
 	m := map[string]string{
 		"LogLevel":              "logLevel",
 		"DaemonAddr":            "daemonAddr",
+		"JSONSocket":            "jsonSocket",
 		"ManagementURL":         "managementURL",
 		"ConfigPath":            "configPath",
 		"LogFiles":              "logFiles",
@@ -537,6 +564,7 @@ func fieldToGlobalVar(field string) string {
 		"DisableUpdateSettings": "updateSettingsDisabled",
 		"EnableCapture":         "captureEnabled",
 		"DisableNetworks":       "networksDisabled",
+		"EnableJSONSocket":      "enableJSONSocket",
 		"ServiceEnvVars":        "serviceEnvVars",
 	}
 	if v, ok := m[field]; ok {

client/cmd/service_pipe_other.go

@@ -0,0 +1,14 @@
+//go:build !windows
+
+package cmd
+
+import (
+	"fmt"
+	"net"
+)
+
+// listenNamedPipe is Windows-only: no other platform serves the daemon on a
+// named pipe.
+func listenNamedPipe(string) (net.Listener, string, error) {
+	return nil, "", fmt.Errorf("named pipes are only supported on Windows")
+}

client/cmd/service_pipe_windows.go

@@ -0,0 +1,41 @@
+//go:build windows
+
+package cmd
+
+import (
+	"errors"
+	"fmt"
+	"net"
+
+	"github.com/Microsoft/go-winio"
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/internal/daemonaddr"
+	"github.com/netbirdio/netbird/client/internal/ipcauth"
+)
+
+// listenNamedPipe creates the daemon control pipe and reports the path it ended
+// up on. The security descriptor lets any local caller connect, as a Unix socket
+// at 0666 does, and the privileged operations are authorized separately from the
+// caller's token.
+//
+// The protected name comes first so that an unprivileged process cannot take the
+// name before the service does. Creating it requires being an administrator or
+// LocalSystem, so a daemon an ordinary user runs themselves, as in netstack mode,
+// falls back to the plain name; clients try both and check who serves them.
+func listenNamedPipe(name string) (net.Listener, string, error) {
+	var errs []error
+	for _, path := range daemonaddr.PipePaths(name) {
+		listener, err := winio.ListenPipe(path, &winio.PipeConfig{
+			SecurityDescriptor: ipcauth.DefaultPipeSDDL(),
+		})
+		if err != nil {
+			log.Debugf("not serving the daemon on %s: %v", path, err)
+			errs = append(errs, fmt.Errorf("%s: %w", path, err))
+			continue
+		}
+		return listener, path, nil
+	}
+
+	return nil, "", errors.Join(errs...)
+}

client/cmd/service_privileged_test.go

@@ -0,0 +1,196 @@
+//go:build privileged
+
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"runtime"
+	"testing"
+	"time"
+
+	"github.com/kardianos/service"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const (
+	serviceStartTimeout = 10 * time.Second
+	serviceStopTimeout  = 5 * time.Second
+	statusPollInterval  = 500 * time.Millisecond
+)
+
+// waitForServiceStatus waits for service to reach expected status with timeout
+func waitForServiceStatus(expectedStatus service.Status, timeout time.Duration) (bool, error) {
+	cfg, err := newSVCConfig()
+	if err != nil {
+		return false, err
+	}
+
+	ctxSvc, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	s, err := newSVC(newProgram(ctxSvc, cancel), cfg)
+	if err != nil {
+		return false, err
+	}
+
+	ctx, timeoutCancel := context.WithTimeout(context.Background(), timeout)
+	defer timeoutCancel()
+
+	ticker := time.NewTicker(statusPollInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return false, fmt.Errorf("timeout waiting for service status %v", expectedStatus)
+		case <-ticker.C:
+			status, err := s.Status()
+			if err != nil {
+				// Continue polling on transient errors
+				continue
+			}
+			if status == expectedStatus {
+				return true, nil
+			}
+		}
+	}
+}
+
+// TestServiceLifecycle tests the complete service lifecycle
+func TestServiceLifecycle(t *testing.T) {
+	// TODO: Add support for Windows and macOS
+	if runtime.GOOS != "linux" && runtime.GOOS != "freebsd" {
+		t.Skipf("Skipping service lifecycle test on unsupported OS: %s", runtime.GOOS)
+	}
+
+	if os.Getenv("CONTAINER") == "true" {
+		t.Skip("Skipping service lifecycle test in container environment")
+	}
+
+	originalServiceName := serviceName
+	serviceName = "netbirdtest" + fmt.Sprintf("%d", time.Now().Unix())
+	defer func() {
+		serviceName = originalServiceName
+	}()
+
+	tempDir := t.TempDir()
+	configPath = fmt.Sprintf("%s/netbird-test-config.json", tempDir)
+	logLevel = "info"
+	daemonAddr = fmt.Sprintf("unix://%s/netbird-test.sock", tempDir)
+
+	// Ensure cleanup even if a subtest fails and Stop/Uninstall subtests don't run.
+	t.Cleanup(func() {
+		cfg, err := newSVCConfig()
+		if err != nil {
+			t.Errorf("cleanup: create service config: %v", err)
+			return
+		}
+		ctxSvc, cancel := context.WithCancel(context.Background())
+		defer cancel()
+		s, err := newSVC(newProgram(ctxSvc, cancel), cfg)
+		if err != nil {
+			t.Errorf("cleanup: create service: %v", err)
+			return
+		}
+
+		// If the subtests already cleaned up, there's nothing to do.
+		if _, err := s.Status(); err != nil {
+			return
+		}
+
+		if err := s.Stop(); err != nil {
+			t.Errorf("cleanup: stop service: %v", err)
+		}
+		if err := s.Uninstall(); err != nil {
+			t.Errorf("cleanup: uninstall service: %v", err)
+		}
+	})
+
+	ctx := context.Background()
+
+	t.Run("Install", func(t *testing.T) {
+		installCmd.SetContext(ctx)
+		err := installCmd.RunE(installCmd, []string{})
+		require.NoError(t, err)
+
+		cfg, err := newSVCConfig()
+		require.NoError(t, err)
+
+		ctxSvc, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		s, err := newSVC(newProgram(ctxSvc, cancel), cfg)
+		require.NoError(t, err)
+
+		status, err := s.Status()
+		assert.NoError(t, err)
+		assert.NotEqual(t, service.StatusUnknown, status)
+	})
+
+	t.Run("Start", func(t *testing.T) {
+		startCmd.SetContext(ctx)
+		err := startCmd.RunE(startCmd, []string{})
+		require.NoError(t, err)
+
+		running, err := waitForServiceStatus(service.StatusRunning, serviceStartTimeout)
+		require.NoError(t, err)
+		assert.True(t, running)
+	})
+
+	t.Run("Restart", func(t *testing.T) {
+		restartCmd.SetContext(ctx)
+		err := restartCmd.RunE(restartCmd, []string{})
+		require.NoError(t, err)
+
+		running, err := waitForServiceStatus(service.StatusRunning, serviceStartTimeout)
+		require.NoError(t, err)
+		assert.True(t, running)
+	})
+
+	t.Run("Reconfigure", func(t *testing.T) {
+		originalLogLevel := logLevel
+		logLevel = "debug"
+		defer func() {
+			logLevel = originalLogLevel
+		}()
+
+		reconfigureCmd.SetContext(ctx)
+		err := reconfigureCmd.RunE(reconfigureCmd, []string{})
+		require.NoError(t, err)
+
+		running, err := waitForServiceStatus(service.StatusRunning, serviceStartTimeout)
+		require.NoError(t, err)
+		assert.True(t, running)
+	})
+
+	t.Run("Stop", func(t *testing.T) {
+		stopCmd.SetContext(ctx)
+		err := stopCmd.RunE(stopCmd, []string{})
+		require.NoError(t, err)
+
+		stopped, err := waitForServiceStatus(service.StatusStopped, serviceStopTimeout)
+		require.NoError(t, err)
+		assert.True(t, stopped)
+	})
+
+	t.Run("Uninstall", func(t *testing.T) {
+		uninstallCmd.SetContext(ctx)
+		err := uninstallCmd.RunE(uninstallCmd, []string{})
+		require.NoError(t, err)
+
+		cfg, err := newSVCConfig()
+		require.NoError(t, err)
+
+		ctxSvc, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		s, err := newSVC(newProgram(ctxSvc, cancel), cfg)
+		require.NoError(t, err)
+
+		_, err = s.Status()
+		assert.Error(t, err)
+	})
+}

client/cmd/service_socket.go

@@ -0,0 +1,119 @@
+//go:build !ios && !android
+
+package cmd
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"os"
+	"strings"
+	"syscall"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+type socketListener struct {
+	net.Listener
+	network string
+	address string
+}
+
+func listenOnAddress(addr string) (*socketListener, error) {
+	network, address, err := parseListenAddress(addr)
+	if err != nil {
+		return nil, err
+	}
+
+	if network == "npipe" {
+		listener, path, err := listenNamedPipe(address) //nolint:staticcheck
+		if err != nil {                                 //nolint:staticcheck // always errors on non-Windows builds
+			return nil, err
+		}
+		return &socketListener{Listener: listener, network: network, address: path}, nil
+	}
+
+	if network == "unix" {
+		removeStaleUnixSocket(address)
+	}
+
+	listener, err := net.Listen(network, address)
+	if err != nil {
+		return nil, err
+	}
+
+	return &socketListener{Listener: listener, network: network, address: address}, nil
+}
+
+func parseListenAddress(addr string) (string, string, error) {
+	network, address, ok := strings.Cut(addr, "://")
+	if !ok || network == "" || address == "" {
+		return "", "", fmt.Errorf("address must be in [unix|tcp|npipe]://[path|host:port|name] format: %q", addr)
+	}
+
+	switch network {
+	case "unix", "tcp", "npipe":
+		return network, address, nil
+	default:
+		return "", "", fmt.Errorf("unsupported daemon address protocol: %v", network)
+	}
+}
+
+func removeStaleUnixSocket(path string) {
+	stat, err := os.Lstat(path)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			log.Debugf("stat socket file: %v", err)
+		}
+		return
+	}
+
+	if stat.Mode()&os.ModeSocket == 0 {
+		return
+	}
+
+	if !isStaleUnixSocket(path) {
+		return
+	}
+
+	if err := os.Remove(path); err != nil {
+		log.Debugf("remove socket file: %v", err)
+	}
+}
+
+func isStaleUnixSocket(path string) bool {
+	conn, err := net.DialTimeout("unix", path, 100*time.Millisecond)
+	if err == nil {
+		if closeErr := conn.Close(); closeErr != nil {
+			log.Debugf("close unix socket probe: %v", closeErr)
+		}
+		return false
+	}
+
+	if os.IsNotExist(err) || os.IsPermission(err) || os.IsTimeout(err) {
+		log.Debugf("not removing unix socket %s after probe error: %v", path, err)
+		return false
+	}
+
+	return errors.Is(err, syscall.ECONNREFUSED)
+}
+
+func removeStaleUnixSocketForAddress(addr string) {
+	network, address, err := parseListenAddress(addr)
+	if err != nil || network != "unix" {
+		return
+	}
+	removeStaleUnixSocket(address)
+}
+
+func (l *socketListener) chmodUnixSocket(description string) error {
+	if l == nil || l.network != "unix" {
+		return nil
+	}
+
+	if err := os.Chmod(l.address, 0666); err != nil {
+		return fmt.Errorf("failed setting %s permissions for %s: %w", description, l.address, err)
+	}
+	return nil
+}

client/cmd/service_test.go

@@ -1,16 +1,12 @@
 package cmd
 
 import (
-	"context"
-	"fmt"
 	"os"
 	"os/signal"
 	"runtime"
 	"syscall"
 	"testing"
-	"time"
 
-	"github.com/kardianos/service"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -31,186 +27,6 @@ func TestMain(m *testing.M) {
 	os.Exit(m.Run())
 }
 
-const (
-	serviceStartTimeout = 10 * time.Second
-	serviceStopTimeout  = 5 * time.Second
-	statusPollInterval  = 500 * time.Millisecond
-)
-
-// waitForServiceStatus waits for service to reach expected status with timeout
-func waitForServiceStatus(expectedStatus service.Status, timeout time.Duration) (bool, error) {
-	cfg, err := newSVCConfig()
-	if err != nil {
-		return false, err
-	}
-
-	ctxSvc, cancel := context.WithCancel(context.Background())
-	defer cancel()
-
-	s, err := newSVC(newProgram(ctxSvc, cancel), cfg)
-	if err != nil {
-		return false, err
-	}
-
-	ctx, timeoutCancel := context.WithTimeout(context.Background(), timeout)
-	defer timeoutCancel()
-
-	ticker := time.NewTicker(statusPollInterval)
-	defer ticker.Stop()
-
-	for {
-		select {
-		case <-ctx.Done():
-			return false, fmt.Errorf("timeout waiting for service status %v", expectedStatus)
-		case <-ticker.C:
-			status, err := s.Status()
-			if err != nil {
-				// Continue polling on transient errors
-				continue
-			}
-			if status == expectedStatus {
-				return true, nil
-			}
-		}
-	}
-}
-
-// TestServiceLifecycle tests the complete service lifecycle
-func TestServiceLifecycle(t *testing.T) {
-	// TODO: Add support for Windows and macOS
-	if runtime.GOOS != "linux" && runtime.GOOS != "freebsd" {
-		t.Skipf("Skipping service lifecycle test on unsupported OS: %s", runtime.GOOS)
-	}
-
-	if os.Getenv("CONTAINER") == "true" {
-		t.Skip("Skipping service lifecycle test in container environment")
-	}
-
-	originalServiceName := serviceName
-	serviceName = "netbirdtest" + fmt.Sprintf("%d", time.Now().Unix())
-	defer func() {
-		serviceName = originalServiceName
-	}()
-
-	tempDir := t.TempDir()
-	configPath = fmt.Sprintf("%s/netbird-test-config.json", tempDir)
-	logLevel = "info"
-	daemonAddr = fmt.Sprintf("unix://%s/netbird-test.sock", tempDir)
-
-	// Ensure cleanup even if a subtest fails and Stop/Uninstall subtests don't run.
-	t.Cleanup(func() {
-		cfg, err := newSVCConfig()
-		if err != nil {
-			t.Errorf("cleanup: create service config: %v", err)
-			return
-		}
-		ctxSvc, cancel := context.WithCancel(context.Background())
-		defer cancel()
-		s, err := newSVC(newProgram(ctxSvc, cancel), cfg)
-		if err != nil {
-			t.Errorf("cleanup: create service: %v", err)
-			return
-		}
-
-		// If the subtests already cleaned up, there's nothing to do.
-		if _, err := s.Status(); err != nil {
-			return
-		}
-
-		if err := s.Stop(); err != nil {
-			t.Errorf("cleanup: stop service: %v", err)
-		}
-		if err := s.Uninstall(); err != nil {
-			t.Errorf("cleanup: uninstall service: %v", err)
-		}
-	})
-
-	ctx := context.Background()
-
-	t.Run("Install", func(t *testing.T) {
-		installCmd.SetContext(ctx)
-		err := installCmd.RunE(installCmd, []string{})
-		require.NoError(t, err)
-
-		cfg, err := newSVCConfig()
-		require.NoError(t, err)
-
-		ctxSvc, cancel := context.WithCancel(context.Background())
-		defer cancel()
-
-		s, err := newSVC(newProgram(ctxSvc, cancel), cfg)
-		require.NoError(t, err)
-
-		status, err := s.Status()
-		assert.NoError(t, err)
-		assert.NotEqual(t, service.StatusUnknown, status)
-	})
-
-	t.Run("Start", func(t *testing.T) {
-		startCmd.SetContext(ctx)
-		err := startCmd.RunE(startCmd, []string{})
-		require.NoError(t, err)
-
-		running, err := waitForServiceStatus(service.StatusRunning, serviceStartTimeout)
-		require.NoError(t, err)
-		assert.True(t, running)
-	})
-
-	t.Run("Restart", func(t *testing.T) {
-		restartCmd.SetContext(ctx)
-		err := restartCmd.RunE(restartCmd, []string{})
-		require.NoError(t, err)
-
-		running, err := waitForServiceStatus(service.StatusRunning, serviceStartTimeout)
-		require.NoError(t, err)
-		assert.True(t, running)
-	})
-
-	t.Run("Reconfigure", func(t *testing.T) {
-		originalLogLevel := logLevel
-		logLevel = "debug"
-		defer func() {
-			logLevel = originalLogLevel
-		}()
-
-		reconfigureCmd.SetContext(ctx)
-		err := reconfigureCmd.RunE(reconfigureCmd, []string{})
-		require.NoError(t, err)
-
-		running, err := waitForServiceStatus(service.StatusRunning, serviceStartTimeout)
-		require.NoError(t, err)
-		assert.True(t, running)
-	})
-
-	t.Run("Stop", func(t *testing.T) {
-		stopCmd.SetContext(ctx)
-		err := stopCmd.RunE(stopCmd, []string{})
-		require.NoError(t, err)
-
-		stopped, err := waitForServiceStatus(service.StatusStopped, serviceStopTimeout)
-		require.NoError(t, err)
-		assert.True(t, stopped)
-	})
-
-	t.Run("Uninstall", func(t *testing.T) {
-		uninstallCmd.SetContext(ctx)
-		err := uninstallCmd.RunE(uninstallCmd, []string{})
-		require.NoError(t, err)
-
-		cfg, err := newSVCConfig()
-		require.NoError(t, err)
-
-		ctxSvc, cancel := context.WithCancel(context.Background())
-		defer cancel()
-
-		s, err := newSVC(newProgram(ctxSvc, cancel), cfg)
-		require.NoError(t, err)
-
-		_, err = s.Status()
-		assert.Error(t, err)
-	})
-}
-
 // TestServiceEnvVars tests environment variable parsing
 func TestServiceEnvVars(t *testing.T) {
 	tests := []struct {

client/cmd/status.go

@@ -6,6 +6,7 @@ import (
 	"net"
 	"net/netip"
 	"strings"
+	"time"
 
 	"github.com/spf13/cobra"
 	"google.golang.org/grpc/status"
@@ -115,8 +116,19 @@ func statusFunc(cmd *cobra.Command, args []string) error {
 	// manager only knows the active profile ID, not its display name.
 	profName := getActiveProfileName(ctx)
 
+	var sessionExpiresAt time.Time
+	if ts := resp.GetSessionExpiresAt(); ts.IsValid() {
+		sessionExpiresAt = ts.AsTime().UTC()
+	}
+
+	anonymizeEnabled, anonymizeLevel, err := effectiveAnonymize()
+	if err != nil {
+		return err
+	}
+
 	var outputInformationHolder = nbstatus.ConvertToStatusOutputOverview(resp.GetFullStatus(), nbstatus.ConvertOptions{
-		Anonymize:            anonymizeFlag,
+		Anonymize:            anonymizeEnabled,
+		AnonymizeLevel:       anonymizeLevel,
 		DaemonVersion:        resp.GetDaemonVersion(),
 		DaemonStatus:         nbstatus.ParseDaemonStatus(status),
 		StatusFilter:         statusFilter,
@@ -125,6 +137,7 @@ func statusFunc(cmd *cobra.Command, args []string) error {
 		IPsFilter:            ipsFilterMap,
 		ConnectionTypeFilter: connectionTypeFilter,
 		ProfileName:          profName,
+		SessionExpiresAt:     sessionExpiresAt,
 	})
 	var statusOutputString string
 	switch {

client/cmd/testutil_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/golang/mock/gomock"
+	"go.uber.org/mock/gomock"
 	"github.com/stretchr/testify/require"
 	"go.opentelemetry.io/otel"
 	"google.golang.org/grpc"

client/cmd/up.go

@@ -21,7 +21,9 @@ import (
 	"github.com/netbirdio/netbird/client/internal"
 	"github.com/netbirdio/netbird/client/internal/peer"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
+	nbnet "github.com/netbirdio/netbird/client/net"
 	"github.com/netbirdio/netbird/client/proto"
+	"github.com/netbirdio/netbird/client/server"
 	"github.com/netbirdio/netbird/client/system"
 	"github.com/netbirdio/netbird/shared/management/domain"
 	"github.com/netbirdio/netbird/util"
@@ -229,6 +231,24 @@ func runInForegroundMode(ctx context.Context, cmd *cobra.Command, activeProf *pr
 
 	_, _ = profilemanager.UpdateOldManagementURL(ctx, config, configFilePath)
 
+	// Restore residual state left by a previous run that did not shut down
+	// cleanly, mirroring what the daemon does before connecting: it recovers
+	// DNS config (a stale resolv.conf takeover can make the management
+	// hostname unresolvable), firewall rules, ssh config and legacy routing.
+	// Route cleanup itself happens at engine start; nbnet.Init() below lets
+	// the management dial bypass a leftover fwmark rule until then.
+	// Foreground mode is particularly exposed in containers: a crashed
+	// container restarts inside the same (pod) network namespace, so stale
+	// state survives while the process does not.
+	if err := server.RestoreResidualState(ctx, profilemanager.NewServiceManager(configPath).GetStatePath()); err != nil {
+		log.Warnf("failed to restore residual state: %v", err)
+	}
+
+	// Enable advanced routing (as the daemon does on startup) so the
+	// management dial bypasses a leftover fwmark rule instead of being
+	// shunted into a stale routing table.
+	nbnet.Init()
+
 	err = foregroundLogin(ctx, cmd, config, providedSetupKey, activeProf.ID)
 	if err != nil {
 		return fmt.Errorf("foreground login failed: %v", err)
@@ -305,7 +325,7 @@ func runInDaemonMode(ctx context.Context, cmd *cobra.Command, pm *profilemanager
 		if st, ok := gstatus.FromError(err); ok && st.Code() == codes.Unavailable {
 			log.Warnf("setConfig method is not available in the daemon: %s", st.Message())
 		} else {
-			return fmt.Errorf("call service setConfig method: %v", err)
+			return daemonCallError("call service setConfig method", err)
 		}
 	}
 
@@ -359,7 +379,7 @@ func doDaemonUp(ctx context.Context, cmd *cobra.Command, client proto.DaemonServ
 	}
 
 	if loginErr != nil {
-		return fmt.Errorf("login failed: %v", loginErr)
+		return daemonCallError("login failed", loginErr)
 	}
 
 	if loginResp.NeedsSSOLogin {
@@ -372,7 +392,7 @@ func doDaemonUp(ctx context.Context, cmd *cobra.Command, client proto.DaemonServ
 		ProfileName: &profileID,
 		Username:    &username,
 	}); err != nil {
-		return fmt.Errorf("call service up method: %v", err)
+		return daemonCallError("call service up method", err)
 	}
 
 	return nil
@@ -479,10 +499,6 @@ func setupSetConfigReq(customDNSAddressConverted []byte, cmd *cobra.Command, pro
 		req.DisableIpv6 = &disableIPv6
 	}
 
-	if cmd.Flag(enableLazyConnectionFlag).Changed {
-		req.LazyConnectionEnabled = &lazyConnEnabled
-	}
-
 	return &req
 }
 
@@ -600,9 +616,6 @@ func setupConfig(customDNSAddressConverted []byte, cmd *cobra.Command, configFil
 		ic.DisableIPv6 = &disableIPv6
 	}
 
-	if cmd.Flag(enableLazyConnectionFlag).Changed {
-		ic.LazyConnectionEnabled = &lazyConnEnabled
-	}
 	return &ic, nil
 }
 
@@ -613,7 +626,7 @@ func setupLoginRequest(providedSetupKey string, customDNSAddressConverted []byte
 		NatExternalIPs:      natExternalIPs,
 		CleanNATExternalIPs: natExternalIPs != nil && len(natExternalIPs) == 0,
 		CustomDNSAddress:    customDNSAddressConverted,
-		IsUnixDesktopClient: isUnixRunningDesktop(),
+		IsUnixDesktopClient: util.HasGraphicalSession(),
 		Hostname:            hostName,
 		ExtraIFaceBlacklist: extraIFaceBlackList,
 		DnsLabels:           dnsLabels,
@@ -718,9 +731,6 @@ func setupLoginRequest(providedSetupKey string, customDNSAddressConverted []byte
 		loginRequest.DisableIpv6 = &disableIPv6
 	}
 
-	if cmd.Flag(enableLazyConnectionFlag).Changed {
-		loginRequest.LazyConnectionEnabled = &lazyConnEnabled
-	}
 	return &loginRequest, nil
 }
 

client/configs/configs.go

@@ -6,6 +6,11 @@ import (
 	"runtime"
 )
 
+// UILogFile is the file name the desktop UI writes its log to. It is defined
+// here so the UI (writer), the daemon's RegisterUILog validation, and the debug
+// bundle collector all share one definition.
+const UILogFile = "gui-client.log"
+
 var StateDir string
 
 func init() {

client/embed/embed.go

@@ -21,7 +21,7 @@ import (
 	"github.com/netbirdio/netbird/client/internal/auth"
 	"github.com/netbirdio/netbird/client/internal/peer"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
-	sshcommon "github.com/netbirdio/netbird/client/ssh"
+	nbssh "github.com/netbirdio/netbird/client/ssh"
 	"github.com/netbirdio/netbird/client/system"
 	"github.com/netbirdio/netbird/shared/management/domain"
 	mgmProto "github.com/netbirdio/netbird/shared/management/proto"
@@ -91,6 +91,13 @@ type Options struct {
 	// when the embedded client must never act as a stepping stone into
 	// the host's local network (e.g. the proxy's overlay peer).
 	BlockLANAccess bool
+	// LazyConnectionEnabled is a tri-state local override for lazy connections,
+	// mirroring the NB_LAZY_CONN env var. Nil defers to the management feature
+	// flag; a set value overrides it in both directions. A short-lived client
+	// that reaches only a few known peers can set this to false, so its peers
+	// connect eagerly and the first request does not wait for the connection to
+	// be established.
+	LazyConnectionEnabled *bool
 	// WireguardPort is the port for the tunnel interface. Use 0 for a random port.
 	WireguardPort *int
 	// MTU is the MTU for the tunnel interface.
@@ -220,6 +227,15 @@ func New(opts Options) (*Client, error) {
 		config.PrivateKey = opts.PrivateKey
 	}
 
+	if opts.LazyConnectionEnabled != nil {
+		// Runtime-only override, read back through lazyconn.ParseState; a set value
+		// wins over the management feature flag in both directions.
+		config.LazyConnection = "off"
+		if *opts.LazyConnectionEnabled {
+			config.LazyConnection = "on"
+		}
+	}
+
 	if opts.Performance.PreallocatedBuffersPerPool != nil {
 		wgdevice.SetPreallocatedBuffersPerPool(*opts.Performance.PreallocatedBuffersPerPool)
 	}
@@ -279,9 +295,11 @@ func (c *Client) Start(startCtx context.Context) error {
 
 	select {
 	case <-startCtx.Done():
-		// Cancel the client context before stopping: Engine.Start blocks on the
-		// signal stream while holding the engine mutex and only unblocks on
-		// cancellation. Stopping first would deadlock on that mutex.
+		// ConnectClient.Stop now cancels its own run context and waits for the
+		// run loop to tear the engine down, so this cancel() is no longer
+		// required to break the deadlock and could be removed. It is kept as a
+		// defensive belt-and-suspenders: cancelling the parent context first
+		// guarantees the run loop is unblocked even if Stop's contract regresses.
 		cancel()
 		if stopErr := client.Stop(); stopErr != nil {
 			return fmt.Errorf("stop error after context done. Stop error: %w. Context done: %w", stopErr, startCtx.Err())
@@ -468,7 +486,7 @@ func (c *Client) Status() (peer.FullStatus, error) {
 	if connect != nil {
 		engine := connect.Engine()
 		if engine != nil {
-			_ = engine.RunHealthProbes(false)
+			_ = engine.RunHealthProbes(context.Background(), false)
 		}
 	}
 
@@ -519,12 +537,7 @@ func (c *Client) VerifySSHHostKey(peerAddress string, key []byte) error {
 		return err
 	}
 
-	storedKey, found := engine.GetPeerSSHKey(peerAddress)
-	if !found {
-		return sshcommon.ErrPeerNotFound
-	}
-
-	return sshcommon.VerifyHostKey(storedKey, key, peerAddress)
+	return nbssh.PeerKeyLookup(engine.GetPeerSSHKey).VerifySSHHostKey(peerAddress, key)
 }
 
 // SetPerformance retunes a running Client. Only PreallocatedBuffersPerPool

client/embed/embed_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/golang/mock/gomock"
+	"go.uber.org/mock/gomock"
 	"github.com/stretchr/testify/require"
 	"google.golang.org/grpc"
 

client/firewall/firewalld/firewalld.go

@@ -2,8 +2,8 @@
 // its wg interface into firewalld's "trusted" zone. This is required because
 // firewalld's nftables chains are created with NFT_CHAIN_OWNER on recent
 // versions, which returns EPERM to any other process that tries to insert
-// rules into them. The workaround mirrors what Tailscale does: let firewalld
-// itself add the accept rules to its own chains by trusting the interface.
+// rules into them. Trusting the interface makes firewalld itself add the
+// accept rules to its own chains instead.
 package firewalld
 
 // TrustedZone is the firewalld zone name used for interfaces whose traffic

client/firewall/iptables/acl_linux.go

@@ -42,6 +42,7 @@ type aclManager struct {
 	optionalEntries map[string][]entry
 	ipsetStore      *ipsetStore
 	v6              bool
+	ipsetSupported  bool
 
 	stateManager *statemanager.Manager
 }
@@ -60,6 +61,8 @@ func newAclManager(iptablesClient *iptables.IPTables, wgIface iFaceMapper) (*acl
 func (m *aclManager) init(stateManager *statemanager.Manager) error {
 	m.stateManager = stateManager
 
+	m.ipsetSupported = m.probeIPSetSupport()
+
 	m.seedInitialEntries()
 	m.seedInitialOptionalEntries()
 
@@ -91,6 +94,12 @@ func (m *aclManager) AddPeerFiltering(
 	if m.v6 && ipsetName != "" {
 		ipsetName += "-v6"
 	}
+	// When the kernel lacks the required ipset hash module, fall back to
+	// per-IP iptables rules (pre-0.68 behavior) so ACLs keep working instead
+	// of silently leaving the chain empty.
+	if ipsetName != "" && !m.ipsetSupported {
+		ipsetName = ""
+	}
 	proto := protoForFamily(protocol, m.v6)
 	specs := filterRuleSpecs(ip, proto, sPort, dPort, action, ipsetName)
 
@@ -498,6 +507,40 @@ func transformIPsetName(ipsetName string, sPort, dPort *firewall.Port, action fi
 	}
 }
 
+// probeIPSetSupport checks whether the kernel can create the ipset type used for
+// ACL rules. On kernels lacking the required ipset hash module, ipset creation
+// fails (e.g. "invalid argument"), which would otherwise leave the ACL chain
+// empty and silently drop all policy-permitted inbound traffic. When unsupported,
+// the manager falls back to per-IP iptables rules.
+func (m *aclManager) probeIPSetSupport() bool {
+	// Use a unique name so concurrent processes don't collide and we only ever
+	// destroy the set we created ourselves. ipset names are limited to 31 chars,
+	// so use a short random suffix.
+	probeName := "nb-probe-" + uuid.New().String()[:8]
+
+	opts := ipset.CreateOptions{
+		Replace: true,
+	}
+	if m.v6 {
+		opts.Family = ipset.FamilyIPV6
+	}
+
+	if err := ipset.Create(probeName, ipset.TypeHashNet, opts); err != nil {
+		log.Warnf("ipset is not available (failed to create probe set: %v); "+
+			"falling back to per-IP iptables ACL rules. Ensure the kernel provides "+
+			"the ipset hash:net module (ip_set_hash_net) for better performance with large rule sets", err)
+		return false
+	}
+
+	defer func() {
+		if err := ipset.Destroy(probeName); err != nil {
+			log.Debugf("destroy ipset probe set %q: %v", probeName, err)
+		}
+	}()
+
+	return true
+}
+
 func (m *aclManager) createIPSet(name string) error {
 	opts := ipset.CreateOptions{
 		Replace: true,

client/firewall/iptables/dnat_refcount_linux_test.go

@@ -0,0 +1,240 @@
+//go:build privileged
+
+package iptables
+
+import (
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	fw "github.com/netbirdio/netbird/client/firewall/manager"
+	"github.com/netbirdio/netbird/client/iface"
+	"github.com/netbirdio/netbird/client/iface/wgaddr"
+)
+
+func iptRefcountIfaceV4() *iFaceMock {
+	return &iFaceMock{
+		NameFunc: func() string { return "wt-refcount" },
+		AddressFunc: func() wgaddr.Address {
+			return wgaddr.Address{
+				IP:      netip.MustParseAddr("10.20.0.1"),
+				Network: netip.MustParsePrefix("10.20.0.0/24"),
+			}
+		},
+	}
+}
+
+func iptRefcountIfaceDual() *iFaceMock {
+	return &iFaceMock{
+		NameFunc: func() string { return "wt-refcount" },
+		AddressFunc: func() wgaddr.Address {
+			return wgaddr.Address{
+				IP:      netip.MustParseAddr("10.20.0.1"),
+				Network: netip.MustParsePrefix("10.20.0.0/24"),
+				IPv6:    netip.MustParseAddr("fd00::1"),
+				IPv6Net: netip.MustParsePrefix("fd00::/64"),
+			}
+		},
+	}
+}
+
+func newIptRefcountManager(t *testing.T, dual bool) *Manager {
+	t.Helper()
+	var ifMock *iFaceMock
+	if dual {
+		ifMock = iptRefcountIfaceDual()
+	} else {
+		ifMock = iptRefcountIfaceV4()
+	}
+	m, err := Create(ifMock, iface.DefaultMTU)
+	require.NoError(t, err, "create manager")
+	require.NoError(t, m.Init(nil), "init manager")
+	t.Cleanup(func() {
+		require.NoError(t, m.Close(nil), "close manager")
+	})
+	return m
+}
+
+func iptDnatV4(port uint16) fw.ForwardRule {
+	return fw.ForwardRule{
+		Protocol:          fw.ProtocolTCP,
+		DestinationPort:   fw.Port{Values: []uint16{port}},
+		TranslatedAddress: netip.MustParseAddr("10.20.0.2"),
+		TranslatedPort:    fw.Port{Values: []uint16{80}},
+	}
+}
+
+func iptDnatV6(port uint16) fw.ForwardRule {
+	return fw.ForwardRule{
+		Protocol:          fw.ProtocolTCP,
+		DestinationPort:   fw.Port{Values: []uint16{port}},
+		TranslatedAddress: netip.MustParseAddr("fd00::2"),
+		TranslatedPort:    fw.Port{Values: []uint16{80}},
+	}
+}
+
+// TestIptablesRouting_RepeatedEnableSingleReference verifies that EnableRouting
+// (called on every network-map update) holds at most one reference per family
+// and a single DisableRouting drops both back to zero.
+func TestIptablesRouting_RepeatedEnableSingleReference(t *testing.T) {
+	m := newIptRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	require.NoError(t, m.EnableRouting(), "first enable")
+	require.NoError(t, m.EnableRouting(), "second enable")
+	require.NoError(t, m.EnableRouting(), "third enable")
+	v4, v6 := state.Counts()
+	assert.Equal(t, 1, v4, "repeated enable holds a single v4 reference")
+	assert.Equal(t, 1, v6, "repeated enable holds a single v6 reference")
+
+	require.NoError(t, m.DisableRouting(), "disable")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4, "single disable releases the v4 reference")
+	assert.Equal(t, 0, v6, "single disable releases the v6 reference")
+}
+
+// TestIptablesRouting_DisableKeepsDNATReference verifies that an unpaired
+// DisableRouting does not release references held by active DNAT rules.
+func TestIptablesRouting_DisableKeepsDNATReference(t *testing.T) {
+	m := newIptRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	r1, err := m.AddDNATRule(iptDnatV6(9095))
+	require.NoError(t, err, "add v6 dnat")
+
+	require.NoError(t, m.DisableRouting(), "unpaired disable")
+	_, v6 := state.Counts()
+	assert.Equal(t, 1, v6, "DNAT-held reference survives unpaired DisableRouting")
+
+	require.NoError(t, m.DeleteDNATRule(r1), "delete v6 dnat")
+	_, v6 = state.Counts()
+	assert.Equal(t, 0, v6, "delete releases the DNAT reference")
+}
+
+// TestIptablesDNAT_RefcountBalancedV4 covers a Balanced Add/Delete pair on v4.
+func TestIptablesDNAT_RefcountBalancedV4(t *testing.T) {
+	m := newIptRefcountManager(t, false)
+	state := m.router.ipFwdState
+
+	r1, err := m.AddDNATRule(iptDnatV4(7081))
+	require.NoError(t, err, "add v4 dnat 1")
+	v4, v6 := state.Counts()
+	assert.Equal(t, 1, v4, "v4 refcount after first add")
+	assert.Equal(t, 0, v6, "v6 refcount unchanged")
+
+	r2, err := m.AddDNATRule(iptDnatV4(7082))
+	require.NoError(t, err, "add v4 dnat 2")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 2, v4, "v4 refcount after second add")
+	assert.Equal(t, 0, v6, "v6 refcount unchanged")
+
+	require.NoError(t, m.DeleteDNATRule(r1))
+	v4, v6 = state.Counts()
+	assert.Equal(t, 1, v4, "v4 refcount after first delete")
+	assert.Equal(t, 0, v6, "v6 refcount unchanged")
+
+	require.NoError(t, m.DeleteDNATRule(r2))
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4, "v4 refcount after second delete")
+	assert.Equal(t, 0, v6, "v6 refcount unchanged")
+}
+
+// TestIptablesDNAT_RefcountBalancedV6 checks the v6 path increments v6 only and
+// decrements back to zero.
+func TestIptablesDNAT_RefcountBalancedV6(t *testing.T) {
+	m := newIptRefcountManager(t, true)
+	require.NotNil(t, m.router6, "v6 router")
+	require.Same(t, m.router.ipFwdState, m.router6.ipFwdState, "shared state")
+	state := m.router.ipFwdState
+
+	r1, err := m.AddDNATRule(iptDnatV6(9081))
+	require.NoError(t, err, "add v6 dnat 1")
+	v4, v6 := state.Counts()
+	assert.Equal(t, 0, v4)
+	assert.Equal(t, 1, v6, "v6 refcount after first add")
+
+	r2, err := m.AddDNATRule(iptDnatV6(9082))
+	require.NoError(t, err, "add v6 dnat 2")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4, "v4 refcount unchanged")
+	assert.Equal(t, 2, v6, "v6 refcount after second add")
+
+	require.NoError(t, m.DeleteDNATRule(r1))
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4, "v4 refcount unchanged")
+	assert.Equal(t, 1, v6, "v6 refcount after first delete")
+
+	require.NoError(t, m.DeleteDNATRule(r2))
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4)
+	assert.Equal(t, 0, v6, "v6 refcount after second delete")
+}
+
+// TestIptablesDNAT_DuplicateAddNoLeak verifies the duplicate-rule path returns
+// without bumping the refcount.
+func TestIptablesDNAT_DuplicateAddNoLeak(t *testing.T) {
+	m := newIptRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	rule := iptDnatV4(7083)
+	r1, err := m.AddDNATRule(rule)
+	require.NoError(t, err)
+	v4, _ := state.Counts()
+	assert.Equal(t, 1, v4)
+
+	_, err = m.AddDNATRule(rule)
+	require.NoError(t, err, "duplicate add")
+	v4, _ = state.Counts()
+	assert.Equal(t, 1, v4, "duplicate add must not increment")
+
+	require.NoError(t, m.DeleteDNATRule(r1))
+	v4, _ = state.Counts()
+	assert.Equal(t, 0, v4, "single delete must drop to zero")
+}
+
+// TestIptablesDNAT_DeleteMissingNoUnderflow verifies Delete on an unknown rule
+// neither errors nor releases the refcount.
+func TestIptablesDNAT_DeleteMissingNoUnderflow(t *testing.T) {
+	m := newIptRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	phantom := iptDnatV4(7099)
+	require.NoError(t, m.DeleteDNATRule(&phantom), "delete missing v4")
+	v4, v6 := state.Counts()
+	assert.Equal(t, 0, v4)
+	assert.Equal(t, 0, v6)
+
+	phantom6 := iptDnatV6(9099)
+	require.NoError(t, m.DeleteDNATRule(&phantom6), "delete missing v6")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4)
+	assert.Equal(t, 0, v6)
+
+	r1, err := m.AddDNATRule(iptDnatV4(7100))
+	require.NoError(t, err)
+	v4, _ = state.Counts()
+	assert.Equal(t, 1, v4, "real add still increments after phantom delete")
+	require.NoError(t, m.DeleteDNATRule(r1))
+}
+
+// TestIptablesDNAT_DoubleDeleteNoUnderflow verifies a second Delete on the same
+// rule is a no-op.
+func TestIptablesDNAT_DoubleDeleteNoUnderflow(t *testing.T) {
+	m := newIptRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	r1, err := m.AddDNATRule(iptDnatV6(9083))
+	require.NoError(t, err)
+	_, v6 := state.Counts()
+	assert.Equal(t, 1, v6)
+
+	require.NoError(t, m.DeleteDNATRule(r1), "first delete")
+	_, v6 = state.Counts()
+	assert.Equal(t, 0, v6)
+
+	require.NoError(t, m.DeleteDNATRule(r1), "second delete must be no-op")
+	_, v6 = state.Counts()
+	assert.Equal(t, 0, v6, "double delete must not underflow")
+}

client/firewall/iptables/manager_linux.go

@@ -89,7 +89,7 @@ func (m *Manager) createIPv6Components(wgIface iFaceMapper, mtu uint16) error {
 	}
 
 	// Share the same IP forwarding state with the v4 router, since
-	// EnableIPForwarding controls both v4 and v6 sysctls.
+	// Forwarding refcounter is per-family but shared between v4 and v6 routers.
 	m.router6.ipFwdState = m.router.ipFwdState
 
 	m.aclMgr6, err = newAclManager(ip6Client, wgIface)
@@ -402,17 +402,12 @@ func (m *Manager) SetLogLevel(log.Level) {
 }
 
 func (m *Manager) EnableRouting() error {
-	if err := m.router.ipFwdState.RequestForwarding(); err != nil {
-		return fmt.Errorf("enable IP forwarding: %w", err)
-	}
-	return nil
+	// v6 only when the overlay actually has v6.
+	return m.router.ipFwdState.RequestRouting(m.router6 != nil)
 }
 
 func (m *Manager) DisableRouting() error {
-	if err := m.router.ipFwdState.ReleaseForwarding(); err != nil {
-		return fmt.Errorf("disable IP forwarding: %w", err)
-	}
-	return nil
+	return m.router.ipFwdState.ReleaseRouting()
 }
 
 // AddDNATRule adds a DNAT rule

client/firewall/iptables/manager_linux_test.go

@@ -1,3 +1,5 @@
+//go:build privileged
+
 package iptables
 
 import (
@@ -289,3 +291,40 @@ func TestIptablesCreatePerformance(t *testing.T) {
 		})
 	}
 }
+
+// TestIptablesACLIPSetFallback verifies that when the kernel lacks ipset support,
+// the ACL manager falls back to per-IP iptables rules (-s <ip>) instead of
+// silently leaving the chain empty. See discussion #6125.
+func TestIptablesACLIPSetFallback(t *testing.T) {
+	ipv4Client, err := iptables.NewWithProtocol(iptables.ProtocolIPv4)
+	require.NoError(t, err)
+
+	// Use Create()/Init() so the router-owned chains (chainRTFWDIN/OUT) are
+	// created before the ACL manager's createDefaultChains() references them.
+	manager, err := Create(ifaceMock, iface.DefaultMTU)
+	require.NoError(t, err)
+	require.NoError(t, manager.Init(nil))
+
+	aclMgr := manager.aclMgr
+	// Simulate a kernel without the ipset hash module.
+	aclMgr.ipsetSupported = false
+
+	defer func() {
+		require.NoError(t, manager.Close(nil))
+	}()
+
+	ip := netip.MustParseAddr("10.20.0.42")
+	port := &fw.Port{Values: []uint16{22}}
+
+	rules, err := aclMgr.AddPeerFiltering(nil, ip.AsSlice(), "tcp", nil, port, fw.ActionAccept, "nb0000001")
+	require.NoError(t, err, "AddPeerFiltering should succeed via fallback")
+	require.NotEmpty(t, rules)
+
+	rule := rules[0].(*Rule)
+	require.Empty(t, rule.ipsetName, "fallback rule must not reference an ipset")
+	require.Contains(t, strings.Join(rule.specs, " "), "-s 10.20.0.42", "fallback rule must match by source IP")
+	require.NotContains(t, strings.Join(rule.specs, " "), "--match-set", "fallback rule must not use ipset matching")
+
+	// The rule must actually be present in the ACL chain (not silently dropped).
+	checkRuleSpecs(t, ipv4Client, rule.chain, true, rule.specs...)
+}

client/firewall/iptables/router_linux.go

@@ -102,7 +102,7 @@ func newRouter(iptablesClient *iptables.IPTables, wgIface iFaceMapper, mtu uint1
 		wgIface:        wgIface,
 		mtu:            mtu,
 		v6:             iptablesClient.Proto() == iptables.ProtocolIPv6,
-		ipFwdState:     ipfwdstate.NewIPForwardingState(),
+		ipFwdState:     ipfwdstate.NewIPForwardingState(wgIface.Name()),
 	}
 
 	r.ipsetCounter = refcounter.New(
@@ -770,10 +770,6 @@ func (r *router) updateState() {
 }
 
 func (r *router) AddDNATRule(rule firewall.ForwardRule) (firewall.Rule, error) {
-	if err := r.ipFwdState.RequestForwarding(); err != nil {
-		return nil, err
-	}
-
 	ruleKey := rule.ID()
 	if _, exists := r.rules[ruleKey+dnatSuffix]; exists {
 		return rule, nil
@@ -840,18 +836,34 @@ func (r *router) AddDNATRule(rule firewall.ForwardRule) (firewall.Rule, error) {
 
 	for key, ruleInfo := range rules {
 		if err := r.iptablesClient.Append(ruleInfo.table, ruleInfo.chain, ruleInfo.rule...); err != nil {
-			if rollbackErr := r.rollbackRules(rules); rollbackErr != nil {
-				log.Errorf("rollback failed: %v", rollbackErr)
-			}
+			r.cleanupFailedDNATAdd(rules)
 			return nil, fmt.Errorf("add rule %s: %w", key, err)
 		}
 		r.rules[key] = ruleInfo.rule
 	}
 
+	if err := r.ipFwdState.RequestForwarding(r.v6); err != nil {
+		r.cleanupFailedDNATAdd(rules)
+		return nil, fmt.Errorf("enable forwarding: %w", err)
+	}
+
 	r.updateState()
 	return rule, nil
 }
 
+// cleanupFailedDNATAdd removes the bookkeeping written by a partially applied
+// AddDNATRule before rolling back the kernel rules, so no entries remain that
+// never got a forwarding refcount. rollbackRules re-adds entries it failed to
+// remove from the kernel.
+func (r *router) cleanupFailedDNATAdd(rules map[string]ruleInfo) {
+	for key := range rules {
+		delete(r.rules, key)
+	}
+	if err := r.rollbackRules(rules); err != nil {
+		log.Errorf("rollback failed: %v", err)
+	}
+}
+
 func (r *router) rollbackRules(rules map[string]ruleInfo) error {
 	var merr *multierror.Error
 	for key, ruleInfo := range rules {
@@ -868,32 +880,47 @@ func (r *router) rollbackRules(rules map[string]ruleInfo) error {
 }
 
 func (r *router) DeleteDNATRule(rule firewall.Rule) error {
-	if err := r.ipFwdState.ReleaseForwarding(); err != nil {
-		log.Errorf("%v", err)
-	}
-
 	ruleKey := rule.ID()
 
+	_, hadDNAT := r.rules[ruleKey+dnatSuffix]
+	_, hadSNAT := r.rules[ruleKey+snatSuffix]
+	_, hadFWD := r.rules[ruleKey+fwdSuffix]
+	if !hadDNAT && !hadSNAT && !hadFWD {
+		return nil
+	}
+
 	var merr *multierror.Error
 	if dnatRule, exists := r.rules[ruleKey+dnatSuffix]; exists {
 		if err := r.iptablesClient.Delete(tableNat, chainRTRDR, dnatRule...); err != nil {
 			merr = multierror.Append(merr, fmt.Errorf("delete DNAT rule: %w", err))
+		} else {
+			delete(r.rules, ruleKey+dnatSuffix)
 		}
-		delete(r.rules, ruleKey+dnatSuffix)
 	}
 
 	if snatRule, exists := r.rules[ruleKey+snatSuffix]; exists {
 		if err := r.iptablesClient.Delete(tableNat, chainRTNAT, snatRule...); err != nil {
 			merr = multierror.Append(merr, fmt.Errorf("delete SNAT rule: %w", err))
+		} else {
+			delete(r.rules, ruleKey+snatSuffix)
 		}
-		delete(r.rules, ruleKey+snatSuffix)
 	}
 
 	if fwdRule, exists := r.rules[ruleKey+fwdSuffix]; exists {
 		if err := r.iptablesClient.Delete(tableFilter, chainRTFWDOUT, fwdRule...); err != nil {
 			merr = multierror.Append(merr, fmt.Errorf("delete forward rule: %w", err))
+		} else {
+			delete(r.rules, ruleKey+fwdSuffix)
+		}
+	}
+
+	// Release the refcount only once all rules are gone from the kernel. On
+	// partial failure the failed entries stay in r.rules so a retry can remove
+	// them and release then.
+	if merr == nil {
+		if err := r.ipFwdState.ReleaseForwarding(r.v6); err != nil {
+			log.Errorf("%v", err)
 		}
-		delete(r.rules, ruleKey+fwdSuffix)
 	}
 
 	r.updateState()

client/firewall/iptables/router_linux_test.go

@@ -1,4 +1,4 @@
-//go:build !android
+//go:build !android && privileged
 
 package iptables
 

client/firewall/nftables/dnat_refcount_linux_test.go

@@ -0,0 +1,249 @@
+//go:build privileged
+
+package nftables
+
+import (
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	fw "github.com/netbirdio/netbird/client/firewall/manager"
+	"github.com/netbirdio/netbird/client/iface"
+	"github.com/netbirdio/netbird/client/iface/wgaddr"
+)
+
+func nftRefcountIfaceV4() *iFaceMock {
+	return &iFaceMock{
+		NameFunc: func() string { return "wt-refcount" },
+		AddressFunc: func() wgaddr.Address {
+			return wgaddr.Address{
+				IP:      netip.MustParseAddr("100.96.0.1"),
+				Network: netip.MustParsePrefix("100.96.0.0/16"),
+			}
+		},
+	}
+}
+
+func nftRefcountIfaceDual() *iFaceMock {
+	return &iFaceMock{
+		NameFunc: func() string { return "wt-refcount" },
+		AddressFunc: func() wgaddr.Address {
+			return wgaddr.Address{
+				IP:      netip.MustParseAddr("100.96.0.1"),
+				Network: netip.MustParsePrefix("100.96.0.0/16"),
+				IPv6:    netip.MustParseAddr("fd00::1"),
+				IPv6Net: netip.MustParsePrefix("fd00::/64"),
+			}
+		},
+	}
+}
+
+func newNftRefcountManager(t *testing.T, dual bool) *Manager {
+	t.Helper()
+	if check() != NFTABLES {
+		t.Skip("nftables not supported on this system")
+	}
+	var ifMock *iFaceMock
+	if dual {
+		ifMock = nftRefcountIfaceDual()
+	} else {
+		ifMock = nftRefcountIfaceV4()
+	}
+	m, err := Create(ifMock, iface.DefaultMTU)
+	require.NoError(t, err, "create manager")
+	require.NoError(t, m.Init(nil), "init manager")
+	t.Cleanup(func() {
+		require.NoError(t, m.Close(nil), "close manager")
+	})
+	return m
+}
+
+func dnatV4(port uint16) fw.ForwardRule {
+	return fw.ForwardRule{
+		Protocol:          fw.ProtocolTCP,
+		DestinationPort:   fw.Port{Values: []uint16{port}},
+		TranslatedAddress: netip.MustParseAddr("100.96.0.2"),
+		TranslatedPort:    fw.Port{Values: []uint16{80}},
+	}
+}
+
+func dnatV6(port uint16) fw.ForwardRule {
+	return fw.ForwardRule{
+		Protocol:          fw.ProtocolTCP,
+		DestinationPort:   fw.Port{Values: []uint16{port}},
+		TranslatedAddress: netip.MustParseAddr("fd00::2"),
+		TranslatedPort:    fw.Port{Values: []uint16{80}},
+	}
+}
+
+// TestNftablesDNAT_RefcountBalancedV4 verifies that Add/Delete pairs leave the
+// v4 refcount at zero.
+func TestNftablesDNAT_RefcountBalancedV4(t *testing.T) {
+	m := newNftRefcountManager(t, false)
+	state := m.router.ipFwdState
+
+	r1, err := m.AddDNATRule(dnatV4(8081))
+	require.NoError(t, err, "add v4 dnat 1")
+	v4, v6 := state.Counts()
+	assert.Equal(t, 1, v4, "v4 refcount after first add")
+	assert.Equal(t, 0, v6, "v6 refcount unchanged")
+
+	r2, err := m.AddDNATRule(dnatV4(8082))
+	require.NoError(t, err, "add v4 dnat 2")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 2, v4, "v4 refcount after second add")
+	assert.Equal(t, 0, v6, "v6 refcount unchanged")
+
+	require.NoError(t, m.DeleteDNATRule(r1), "delete v4 dnat 1")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 1, v4, "v4 refcount after first delete")
+	assert.Equal(t, 0, v6, "v6 refcount unchanged")
+
+	require.NoError(t, m.DeleteDNATRule(r2), "delete v4 dnat 2")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4, "v4 refcount after second delete")
+	assert.Equal(t, 0, v6, "v6 refcount unchanged")
+}
+
+// TestNftablesDNAT_RefcountBalancedV6 verifies the v6 path increments v6 only
+// and decrements back to zero on Delete.
+func TestNftablesDNAT_RefcountBalancedV6(t *testing.T) {
+	m := newNftRefcountManager(t, true)
+	require.NotNil(t, m.router6, "v6 router")
+	require.Same(t, m.router.ipFwdState, m.router6.ipFwdState, "shared state")
+	state := m.router.ipFwdState
+
+	r1, err := m.AddDNATRule(dnatV6(9091))
+	require.NoError(t, err, "add v6 dnat 1")
+	v4, v6 := state.Counts()
+	assert.Equal(t, 0, v4, "v4 refcount unchanged")
+	assert.Equal(t, 1, v6, "v6 refcount after first add")
+
+	r2, err := m.AddDNATRule(dnatV6(9092))
+	require.NoError(t, err, "add v6 dnat 2")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4)
+	assert.Equal(t, 2, v6, "v6 refcount after second add")
+
+	require.NoError(t, m.DeleteDNATRule(r1), "delete v6 dnat 1")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4, "v4 refcount unchanged")
+	assert.Equal(t, 1, v6, "v6 refcount after first delete")
+
+	require.NoError(t, m.DeleteDNATRule(r2), "delete v6 dnat 2")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4)
+	assert.Equal(t, 0, v6, "v6 refcount after second delete")
+}
+
+// TestNftablesDNAT_DuplicateAddNoLeak verifies that a duplicate Add (same
+// ForwardRule) does not double-increment the refcount.
+func TestNftablesDNAT_DuplicateAddNoLeak(t *testing.T) {
+	m := newNftRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	rule := dnatV4(8083)
+	r1, err := m.AddDNATRule(rule)
+	require.NoError(t, err, "add v4 dnat")
+	v4, _ := state.Counts()
+	assert.Equal(t, 1, v4)
+
+	// duplicate add: same rule ID, must be a no-op for the refcount.
+	_, err = m.AddDNATRule(rule)
+	require.NoError(t, err, "duplicate add")
+	v4, _ = state.Counts()
+	assert.Equal(t, 1, v4, "duplicate add must not increment")
+
+	require.NoError(t, m.DeleteDNATRule(r1), "delete v4 dnat")
+	v4, _ = state.Counts()
+	assert.Equal(t, 0, v4, "single delete must drop to zero")
+}
+
+// TestNftablesDNAT_DeleteMissingNoUnderflow verifies deleting a rule that was
+// never added does not underflow the refcount.
+func TestNftablesDNAT_DeleteMissingNoUnderflow(t *testing.T) {
+	m := newNftRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	// Construct a Rule reference for something never added. The router stores
+	// rules by ID(), and DeleteDNATRule looks them up in r.rules; a missing
+	// entry must be a no-op rather than calling Release.
+	phantom := dnatV4(8099)
+	require.NoError(t, m.DeleteDNATRule(&phantom), "delete missing v4 dnat")
+	v4, v6 := state.Counts()
+	assert.Equal(t, 0, v4, "v4 refcount unaffected by missing delete")
+	assert.Equal(t, 0, v6, "v6 refcount unaffected")
+
+	phantom6 := dnatV6(9099)
+	require.NoError(t, m.DeleteDNATRule(&phantom6), "delete missing v6 dnat")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4)
+	assert.Equal(t, 0, v6, "v6 refcount unaffected by missing delete")
+
+	// And after a phantom delete, a real add still results in count=1.
+	r1, err := m.AddDNATRule(dnatV4(8100))
+	require.NoError(t, err, "add v4 dnat after phantom delete")
+	v4, _ = state.Counts()
+	assert.Equal(t, 1, v4, "real add still increments after phantom delete")
+	require.NoError(t, m.DeleteDNATRule(r1))
+}
+
+// TestNftablesRouting_RepeatedEnableSingleReference verifies that EnableRouting
+// (called on every network-map update) holds at most one reference per family
+// and a single DisableRouting drops both back to zero.
+func TestNftablesRouting_RepeatedEnableSingleReference(t *testing.T) {
+	m := newNftRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	require.NoError(t, m.EnableRouting(), "first enable")
+	require.NoError(t, m.EnableRouting(), "second enable")
+	require.NoError(t, m.EnableRouting(), "third enable")
+	v4, v6 := state.Counts()
+	assert.Equal(t, 1, v4, "repeated enable holds a single v4 reference")
+	assert.Equal(t, 1, v6, "repeated enable holds a single v6 reference")
+
+	require.NoError(t, m.DisableRouting(), "disable")
+	v4, v6 = state.Counts()
+	assert.Equal(t, 0, v4, "single disable releases the v4 reference")
+	assert.Equal(t, 0, v6, "single disable releases the v6 reference")
+}
+
+// TestNftablesRouting_DisableKeepsDNATReference verifies that an unpaired
+// DisableRouting does not release references held by active DNAT rules.
+func TestNftablesRouting_DisableKeepsDNATReference(t *testing.T) {
+	m := newNftRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	r1, err := m.AddDNATRule(dnatV6(9095))
+	require.NoError(t, err, "add v6 dnat")
+
+	require.NoError(t, m.DisableRouting(), "unpaired disable")
+	_, v6 := state.Counts()
+	assert.Equal(t, 1, v6, "DNAT-held reference survives unpaired DisableRouting")
+
+	require.NoError(t, m.DeleteDNATRule(r1), "delete v6 dnat")
+	_, v6 = state.Counts()
+	assert.Equal(t, 0, v6, "delete releases the DNAT reference")
+}
+
+// TestNftablesDNAT_DoubleDeleteNoUnderflow verifies that deleting the same rule
+// twice does not underflow the refcount (the second delete is a no-op).
+func TestNftablesDNAT_DoubleDeleteNoUnderflow(t *testing.T) {
+	m := newNftRefcountManager(t, true)
+	state := m.router.ipFwdState
+
+	r1, err := m.AddDNATRule(dnatV6(9093))
+	require.NoError(t, err)
+	_, v6 := state.Counts()
+	assert.Equal(t, 1, v6)
+
+	require.NoError(t, m.DeleteDNATRule(r1), "first delete")
+	_, v6 = state.Counts()
+	assert.Equal(t, 0, v6)
+
+	require.NoError(t, m.DeleteDNATRule(r1), "second delete must be no-op")
+	_, v6 = state.Counts()
+	assert.Equal(t, 0, v6, "double delete must not underflow")
+}

client/firewall/nftables/legacy_rule_linux_test.go

@@ -0,0 +1,60 @@
+package nftables
+
+import (
+	"testing"
+
+	"github.com/google/nftables/expr"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBuildLegacyRouteRuleExpressions(t *testing.T) {
+	sourcePayload := &expr.Payload{}
+	sourceCmp := &expr.Cmp{}
+	destinationPayload := &expr.Payload{}
+	destinationCmp := &expr.Cmp{}
+	nilSourceDestination := &expr.Payload{}
+	nilDestinationSource := &expr.Cmp{}
+
+	tests := []struct {
+		name        string
+		source      []expr.Any
+		destination []expr.Any
+		matches     []expr.Any
+	}{
+		{
+			name:        "both non-empty",
+			source:      []expr.Any{sourcePayload, sourceCmp},
+			destination: []expr.Any{destinationPayload, destinationCmp},
+			matches:     []expr.Any{sourcePayload, sourceCmp, destinationPayload, destinationCmp},
+		},
+		{
+			name:        "nil source",
+			destination: []expr.Any{nilSourceDestination},
+			matches:     []expr.Any{nilSourceDestination},
+		},
+		{
+			name:    "nil destination",
+			source:  []expr.Any{nilDestinationSource},
+			matches: []expr.Any{nilDestinationSource},
+		},
+		{
+			name: "both nil",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := buildLegacyRouteRuleExpressions(tt.source, tt.destination)
+
+			require.Len(t, got, len(tt.matches)+2)
+			for i, match := range tt.matches {
+				require.Same(t, match, got[i])
+			}
+
+			require.IsType(t, &expr.Counter{}, got[len(tt.matches)])
+			verdict, ok := got[len(tt.matches)+1].(*expr.Verdict)
+			require.True(t, ok)
+			require.Equal(t, expr.VerdictAccept, verdict.Kind)
+		})
+	}
+}

client/firewall/nftables/manager_linux.go

@@ -105,8 +105,8 @@ func (m *Manager) createIPv6Components(tableName string, wgIface iFaceMapper, mt
 		return fmt.Errorf("create v6 router: %w", err)
 	}
 
-	// Share the same IP forwarding state with the v4 router, since
-	// EnableIPForwarding controls both v4 and v6 sysctls.
+	// Share the per-family forwarding refcounter with the v4 router so a v4
+	// rule and a v6 rule against the same state machine cooperate cleanly.
 	m.router6.ipFwdState = m.router.ipFwdState
 
 	m.aclManager6, err = newAclManager(workTable6, wgIface, chainNameRoutingFw)
@@ -530,17 +530,12 @@ func (m *Manager) SetLogLevel(log.Level) {
 }
 
 func (m *Manager) EnableRouting() error {
-	if err := m.router.ipFwdState.RequestForwarding(); err != nil {
-		return fmt.Errorf("enable IP forwarding: %w", err)
-	}
-	return nil
+	// v6 only when the overlay actually has v6.
+	return m.router.ipFwdState.RequestRouting(m.router6 != nil)
 }
 
 func (m *Manager) DisableRouting() error {
-	if err := m.router.ipFwdState.ReleaseForwarding(); err != nil {
-		return fmt.Errorf("disable IP forwarding: %w", err)
-	}
-	return nil
+	return m.router.ipFwdState.ReleaseRouting()
 }
 
 // Flush rule/chain/set operations from the buffer

client/firewall/nftables/manager_linux_test.go

@@ -1,3 +1,5 @@
+//go:build privileged
+
 package nftables
 
 import (

client/firewall/nftables/router_linux.go

@@ -93,7 +93,7 @@ func newRouter(workTable *nftables.Table, wgIface iFaceMapper, mtu uint16) (*rou
 		rules:      make(map[string]*nftables.Rule),
 		af:         familyForAddr(workTable.Family == nftables.TableFamilyIPv4),
 		wgIface:    wgIface,
-		ipFwdState: ipfwdstate.NewIPForwardingState(),
+		ipFwdState: ipfwdstate.NewIPForwardingState(wgIface.Name()),
 		mtu:        mtu,
 	}
 
@@ -953,6 +953,17 @@ func (r *router) addMSSClampingRules() error {
 	return r.conn.Flush()
 }
 
+func buildLegacyRouteRuleExpressions(sourceExp, destExp []expr.Any) []expr.Any {
+	exprs := make([]expr.Any, 0, len(sourceExp)+len(destExp)+2)
+	exprs = append(exprs, sourceExp...)
+	exprs = append(exprs, destExp...)
+	exprs = append(exprs,
+		&expr.Counter{},
+		&expr.Verdict{Kind: expr.VerdictAccept},
+	)
+	return exprs
+}
+
 // addLegacyRouteRule adds a legacy routing rule for mgmt servers pre route acls
 func (r *router) addLegacyRouteRule(pair firewall.RouterPair) error {
 	sourceExp, err := r.applyNetwork(pair.Source, nil, true)
@@ -965,15 +976,7 @@ func (r *router) addLegacyRouteRule(pair firewall.RouterPair) error {
 		return fmt.Errorf("apply destination: %w", err)
 	}
 
-	exprs := []expr.Any{
-		&expr.Counter{},
-		&expr.Verdict{
-			Kind: expr.VerdictAccept,
-		},
-	}
-
-	exprs = append(exprs, sourceExp...)
-	exprs = append(exprs, destExp...)
+	exprs := buildLegacyRouteRuleExpressions(sourceExp, destExp)
 
 	ruleKey := firewall.GenKey(firewall.ForwardingFormat, pair)
 
@@ -1550,10 +1553,6 @@ func (r *router) refreshRulesMap() error {
 }
 
 func (r *router) AddDNATRule(rule firewall.ForwardRule) (firewall.Rule, error) {
-	if err := r.ipFwdState.RequestForwarding(); err != nil {
-		return nil, err
-	}
-
 	ruleKey := rule.ID()
 	if _, exists := r.rules[ruleKey+dnatSuffix]; exists {
 		return rule, nil
@@ -1564,7 +1563,18 @@ func (r *router) AddDNATRule(rule firewall.ForwardRule) (firewall.Rule, error) {
 		return nil, fmt.Errorf("convert protocol to number: %w", err)
 	}
 
+	// Request forwarding before queueing rules: addDnatRedirect/addDnatMasq
+	// buffer netlink messages on r.conn that the next caller's Flush would
+	// commit if we returned without flushing them ourselves.
+	v6 := r.af.tableFamily == nftables.TableFamilyIPv6
+	if err := r.ipFwdState.RequestForwarding(v6); err != nil {
+		return nil, fmt.Errorf("enable forwarding: %w", err)
+	}
+
 	if err := r.addDnatRedirect(rule, protoNum, ruleKey); err != nil {
+		if rerr := r.ipFwdState.ReleaseForwarding(v6); rerr != nil {
+			log.Warnf("rollback forwarding refcount: %v", rerr)
+		}
 		return nil, err
 	}
 
@@ -1576,6 +1586,11 @@ func (r *router) AddDNATRule(rule firewall.ForwardRule) (firewall.Rule, error) {
 	// TODO: find chains with drop policies and add rules there
 
 	if err := r.conn.Flush(); err != nil {
+		if rerr := r.ipFwdState.ReleaseForwarding(v6); rerr != nil {
+			log.Warnf("rollback forwarding refcount: %v", rerr)
+		}
+		delete(r.rules, ruleKey+dnatSuffix)
+		delete(r.rules, ruleKey+snatSuffix)
 		return nil, fmt.Errorf("flush rules: %w", err)
 	}
 
@@ -1778,16 +1793,18 @@ func (r *router) addDnatMasq(rule firewall.ForwardRule, protoNum uint8, ruleKey
 }
 
 func (r *router) DeleteDNATRule(rule firewall.Rule) error {
-	if err := r.ipFwdState.ReleaseForwarding(); err != nil {
-		log.Errorf("%v", err)
-	}
-
 	ruleKey := rule.ID()
 
 	if err := r.refreshRulesMap(); err != nil {
 		return fmt.Errorf(refreshRulesMapError, err)
 	}
 
+	_, hadDNAT := r.rules[ruleKey+dnatSuffix]
+	_, hadSNAT := r.rules[ruleKey+snatSuffix]
+	if !hadDNAT && !hadSNAT {
+		return nil
+	}
+
 	var merr *multierror.Error
 	var needsFlush bool
 
@@ -1819,9 +1836,16 @@ func (r *router) DeleteDNATRule(rule firewall.Rule) error {
 		}
 	}
 
+	// Release the refcount only once the rules are gone from the kernel. On
+	// failure (including the refreshRulesMap error above) the rules and their
+	// map entries remain, keeping forwarding on until a retry removes them.
 	if merr == nil {
 		delete(r.rules, ruleKey+dnatSuffix)
 		delete(r.rules, ruleKey+snatSuffix)
+
+		if err := r.ipFwdState.ReleaseForwarding(r.af.tableFamily == nftables.TableFamilyIPv6); err != nil {
+			log.Errorf("%v", err)
+		}
 	}
 
 	return nberrors.FormatErrorOrNil(merr)

client/firewall/nftables/router_linux_test.go

@@ -1,4 +1,4 @@
-//go:build !android
+//go:build !android && privileged
 
 package nftables
 

client/firewall/uspfilter/filter.go

@@ -121,6 +121,7 @@ type Manager struct {
 	udpTracker     *conntrack.UDPTracker
 	icmpTracker    *conntrack.ICMPTracker
 	tcpTracker     *conntrack.TCPTracker
+	fragments      *fragmentTracker
 	forwarder      atomic.Pointer[forwarder.Forwarder]
 	pendingCapture atomic.Pointer[forwarder.PacketCapture]
 	logger         *nblog.Logger
@@ -183,6 +184,41 @@ func (d *decoder) decodePacket(data []byte) error {
 	}
 }
 
+// decodeTransport decodes the transport header of a first fragment (which
+// gopacket leaves undecoded) into the decoder and appends its layer type to
+// decoded, so the ACL pipeline can evaluate it like a normal packet. It returns
+// false if the protocol is unsupported or the header is truncated.
+func (d *decoder) decodeTransport(proto layers.IPProtocol, payload []byte) bool {
+	var l4 gopacket.DecodingLayer
+	var layerType gopacket.LayerType
+	var minLen int
+	switch proto {
+	case layers.IPProtocolTCP:
+		l4, layerType, minLen = &d.tcp, layers.LayerTypeTCP, 20
+	case layers.IPProtocolUDP:
+		l4, layerType, minLen = &d.udp, layers.LayerTypeUDP, 8
+	case layers.IPProtocolICMPv4:
+		l4, layerType, minLen = &d.icmp4, layers.LayerTypeICMPv4, 8
+	case layers.IPProtocolICMPv6:
+		l4, layerType, minLen = &d.icmp6, layers.LayerTypeICMPv6, 8
+	default:
+		return false
+	}
+
+	// Reject a fragment too small to hold the full transport header before
+	// decoding: it can't be ACL-evaluated (tiny-fragment attack), and skipping
+	// the decode avoids gopacket allocating an error on the drop path.
+	if len(payload) < minLen {
+		return false
+	}
+
+	if err := l4.DecodeFromBytes(payload, gopacket.NilDecodeFeedback); err != nil {
+		return false
+	}
+	d.decoded = append(d.decoded, layerType)
+	return true
+}
+
 // Create userspace firewall manager constructor
 func Create(iface common.IFaceMapper, disableServerRoutes bool, flowLogger nftypes.FlowLogger, mtu uint16) (*Manager, error) {
 	return create(iface, nil, disableServerRoutes, flowLogger, mtu)
@@ -286,6 +322,8 @@ func create(iface common.IFaceMapper, nativeFirewall firewall.Manager, disableSe
 	if err := m.localipmanager.UpdateLocalIPs(iface); err != nil {
 		return nil, fmt.Errorf("update local IPs: %w", err)
 	}
+	m.fragments = newFragmentTracker(m.logger)
+
 	if disableConntrack {
 		log.Info("conntrack is disabled")
 	} else {
@@ -299,6 +337,7 @@ func create(iface common.IFaceMapper, nativeFirewall firewall.Manager, disableSe
 		}
 	}
 	if err := iface.SetFilter(m); err != nil {
+		m.fragments.Close()
 		return nil, fmt.Errorf("set filter: %w", err)
 	}
 	return m, nil
@@ -694,6 +733,10 @@ func (m *Manager) resetState() {
 		m.tcpTracker.Close()
 	}
 
+	if m.fragments != nil {
+		m.fragments.Close()
+	}
+
 	if fwder := m.forwarder.Load(); fwder != nil {
 		fwder.SetCapture(nil)
 		fwder.Stop()
@@ -1046,19 +1089,20 @@ func (m *Manager) filterInbound(packetData []byte, size int) bool {
 		return true
 	}
 
-	// TODO: pass fragments of routed packets to forwarder
+	// gopacket does not decode the transport header of any IP fragment, so
+	// fragments take a dedicated path: the first fragment's header is decoded
+	// and ACL-evaluated here, and the remaining fragments inherit its verdict.
 	if fragment {
-		if m.logger.Enabled(nblog.LevelTrace) {
-			if d.decoded[0] == layers.LayerTypeIPv4 {
-				m.logger.Trace4("packet is a fragment: src=%v dst=%v id=%v flags=%v",
-					srcIP, dstIP, d.ip4.Id, d.ip4.Flags)
-			} else {
-				m.logger.Trace2("packet is an IPv6 fragment: src=%v dst=%v", srcIP, dstIP)
-			}
-		}
-		return false
+		return m.filterInboundFragment(d, srcIP, dstIP, size)
 	}
 
+	return m.filterInboundDecoded(d, srcIP, dstIP, packetData, size)
+}
+
+// filterInboundDecoded runs the ACL, DNAT and conntrack pipeline on a fully
+// decoded (non-fragment) inbound packet. It returns true if the packet should
+// be dropped.
+func (m *Manager) filterInboundDecoded(d *decoder, srcIP, dstIP netip.Addr, packetData []byte, size int) bool {
 	// TODO: optimize port DNAT by caching matched rules in conntrack
 	if translated := m.translateInboundPortDNAT(packetData, d, srcIP, dstIP); translated {
 		// Re-decode after port DNAT translation to update port information
@@ -1089,33 +1133,226 @@ func (m *Manager) filterInbound(packetData []byte, size int) bool {
 	return m.handleRoutedTraffic(d, srcIP, dstIP, packetData, size)
 }
 
+// fragmentMeta holds the reassembly identity and layout of an IP fragment,
+// extracted uniformly for IPv4 and IPv6.
+type fragmentMeta struct {
+	key fragmentKey
+	// offset is the fragment offset in 8-byte units (zero for the first
+	// fragment).
+	offset uint16
+	// moreFragments is the More Fragments bit. A first fragment with it unset is
+	// an IPv6 atomic fragment (a complete datagram, RFC 6946): it has no trailing
+	// fragments to inherit a verdict, so it must not be recorded.
+	moreFragments bool
+	proto         layers.IPProtocol
+	// l4payload is the fragmentable payload of this fragment. For the first
+	// fragment it starts with the transport header.
+	l4payload []byte
+	// headerEndOctets is the first fragment's payload length in 8-byte units:
+	// the smallest offset a trailing fragment may start at without overlapping
+	// the inspected transport header.
+	headerEndOctets uint16
+}
+
+// fragmentMetadata extracts the fragment identity and layout from a decoded IP
+// fragment. It returns false for fragments it can't interpret (e.g. an IPv6
+// fragment header shorter than 8 bytes), which are then dropped.
+func fragmentMetadata(d *decoder, srcIP, dstIP netip.Addr) (fragmentMeta, bool) {
+	switch d.decoded[0] {
+	case layers.LayerTypeIPv4:
+		payload := d.ip4.Payload
+		return fragmentMeta{
+			key:             fragmentKey{srcIP: srcIP, dstIP: dstIP, id: uint32(d.ip4.Id), proto: uint8(d.ip4.Protocol)},
+			offset:          d.ip4.FragOffset,
+			moreFragments:   d.ip4.Flags&layers.IPv4MoreFragments != 0,
+			proto:           d.ip4.Protocol,
+			l4payload:       payload,
+			headerEndOctets: octets(len(payload)),
+		}, true
+
+	case layers.LayerTypeIPv6:
+		// IPv6 fragment extension header: 8 bytes, followed by the fragmentable
+		// payload. Layout: next header (1), reserved (1), offset+flags (2), id (4).
+		payload := d.ip6.Payload
+		if len(payload) < 8 {
+			return fragmentMeta{}, false
+		}
+		nextHeader := layers.IPProtocol(payload[0])
+		offsetFlags := binary.BigEndian.Uint16(payload[2:4])
+		id := binary.BigEndian.Uint32(payload[4:8])
+		l4 := payload[8:]
+		return fragmentMeta{
+			key:             fragmentKey{srcIP: srcIP, dstIP: dstIP, id: id, proto: uint8(nextHeader)},
+			offset:          offsetFlags >> 3,
+			moreFragments:   offsetFlags&1 != 0,
+			proto:           nextHeader,
+			l4payload:       l4,
+			headerEndOctets: octets(len(l4)),
+		}, true
+
+	default:
+		return fragmentMeta{}, false
+	}
+}
+
+// octets rounds a byte length up to whole 8-byte units, the granularity of the
+// IP fragment offset field.
+func octets(nbytes int) uint16 {
+	return uint16((nbytes + 7) / 8)
+}
+
+// filterInboundFragment decides the fate of an IP fragment. gopacket stops
+// decoding at the network layer for every fragment, so the first fragment's
+// transport header is decoded and ACL-evaluated here and its verdict recorded;
+// the remaining (headerless) fragments inherit that verdict. Anything that
+// cannot be tied to an allowed, non-overlapping first fragment is dropped.
+func (m *Manager) filterInboundFragment(d *decoder, srcIP, dstIP netip.Addr, size int) bool {
+	meta, ok := fragmentMetadata(d, srcIP, dstIP)
+	if !ok {
+		if m.logger.Enabled(nblog.LevelTrace) {
+			m.logger.Trace2("dropping unsupported fragment: src=%v dst=%v", srcIP, dstIP)
+		}
+		return true
+	}
+
+	if meta.offset != 0 {
+		return m.filterTrailingFragment(meta, srcIP, dstIP)
+	}
+
+	// A new first fragment supersedes any recorded verdict for this datagram, so
+	// a re-sent or overlapping offset-zero fragment can't inherit the old one.
+	m.fragments.poison(meta.key)
+
+	// First fragment: decode its transport header so the ACL can evaluate it. A
+	// decode failure means the fragment is too small to hold the full transport
+	// header (RFC 1858 §3 tiny-fragment attack); it can't be evaluated, so drop it.
+	if !d.decodeTransport(meta.proto, meta.l4payload) {
+		if m.logger.Enabled(nblog.LevelTrace) {
+			m.logger.Trace3("dropping first fragment without full L4 header: src=%v dst=%v id=%v",
+				srcIP, dstIP, meta.key.id)
+		}
+		return true
+	}
+
+	return m.filterFirstFragment(d, meta, srcIP, dstIP, size)
+}
+
+// filterTrailingFragment applies a recorded first-fragment verdict to a
+// non-first fragment.
+func (m *Manager) filterTrailingFragment(meta fragmentMeta, srcIP, dstIP netip.Addr) bool {
+	switch m.fragments.verdict(meta.key, meta.offset) {
+	case fragmentAllow:
+		return false
+	case fragmentOverlap:
+		if m.logger.Enabled(nblog.LevelTrace) {
+			m.logger.Trace3("dropping overlapping fragment rewriting inspected header: src=%v dst=%v id=%v",
+				srcIP, dstIP, meta.key.id)
+		}
+		return true
+	default:
+		if m.logger.Enabled(nblog.LevelTrace) {
+			m.logger.Trace3("dropping fragment with no allowed first fragment: src=%v dst=%v id=%v",
+				srcIP, dstIP, meta.key.id)
+		}
+		return true
+	}
+}
+
+// filterFirstFragment runs the verdict part of the inbound pipeline on a first
+// fragment with its transport header decoded. It mirrors filterInboundDecoded
+// but skips DNAT (port rewriting on fragments is unsupported) and forwarder
+// injection (fragments are left to the stack to reassemble, not forwarded).
+// Allowed fragments have their verdict recorded so the datagram's trailing
+// fragments inherit it.
+func (m *Manager) filterFirstFragment(d *decoder, meta fragmentMeta, srcIP, dstIP netip.Addr, size int) bool {
+	if m.stateful && m.isValidTrackedConnection(d, srcIP, dstIP, size) {
+		m.recordFirstFragment(meta)
+		return false
+	}
+
+	if m.localipmanager.IsLocalIP(dstIP) {
+		ruleID, blocked := m.peerACLsBlock(srcIP, d, nil)
+		if blocked {
+			m.storeDropFlow("Dropping local first fragment (ACL denied): rule_id=%s proto=%v src=%s:%d dst=%s:%d",
+				d, srcIP, dstIP, ruleID, size)
+			return true
+		}
+		m.trackInbound(d, srcIP, dstIP, ruleID, size)
+		m.recordFirstFragment(meta)
+		return false
+	}
+
+	if !m.routingEnabled.Load() {
+		if m.logger.Enabled(nblog.LevelTrace) {
+			m.logger.Trace2("Dropping routed fragment (routing disabled): src=%s dst=%s", srcIP, dstIP)
+		}
+		return true
+	}
+	if m.nativeRouter.Load() {
+		m.trackInbound(d, srcIP, dstIP, nil, size)
+		m.recordFirstFragment(meta)
+		return false
+	}
+
+	// TODO: pass fragments of routed packets to the forwarder; until then
+	// allowed routed fragments go to the native stack.
+	srcPort, dstPort := getPortsFromPacket(d)
+	ruleID, pass := m.routeACLsPass(srcIP, dstIP, d.decoded[1], srcPort, dstPort)
+	if !pass {
+		m.storeDropFlow("Dropping routed first fragment (ACL denied): rule_id=%s proto=%v src=%s:%d dst=%s:%d",
+			d, srcIP, dstIP, ruleID, size)
+		return true
+	}
+
+	m.recordFirstFragment(meta)
+	return false
+}
+
+// recordFirstFragment caches an allowed first fragment's verdict for its
+// trailing fragments to inherit. Atomic fragments (no More Fragments bit) are
+// complete datagrams with no trailing fragments, so they are not cached and
+// cannot exhaust the verdict table.
+func (m *Manager) recordFirstFragment(meta fragmentMeta) {
+	if !meta.moreFragments {
+		return
+	}
+	m.fragments.recordAllowed(meta.key, meta.headerEndOctets)
+}
+
+// storeDropFlow logs and records a netflow drop event for an inbound packet
+// denied by the ACLs. msg is the trace format taking rule id, protocol, source
+// and destination.
+func (m *Manager) storeDropFlow(msg string, d *decoder, srcIP, dstIP netip.Addr, ruleID []byte, size int) {
+	pnum := getProtocolFromPacket(d)
+	srcPort, dstPort := getPortsFromPacket(d)
+
+	if m.logger.Enabled(nblog.LevelTrace) {
+		m.logger.Trace6(msg, ruleID, pnum, srcIP, srcPort, dstIP, dstPort)
+	}
+
+	m.flowLogger.StoreEvent(nftypes.EventFields{
+		FlowID:     uuid.New(),
+		Type:       nftypes.TypeDrop,
+		RuleID:     ruleID,
+		Direction:  nftypes.Ingress,
+		Protocol:   pnum,
+		SourceIP:   srcIP,
+		DestIP:     dstIP,
+		SourcePort: srcPort,
+		DestPort:   dstPort,
+		// TODO: icmp type/code
+		RxPackets: 1,
+		RxBytes:   uint64(size),
+	})
+}
+
 // handleLocalTraffic handles local traffic.
 // If it returns true, the packet should be dropped.
 func (m *Manager) handleLocalTraffic(d *decoder, srcIP, dstIP netip.Addr, packetData []byte, size int) bool {
 	ruleID, blocked := m.peerACLsBlock(srcIP, d, packetData)
 	if blocked {
-		pnum := getProtocolFromPacket(d)
-		srcPort, dstPort := getPortsFromPacket(d)
-
-		if m.logger.Enabled(nblog.LevelTrace) {
-			m.logger.Trace6("Dropping local packet (ACL denied): rule_id=%s proto=%v src=%s:%d dst=%s:%d",
-				ruleID, pnum, srcIP, srcPort, dstIP, dstPort)
-		}
-
-		m.flowLogger.StoreEvent(nftypes.EventFields{
-			FlowID:     uuid.New(),
-			Type:       nftypes.TypeDrop,
-			RuleID:     ruleID,
-			Direction:  nftypes.Ingress,
-			Protocol:   pnum,
-			SourceIP:   srcIP,
-			DestIP:     dstIP,
-			SourcePort: srcPort,
-			DestPort:   dstPort,
-			// TODO: icmp type/code
-			RxPackets: 1,
-			RxBytes:   uint64(size),
-		})
+		m.storeDropFlow("Dropping local packet (ACL denied): rule_id=%s proto=%v src=%s:%d dst=%s:%d",
+			d, srcIP, dstIP, ruleID, size)
 		return true
 	}
 
@@ -1168,27 +1405,8 @@ func (m *Manager) handleRoutedTraffic(d *decoder, srcIP, dstIP netip.Addr, packe
 
 	ruleID, pass := m.routeACLsPass(srcIP, dstIP, protoLayer, srcPort, dstPort)
 	if !pass {
-		proto := getProtocolFromPacket(d)
-
-		if m.logger.Enabled(nblog.LevelTrace) {
-			m.logger.Trace6("Dropping routed packet (ACL denied): rule_id=%s proto=%v src=%s:%d dst=%s:%d",
-				ruleID, proto, srcIP, srcPort, dstIP, dstPort)
-		}
-
-		m.flowLogger.StoreEvent(nftypes.EventFields{
-			FlowID:     uuid.New(),
-			Type:       nftypes.TypeDrop,
-			RuleID:     ruleID,
-			Direction:  nftypes.Ingress,
-			Protocol:   proto,
-			SourceIP:   srcIP,
-			DestIP:     dstIP,
-			SourcePort: srcPort,
-			DestPort:   dstPort,
-			// TODO: icmp type/code
-			RxPackets: 1,
-			RxBytes:   uint64(size),
-		})
+		m.storeDropFlow("Dropping routed packet (ACL denied): rule_id=%s proto=%v src=%s:%d dst=%s:%d",
+			d, srcIP, dstIP, ruleID, size)
 		return true
 	}
 

client/firewall/uspfilter/filter_filter_test.go

@@ -5,7 +5,7 @@ import (
 	"net/netip"
 	"testing"
 
-	"github.com/golang/mock/gomock"
+	"go.uber.org/mock/gomock"
 	"github.com/google/gopacket"
 	"github.com/google/gopacket/layers"
 	"github.com/stretchr/testify/require"

client/firewall/uspfilter/filter_routeacl_test.go

@@ -4,7 +4,7 @@ import (
 	"net/netip"
 	"testing"
 
-	"github.com/golang/mock/gomock"
+	"go.uber.org/mock/gomock"
 	"github.com/google/gopacket/layers"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"

client/firewall/uspfilter/forwarder/forwarder.go

@@ -5,7 +5,9 @@ import (
 	"fmt"
 	"net"
 	"net/netip"
+	"os"
 	"runtime"
+	"strconv"
 	"sync"
 	"time"
 
@@ -31,6 +33,11 @@ const (
 	defaultMaxInFlight   = 1024
 	iosReceiveWindow     = 16384
 	iosMaxInFlight       = 256
+
+	// envForceTCPRACK overrides the platform default for gVisor's RACK loss
+	// detection. Set to a truthy value to force RACK on, or a falsy value to
+	// force it off, on any platform.
+	envForceTCPRACK = "NB_FORCE_TCP_RACK"
 )
 
 type Forwarder struct {
@@ -152,6 +159,8 @@ func New(iface common.IFaceMapper, logger *nblog.Logger, flowLogger nftypes.Flow
 		maxInFlight = iosMaxInFlight
 	}
 
+	configureTCPRecovery(s)
+
 	tcpForwarder := tcp.NewForwarder(s, receiveWindow, maxInFlight, f.handleTCP)
 	s.SetTransportProtocolHandler(tcp.ProtocolNumber, tcpForwarder.HandlePacket)
 
@@ -466,3 +475,31 @@ func probeRawICMP(network, addr string, logger *nblog.Logger) bool {
 	logger.Debug1("forwarder: raw %s socket access available", network)
 	return true
 }
+
+// configureTCPRecovery disables gVisor's RACK loss detection on Windows, where
+// it interacts poorly with the host and collapses throughput on routed TCP
+// connections (gVisor issue #9778). Other platforms keep the default. The
+// EnvForceTCPRACK environment variable overrides the platform default.
+func configureTCPRecovery(s *stack.Stack) {
+	disableRACK := runtime.GOOS == "windows"
+
+	if val := os.Getenv(envForceTCPRACK); val != "" {
+		force, err := strconv.ParseBool(val)
+		if err != nil {
+			log.Warnf("parse %s: %v", envForceTCPRACK, err)
+		} else {
+			disableRACK = !force
+		}
+	}
+
+	if !disableRACK {
+		return
+	}
+
+	opt := tcpip.TCPRecovery(0)
+	if err := s.SetTransportProtocolOption(tcp.ProtocolNumber, &opt); err != nil {
+		log.Warnf("disable TCP RACK loss detection: %v", err)
+		return
+	}
+	log.Info("forwarder: TCP RACK loss detection disabled")
+}

client/firewall/uspfilter/fragment.go

@@ -0,0 +1,204 @@
+package uspfilter
+
+import (
+	"context"
+	"net/netip"
+	"os"
+	"strconv"
+	"sync"
+	"time"
+
+	nblog "github.com/netbirdio/netbird/client/firewall/uspfilter/log"
+)
+
+const (
+	// defaultFragmentTimeout bounds how long a first-fragment verdict is kept
+	// while the remaining fragments arrive. It mirrors the Linux IP reassembly
+	// timeout (net.ipv4.ipfrag_time).
+	defaultFragmentTimeout = 30 * time.Second
+	// fragmentCleanupInterval is how often expired verdicts are purged.
+	fragmentCleanupInterval = 10 * time.Second
+	// defaultMaxFragmentEntries caps the number of concurrently tracked
+	// fragmented datagrams. The table stays bounded because each datagram is a
+	// single small entry regardless of how many fragments it is split into, and
+	// the 13-bit IPv4 fragment-offset field limits any datagram to 64 KiB.
+	defaultMaxFragmentEntries = 16384
+
+	// EnvFragmentMaxEntries overrides defaultMaxFragmentEntries.
+	EnvFragmentMaxEntries = "NB_FRAGMENT_MAX_ENTRIES"
+)
+
+// fragmentVerdict is the decision for a trailing (headerless) fragment.
+type fragmentVerdict int
+
+const (
+	// fragmentDeny drops the fragment: no allowed first fragment is on record.
+	fragmentDeny fragmentVerdict = iota
+	// fragmentAllow passes the fragment: it belongs to an allowed datagram and
+	// does not overlap the already-inspected transport header.
+	fragmentAllow
+	// fragmentOverlap drops the fragment and poisons its datagram: it overlaps
+	// the transport header the ACL inspected (RFC 1858 §4, RFC 3128; RFC 5722
+	// requires discarding the whole datagram on overlap for IPv6).
+	fragmentOverlap
+)
+
+// fragmentKey identifies a fragmented datagram. It matches the RFC 791 / RFC
+// 8200 reassembly key: source, destination, protocol and identification. The id
+// is 32-bit to hold both the IPv4 (16-bit) and IPv6 (32-bit) identification.
+type fragmentKey struct {
+	srcIP netip.Addr
+	dstIP netip.Addr
+	id    uint32
+	proto uint8
+}
+
+// fragmentEntry records the verdict of an allowed first fragment.
+type fragmentEntry struct {
+	// headerEndOctets is the offset, in 8-byte units, at which the first
+	// fragment's payload ended. A trailing fragment starting before this
+	// overlaps bytes the ACL already inspected and is rejected.
+	headerEndOctets uint16
+	// recordedAt is when the first fragment was accepted. The verdict expires a
+	// fixed timeout later and is not refreshed, mirroring the kernel reassembly
+	// timer so a trailing-fragment flood can't keep a datagram alive.
+	recordedAt time.Time
+}
+
+// fragmentTracker records the ACL verdict of a datagram's first fragment so the
+// remaining fragments, which carry no L4 header, can inherit the decision
+// without reassembling the datagram. Only allowed first fragments are stored;
+// anything that cannot be tied to an allowed, non-overlapping first fragment is
+// dropped (fail closed).
+type fragmentTracker struct {
+	logger  *nblog.Logger
+	mutex   sync.Mutex
+	entries map[fragmentKey]fragmentEntry
+	timeout time.Duration
+	// maxEntries caps the table; atCapacity dedups the capacity warning until
+	// the table drains below the cap again.
+	maxEntries    int
+	atCapacity    bool
+	cleanupTicker *time.Ticker
+	cancel        context.CancelFunc
+}
+
+func newFragmentTracker(logger *nblog.Logger) *fragmentTracker {
+	ctx, cancel := context.WithCancel(context.Background())
+	t := &fragmentTracker{
+		logger:        logger,
+		entries:       make(map[fragmentKey]fragmentEntry),
+		timeout:       defaultFragmentTimeout,
+		maxEntries:    fragmentMaxEntries(logger),
+		cleanupTicker: time.NewTicker(fragmentCleanupInterval),
+		cancel:        cancel,
+	}
+	go t.cleanupRoutine(ctx)
+	return t
+}
+
+func fragmentMaxEntries(logger *nblog.Logger) int {
+	v := os.Getenv(EnvFragmentMaxEntries)
+	if v == "" {
+		return defaultMaxFragmentEntries
+	}
+	n, err := strconv.Atoi(v)
+	if err != nil || n <= 0 {
+		logger.Warn2("invalid %s=%q, using default", EnvFragmentMaxEntries, v)
+		return defaultMaxFragmentEntries
+	}
+	return n
+}
+
+// recordAllowed stores the verdict of an allowed first fragment. headerEndOctets
+// is the first fragment's payload length in 8-byte units. When the table is full
+// the record is dropped, which fails closed: the datagram's trailing fragments
+// will be denied.
+func (t *fragmentTracker) recordAllowed(key fragmentKey, headerEndOctets uint16) {
+	t.mutex.Lock()
+	defer t.mutex.Unlock()
+
+	if t.entries == nil {
+		return
+	}
+	if _, ok := t.entries[key]; !ok && len(t.entries) >= t.maxEntries {
+		if !t.atCapacity {
+			t.atCapacity = true
+			t.logger.Warn2("fragment verdict table at capacity (%d/%d): trailing fragments of new datagrams will be dropped",
+				len(t.entries), t.maxEntries)
+		}
+		return
+	}
+	t.entries[key] = fragmentEntry{
+		headerEndOctets: headerEndOctets,
+		recordedAt:      time.Now(),
+	}
+}
+
+// poison drops any recorded verdict for a datagram, so its later fragments are
+// denied until a new allowed first fragment is recorded. Called on every
+// offset-zero fragment to defeat offset-zero overlap rewrites (RFC 3128).
+func (t *fragmentTracker) poison(key fragmentKey) {
+	t.mutex.Lock()
+	defer t.mutex.Unlock()
+	delete(t.entries, key)
+}
+
+// verdict decides the fate of a trailing fragment at fragOffsetOctets (the IPv4
+// fragment offset, in 8-byte units). A fragment overlapping the inspected
+// header poisons the datagram: the entry is removed so all further fragments of
+// that datagram are denied too.
+func (t *fragmentTracker) verdict(key fragmentKey, fragOffsetOctets uint16) fragmentVerdict {
+	t.mutex.Lock()
+	defer t.mutex.Unlock()
+
+	entry, ok := t.entries[key]
+	if !ok {
+		return fragmentDeny
+	}
+	if time.Since(entry.recordedAt) > t.timeout {
+		delete(t.entries, key)
+		return fragmentDeny
+	}
+	if fragOffsetOctets < entry.headerEndOctets {
+		delete(t.entries, key)
+		return fragmentOverlap
+	}
+	return fragmentAllow
+}
+
+func (t *fragmentTracker) cleanupRoutine(ctx context.Context) {
+	defer t.cleanupTicker.Stop()
+	for {
+		select {
+		case <-t.cleanupTicker.C:
+			t.cleanup()
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+func (t *fragmentTracker) cleanup() {
+	t.mutex.Lock()
+	defer t.mutex.Unlock()
+
+	for key, entry := range t.entries {
+		if time.Since(entry.recordedAt) > t.timeout {
+			delete(t.entries, key)
+		}
+	}
+
+	if len(t.entries) < t.maxEntries {
+		t.atCapacity = false
+	}
+}
+
+// Close stops the cleanup routine and releases resources.
+func (t *fragmentTracker) Close() {
+	t.cancel()
+
+	t.mutex.Lock()
+	t.entries = nil
+	t.mutex.Unlock()
+}

client/firewall/uspfilter/fragment_bench_test.go

@@ -0,0 +1,115 @@
+package uspfilter
+
+import (
+	"encoding/binary"
+	"testing"
+)
+
+// benchFilterInbound drives filterInbound over a fixed packet in a tight loop.
+// Packets are built once, outside the timed region, so the benchmark measures
+// only pipeline cost, which is what an attacker can amplify.
+func benchFilterInbound(b *testing.B, pkt []byte) {
+	b.Helper()
+	b.ReportAllocs()
+	b.SetBytes(int64(len(pkt)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		m := benchManager
+		m.filterInbound(pkt, len(pkt))
+	}
+}
+
+// benchManager is a package-level manager reused across fragment benchmarks so
+// setup cost stays out of the timed region.
+var benchManager *Manager
+
+func setupBenchManager(b *testing.B) *Manager {
+	b.Helper()
+	m := newFragmentTestManager(b)
+	allowUDP(b, m, 8080)
+	// Disable conntrack so the allowed-first-fragment path measures transport
+	// decode + ACL every iteration instead of matching the connection tracked
+	// on the first iteration.
+	m.stateful = false
+	benchManager = m
+	return m
+}
+
+// BenchmarkInbound_NormalPacket is the baseline: a full, non-fragmented UDP
+// packet that passes the ACL. Fragment paths should stay comparable to this.
+func BenchmarkInbound_NormalPacket(b *testing.B) {
+	setupBenchManager(b)
+	pkt := normalUDPPacket(b, 8080, 32)
+	benchFilterInbound(b, pkt)
+}
+
+// BenchmarkInbound_FirstFragmentAllowed measures the first-fragment path:
+// transport decode + ACL evaluation + verdict record.
+func BenchmarkInbound_FirstFragmentAllowed(b *testing.B) {
+	setupBenchManager(b)
+	pkt := firstFragmentUDP(b, 0x2000, 8080, 32)
+	benchFilterInbound(b, pkt)
+}
+
+// BenchmarkInbound_TrailingFragmentAllowed measures the common trailing-fragment
+// path: a single map lookup after the first fragment is on record.
+func BenchmarkInbound_TrailingFragmentAllowed(b *testing.B) {
+	m := setupBenchManager(b)
+	first := firstFragmentUDP(b, 0x3000, 8080, 32)
+	m.filterInbound(first, len(first))
+	pkt := trailingFragment(b, 0x3000, 5, false, 24)
+	benchFilterInbound(b, pkt)
+}
+
+// BenchmarkInbound_TrailingFragmentNoFirst is the primary DoS vector: an
+// attacker floods trailing fragments with no first fragment on record. Each is
+// a map miss and must be cheap.
+func BenchmarkInbound_TrailingFragmentNoFirst(b *testing.B) {
+	setupBenchManager(b)
+	pkt := trailingFragment(b, 0x4000, 185, false, 40)
+	benchFilterInbound(b, pkt)
+}
+
+// BenchmarkInbound_TinyFirstFragment measures the tiny-fragment drop path: a
+// first fragment too small to decode a transport header.
+func BenchmarkInbound_TinyFirstFragment(b *testing.B) {
+	setupBenchManager(b)
+	pkt := trailingFragment(b, 0x5000, 0, true, 4)
+	benchFilterInbound(b, pkt)
+}
+
+// BenchmarkInbound_TrailingFragmentDistinctIDs is the worst case for the
+// verdict table: an attacker varies the datagram id on every packet so no first
+// fragment ever matches. Verdict lookups always miss and nothing is recorded,
+// so the table cannot grow. Each iteration rewrites the id field in place.
+func BenchmarkInbound_TrailingFragmentDistinctIDs(b *testing.B) {
+	setupBenchManager(b)
+	pkt := trailingFragment(b, 0x6000, 185, false, 40)
+	m := benchManager
+
+	b.ReportAllocs()
+	b.SetBytes(int64(len(pkt)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		// IPv4 identification field is at bytes 4:6.
+		binary.BigEndian.PutUint16(pkt[4:6], uint16(i))
+		m.filterInbound(pkt, len(pkt))
+	}
+}
+
+// BenchmarkInbound_FirstFragmentDistinctIDs measures sustained first-fragment
+// pressure with distinct ids: transport decode + ACL + verdict insert until the
+// table caps, exercising the map growth and capacity guard.
+func BenchmarkInbound_FirstFragmentDistinctIDs(b *testing.B) {
+	setupBenchManager(b)
+	pkt := firstFragmentUDP(b, 0x7000, 8080, 32)
+	m := benchManager
+
+	b.ReportAllocs()
+	b.SetBytes(int64(len(pkt)))
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		binary.BigEndian.PutUint16(pkt[4:6], uint16(i))
+		m.filterInbound(pkt, len(pkt))
+	}
+}

client/firewall/uspfilter/fragment_test.go

@@ -0,0 +1,554 @@
+package uspfilter
+
+import (
+	"encoding/binary"
+	"net"
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/google/gopacket"
+	"github.com/google/gopacket/layers"
+	"github.com/stretchr/testify/require"
+
+	fw "github.com/netbirdio/netbird/client/firewall/manager"
+	nbiface "github.com/netbirdio/netbird/client/iface"
+	"github.com/netbirdio/netbird/client/iface/device"
+	"github.com/netbirdio/netbird/client/iface/wgaddr"
+)
+
+const (
+	fragTestSrc   = "100.10.0.1"
+	fragTestDst   = "100.10.0.100"
+	fragTestSrcV6 = "fd00::1"
+	fragTestDstV6 = "fd00::100"
+)
+
+func newFragmentTestManager(tb testing.TB) *Manager {
+	tb.Helper()
+
+	ifaceMock := &IFaceMock{
+		SetFilterFunc: func(device.PacketFilter) error { return nil },
+		AddressFunc: func() wgaddr.Address {
+			return wgaddr.Address{
+				IP:      netip.MustParseAddr(fragTestDst),
+				Network: netip.MustParsePrefix("100.10.0.0/16"),
+				IPv6:    netip.MustParseAddr(fragTestDstV6),
+				IPv6Net: netip.MustParsePrefix("fd00::/64"),
+			}
+		},
+	}
+
+	m, err := Create(ifaceMock, false, flowLogger, nbiface.DefaultMTU)
+	require.NoError(tb, err)
+	require.NoError(tb, m.UpdateLocalIPs())
+	tb.Cleanup(func() { require.NoError(tb, m.Close(nil)) })
+	return m
+}
+
+// firstFragmentUDPTo builds the first fragment of a fragmented UDP datagram to
+// the given destination: it carries the full UDP header plus payloadLen bytes
+// of data, with the More Fragments flag set and offset zero.
+func firstFragmentUDPTo(tb testing.TB, dst string, id uint16, dstPort uint16, payloadLen int) []byte {
+	tb.Helper()
+
+	ip := &layers.IPv4{
+		Version:  4,
+		TTL:      64,
+		Id:       id,
+		Protocol: layers.IPProtocolUDP,
+		SrcIP:    net.ParseIP(fragTestSrc),
+		DstIP:    net.ParseIP(dst),
+		Flags:    layers.IPv4MoreFragments,
+	}
+	udp := &layers.UDP{SrcPort: 40000, DstPort: layers.UDPPort(dstPort)}
+	require.NoError(tb, udp.SetNetworkLayerForChecksum(ip))
+
+	buf := gopacket.NewSerializeBuffer()
+	opts := gopacket.SerializeOptions{ComputeChecksums: true, FixLengths: true}
+	require.NoError(tb, gopacket.SerializeLayers(buf, opts, ip, udp, gopacket.Payload(make([]byte, payloadLen))))
+	return buf.Bytes()
+}
+
+func firstFragmentUDP(tb testing.TB, id uint16, dstPort uint16, payloadLen int) []byte {
+	tb.Helper()
+	return firstFragmentUDPTo(tb, fragTestDst, id, dstPort, payloadLen)
+}
+
+// firstFragmentTCP builds the first fragment of a fragmented TCP datagram: the
+// full 20-byte TCP header plus 12 bytes of data, with the More Fragments flag
+// set and offset zero.
+func firstFragmentTCP(tb testing.TB, id uint16, dstPort uint16) []byte {
+	tb.Helper()
+
+	ip := &layers.IPv4{
+		Version:  4,
+		TTL:      64,
+		Id:       id,
+		Protocol: layers.IPProtocolTCP,
+		SrcIP:    net.ParseIP(fragTestSrc),
+		DstIP:    net.ParseIP(fragTestDst),
+		Flags:    layers.IPv4MoreFragments,
+	}
+	tcp := &layers.TCP{SrcPort: 40000, DstPort: layers.TCPPort(dstPort), SYN: true, Window: 64240}
+	require.NoError(tb, tcp.SetNetworkLayerForChecksum(ip))
+
+	buf := gopacket.NewSerializeBuffer()
+	opts := gopacket.SerializeOptions{ComputeChecksums: true, FixLengths: true}
+	require.NoError(tb, gopacket.SerializeLayers(buf, opts, ip, tcp, gopacket.Payload(make([]byte, 12))))
+	return buf.Bytes()
+}
+
+// trailingFragmentTo builds a non-first fragment to the given destination: an
+// IPv4 header at the given fragment offset (in 8-byte units) carrying raw
+// payload and no L4 header.
+func trailingFragmentTo(tb testing.TB, dst string, proto layers.IPProtocol, id uint16, fragOffsetOctets uint16, moreFragments bool, payloadLen int) []byte {
+	tb.Helper()
+
+	ip := &layers.IPv4{
+		Version:    4,
+		TTL:        64,
+		Id:         id,
+		Protocol:   proto,
+		SrcIP:      net.ParseIP(fragTestSrc),
+		DstIP:      net.ParseIP(dst),
+		FragOffset: fragOffsetOctets,
+	}
+	if moreFragments {
+		ip.Flags = layers.IPv4MoreFragments
+	}
+
+	buf := gopacket.NewSerializeBuffer()
+	opts := gopacket.SerializeOptions{FixLengths: true}
+	require.NoError(tb, gopacket.SerializeLayers(buf, opts, ip, gopacket.Payload(make([]byte, payloadLen))))
+	return buf.Bytes()
+}
+
+func trailingFragment(tb testing.TB, id uint16, fragOffsetOctets uint16, moreFragments bool, payloadLen int) []byte {
+	tb.Helper()
+	return trailingFragmentTo(tb, fragTestDst, layers.IPProtocolUDP, id, fragOffsetOctets, moreFragments, payloadLen)
+}
+
+// outboundUDPPacket builds a complete outbound UDP packet from the local
+// address, used to establish conntrack state for reply-direction tests.
+func outboundUDPPacket(tb testing.TB, srcPort, dstPort uint16) []byte {
+	tb.Helper()
+
+	ip := &layers.IPv4{
+		Version:  4,
+		TTL:      64,
+		Id:       1,
+		Protocol: layers.IPProtocolUDP,
+		SrcIP:    net.ParseIP(fragTestDst),
+		DstIP:    net.ParseIP(fragTestSrc),
+	}
+	udp := &layers.UDP{SrcPort: layers.UDPPort(srcPort), DstPort: layers.UDPPort(dstPort)}
+	require.NoError(tb, udp.SetNetworkLayerForChecksum(ip))
+
+	buf := gopacket.NewSerializeBuffer()
+	opts := gopacket.SerializeOptions{ComputeChecksums: true, FixLengths: true}
+	require.NoError(tb, gopacket.SerializeLayers(buf, opts, ip, udp, gopacket.Payload(make([]byte, 16))))
+	return buf.Bytes()
+}
+
+// normalUDPPacket builds a complete, non-fragmented UDP packet for baseline
+// comparisons against the fragment paths.
+func normalUDPPacket(tb testing.TB, dstPort uint16, payloadLen int) []byte {
+	tb.Helper()
+
+	ip := &layers.IPv4{
+		Version:  4,
+		TTL:      64,
+		Id:       1,
+		Protocol: layers.IPProtocolUDP,
+		SrcIP:    net.ParseIP(fragTestSrc),
+		DstIP:    net.ParseIP(fragTestDst),
+	}
+	udp := &layers.UDP{SrcPort: 40000, DstPort: layers.UDPPort(dstPort)}
+	require.NoError(tb, udp.SetNetworkLayerForChecksum(ip))
+
+	buf := gopacket.NewSerializeBuffer()
+	opts := gopacket.SerializeOptions{ComputeChecksums: true, FixLengths: true}
+	require.NoError(tb, gopacket.SerializeLayers(buf, opts, ip, udp, gopacket.Payload(make([]byte, payloadLen))))
+	return buf.Bytes()
+}
+
+func allowUDP(tb testing.TB, m *Manager, dstPort uint16) {
+	tb.Helper()
+	_, err := m.AddPeerFiltering(nil, net.ParseIP(fragTestSrc), fw.ProtocolUDP, nil,
+		&fw.Port{Values: []uint16{dstPort}}, fw.ActionAccept, "")
+	require.NoError(tb, err)
+}
+
+// TestFragment_TrailingWithoutFirstDropped is the core bypass repro: a trailing
+// fragment with no allowed first fragment on record must be dropped. Before the
+// fix, filterInbound returned false (allow) for any fragment.
+func TestFragment_TrailingWithoutFirstDropped(t *testing.T) {
+	m := newFragmentTestManager(t)
+
+	frag := trailingFragment(t, 0x1234, 185, false, 40)
+	require.True(t, m.filterInbound(frag, len(frag)),
+		"trailing fragment without an allowed first fragment must be dropped")
+}
+
+// TestFragment_AllowedFirstPassesTrailing verifies that once a first fragment
+// passes the ACL, its trailing fragments inherit the allow verdict.
+func TestFragment_AllowedFirstPassesTrailing(t *testing.T) {
+	m := newFragmentTestManager(t)
+	allowUDP(t, m, 8080)
+
+	// First fragment: UDP header (8) + 32 payload = 40 octets -> headerEnd = 5.
+	first := firstFragmentUDP(t, 0x2222, 8080, 32)
+	require.False(t, m.filterInbound(first, len(first)),
+		"allowed first fragment should pass and be recorded")
+
+	trailing := trailingFragment(t, 0x2222, 5, false, 24)
+	require.False(t, m.filterInbound(trailing, len(trailing)),
+		"trailing fragment of an allowed datagram should pass")
+}
+
+// TestFragment_DeniedFirstDropsTrailing verifies that a first fragment blocked
+// by the ACL leaves no verdict, so its trailing fragments are dropped.
+func TestFragment_DeniedFirstDropsTrailing(t *testing.T) {
+	m := newFragmentTestManager(t)
+	// No accept rule: local traffic defaults to deny.
+
+	first := firstFragmentUDP(t, 0x3333, 9999, 32)
+	require.True(t, m.filterInbound(first, len(first)),
+		"first fragment to a blocked port should be dropped by the ACL")
+
+	trailing := trailingFragment(t, 0x3333, 5, false, 24)
+	require.True(t, m.filterInbound(trailing, len(trailing)),
+		"trailing fragment of a denied datagram must be dropped")
+}
+
+// TestFragment_OverlappingHeaderDropped covers the RFC 1858 §4 / RFC 3128
+// overlapping-fragment rewrite: a trailing fragment starting inside the range
+// the ACL already inspected is dropped and poisons the datagram. TCP is used so
+// the overlap lands on real header bytes (the flags at byte 13).
+func TestFragment_OverlappingHeaderDropped(t *testing.T) {
+	m := newFragmentTestManager(t)
+	_, err := m.AddPeerFiltering(nil, net.ParseIP(fragTestSrc), fw.ProtocolTCP, nil,
+		&fw.Port{Values: []uint16{8080}}, fw.ActionAccept, "")
+	require.NoError(t, err)
+
+	// First fragment: TCP header (20) + 12 data = 32 bytes -> headerEnd = 4 octets.
+	first := firstFragmentTCP(t, 0x4444, 8080)
+	require.False(t, m.filterInbound(first, len(first)))
+
+	// Overlapping fragment at offset 1 (byte 8) falls inside the inspected TCP
+	// header, so it could rewrite the flags or port on reassembly.
+	overlap := trailingFragmentTo(t, fragTestDst, layers.IPProtocolTCP, 0x4444, 1, true, 32)
+	require.True(t, m.filterInbound(overlap, len(overlap)),
+		"fragment overlapping the inspected header must be dropped")
+
+	// The datagram is now poisoned: a later, non-overlapping fragment is also
+	// dropped because the verdict was removed.
+	later := trailingFragmentTo(t, fragTestDst, layers.IPProtocolTCP, 0x4444, 4, false, 24)
+	require.True(t, m.filterInbound(later, len(later)),
+		"fragments after an overlap must be dropped (datagram poisoned)")
+}
+
+// TestFragment_OffsetZeroOverlapPoisons covers the RFC 3128 offset-zero rewrite:
+// an allowed first fragment followed by a denied offset-zero fragment for the
+// same datagram must not leave the earlier allow verdict in place.
+func TestFragment_OffsetZeroOverlapPoisons(t *testing.T) {
+	m := newFragmentTestManager(t)
+	allowUDP(t, m, 8080)
+
+	allowed := firstFragmentUDP(t, 0x5A5A, 8080, 32)
+	require.False(t, m.filterInbound(allowed, len(allowed)),
+		"allowed first fragment should pass and be recorded")
+
+	// A second offset-zero fragment to a denied port supersedes the datagram's
+	// verdict; it is dropped and must not leave the allow in place.
+	denied := firstFragmentUDP(t, 0x5A5A, 9999, 32)
+	require.True(t, m.filterInbound(denied, len(denied)),
+		"denied offset-zero fragment must be dropped")
+
+	trailing := trailingFragment(t, 0x5A5A, 5, false, 24)
+	require.True(t, m.filterInbound(trailing, len(trailing)),
+		"trailing fragment must be denied after the datagram was poisoned")
+}
+
+// TestFragment_TinyFirstDropped covers the tiny-fragment attack: a first
+// fragment too small to contain the full transport header can't be
+// ACL-evaluated and must be dropped.
+func TestFragment_TinyFirstDropped(t *testing.T) {
+	m := newFragmentTestManager(t)
+	allowUDP(t, m, 8080)
+
+	// IPv4 header + 4 raw bytes, MF set, offset 0: too small for the 8-byte UDP
+	// header, so it decodes to L3 only.
+	tiny := trailingFragment(t, 0x5555, 0, true, 4)
+	require.True(t, m.filterInbound(tiny, len(tiny)),
+		"tiny first fragment without a full L4 header must be dropped")
+}
+
+// TestFragment_TCPFirstFragment verifies the TCP arm of the transport decode: a
+// first fragment carrying the full 20-byte TCP header is ACL-evaluated and its
+// trailing fragments inherit the verdict.
+func TestFragment_TCPFirstFragment(t *testing.T) {
+	m := newFragmentTestManager(t)
+	_, err := m.AddPeerFiltering(nil, net.ParseIP(fragTestSrc), fw.ProtocolTCP, nil,
+		&fw.Port{Values: []uint16{8080}}, fw.ActionAccept, "")
+	require.NoError(t, err)
+
+	// TCP header (20) + 12 data = 32 bytes -> headerEnd = 4 octets.
+	first := firstFragmentTCP(t, 0x6666, 8080)
+	require.False(t, m.filterInbound(first, len(first)),
+		"allowed TCP first fragment should pass and be recorded")
+
+	trailing := trailingFragmentTo(t, fragTestDst, layers.IPProtocolTCP, 0x6666, 4, false, 24)
+	require.False(t, m.filterInbound(trailing, len(trailing)),
+		"trailing fragment of an allowed TCP datagram should pass")
+}
+
+// TestFragment_TCPTinyFirstDropped verifies the TCP minimum header length: 12
+// bytes would satisfy a UDP header but falls short of the 20-byte TCP header.
+func TestFragment_TCPTinyFirstDropped(t *testing.T) {
+	m := newFragmentTestManager(t)
+	_, err := m.AddPeerFiltering(nil, net.ParseIP(fragTestSrc), fw.ProtocolTCP, nil,
+		&fw.Port{Values: []uint16{8080}}, fw.ActionAccept, "")
+	require.NoError(t, err)
+
+	tiny := trailingFragmentTo(t, fragTestDst, layers.IPProtocolTCP, 0x7777, 0, true, 12)
+	require.True(t, m.filterInbound(tiny, len(tiny)),
+		"first fragment shorter than the TCP header must be dropped")
+}
+
+// TestFragment_ConntrackAllowsFirstFragment verifies the conntrack branch: reply
+// fragments of an outbound-established UDP flow pass without any inbound rule.
+func TestFragment_ConntrackAllowsFirstFragment(t *testing.T) {
+	m := newFragmentTestManager(t)
+
+	out := outboundUDPPacket(t, 12345, 40000)
+	require.False(t, m.filterOutbound(out, len(out)))
+
+	first := firstFragmentUDP(t, 0x8888, 12345, 32)
+	require.False(t, m.filterInbound(first, len(first)),
+		"reply first fragment should pass via conntrack")
+
+	trailing := trailingFragment(t, 0x8888, 5, false, 24)
+	require.False(t, m.filterInbound(trailing, len(trailing)),
+		"trailing fragment of a tracked flow should pass")
+}
+
+// TestFragment_RoutingDisabledDropsFragment verifies routed first fragments are
+// dropped when routing is disabled.
+func TestFragment_RoutingDisabledDropsFragment(t *testing.T) {
+	m := newFragmentTestManager(t)
+	m.routingEnabled.Store(false)
+
+	first := firstFragmentUDPTo(t, "198.51.100.10", 0x9999, 8080, 32)
+	require.True(t, m.filterInbound(first, len(first)),
+		"routed first fragment must be dropped when routing is disabled")
+}
+
+// TestFragment_RouteACL verifies the route-ACL branch: fragments to a non-local
+// destination follow the route rules, allowed datagrams pass their trailing
+// fragments and denied ones don't.
+func TestFragment_RouteACL(t *testing.T) {
+	m := newFragmentTestManager(t)
+	m.routingEnabled.Store(true)
+	m.nativeRouter.Store(false)
+
+	_, err := m.AddRouteFiltering(
+		[]byte("rt-1"),
+		[]netip.Prefix{netip.MustParsePrefix("100.10.0.0/16")},
+		fw.Network{Prefix: netip.MustParsePrefix("198.51.100.0/24")},
+		fw.ProtocolUDP,
+		nil,
+		&fw.Port{Values: []uint16{8080}},
+		fw.ActionAccept,
+	)
+	require.NoError(t, err)
+
+	first := firstFragmentUDPTo(t, "198.51.100.10", 0xAAAA, 8080, 32)
+	require.False(t, m.filterInbound(first, len(first)),
+		"route-ACL-allowed first fragment should pass")
+	trailing := trailingFragmentTo(t, "198.51.100.10", layers.IPProtocolUDP, 0xAAAA, 5, false, 24)
+	require.False(t, m.filterInbound(trailing, len(trailing)),
+		"trailing fragment of an allowed routed datagram should pass")
+
+	denied := firstFragmentUDPTo(t, "198.51.100.10", 0xBBBB, 9999, 32)
+	require.True(t, m.filterInbound(denied, len(denied)),
+		"route-ACL-denied first fragment must be dropped")
+	deniedTrailing := trailingFragmentTo(t, "198.51.100.10", layers.IPProtocolUDP, 0xBBBB, 5, false, 24)
+	require.True(t, m.filterInbound(deniedTrailing, len(deniedTrailing)),
+		"trailing fragment of a denied routed datagram must be dropped")
+}
+
+// TestFragment_ExpiredVerdictDropsTrailing verifies a verdict older than the
+// tracker timeout no longer admits trailing fragments.
+func TestFragment_ExpiredVerdictDropsTrailing(t *testing.T) {
+	m := newFragmentTestManager(t)
+	allowUDP(t, m, 8080)
+
+	first := firstFragmentUDP(t, 0xCCCC, 8080, 32)
+	require.False(t, m.filterInbound(first, len(first)))
+
+	m.fragments.mutex.Lock()
+	for key, entry := range m.fragments.entries {
+		entry.recordedAt = time.Now().Add(-defaultFragmentTimeout - time.Second)
+		m.fragments.entries[key] = entry
+	}
+	m.fragments.mutex.Unlock()
+
+	trailing := trailingFragment(t, 0xCCCC, 5, false, 24)
+	require.True(t, m.filterInbound(trailing, len(trailing)),
+		"trailing fragment after verdict expiry must be dropped")
+}
+
+// TestFragment_CapacityFailsClosed verifies the table cap: at capacity, new
+// datagram verdicts are not recorded (their trailing fragments are dropped)
+// while already-recorded datagrams keep working.
+func TestFragment_CapacityFailsClosed(t *testing.T) {
+	m := newFragmentTestManager(t)
+	allowUDP(t, m, 8080)
+
+	m.fragments.mutex.Lock()
+	m.fragments.maxEntries = 1
+	m.fragments.mutex.Unlock()
+
+	first1 := firstFragmentUDP(t, 0x0101, 8080, 32)
+	require.False(t, m.filterInbound(first1, len(first1)))
+
+	first2 := firstFragmentUDP(t, 0x0202, 8080, 32)
+	require.False(t, m.filterInbound(first2, len(first2)),
+		"first fragment itself still passes at capacity")
+
+	trailing2 := trailingFragment(t, 0x0202, 5, false, 24)
+	require.True(t, m.filterInbound(trailing2, len(trailing2)),
+		"trailing fragment of an unrecorded datagram must be dropped at capacity")
+
+	trailing1 := trailingFragment(t, 0x0101, 5, false, 24)
+	require.False(t, m.filterInbound(trailing1, len(trailing1)),
+		"already-recorded datagram should keep passing at capacity")
+}
+
+// v6FragmentHeader builds the 8-byte IPv6 fragment extension header for the
+// given inner protocol, offset (8-byte units), More Fragments bit and id.
+func v6FragmentHeader(proto layers.IPProtocol, offsetOctets uint16, moreFragments bool, id uint32) []byte {
+	offsetFlags := offsetOctets << 3
+	if moreFragments {
+		offsetFlags |= 1
+	}
+	hdr := make([]byte, 8)
+	hdr[0] = uint8(proto)
+	binary.BigEndian.PutUint16(hdr[2:4], offsetFlags)
+	binary.BigEndian.PutUint32(hdr[4:8], id)
+	return hdr
+}
+
+func v6UDPHeader(dstPort uint16, dataLen int) []byte {
+	hdr := make([]byte, 8)
+	binary.BigEndian.PutUint16(hdr[0:2], 40000)
+	binary.BigEndian.PutUint16(hdr[2:4], dstPort)
+	binary.BigEndian.PutUint16(hdr[4:6], uint16(8+dataLen))
+	return hdr
+}
+
+// firstFragmentUDPv6 builds the first fragment of a fragmented IPv6 UDP
+// datagram: fragment header (offset 0, More Fragments set) + full UDP header +
+// data.
+func firstFragmentUDPv6(tb testing.TB, id uint32, dstPort uint16, dataLen int) []byte {
+	tb.Helper()
+	return fragmentUDPv6(tb, id, dstPort, dataLen, true)
+}
+
+// fragmentUDPv6 builds an offset-zero IPv6 UDP fragment. With moreFragments
+// false it is an atomic fragment (a complete datagram, RFC 6946).
+func fragmentUDPv6(tb testing.TB, id uint32, dstPort uint16, dataLen int, moreFragments bool) []byte {
+	tb.Helper()
+
+	ip := &layers.IPv6{
+		Version:    6,
+		NextHeader: layers.IPProtocolIPv6Fragment,
+		HopLimit:   64,
+		SrcIP:      net.ParseIP(fragTestSrcV6),
+		DstIP:      net.ParseIP(fragTestDstV6),
+	}
+	payload := append(v6FragmentHeader(layers.IPProtocolUDP, 0, moreFragments, id), v6UDPHeader(dstPort, dataLen)...)
+	payload = append(payload, make([]byte, dataLen)...)
+
+	buf := gopacket.NewSerializeBuffer()
+	require.NoError(tb, gopacket.SerializeLayers(buf, gopacket.SerializeOptions{FixLengths: true}, ip, gopacket.Payload(payload)))
+	return buf.Bytes()
+}
+
+// trailingFragmentV6 builds a non-first IPv6 fragment: fragment header at the
+// given offset carrying raw data and no transport header.
+func trailingFragmentV6(tb testing.TB, id uint32, offsetOctets uint16, moreFragments bool, dataLen int) []byte {
+	tb.Helper()
+
+	ip := &layers.IPv6{
+		Version:    6,
+		NextHeader: layers.IPProtocolIPv6Fragment,
+		HopLimit:   64,
+		SrcIP:      net.ParseIP(fragTestSrcV6),
+		DstIP:      net.ParseIP(fragTestDstV6),
+	}
+	payload := append(v6FragmentHeader(layers.IPProtocolUDP, offsetOctets, moreFragments, id), make([]byte, dataLen)...)
+
+	buf := gopacket.NewSerializeBuffer()
+	require.NoError(tb, gopacket.SerializeLayers(buf, gopacket.SerializeOptions{FixLengths: true}, ip, gopacket.Payload(payload)))
+	return buf.Bytes()
+}
+
+// TestFragmentV6_TrailingWithoutFirstDropped verifies the IPv6 bypass is closed:
+// a trailing fragment with no allowed first fragment is dropped.
+func TestFragmentV6_TrailingWithoutFirstDropped(t *testing.T) {
+	m := newFragmentTestManager(t)
+
+	frag := trailingFragmentV6(t, 0xAABBCCDD, 100, false, 40)
+	require.True(t, m.filterInbound(frag, len(frag)),
+		"IPv6 trailing fragment without an allowed first fragment must be dropped")
+}
+
+// TestFragmentV6_AllowedFirstPassesTrailing verifies IPv6 fragments are
+// evaluated like IPv4: an allowed first fragment lets its trailing fragments
+// through.
+func TestFragmentV6_AllowedFirstPassesTrailing(t *testing.T) {
+	m := newFragmentTestManager(t)
+	_, err := m.AddPeerFiltering(nil, net.ParseIP(fragTestSrcV6), fw.ProtocolUDP, nil,
+		&fw.Port{Values: []uint16{8080}}, fw.ActionAccept, "")
+	require.NoError(t, err)
+
+	// First fragment: UDP header (8) + 32 data = 40 octets -> headerEnd = 5.
+	first := firstFragmentUDPv6(t, 0xAABBCCDD, 8080, 32)
+	require.False(t, m.filterInbound(first, len(first)),
+		"allowed IPv6 first fragment should pass and be recorded")
+
+	trailing := trailingFragmentV6(t, 0xAABBCCDD, 5, false, 24)
+	require.False(t, m.filterInbound(trailing, len(trailing)),
+		"trailing fragment of an allowed IPv6 datagram should pass")
+}
+
+// TestFragmentV6_AtomicNotCached verifies an IPv6 atomic fragment (fragment
+// header with offset 0 and no More Fragments, a complete datagram per RFC 6946)
+// is evaluated but not recorded, so a flood of allowed atomic fragments can't
+// exhaust the verdict table.
+func TestFragmentV6_AtomicNotCached(t *testing.T) {
+	m := newFragmentTestManager(t)
+	_, err := m.AddPeerFiltering(nil, net.ParseIP(fragTestSrcV6), fw.ProtocolUDP, nil,
+		&fw.Port{Values: []uint16{8080}}, fw.ActionAccept, "")
+	require.NoError(t, err)
+
+	atomic := fragmentUDPv6(t, 0xA70301C, 8080, 16, false)
+	require.False(t, m.filterInbound(atomic, len(atomic)),
+		"allowed IPv6 atomic fragment should pass")
+
+	m.fragments.mutex.Lock()
+	n := len(m.fragments.entries)
+	m.fragments.mutex.Unlock()
+	require.Zero(t, n, "atomic fragment must not create a verdict entry")
+
+	// A genuine fragmented datagram (More Fragments set) is still recorded.
+	first := fragmentUDPv6(t, 0xBEEF, 8080, 32, true)
+	require.False(t, m.filterInbound(first, len(first)))
+	m.fragments.mutex.Lock()
+	n = len(m.fragments.entries)
+	m.fragments.mutex.Unlock()
+	require.Equal(t, 1, n, "genuine first fragment must record a verdict")
+}

client/grpc/dialer_generic.go

@@ -16,28 +16,47 @@ import (
 	"google.golang.org/grpc"
 
 	nbnet "github.com/netbirdio/netbird/client/net"
+	"github.com/netbirdio/netbird/client/netsweep"
 )
 
 func WithCustomDialer(_ bool, _ string) grpc.DialOption {
+	return grpc.WithContextDialer(dialContext)
+}
+
+// WithSweeper dials like WithCustomDialer but registers connections and
+// dials with the sweeper. Append it after WithCustomDialer: gRPC applies
+// dial options in order, so the later context dialer wins.
+func WithSweeper(sweeper *netsweep.Sweeper) grpc.DialOption {
 	return grpc.WithContextDialer(func(ctx context.Context, addr string) (net.Conn, error) {
-		if runtime.GOOS == "linux" {
-			currentUser, err := user.Current()
-			if err != nil {
-				return nil, status.Errorf(codes.FailedPrecondition, "failed to get current user: %v", err)
-			}
+		dial := sweeper.StartDial(ctx)
+		defer dial.Release()
 
-			// the custom dialer requires root permissions which are not required for use cases run as non-root
-			if currentUser.Uid != "0" {
-				log.Debug("Not running as root, using standard dialer")
-				dialer := &net.Dialer{}
-				return dialer.DialContext(ctx, "tcp", addr)
-			}
-		}
-
-		conn, err := nbnet.NewDialer().DialContext(ctx, "tcp", addr)
+		conn, err := dialContext(dial.Ctx(), addr)
 		if err != nil {
-			return nil, fmt.Errorf("nbnet.NewDialer().DialContext: %w", err)
+			return nil, err
 		}
-		return conn, nil
+		return dial.WrapConn(conn)
 	})
 }
+
+func dialContext(ctx context.Context, addr string) (net.Conn, error) {
+	if runtime.GOOS == "linux" {
+		currentUser, err := user.Current()
+		if err != nil {
+			return nil, status.Errorf(codes.FailedPrecondition, "failed to get current user: %v", err)
+		}
+
+		// the custom dialer requires root permissions which are not required for use cases run as non-root
+		if currentUser.Uid != "0" {
+			log.Debug("Not running as root, using standard dialer")
+			dialer := &net.Dialer{}
+			return dialer.DialContext(ctx, "tcp", addr)
+		}
+	}
+
+	conn, err := nbnet.NewDialer().DialContext(ctx, "tcp", addr)
+	if err != nil {
+		return nil, fmt.Errorf("nbnet.NewDialer().DialContext: %w", err)
+	}
+	return conn, nil
+}

client/grpc/dialer_js.go

@@ -3,6 +3,7 @@ package grpc
 import (
 	"google.golang.org/grpc"
 
+	"github.com/netbirdio/netbird/client/netsweep"
 	"github.com/netbirdio/netbird/util/wsproxy/client"
 )
 
@@ -11,3 +12,8 @@ import (
 func WithCustomDialer(tlsEnabled bool, component string) grpc.DialOption {
 	return client.WithWebSocketDialer(tlsEnabled, component)
 }
+
+// WithSweeper is a no-op on WASM/JS: there is no network change signal.
+func WithSweeper(_ *netsweep.Sweeper) grpc.DialOption {
+	return grpc.EmptyDialOption{}
+}

client/grpc/retry.go

@@ -0,0 +1,49 @@
+package grpc
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/cenkalti/backoff/v4"
+
+	"github.com/netbirdio/netbird/client/netstate"
+)
+
+// Retry mirrors backoff.Retry, but the sleep between attempts also wakes on
+// OS network availability transitions: an operation cut down by a network
+// change retries the moment the network settles instead of sleeping through
+// the recovery. A nil netState never fires, leaving plain backoff.Retry
+// behavior.
+func Retry(ctx context.Context, operation backoff.Operation, bo backoff.BackOff, netState *netstate.State) error {
+	bo.Reset()
+	for {
+		err := operation()
+		if err == nil {
+			return nil
+		}
+
+		var permanent *backoff.PermanentError
+		if errors.As(err, &permanent) {
+			return permanent.Err
+		}
+
+		next := bo.NextBackOff()
+		if next == backoff.Stop {
+			if cerr := ctx.Err(); cerr != nil {
+				return cerr
+			}
+			return err
+		}
+
+		timer := time.NewTimer(next)
+		select {
+		case <-timer.C:
+		case <-netState.Changed():
+			timer.Stop()
+		case <-ctx.Done():
+			timer.Stop()
+			return ctx.Err()
+		}
+	}
+}

client/grpc/retry_test.go

@@ -0,0 +1,91 @@
+package grpc
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/cenkalti/backoff/v4"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/client/netstate"
+)
+
+func TestRetryWakesOnNetworkChange(t *testing.T) {
+	ns := netstate.New()
+	attempts := 0
+	operation := func() error {
+		attempts++
+		if attempts == 1 {
+			return errors.New("cut by network change")
+		}
+		return nil
+	}
+
+	go func() {
+		time.Sleep(20 * time.Millisecond)
+		ns.Set(false)
+	}()
+
+	start := time.Now()
+	err := Retry(context.Background(), operation, backoff.NewConstantBackOff(time.Minute), ns)
+
+	require.NoError(t, err)
+	assert.Equal(t, 2, attempts, "network change must cause one immediate retry")
+	assert.Less(t, time.Since(start), time.Second, "the transition must cut the minute-long sleep short")
+}
+
+func TestRetryPermanentError(t *testing.T) {
+	sentinel := errors.New("permission denied")
+	operation := func() error {
+		return backoff.Permanent(sentinel)
+	}
+
+	err := Retry(context.Background(), operation, backoff.NewConstantBackOff(time.Millisecond), nil)
+	assert.ErrorIs(t, err, sentinel, "permanent errors must stop retries")
+}
+
+func TestRetryNilNetState(t *testing.T) {
+	attempts := 0
+	operation := func() error {
+		attempts++
+		if attempts < 3 {
+			return errors.New("transient")
+		}
+		return nil
+	}
+
+	err := Retry(context.Background(), operation, backoff.NewConstantBackOff(time.Millisecond), nil)
+	require.NoError(t, err)
+	assert.Equal(t, 3, attempts, "nil network state must preserve timed retries")
+}
+
+func TestRetryStops(t *testing.T) {
+	failure := errors.New("still failing")
+	operation := func() error {
+		return failure
+	}
+
+	err := Retry(context.Background(), operation, &backoff.StopBackOff{}, nil)
+	assert.ErrorIs(t, err, failure, "stop backoff must return the operation error")
+}
+
+func TestRetryCtxCancelDuringSleep(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	operation := func() error {
+		return errors.New("failing")
+	}
+
+	go func() {
+		time.Sleep(20 * time.Millisecond)
+		cancel()
+	}()
+
+	start := time.Now()
+	err := Retry(ctx, operation, backoff.NewConstantBackOff(time.Minute), netstate.New())
+
+	assert.ErrorIs(t, err, context.Canceled, "context cancellation must stop the retry loop")
+	assert.Less(t, time.Since(start), time.Second, "context cancellation must interrupt backoff sleep")
+}

client/iface/bind/ice_bind.go

@@ -22,6 +22,16 @@ import (
 	nbnet "github.com/netbirdio/netbird/client/net"
 )
 
+const (
+	// wgMsgTypeHandshakeInitiation is the lowest WireGuard message type.
+	wgMsgTypeHandshakeInitiation uint32 = 1
+	// wgMsgTypeTransport is the highest WireGuard message type.
+	wgMsgTypeTransport uint32 = 4
+	// wgMinMsgSize is the smallest WireGuard message: transport data with an empty
+	// payload, which is what a keepalive is.
+	wgMinMsgSize = 32
+)
+
 type receiverCreator struct {
 	iceBind *ICEBind
 }
@@ -216,8 +226,15 @@ func (s *ICEBind) createReceiverFn(pc wgConn.BatchReader, conn *net.UDPConn, rxO
 		for i := 0; i < numMsgs; i++ {
 			msg := &(*msgs)[i]
 
-			// todo: handle err
-			if ok, _ := s.filterOutStunMessages(msg.Buffers, msg.N, msg.Addr); ok {
+			if ok, err := s.filterOutStunMessages(msg.Buffers, msg.N, msg.Addr); ok {
+				if err != nil {
+					log.Debugf("failed to handle STUN packet from %s: %v", msg.Addr, err)
+				}
+				// WireGuard reuses sizes and eps across reads and only skips a slot
+				// whose size is below the minimum message size. Leaving a consumed
+				// slot untouched makes it process this buffer again under the
+				// previous packet's length and endpoint.
+				sizes[i] = 0
 				continue
 			}
 			sizes[i] = msg.N
@@ -271,11 +288,16 @@ func (s *ICEBind) createOrUpdateMux() {
 
 func (s *ICEBind) filterOutStunMessages(buffers [][]byte, n int, addr net.Addr) (bool, error) {
 	for i := range buffers {
-		if !stun.IsMessage(buffers[i]) {
+		if n > len(buffers[i]) {
+			continue
+		}
+		pkt := buffers[i][:n]
+
+		if isWireGuardMsg(pkt) || !stun.IsMessage(pkt) {
 			continue
 		}
 
-		msg, err := s.parseSTUNMessage(buffers[i][:n])
+		msg, err := s.parseSTUNMessage(pkt)
 		if err != nil {
 			buffers[i] = []byte{}
 			return true, err
@@ -347,18 +369,34 @@ func putMessages(msgs *[]ipv6.Message, msgsPool *sync.Pool) {
 	msgsPool.Put(msgs)
 }
 
-func isTransportPkg(buffers [][]byte, n int) bool {
-	// The first buffer should contain at least 4 bytes for type
-	if len(buffers[0]) < 4 {
-		return true
+// isWireGuardMsg reports whether the packet carries a WireGuard message header: a
+// little-endian uint32 message type in the range 1..4, which leaves the three bytes
+// after the type byte zero, in a packet long enough to hold any WireGuard message.
+//
+// A well formed STUN message cannot take that shape. Its length field sits in the two
+// bytes the type must leave zero, and for a message of at least wgMinMsgSize bytes that
+// field holds at least 12, so the two framings do not overlap. The test has to be this
+// tight because stun.IsMessage only looks at the magic cookie, which in a WireGuard
+// message overlaps the receiver index: a session whose index happens to equal the cookie
+// would otherwise have all of its inbound data misrouted to the STUN handler until the
+// next rekey.
+func isWireGuardMsg(pkt []byte) bool {
+	if len(pkt) < wgMinMsgSize {
+		return false
 	}
 
-	// WireGuard packet type is a little-endian uint32 at start
-	packetType := binary.LittleEndian.Uint32(buffers[0][:4])
+	msgType := binary.LittleEndian.Uint32(pkt[:4])
+	return msgType >= wgMsgTypeHandshakeInitiation && msgType <= wgMsgTypeTransport
+}
 
-	// Check if packetType matches known WireGuard message types
-	if packetType == 4 && n > 32 {
-		return true
+// isTransportPkg reports whether the packet is WireGuard transport data carrying a
+// payload, which is what counts as peer activity. A keepalive holds no payload and is
+// exactly wgMinMsgSize bytes.
+func isTransportPkg(buffers [][]byte, n int) bool {
+	if n < 4 || n > len(buffers[0]) {
+		return false
 	}
-	return false
+
+	msgType := binary.LittleEndian.Uint32(buffers[0][:4])
+	return msgType == wgMsgTypeTransport && n > wgMinMsgSize
 }

client/iface/bind/stun_filter_test.go

@@ -0,0 +1,215 @@
+//go:build !js
+
+package bind
+
+import (
+	"encoding/binary"
+	"net"
+	"testing"
+	"time"
+
+	"github.com/pion/stun/v3"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/net/ipv4"
+	wgConn "golang.zx2c4.com/wireguard/conn"
+)
+
+// magicCookieBytes is the STUN magic cookie as it appears on the wire. In a
+// WireGuard message the same offset holds the receiver (or sender) index, which is
+// a random uint32, so a session can draw exactly this value.
+var magicCookieBytes = []byte{0x21, 0x12, 0xA4, 0x42}
+
+const testBufSize = 1500
+
+// wgMsg builds a WireGuard message of the given type and size, with the index field
+// at bytes 4:8 set to index.
+func wgMsg(msgType uint32, size int, index []byte) []byte {
+	pkt := make([]byte, size)
+	binary.LittleEndian.PutUint32(pkt[:4], msgType)
+	copy(pkt[4:8], index)
+	return pkt
+}
+
+// intoBuffer copies pkt into a full-size receive buffer, the way the kernel read
+// does, so tests see the same buffer/length split as the hot path.
+func intoBuffer(pkt []byte) [][]byte {
+	buf := make([]byte, testBufSize)
+	copy(buf, pkt)
+	return [][]byte{buf}
+}
+
+func TestFilterOutStunMessages_PassesWireGuardWithCookieShapedIndex(t *testing.T) {
+	tests := []struct {
+		name    string
+		msgType uint32
+		size    int
+	}{
+		{"transport data", wgMsgTypeTransport, 128},
+		{"keepalive", wgMsgTypeTransport, wgMinMsgSize},
+		{"handshake initiation", wgMsgTypeHandshakeInitiation, 148},
+		{"handshake response", 2, 92},
+		{"cookie reply", 3, 64},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			pkt := wgMsg(tc.msgType, tc.size, magicCookieBytes)
+			require.True(t, stun.IsMessage(pkt), "precondition: pion sees this as STUN")
+
+			buffers := intoBuffer(pkt)
+			bind := &ICEBind{}
+
+			filtered, err := bind.filterOutStunMessages(buffers, tc.size, &net.UDPAddr{})
+			assert.NoError(t, err)
+			assert.False(t, filtered, "WireGuard message must be handed to WireGuard, not the STUN handler")
+			assert.Len(t, buffers[0], testBufSize, "buffer must be left intact for WireGuard")
+		})
+	}
+}
+
+func TestFilterOutStunMessages_FiltersRealSTUNMessage(t *testing.T) {
+	msg, err := stun.Build(stun.BindingRequest, stun.TransactionID, stun.Fingerprint)
+	require.NoError(t, err)
+
+	buffers := intoBuffer(msg.Raw)
+	bind := &ICEBind{}
+
+	filtered, err := bind.filterOutStunMessages(buffers, len(msg.Raw), &net.UDPAddr{})
+	assert.NoError(t, err)
+	assert.True(t, filtered, "STUN message must be consumed by the STUN handler")
+	assert.Empty(t, buffers[0], "consumed buffer must be emptied so WireGuard does not see it")
+}
+
+// TestIsWireGuardMsg_DisjointFromSTUN locks the invariant the filter relies on: a
+// well formed STUN message long enough to be a WireGuard message always has a
+// non-zero length field, so it cannot be mistaken for a WireGuard header.
+func TestIsWireGuardMsg_DisjointFromSTUN(t *testing.T) {
+	types := []stun.MessageType{
+		stun.BindingRequest,
+		stun.BindingSuccess,
+		stun.BindingError,
+		{Method: stun.MethodBinding, Class: stun.ClassIndication},
+	}
+
+	for _, msgType := range types {
+		// Long enough that the length guard is not what makes this pass.
+		msg, err := stun.Build(msgType, stun.TransactionID,
+			stun.NewUsername("remoteUfrag:localUfrag"), stun.Fingerprint)
+		require.NoError(t, err)
+		require.GreaterOrEqual(t, len(msg.Raw), wgMinMsgSize, "precondition: %s", msgType)
+		assert.False(t, isWireGuardMsg(msg.Raw),
+			"%s must not look like a WireGuard message", msgType)
+	}
+}
+
+func TestIsWireGuardMsg(t *testing.T) {
+	tests := []struct {
+		name string
+		pkt  []byte
+		want bool
+	}{
+		{"transport data", wgMsg(wgMsgTypeTransport, 128, nil), true},
+		{"handshake initiation", wgMsg(wgMsgTypeHandshakeInitiation, 148, nil), true},
+		{"unknown type 5", wgMsg(5, 128, nil), false},
+		{"type 0", wgMsg(0, 128, nil), false},
+		{"non-zero reserved byte", []byte{0x04, 0x00, 0x01, 0x00}, false},
+		{"too short", []byte{0x04, 0x00, 0x00}, false},
+		{"empty", nil, false},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.Equal(t, tc.want, isWireGuardMsg(tc.pkt), "wrong classification for %s", tc.name)
+		})
+	}
+}
+
+// TestFilterOutStunMessages_IgnoresBytesBeyondPacket guards against classifying on
+// buffer contents left over from an earlier, longer packet.
+func TestFilterOutStunMessages_IgnoresBytesBeyondPacket(t *testing.T) {
+	buf := make([]byte, testBufSize)
+	copy(buf[4:8], magicCookieBytes)
+	buffers := [][]byte{buf}
+	bind := &ICEBind{}
+
+	filtered, err := bind.filterOutStunMessages(buffers, 2, &net.UDPAddr{})
+	assert.NoError(t, err)
+	assert.False(t, filtered, "a 2 byte packet must not be classified from stale buffer bytes")
+}
+
+// TestReceiveFn_ClearsSizeOfConsumedPacket covers the accounting WireGuard relies
+// on: sizes is reused across reads, so a slot whose packet was consumed as STUN must
+// be reported as empty. Otherwise WireGuard reprocesses the same buffer under the
+// previous packet's length, which for a WireGuard-shaped packet means it is handled
+// twice.
+func TestReceiveFn_ClearsSizeOfConsumedPacket(t *testing.T) {
+	conn := listenUDP(t, "udp4", "127.0.0.1:0")
+	defer conn.Close()
+
+	recvFn := receiverCreator{setupICEBind(t)}.CreateReceiverFn(
+		ipv4.NewPacketConn(conn), conn, false, createMsgPool(),
+	)
+
+	msg, err := stun.Build(stun.BindingRequest, stun.TransactionID, stun.Fingerprint)
+	require.NoError(t, err)
+
+	sender := listenUDP(t, "udp4", "127.0.0.1:0")
+	defer sender.Close()
+	_, err = sender.WriteTo(msg.Raw, conn.LocalAddr())
+	require.NoError(t, err)
+
+	require.NoError(t, conn.SetReadDeadline(time.Now().Add(3*time.Second)))
+
+	bufs := [][]byte{make([]byte, 1500)}
+	// A leftover size from an earlier read, which is what makes the missing reset
+	// observable.
+	sizes := []int{148}
+	eps := make([]wgConn.Endpoint, 1)
+
+	n, err := recvFn(bufs, sizes, eps)
+	require.NoError(t, err)
+	require.Equal(t, 1, n)
+	assert.Zero(t, sizes[0], "consumed STUN packet must not leave a size behind for WireGuard")
+}
+
+func TestIsTransportPkg(t *testing.T) {
+	tests := []struct {
+		name string
+		pkt  []byte
+		n    int
+		want bool
+	}{
+		{"transport data with payload", wgMsg(wgMsgTypeTransport, 128, nil), 128, true},
+		{"keepalive", wgMsg(wgMsgTypeTransport, wgMinMsgSize, nil), wgMinMsgSize, false},
+		{"handshake initiation", wgMsg(wgMsgTypeHandshakeInitiation, 148, nil), 148, false},
+		{"stale type bytes beyond packet", wgMsg(wgMsgTypeTransport, 128, nil), 2, false},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.Equal(t, tc.want, isTransportPkg(intoBuffer(tc.pkt), tc.n),
+				"wrong activity classification for %s", tc.name)
+		})
+	}
+}
+
+// TestFilterOutStunMessages_ConsumesSTUNWithWireGuardShapedType covers the one STUN
+// encoding whose leading bytes collide with a WireGuard message type: method 0x080 as a
+// request encodes to 0x0200, so the type byte reads as a handshake response and the byte
+// after it is zero. Only the length check keeps such a message out of WireGuard's hands.
+// pion implements no method in that range, so this is a synthetic worst case rather than
+// traffic ICE produces.
+func TestFilterOutStunMessages_ConsumesSTUNWithWireGuardShapedType(t *testing.T) {
+	msg, err := stun.Build(stun.NewType(stun.Method(0x080), stun.ClassRequest), stun.TransactionID)
+	require.NoError(t, err)
+	require.Equal(t, []byte{0x02, 0x00, 0x00, 0x00}, msg.Raw[:4],
+		"precondition: the leading bytes read as a WireGuard message type")
+
+	buffers := intoBuffer(msg.Raw)
+	bind := &ICEBind{}
+
+	filtered, err := bind.filterOutStunMessages(buffers, len(msg.Raw), &net.UDPAddr{})
+	assert.NoError(t, err)
+	assert.True(t, filtered, "STUN message must be consumed despite its WireGuard-shaped type")
+}

client/iface/configurer/kernel_unix.go

@@ -17,12 +17,15 @@ import (
 
 type KernelConfigurer struct {
 	deviceName string
+	statsCache *statsCache
 }
 
 func NewKernelConfigurer(deviceName string) *KernelConfigurer {
-	return &KernelConfigurer{
+	c := &KernelConfigurer{
 		deviceName: deviceName,
 	}
+	c.statsCache = newStatsCache(statsCacheTTL, c.fetchStats)
+	return c
 }
 
 func (c *KernelConfigurer) ConfigureInterface(privateKey string, port int) error {
@@ -246,12 +249,6 @@ func (c *KernelConfigurer) configure(config wgtypes.Config) error {
 		}
 	}()
 
-	// validate if device with name exists
-	_, err = wg.Device(c.deviceName)
-	if err != nil {
-		return err
-	}
-
 	return wg.ConfigureDevice(c.deviceName, config)
 }
 
@@ -300,6 +297,14 @@ func (c *KernelConfigurer) FullStats() (*Stats, error) {
 }
 
 func (c *KernelConfigurer) GetStats() (map[string]WGStats, error) {
+	return c.statsCache.get()
+}
+
+func (c *KernelConfigurer) LastActivities() map[string]monotime.Time {
+	return nil
+}
+
+func (c *KernelConfigurer) fetchStats() (map[string]WGStats, error) {
 	stats := make(map[string]WGStats)
 	wg, err := wgctrl.New()
 	if err != nil {
@@ -326,7 +331,3 @@ func (c *KernelConfigurer) GetStats() (map[string]WGStats, error) {
 	}
 	return stats, nil
 }
-
-func (c *KernelConfigurer) LastActivities() map[string]monotime.Time {
-	return nil
-}

client/iface/configurer/stats_cache.go

@@ -0,0 +1,52 @@
+package configurer
+
+import (
+	"sync"
+	"time"
+
+	"golang.org/x/sync/singleflight"
+)
+
+const statsCacheTTL = 1 * time.Second
+
+type statsCache struct {
+	ttl   time.Duration
+	fetch func() (map[string]WGStats, error)
+
+	mu       sync.RWMutex
+	value    map[string]WGStats
+	expireAt time.Time
+
+	sf singleflight.Group
+}
+
+func newStatsCache(ttl time.Duration, fetch func() (map[string]WGStats, error)) *statsCache {
+	return &statsCache{ttl: ttl, fetch: fetch}
+}
+
+func (c *statsCache) get() (map[string]WGStats, error) {
+	c.mu.RLock()
+	if c.value != nil && time.Now().Before(c.expireAt) {
+		value := c.value
+		c.mu.RUnlock()
+		return value, nil
+	}
+	c.mu.RUnlock()
+
+	value, err, _ := c.sf.Do("stats", func() (interface{}, error) {
+		res, err := c.fetch()
+		if err != nil {
+			return nil, err
+		}
+
+		c.mu.Lock()
+		c.value = res
+		c.expireAt = time.Now().Add(c.ttl)
+		c.mu.Unlock()
+		return res, nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return value.(map[string]WGStats), nil
+}

client/iface/configurer/stats_cache_test.go

@@ -0,0 +1,70 @@
+package configurer
+
+import (
+	"errors"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestStatsCache_CachesWithinTTL(t *testing.T) {
+	var calls atomic.Int64
+	c := newStatsCache(50*time.Millisecond, func() (map[string]WGStats, error) {
+		calls.Add(1)
+		return map[string]WGStats{"p": {}}, nil
+	})
+
+	for i := 0; i < 10; i++ {
+		_, err := c.get()
+		require.NoError(t, err)
+	}
+	require.Equal(t, int64(1), calls.Load(), "within TTL only one underlying fetch")
+
+	time.Sleep(60 * time.Millisecond)
+	_, err := c.get()
+	require.NoError(t, err)
+	require.Equal(t, int64(2), calls.Load(), "after TTL expiry a fresh fetch happens")
+}
+
+func TestStatsCache_SingleFlight(t *testing.T) {
+	var calls atomic.Int64
+	release := make(chan struct{})
+	c := newStatsCache(time.Minute, func() (map[string]WGStats, error) {
+		calls.Add(1)
+		<-release
+		return map[string]WGStats{}, nil
+	})
+
+	const n = 50
+	var wg sync.WaitGroup
+	wg.Add(n)
+	for i := 0; i < n; i++ {
+		go func() {
+			defer wg.Done()
+			_, _ = c.get()
+		}()
+	}
+	time.Sleep(20 * time.Millisecond)
+	close(release)
+	wg.Wait()
+
+	require.Equal(t, int64(1), calls.Load(), "concurrent misses collapse into one fetch")
+}
+
+func TestStatsCache_ErrorNotCached(t *testing.T) {
+	var calls atomic.Int64
+	wantErr := errors.New("dump failed")
+	c := newStatsCache(time.Minute, func() (map[string]WGStats, error) {
+		calls.Add(1)
+		return nil, wantErr
+	})
+
+	_, err := c.get()
+	require.ErrorIs(t, err, wantErr)
+	_, err = c.get()
+	require.ErrorIs(t, err, wantErr)
+	require.Equal(t, int64(2), calls.Load(), "errors are not cached; each call retries")
+}

client/iface/configurer/usp.go

@@ -40,6 +40,7 @@ type WGUSPConfigurer struct {
 	device           *device.Device
 	deviceName       string
 	activityRecorder *bind.ActivityRecorder
+	statsCache       *statsCache
 
 	uapiListener net.Listener
 }
@@ -50,16 +51,19 @@ func NewUSPConfigurer(device *device.Device, deviceName string, activityRecorder
 		deviceName:       deviceName,
 		activityRecorder: activityRecorder,
 	}
+	wgCfg.statsCache = newStatsCache(statsCacheTTL, wgCfg.fetchStats)
 	wgCfg.startUAPI()
 	return wgCfg
 }
 
 func NewUSPConfigurerNoUAPI(device *device.Device, deviceName string, activityRecorder *bind.ActivityRecorder) *WGUSPConfigurer {
-	return &WGUSPConfigurer{
+	wgCfg := &WGUSPConfigurer{
 		device:           device,
 		deviceName:       deviceName,
 		activityRecorder: activityRecorder,
 	}
+	wgCfg.statsCache = newStatsCache(statsCacheTTL, wgCfg.fetchStats)
+	return wgCfg
 }
 
 func (c *WGUSPConfigurer) ConfigureInterface(privateKey string, port int) error {
@@ -348,6 +352,10 @@ func (t *WGUSPConfigurer) Close() {
 }
 
 func (t *WGUSPConfigurer) GetStats() (map[string]WGStats, error) {
+	return t.statsCache.get()
+}
+
+func (t *WGUSPConfigurer) fetchStats() (map[string]WGStats, error) {
 	ipc, err := t.device.IpcGet()
 	if err != nil {
 		return nil, fmt.Errorf("ipc get: %w", err)

client/iface/device/device_filter_test.go

@@ -4,7 +4,7 @@ import (
 	"net"
 	"testing"
 
-	"github.com/golang/mock/gomock"
+	"go.uber.org/mock/gomock"
 	"github.com/google/gopacket"
 	"github.com/google/gopacket/layers"
 

client/iface/iface_test.go

@@ -1,3 +1,5 @@
+//go:build privileged
+
 package iface
 
 import (
@@ -462,6 +464,8 @@ func Test_RemovePeer(t *testing.T) {
 }
 
 func Test_ConnectPeers(t *testing.T) {
+	t.Setenv("NB_DISABLE_EBPF_WG_PROXY", "true")
+
 	peer1ifaceName := fmt.Sprintf("utun%d", WgIntNumber+400)
 	peer1wgIP := netip.MustParsePrefix("10.99.99.17/30")
 	peer1Key, _ := wgtypes.GeneratePrivateKey()
@@ -503,12 +507,8 @@ func Test_ConnectPeers(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	localIP, err := getLocalIP()
-	if err != nil {
-		t.Fatal(err)
-	}
-
-	peer1endpoint, err := net.ResolveUDPAddr("udp", fmt.Sprintf("%s:%d", localIP, peer1wgPort))
+	localIP1 := "127.0.0.1"
+	peer1endpoint, err := net.ResolveUDPAddr("udp", fmt.Sprintf("%s:%d", localIP1, peer1wgPort))
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -544,7 +544,8 @@ func Test_ConnectPeers(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	peer2endpoint, err := net.ResolveUDPAddr("udp", fmt.Sprintf("%s:%d", localIP, peer2wgPort))
+	localIP2 := "127.0.0.1"
+	peer2endpoint, err := net.ResolveUDPAddr("udp", fmt.Sprintf("%s:%d", localIP2, peer2wgPort))
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -567,17 +568,17 @@ func Test_ConnectPeers(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	// todo: investigate why in some tests execution we need 30s
+	// The peers use userspace WireGuard (stdnet transport). A tight busy-loop
+	// here starves the wireguard-go goroutines that process the handshake, so
+	// poll on a ticker instead and yield the CPU between checks. WireGuard also
+	// only retries a lost handshake initiation every REKEY_TIMEOUT (5s), which
+	// is why the overall wait can occasionally stretch to tens of seconds.
 	timeout := 30 * time.Second
 	timeoutChannel := time.After(timeout)
+	ticker := time.NewTicker(500 * time.Millisecond)
+	defer ticker.Stop()
 
 	for {
-		select {
-		case <-timeoutChannel:
-			t.Fatalf("waiting for peer handshake timeout after %s", timeout.String())
-		default:
-		}
-
 		peer, gpErr := getPeer(peer1ifaceName, peer2Key.PublicKey().String())
 		if gpErr != nil {
 			t.Fatal(gpErr)
@@ -586,6 +587,12 @@ func Test_ConnectPeers(t *testing.T) {
 			t.Log("peers successfully handshake")
 			break
 		}
+
+		select {
+		case <-timeoutChannel:
+			t.Fatalf("waiting for peer handshake timeout after %s", timeout.String())
+		case <-ticker.C:
+		}
 	}
 
 }
@@ -613,28 +620,3 @@ func getPeer(ifaceName, peerPubKey string) (wgtypes.Peer, error) {
 	}
 	return wgtypes.Peer{}, fmt.Errorf("peer not found")
 }
-
-func getLocalIP() (string, error) {
-	// Get all interfaces
-	addrs, err := net.InterfaceAddrs()
-	if err != nil {
-		return "", err
-	}
-
-	for _, addr := range addrs {
-		ipNet, ok := addr.(*net.IPNet)
-		if !ok {
-			continue
-		}
-		if ipNet.IP.IsLoopback() {
-			continue
-		}
-
-		if ipNet.IP.To4() == nil {
-			continue
-		}
-		return ipNet.IP.String(), nil
-	}
-
-	return "", fmt.Errorf("no local IP found")
-}

client/iface/mocks/filter.go

@@ -8,7 +8,7 @@ import (
 	"net/netip"
 	reflect "reflect"
 
-	gomock "github.com/golang/mock/gomock"
+	gomock "go.uber.org/mock/gomock"
 )
 
 // MockPacketFilter is a mock of PacketFilter interface.

client/iface/mocks/tun.go

@@ -8,7 +8,7 @@ import (
 	os "os"
 	reflect "reflect"
 
-	gomock "github.com/golang/mock/gomock"
+	gomock "go.uber.org/mock/gomock"
 	tun "golang.zx2c4.com/wireguard/tun"
 )
 

client/iface/netstack/env.go

@@ -3,14 +3,31 @@
 package netstack
 
 import (
-	"fmt"
+	"net"
 	"os"
 	"strconv"
 
 	log "github.com/sirupsen/logrus"
 )
 
-const EnvUseNetstackMode = "NB_USE_NETSTACK_MODE"
+const (
+	EnvUseNetstackMode = "NB_USE_NETSTACK_MODE"
+
+	// EnvSocks5ListenerPort overrides the port the SOCKS5 proxy listens on.
+	EnvSocks5ListenerPort = "NB_SOCKS5_LISTENER_PORT"
+
+	// EnvSocks5ListenerAddress overrides the host/IP the SOCKS5 proxy binds to.
+	// The proxy is a bridge for local host applications into the userspace
+	// WireGuard netstack, so it binds to loopback by default. Override this only
+	// when the proxy must be reachable from other hosts (e.g. a container
+	// gateway); doing so exposes an unauthenticated SOCKS5 proxy on that
+	// address.
+	EnvSocks5ListenerAddress = "NB_SOCKS5_LISTENER_ADDRESS"
+
+	// defaultSocks5Host is the loopback address the SOCKS5 proxy binds to unless
+	// overridden via EnvSocks5ListenerAddress.
+	defaultSocks5Host = "127.0.0.1"
+)
 
 // IsEnabled todo: move these function to cmd layer
 func IsEnabled() bool {
@@ -18,24 +35,40 @@ func IsEnabled() bool {
 }
 
 func ListenAddr() string {
-	sPort := os.Getenv("NB_SOCKS5_LISTENER_PORT")
+	return net.JoinHostPort(listenHost(), strconv.Itoa(listenPort()))
+}
+
+// listenHost returns the host/IP the SOCKS5 proxy binds to. It defaults to
+// loopback and only honors EnvSocks5ListenerAddress when it holds a valid IP.
+func listenHost() string {
+	addr := os.Getenv(EnvSocks5ListenerAddress)
+	if addr == "" {
+		return defaultSocks5Host
+	}
+	if net.ParseIP(addr) == nil {
+		log.Warnf("invalid socks5 listener address %q, falling back to default: %s", addr, defaultSocks5Host)
+		return defaultSocks5Host
+	}
+	return addr
+}
+
+// listenPort returns the port the SOCKS5 proxy binds to, defaulting to
+// DefaultSocks5Port when EnvSocks5ListenerPort is unset or invalid.
+func listenPort() int {
+	sPort := os.Getenv(EnvSocks5ListenerPort)
 	if sPort == "" {
-		return listenAddr(DefaultSocks5Port)
+		return DefaultSocks5Port
 	}
 
 	port, err := strconv.Atoi(sPort)
 	if err != nil {
 		log.Warnf("invalid socks5 listener port, unable to convert it to int, falling back to default: %d", DefaultSocks5Port)
-		return listenAddr(DefaultSocks5Port)
+		return DefaultSocks5Port
 	}
 	if port < 1 || port > 65535 {
 		log.Warnf("invalid socks5 listener port, it should be in the range 1-65535, falling back to default: %d", DefaultSocks5Port)
-		return listenAddr(DefaultSocks5Port)
+		return DefaultSocks5Port
 	}
 
-	return listenAddr(port)
-}
-
-func listenAddr(port int) string {
-	return fmt.Sprintf("0.0.0.0:%d", port)
+	return port
 }

client/iface/netstack/env_test.go

@@ -0,0 +1,63 @@
+//go:build !js
+
+package netstack
+
+import (
+	"net"
+	"strconv"
+	"testing"
+)
+
+func TestListenAddr_DefaultsToLoopback(t *testing.T) {
+	// No env overrides: must bind loopback, never all interfaces.
+	got := ListenAddr()
+	want := net.JoinHostPort("127.0.0.1", strconv.Itoa(DefaultSocks5Port))
+	if got != want {
+		t.Fatalf("ListenAddr() = %q, want %q", got, want)
+	}
+}
+
+func TestListenAddr_AddressOverride(t *testing.T) {
+	tests := []struct {
+		name string
+		env  string
+		want string
+	}{
+		{name: "valid override honored", env: "0.0.0.0", want: "0.0.0.0"},
+		{name: "valid specific ip honored", env: "10.0.0.5", want: "10.0.0.5"},
+		{name: "ipv6 loopback bracketed", env: "::1", want: "::1"},
+		{name: "invalid falls back to loopback", env: "not-an-ip", want: "127.0.0.1"},
+		{name: "empty falls back to loopback", env: "", want: "127.0.0.1"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv(EnvSocks5ListenerAddress, tc.env)
+			want := net.JoinHostPort(tc.want, strconv.Itoa(DefaultSocks5Port))
+			if got := ListenAddr(); got != want {
+				t.Fatalf("ListenAddr() = %q, want %q", got, want)
+			}
+		})
+	}
+}
+
+func TestListenAddr_PortOverride(t *testing.T) {
+	tests := []struct {
+		name string
+		env  string
+		want int
+	}{
+		{name: "valid port honored", env: "1081", want: 1081},
+		{name: "non-numeric falls back", env: "abc", want: DefaultSocks5Port},
+		{name: "out of range falls back", env: "70000", want: DefaultSocks5Port},
+		{name: "zero falls back", env: "0", want: DefaultSocks5Port},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv(EnvSocks5ListenerPort, tc.env)
+			want := net.JoinHostPort("127.0.0.1", strconv.Itoa(tc.want))
+			if got := ListenAddr(); got != want {
+				t.Fatalf("ListenAddr() = %q, want %q", got, want)
+			}
+		})
+	}
+}

client/iface/wgproxy/bind/proxy.go

@@ -53,15 +53,15 @@ func NewProxyBind(bind Bind, mtu uint16) *ProxyBind {
 	return p
 }
 
-// AddTurnConn adds a new connection to the bind.
+// AddRelayedConn adds a new connection to the bind.
 // endpoint is the NetBird address of the remote peer. The SetEndpoint return with the address what will be used in the
 // WireGuard configuration.
 //
 // Parameters:
 //   - ctx: Context is used for proxyToLocal to avoid unnecessary error messages
 //   - nbAddr: The NetBird UDP address of the remote peer, it required to generate fake address
-//   - remoteConn: The established TURN connection to the remote peer
-func (p *ProxyBind) AddTurnConn(ctx context.Context, nbAddr *net.UDPAddr, remoteConn net.Conn) error {
+//   - remoteConn: The established relayed connection to the remote peer
+func (p *ProxyBind) AddRelayedConn(ctx context.Context, nbAddr *net.UDPAddr, remoteConn net.Conn) error {
 	fakeNetIP, err := fakeAddress(nbAddr)
 	if err != nil {
 		return err
@@ -136,6 +136,11 @@ func (p *ProxyBind) CloseConn() error {
 	return p.close()
 }
 
+// InjectPacket is a no-op for the userspace proxy: first-packet reinjection is kernel-only.
+func (p *ProxyBind) InjectPacket(_ []byte) error {
+	return nil
+}
+
 func (p *ProxyBind) close() error {
 	if p.remoteConn == nil {
 		return nil

client/iface/wgproxy/ebpf/proxy.go

@@ -30,9 +30,9 @@ type WGEBPFProxy struct {
 	proxyPort         int
 	mtu               uint16
 
-	ebpfManager   ebpfMgr.Manager
-	turnConnStore map[uint16]net.Conn
-	turnConnMutex sync.Mutex
+	ebpfManager      ebpfMgr.Manager
+	relayedConnStore map[uint16]net.Conn
+	relayedConnMutex sync.Mutex
 
 	lastUsedPort uint16
 	rawConnIPv4  net.PacketConn
@@ -50,7 +50,7 @@ func NewWGEBPFProxy(wgPort int, mtu uint16) *WGEBPFProxy {
 		localWGListenPort: wgPort,
 		mtu:               mtu,
 		ebpfManager:       ebpf.GetEbpfManagerInstance(),
-		turnConnStore:     make(map[uint16]net.Conn),
+		relayedConnStore:  make(map[uint16]net.Conn),
 	}
 	return wgProxy
 }
@@ -110,14 +110,14 @@ func (p *WGEBPFProxy) Listen() error {
 	return nil
 }
 
-// AddTurnConn add new turn connection for the proxy
-func (p *WGEBPFProxy) AddTurnConn(turnConn net.Conn) (*net.UDPAddr, error) {
-	wgEndpointPort, err := p.storeTurnConn(turnConn)
+// AddRelayedConn add new relayed connection for the proxy
+func (p *WGEBPFProxy) AddRelayedConn(relayedConn net.Conn) (*net.UDPAddr, error) {
+	wgEndpointPort, err := p.storeRelayedConn(relayedConn)
 	if err != nil {
 		return nil, err
 	}
 
-	log.Infof("turn conn added to wg proxy store: %s, endpoint port: :%d", turnConn.RemoteAddr(), wgEndpointPort)
+	log.Infof("relayed conn added to wg proxy store: %s, endpoint port: :%d", relayedConn.RemoteAddr(), wgEndpointPort)
 
 	wgEndpoint := &net.UDPAddr{
 		IP:   net.ParseIP(loopbackAddr),
@@ -186,48 +186,48 @@ func (p *WGEBPFProxy) readAndForwardPacket(buf []byte) error {
 		return fmt.Errorf("failed to read UDP packet from WG: %w", err)
 	}
 
-	p.turnConnMutex.Lock()
-	conn, ok := p.turnConnStore[uint16(addr.Port)]
-	p.turnConnMutex.Unlock()
+	p.relayedConnMutex.Lock()
+	conn, ok := p.relayedConnStore[uint16(addr.Port)]
+	p.relayedConnMutex.Unlock()
 	if !ok {
 		if p.ctx.Err() == nil {
-			log.Debugf("turn conn not found by port because conn already has been closed: %d", addr.Port)
+			log.Debugf("relayed conn not found by port because conn already has been closed: %d", addr.Port)
 		}
 		return nil
 	}
 
 	if _, err := conn.Write(buf[:n]); err != nil {
-		return fmt.Errorf("failed to forward local WG packet (%d) to remote turn conn: %w", addr.Port, err)
+		return fmt.Errorf("forward local WG packet (%d) to remote relayed conn: %w", addr.Port, err)
 	}
 	return nil
 }
 
-func (p *WGEBPFProxy) storeTurnConn(turnConn net.Conn) (uint16, error) {
-	p.turnConnMutex.Lock()
-	defer p.turnConnMutex.Unlock()
+func (p *WGEBPFProxy) storeRelayedConn(relayedConn net.Conn) (uint16, error) {
+	p.relayedConnMutex.Lock()
+	defer p.relayedConnMutex.Unlock()
 
 	np, err := p.nextFreePort()
 	if err != nil {
 		return np, err
 	}
-	p.turnConnStore[np] = turnConn
+	p.relayedConnStore[np] = relayedConn
 	return np, nil
 }
 
-func (p *WGEBPFProxy) removeTurnConn(turnConnID uint16) {
-	p.turnConnMutex.Lock()
-	defer p.turnConnMutex.Unlock()
+func (p *WGEBPFProxy) removeRelayedConn(relayedConnID uint16) {
+	p.relayedConnMutex.Lock()
+	defer p.relayedConnMutex.Unlock()
 
-	_, ok := p.turnConnStore[turnConnID]
+	_, ok := p.relayedConnStore[relayedConnID]
 	if ok {
-		log.Debugf("remove turn conn from store by port: %d", turnConnID)
+		log.Debugf("remove relayed conn from store by port: %d", relayedConnID)
 	}
-	delete(p.turnConnStore, turnConnID)
+	delete(p.relayedConnStore, relayedConnID)
 }
 
 func (p *WGEBPFProxy) nextFreePort() (uint16, error) {
-	if len(p.turnConnStore) == 65535 {
-		return 0, fmt.Errorf("reached maximum turn connection numbers")
+	if len(p.relayedConnStore) == 65535 {
+		return 0, fmt.Errorf("reached maximum relayed connection numbers")
 	}
 generatePort:
 	if p.lastUsedPort == 65535 {
@@ -236,7 +236,7 @@ generatePort:
 		p.lastUsedPort++
 	}
 
-	if _, ok := p.turnConnStore[p.lastUsedPort]; ok {
+	if _, ok := p.relayedConnStore[p.lastUsedPort]; ok {
 		goto generatePort
 	}
 	return p.lastUsedPort, nil

client/iface/wgproxy/ebpf/proxy_test.go

@@ -9,32 +9,32 @@ import (
 func TestWGEBPFProxy_connStore(t *testing.T) {
 	wgProxy := NewWGEBPFProxy(1, 1280)
 
-	p, _ := wgProxy.storeTurnConn(nil)
+	p, _ := wgProxy.storeRelayedConn(nil)
 	if p != 1 {
 		t.Errorf("invalid initial port: %d", wgProxy.lastUsedPort)
 	}
 
 	numOfConns := 10
 	for i := 0; i < numOfConns; i++ {
-		p, _ = wgProxy.storeTurnConn(nil)
+		p, _ = wgProxy.storeRelayedConn(nil)
 	}
 	if p != uint16(numOfConns)+1 {
 		t.Errorf("invalid last used port: %d, expected: %d", p, numOfConns+1)
 	}
-	if len(wgProxy.turnConnStore) != numOfConns+1 {
-		t.Errorf("invalid store size: %d, expected: %d", len(wgProxy.turnConnStore), numOfConns+1)
+	if len(wgProxy.relayedConnStore) != numOfConns+1 {
+		t.Errorf("invalid store size: %d, expected: %d", len(wgProxy.relayedConnStore), numOfConns+1)
 	}
 }
 
 func TestWGEBPFProxy_portCalculation_overflow(t *testing.T) {
 	wgProxy := NewWGEBPFProxy(1, 1280)
 
-	_, _ = wgProxy.storeTurnConn(nil)
+	_, _ = wgProxy.storeRelayedConn(nil)
 	wgProxy.lastUsedPort = 65535
-	p, _ := wgProxy.storeTurnConn(nil)
+	p, _ := wgProxy.storeRelayedConn(nil)
 
-	if len(wgProxy.turnConnStore) != 2 {
-		t.Errorf("invalid store size: %d, expected: %d", len(wgProxy.turnConnStore), 2)
+	if len(wgProxy.relayedConnStore) != 2 {
+		t.Errorf("invalid store size: %d, expected: %d", len(wgProxy.relayedConnStore), 2)
 	}
 
 	if p != 2 {
@@ -46,11 +46,11 @@ func TestWGEBPFProxy_portCalculation_maxConn(t *testing.T) {
 	wgProxy := NewWGEBPFProxy(1, 1280)
 
 	for i := 0; i < 65535; i++ {
-		_, _ = wgProxy.storeTurnConn(nil)
+		_, _ = wgProxy.storeRelayedConn(nil)
 	}
 
-	_, err := wgProxy.storeTurnConn(nil)
+	_, err := wgProxy.storeRelayedConn(nil)
 	if err == nil {
-		t.Errorf("invalid turn conn store calculation")
+		t.Errorf("invalid relayed conn store calculation")
 	}
 }

client/iface/wgproxy/ebpf/wrapper.go

@@ -121,10 +121,10 @@ func NewProxyWrapper(proxy *WGEBPFProxy) *ProxyWrapper {
 	}
 }
 
-func (p *ProxyWrapper) AddTurnConn(ctx context.Context, _ *net.UDPAddr, remoteConn net.Conn) error {
-	addr, err := p.wgeBPFProxy.AddTurnConn(remoteConn)
+func (p *ProxyWrapper) AddRelayedConn(ctx context.Context, _ *net.UDPAddr, remoteConn net.Conn) error {
+	addr, err := p.wgeBPFProxy.AddRelayedConn(remoteConn)
 	if err != nil {
-		return fmt.Errorf("add turn conn: %w", err)
+		return fmt.Errorf("add relayed conn: %w", err)
 	}
 
 	headers, err := NewPacketHeaders(p.wgeBPFProxy.localWGListenPort, addr)
@@ -219,6 +219,17 @@ func (p *ProxyWrapper) RedirectAs(endpoint *net.UDPAddr) {
 	p.pausedCond.L.Unlock()
 }
 
+// InjectPacket writes b to the remote peer over the underlying transport.
+func (p *ProxyWrapper) InjectPacket(b []byte) error {
+	if p.remoteConn == nil {
+		return errors.New("proxy not started")
+	}
+	if _, err := p.remoteConn.Write(b); err != nil {
+		return err
+	}
+	return nil
+}
+
 // CloseConn close the remoteConn and automatically remove the conn instance from the map
 func (p *ProxyWrapper) CloseConn() error {
 	if p.cancel == nil {
@@ -241,7 +252,7 @@ func (p *ProxyWrapper) CloseConn() error {
 }
 
 func (p *ProxyWrapper) proxyToLocal(ctx context.Context) {
-	defer p.wgeBPFProxy.removeTurnConn(uint16(p.wgRelayedEndpointAddr.Port))
+	defer p.wgeBPFProxy.removeRelayedConn(uint16(p.wgRelayedEndpointAddr.Port))
 
 	buf := make([]byte, p.wgeBPFProxy.mtu+bufsize.WGBufferOverhead)
 	for {
@@ -262,7 +273,7 @@ func (p *ProxyWrapper) proxyToLocal(ctx context.Context) {
 			if ctx.Err() != nil {
 				return
 			}
-			log.Errorf("failed to write out turn pkg to local conn: %v", err)
+			log.Errorf("failed to write out relayed pkg to local conn: %v", err)
 		}
 	}
 }
@@ -275,7 +286,7 @@ func (p *ProxyWrapper) readFromRemote(ctx context.Context, buf []byte) (int, err
 		}
 		p.closeListener.Notify()
 		if !errors.Is(err, io.EOF) {
-			log.Errorf("failed to read from turn conn (endpoint: :%d): %s", p.wgRelayedEndpointAddr.Port, err)
+			log.Errorf("failed to read from relayed conn (endpoint: :%d): %s", p.wgRelayedEndpointAddr.Port, err)
 		}
 		return 0, err
 	}

client/iface/wgproxy/proxy.go

@@ -7,7 +7,7 @@ import (
 
 // Proxy is a transfer layer between the relayed connection and the WireGuard
 type Proxy interface {
-	AddTurnConn(ctx context.Context, endpoint *net.UDPAddr, remoteConn net.Conn) error
+	AddRelayedConn(ctx context.Context, endpoint *net.UDPAddr, remoteConn net.Conn) error
 	EndpointAddr() *net.UDPAddr // EndpointAddr returns the address of the WireGuard peer endpoint
 	Work()                      // Work start or resume the proxy
 	Pause()                     // Pause to forward the packages from remote connection to WireGuard. The opposite way still works.
@@ -18,4 +18,9 @@ type Proxy interface {
 	RedirectAs(endpoint *net.UDPAddr)
 	CloseConn() error
 	SetDisconnectListener(disconnected func())
+
+	// InjectPacket writes a raw packet directly to the remote peer over the underlying transport,
+	// bypassing WireGuard. Used to replay the captured lazyconn handshake initiation. Only the
+	// kernel-mode proxies act on it; the userspace proxy is a no-op since reinjection is kernel-only.
+	InjectPacket(b []byte) error
 }

client/iface/wgproxy/proxy_linux_test.go

@@ -1,4 +1,4 @@
-//go:build linux && !android
+//go:build linux && !android && privileged
 
 package wgproxy
 

client/iface/wgproxy/proxy_seed_test.go

@@ -1,4 +1,4 @@
-//go:build !linux
+//go:build !linux || !privileged
 
 package wgproxy
 

client/iface/wgproxy/proxy_test.go

@@ -95,7 +95,7 @@ func TestProxyCloseByRemoteConn(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			addr, _ := net.ResolveUDPAddr("udp", "100.108.135.221:51892")
 			relayedConn := newMockConn()
-			err := tt.proxy.AddTurnConn(ctx, addr, relayedConn)
+			err := tt.proxy.AddRelayedConn(ctx, addr, relayedConn)
 			if err != nil {
 				t.Errorf("error: %v", err)
 			}
@@ -157,7 +157,7 @@ func redirectTraffic(t *testing.T, proxy Proxy, wgPort int, endPointAddr *net.UD
 		_ = relayedServer.Close()
 	}()
 
-	if err := proxy.AddTurnConn(context.Background(), endPointAddr, relayedConn); err != nil {
+	if err := proxy.AddRelayedConn(context.Background(), endPointAddr, relayedConn); err != nil {
 		t.Errorf("error: %v", err)
 	}
 	defer func() {

client/iface/wgproxy/redirect_test.go

@@ -1,4 +1,4 @@
-//go:build linux && !android
+//go:build linux && !android && privileged
 
 package wgproxy
 
@@ -26,64 +26,6 @@ func compareUDPAddr(addr1, addr2 net.Addr) bool {
 	return udpAddr1.IP.Equal(udpAddr2.IP) && udpAddr1.Port == udpAddr2.Port
 }
 
-// TestRedirectAs_eBPF_IPv4 tests RedirectAs with eBPF proxy using IPv4 addresses
-func TestRedirectAs_eBPF_IPv4(t *testing.T) {
-	wgPort := 51850
-	ebpfProxy := ebpf.NewWGEBPFProxy(wgPort, 1280)
-	if err := ebpfProxy.Listen(); err != nil {
-		t.Fatalf("failed to initialize ebpf proxy: %v", err)
-	}
-	defer func() {
-		if err := ebpfProxy.Free(); err != nil {
-			t.Errorf("failed to free ebpf proxy: %v", err)
-		}
-	}()
-
-	proxy := ebpf.NewProxyWrapper(ebpfProxy)
-
-	// NetBird UDP address of the remote peer
-	nbAddr := &net.UDPAddr{
-		IP:   net.ParseIP("100.108.111.177"),
-		Port: 38746,
-	}
-
-	p2pEndpoint := &net.UDPAddr{
-		IP:   net.ParseIP("192.168.0.56"),
-		Port: 51820,
-	}
-
-	testRedirectAs(t, proxy, wgPort, nbAddr, p2pEndpoint)
-}
-
-// TestRedirectAs_eBPF_IPv6 tests RedirectAs with eBPF proxy using IPv6 addresses
-func TestRedirectAs_eBPF_IPv6(t *testing.T) {
-	wgPort := 51851
-	ebpfProxy := ebpf.NewWGEBPFProxy(wgPort, 1280)
-	if err := ebpfProxy.Listen(); err != nil {
-		t.Fatalf("failed to initialize ebpf proxy: %v", err)
-	}
-	defer func() {
-		if err := ebpfProxy.Free(); err != nil {
-			t.Errorf("failed to free ebpf proxy: %v", err)
-		}
-	}()
-
-	proxy := ebpf.NewProxyWrapper(ebpfProxy)
-
-	// NetBird UDP address of the remote peer
-	nbAddr := &net.UDPAddr{
-		IP:   net.ParseIP("100.108.111.177"),
-		Port: 38746,
-	}
-
-	p2pEndpoint := &net.UDPAddr{
-		IP:   net.ParseIP("fe80::56"),
-		Port: 51820,
-	}
-
-	testRedirectAs(t, proxy, wgPort, nbAddr, p2pEndpoint)
-}
-
 // TestRedirectAs_UDP_IPv4 tests RedirectAs with UDP proxy using IPv4 addresses
 func TestRedirectAs_UDP_IPv4(t *testing.T) {
 	wgPort := 51852
@@ -177,9 +119,9 @@ func testRedirectAs(t *testing.T, proxy Proxy, wgPort int, nbAddr, p2pEndpoint *
 	}
 	defer relayConn.Close()
 
-	// Add TURN connection to proxy
-	if err := proxy.AddTurnConn(ctx, nbAddr, relayConn); err != nil {
-		t.Fatalf("failed to add TURN connection: %v", err)
+	// Add relayed connection to proxy
+	if err := proxy.AddRelayedConn(ctx, nbAddr, relayConn); err != nil {
+		t.Fatalf("failed to add relayed connection: %v", err)
 	}
 	defer func() {
 		if err := proxy.CloseConn(); err != nil {
@@ -256,6 +198,64 @@ func testRedirectAs(t *testing.T, proxy Proxy, wgPort int, nbAddr, p2pEndpoint *
 	}
 }
 
+// TestRedirectAs_eBPF_IPv4 tests RedirectAs with eBPF proxy using IPv4 addresses
+func TestRedirectAs_eBPF_IPv4(t *testing.T) {
+	wgPort := 51850
+	ebpfProxy := ebpf.NewWGEBPFProxy(wgPort, 1280)
+	if err := ebpfProxy.Listen(); err != nil {
+		t.Fatalf("failed to initialize ebpf proxy: %v", err)
+	}
+	defer func() {
+		if err := ebpfProxy.Free(); err != nil {
+			t.Errorf("failed to free ebpf proxy: %v", err)
+		}
+	}()
+
+	proxy := ebpf.NewProxyWrapper(ebpfProxy)
+
+	// NetBird UDP address of the remote peer
+	nbAddr := &net.UDPAddr{
+		IP:   net.ParseIP("100.108.111.177"),
+		Port: 38746,
+	}
+
+	p2pEndpoint := &net.UDPAddr{
+		IP:   net.ParseIP("192.168.0.56"),
+		Port: 51820,
+	}
+
+	testRedirectAs(t, proxy, wgPort, nbAddr, p2pEndpoint)
+}
+
+// TestRedirectAs_eBPF_IPv6 tests RedirectAs with eBPF proxy using IPv6 addresses
+func TestRedirectAs_eBPF_IPv6(t *testing.T) {
+	wgPort := 51851
+	ebpfProxy := ebpf.NewWGEBPFProxy(wgPort, 1280)
+	if err := ebpfProxy.Listen(); err != nil {
+		t.Fatalf("failed to initialize ebpf proxy: %v", err)
+	}
+	defer func() {
+		if err := ebpfProxy.Free(); err != nil {
+			t.Errorf("failed to free ebpf proxy: %v", err)
+		}
+	}()
+
+	proxy := ebpf.NewProxyWrapper(ebpfProxy)
+
+	// NetBird UDP address of the remote peer
+	nbAddr := &net.UDPAddr{
+		IP:   net.ParseIP("100.108.111.177"),
+		Port: 38746,
+	}
+
+	p2pEndpoint := &net.UDPAddr{
+		IP:   net.ParseIP("fe80::56"),
+		Port: 51820,
+	}
+
+	testRedirectAs(t, proxy, wgPort, nbAddr, p2pEndpoint)
+}
+
 // TestRedirectAs_Multiple_Switches tests switching between multiple endpoints
 func TestRedirectAs_Multiple_Switches(t *testing.T) {
 	wgPort := 51856
@@ -304,8 +304,8 @@ func TestRedirectAs_Multiple_Switches(t *testing.T) {
 		Port: 38746,
 	}
 
-	if err := proxy.AddTurnConn(ctx, nbAddr, relayConn); err != nil {
-		t.Fatalf("failed to add TURN connection: %v", err)
+	if err := proxy.AddRelayedConn(ctx, nbAddr, relayConn); err != nil {
+		t.Fatalf("failed to add relayed connection: %v", err)
 	}
 	defer func() {
 		if err := proxy.CloseConn(); err != nil {

client/iface/wgproxy/udp/proxy.go

@@ -51,12 +51,12 @@ func NewWGUDPProxy(wgPort int, mtu uint16) *WGUDPProxy {
 	return p
 }
 
-// AddTurnConn
+// AddRelayedConn dials the local WireGuard port and stores the relayed connection.
 // The provided Context must be non-nil. If the context expires before
 // the connection is complete, an error is returned. Once successfully
 // connected, any expiration of the context will not affect the
 // connection.
-func (p *WGUDPProxy) AddTurnConn(ctx context.Context, _ *net.UDPAddr, remoteConn net.Conn) error {
+func (p *WGUDPProxy) AddRelayedConn(ctx context.Context, _ *net.UDPAddr, remoteConn net.Conn) error {
 	dialer := net.Dialer{}
 	localConn, err := dialer.DialContext(ctx, "udp", fmt.Sprintf(":%d", p.localWGListenPort))
 	if err != nil {
@@ -147,6 +147,17 @@ func (p *WGUDPProxy) RedirectAs(endpoint *net.UDPAddr) {
 	p.sendPkg = p.srcFakerConn.SendPkg
 }
 
+// InjectPacket writes b to the remote peer over the underlying transport.
+func (p *WGUDPProxy) InjectPacket(b []byte) error {
+	if p.remoteConn == nil {
+		return errors.New("proxy not started")
+	}
+	if _, err := p.remoteConn.Write(b); err != nil {
+		return err
+	}
+	return nil
+}
+
 // CloseConn close the localConn
 func (p *WGUDPProxy) CloseConn() error {
 	if p.cancel == nil {

client/installer.nsis

@@ -6,7 +6,7 @@
 !define DESCRIPTION "Connect your devices into a secure WireGuard-based overlay network with SSO, MFA, and granular access controls."
 !define INSTALLER_NAME "netbird-installer.exe"
 !define MAIN_APP_EXE "Netbird"
-!define ICON "ui\\assets\\netbird.ico"
+!define ICON "ui\\build\\windows\\icon.ico"
 !define BANNER "ui\\build\\banner.bmp"
 !define LICENSE_DATA "..\\LICENSE"
 
@@ -22,8 +22,6 @@
 !define UI_REG_APP_PATH "Software\Microsoft\Windows\CurrentVersion\App Paths\${UI_APP_EXE}"
 !define UI_UNINSTALL_PATH "Software\Microsoft\Windows\CurrentVersion\Uninstall\${UI_APP_NAME}"
 
-!define AUTOSTART_REG_KEY "Software\Microsoft\Windows\CurrentVersion\Run"
-
 !define NETBIRD_DATA_DIR "$COMMONPROGRAMDATA\Netbird"
 
 Unicode True
@@ -79,8 +77,6 @@ ShowInstDetails Show
 
 !insertmacro MUI_PAGE_DIRECTORY
 
-Page custom AutostartPage AutostartPageLeave
-
 !insertmacro MUI_PAGE_INSTFILES
 
 !insertmacro MUI_PAGE_FINISH
@@ -97,40 +93,12 @@ UninstPage custom un.DeleteDataPage un.DeleteDataPageLeave
 
 !insertmacro MUI_LANGUAGE "English"
 
-; Variables for autostart option
-Var AutostartCheckbox
-Var AutostartEnabled
-
 ; Variables for uninstall data deletion option
 Var DeleteDataCheckbox
 Var DeleteDataEnabled
 
 ######################################################################
 
-; Function to create the autostart options page
-Function AutostartPage
-  !insertmacro MUI_HEADER_TEXT "Startup Options" "Configure how ${APP_NAME} launches with Windows."
-
-  nsDialogs::Create 1018
-  Pop $0
-
-  ${If} $0 == error
-    Abort
-  ${EndIf}
-
-  ${NSD_CreateCheckbox} 0 20u 100% 10u "Start ${APP_NAME} UI automatically when Windows starts"
-  Pop $AutostartCheckbox
-  ${NSD_Check} $AutostartCheckbox
-  StrCpy $AutostartEnabled "1"
-
-  nsDialogs::Show
-FunctionEnd
-
-; Function to handle leaving the autostart page
-Function AutostartPageLeave
-  ${NSD_GetState} $AutostartCheckbox $AutostartEnabled
-FunctionEnd
-
 ; Function to create the uninstall data deletion page
 Function un.DeleteDataPage
   !insertmacro MUI_HEADER_TEXT "Uninstall Options" "Choose whether to delete ${APP_NAME} data."
@@ -201,8 +169,6 @@ Pop $0
 
 Function .onInit
 StrCpy $INSTDIR "${INSTALL_DIR}"
-; Default autostart to enabled so silent installs (/S) match the interactive default
-StrCpy $AutostartEnabled "1"
 
 ; Pre-0.70.1 installers ran without SetRegView, so their uninstall keys live
 ; in the 32-bit view. Fall back to it so upgrades still find them.
@@ -260,18 +226,6 @@ WriteRegStr ${REG_ROOT} "${UNINSTALL_PATH}"  "Publisher" "${COMP_NAME}"
 
 WriteRegStr ${REG_ROOT} "${UI_REG_APP_PATH}" "" "$INSTDIR\${UI_APP_EXE}"
 
-; Create autostart registry entry based on checkbox
-DetailPrint "Autostart enabled: $AutostartEnabled"
-${If} $AutostartEnabled == "1"
-    WriteRegStr HKLM "${AUTOSTART_REG_KEY}" "${APP_NAME}" '"$INSTDIR\${UI_APP_EXE}.exe"'
-    DetailPrint "Added autostart registry entry: $INSTDIR\${UI_APP_EXE}.exe"
-${Else}
-    DeleteRegValue HKLM "${AUTOSTART_REG_KEY}" "${APP_NAME}"
-    ; Legacy: pre-HKLM installs wrote to HKCU; clean that up too.
-    DeleteRegValue HKCU "${AUTOSTART_REG_KEY}" "${APP_NAME}"
-    DetailPrint "Autostart not enabled by user"
-${EndIf}
-
 EnVar::SetHKLM
 EnVar::AddValueEx "path" "$INSTDIR"
 
@@ -280,6 +234,43 @@ CreateShortCut "$SMPROGRAMS\${APP_NAME}.lnk" "$INSTDIR\${UI_APP_EXE}"
 CreateShortCut "$DESKTOP\${APP_NAME}.lnk" "$INSTDIR\${UI_APP_EXE}"
 SectionEnd
 
+# Install the Microsoft Edge WebView2 runtime if it isn't already present.
+# Macro adapted from Wails3's NSIS template (wails_tools.nsh): a registry
+# probe followed by a silent install of the embedded evergreen bootstrapper.
+# The MicrosoftEdgeWebview2Setup.exe payload is staged next to this script
+# by the sign-pipelines build step (`wails3 generate webview2bootstrapper`).
+!macro nb.webview2runtime
+    SetRegView 64
+    # Per-machine install marker — populated when the runtime ships with
+    # Edge or has been installed by an admin previously.
+    ReadRegStr $0 HKLM "SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}" "pv"
+    ${If} $0 != ""
+        Goto webview2_ok
+    ${EndIf}
+    # Per-user fallback for HKCU installs.
+    ReadRegStr $0 HKCU "Software\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}" "pv"
+    ${If} $0 != ""
+        Goto webview2_ok
+    ${EndIf}
+
+    SetDetailsPrint both
+    DetailPrint "Installing: WebView2 Runtime"
+    SetDetailsPrint listonly
+
+    InitPluginsDir
+    CreateDirectory "$pluginsdir\webview2bootstrapper"
+    SetOutPath "$pluginsdir\webview2bootstrapper"
+    File "MicrosoftEdgeWebview2Setup.exe"
+    ExecWait '"$pluginsdir\webview2bootstrapper\MicrosoftEdgeWebview2Setup.exe" /silent /install'
+
+    SetDetailsPrint both
+    webview2_ok:
+!macroend
+
+Section -WebView2
+    !insertmacro nb.webview2runtime
+SectionEnd
+
 Section -Post
 ExecWait '"$INSTDIR\${MAIN_APP_EXE}" service install'
 ExecWait '"$INSTDIR\${MAIN_APP_EXE}" service start'
@@ -299,12 +290,6 @@ ExecWait '"$INSTDIR\${MAIN_APP_EXE}" service uninstall'
 DetailPrint "Terminating Netbird UI process..."
 ExecWait `taskkill /im ${UI_APP_EXE}.exe /f`
 
-; Remove autostart registry entry
-DetailPrint "Removing autostart registry entry if exists..."
-DeleteRegValue HKLM "${AUTOSTART_REG_KEY}" "${APP_NAME}"
-; Legacy: pre-HKLM installs wrote to HKCU; clean that up too.
-DeleteRegValue HKCU "${AUTOSTART_REG_KEY}" "${APP_NAME}"
-
 ; Handle data deletion based on checkbox
 DetailPrint "Checking if user requested data deletion..."
 ${If} $DeleteDataEnabled == "1"
@@ -326,9 +311,9 @@ DetailPrint "Deleting application files..."
 Delete "$INSTDIR\${UI_APP_EXE}"
 Delete "$INSTDIR\${MAIN_APP_EXE}"
 Delete "$INSTDIR\wintun.dll"
-!if ${ARCH} == "amd64"
+# Legacy: pre-Wails installs shipped opengl32.dll (Mesa3D for Fyne); remove
+# any leftover copy on uninstall so old upgrades don't leave it behind.
 Delete "$INSTDIR\opengl32.dll"
-!endif
 DetailPrint "Removing application directory..."
 RmDir /r "$INSTDIR"
 

client/internal/acl/manager.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/hashicorp/go-multierror"
+	"github.com/mitchellh/hashstructure/v2"
 	log "github.com/sirupsen/logrus"
 
 	nberrors "github.com/netbirdio/netbird/client/errors"
@@ -30,11 +31,13 @@ type Manager interface {
 
 // DefaultManager uses firewall manager to handle
 type DefaultManager struct {
-	firewall       firewall.Manager
-	ipsetCounter   int
-	peerRulesPairs map[id.RuleID][]firewall.Rule
-	routeRules     map[id.RuleID]struct{}
-	mutex          sync.Mutex
+	firewall           firewall.Manager
+	ipsetCounter       int
+	peerRulesPairs     map[id.RuleID][]firewall.Rule
+	routeRules         map[id.RuleID]struct{}
+	previousConfigHash uint64
+	hasAppliedConfig   bool
+	mutex              sync.Mutex
 }
 
 func NewDefaultManager(fm firewall.Manager) *DefaultManager {
@@ -57,6 +60,23 @@ func (d *DefaultManager) ApplyFiltering(networkMap *mgmProto.NetworkMap, dnsRout
 		return
 	}
 
+	// Skip the full rebuild + flush when the inputs that drive the firewall
+	// state are byte-for-byte identical to the last successfully applied
+	// update. Management re-sends the same network map far more often than it
+	// actually changes (account-wide updates, peer meta churn), and rebuilding
+	// every peer/route ACL and flushing the firewall on every such sync is the
+	// dominant client-side cost when nothing changed. Mirrors the same guard the
+	// DNS server already uses (previousConfigHash). Only the fields ApplyFiltering
+	// consumes participate in the hash, so an unrelated map change cannot mask a
+	// real ACL change.
+	hash, err := d.firewallConfigHash(networkMap, dnsRouteFeatureFlag)
+	if err != nil {
+		log.Errorf("unable to hash firewall configuration, applying unconditionally: %v", err)
+	} else if d.hasAppliedConfig && d.previousConfigHash == hash {
+		log.Debugf("not applying the firewall configuration update as there is nothing new (hash: %d)", hash)
+		return
+	}
+
 	start := time.Now()
 	defer func() {
 		total := 0
@@ -70,13 +90,49 @@ func (d *DefaultManager) ApplyFiltering(networkMap *mgmProto.NetworkMap, dnsRout
 
 	d.applyPeerACLs(networkMap)
 
-	if err := d.applyRouteACLs(networkMap.RoutesFirewallRules, dnsRouteFeatureFlag); err != nil {
-		log.Errorf("Failed to apply route ACLs: %v", err)
+	routeErr := d.applyRouteACLs(networkMap.RoutesFirewallRules, dnsRouteFeatureFlag)
+	if routeErr != nil {
+		log.Errorf("Failed to apply route ACLs: %v", routeErr)
 	}
 
-	if err := d.firewall.Flush(); err != nil {
-		log.Error("failed to flush firewall rules: ", err)
+	flushErr := d.firewall.Flush()
+	if flushErr != nil {
+		log.Error("failed to flush firewall rules: ", flushErr)
 	}
+
+	// Only remember the hash once the firewall actually reflects this config.
+	// If applying or flushing failed, leave the previous hash untouched so the
+	// next (possibly identical) update is not skipped and gets a chance to
+	// reconcile the firewall state.
+	if err == nil && routeErr == nil && flushErr == nil {
+		d.previousConfigHash = hash
+		d.hasAppliedConfig = true
+	} else {
+		d.hasAppliedConfig = false
+	}
+}
+
+// firewallConfigHash hashes exactly the inputs ApplyFiltering uses to build the
+// firewall state, so an identical hash means an identical resulting ruleset.
+func (d *DefaultManager) firewallConfigHash(networkMap *mgmProto.NetworkMap, dnsRouteFeatureFlag bool) (uint64, error) {
+	return hashstructure.Hash(struct {
+		PeerRules           []*mgmProto.FirewallRule
+		PeerRulesIsEmpty    bool
+		RouteRules          []*mgmProto.RouteFirewallRule
+		RouteRulesIsEmpty   bool
+		DNSRouteFeatureFlag bool
+	}{
+		PeerRules:           networkMap.GetFirewallRules(),
+		PeerRulesIsEmpty:    networkMap.GetFirewallRulesIsEmpty(),
+		RouteRules:          networkMap.GetRoutesFirewallRules(),
+		RouteRulesIsEmpty:   networkMap.GetRoutesFirewallRulesIsEmpty(),
+		DNSRouteFeatureFlag: dnsRouteFeatureFlag,
+	}, hashstructure.FormatV2, &hashstructure.HashOptions{
+		ZeroNil:         true,
+		IgnoreZeroValue: true,
+		SlicesAsSets:    true,
+		UseStringer:     true,
+	})
 }
 
 func (d *DefaultManager) applyPeerACLs(networkMap *mgmProto.NetworkMap) {
@@ -88,13 +144,13 @@ func (d *DefaultManager) applyPeerACLs(networkMap *mgmProto.NetworkMap) {
 		log.Warn("this peer is connected to a NetBird Management service with an older version. Allowing all traffic from connected peers")
 		rules = append(rules,
 			&mgmProto.FirewallRule{
-				PeerIP:    "0.0.0.0",
+				PeerIP:    "0.0.0.0", //nolint:staticcheck
 				Direction: mgmProto.RuleDirection_IN,
 				Action:    mgmProto.RuleAction_ACCEPT,
 				Protocol:  mgmProto.RuleProtocol_ALL,
 			},
 			&mgmProto.FirewallRule{
-				PeerIP:    "0.0.0.0",
+				PeerIP:    "0.0.0.0", //nolint:staticcheck
 				Direction: mgmProto.RuleDirection_OUT,
 				Action:    mgmProto.RuleAction_ACCEPT,
 				Protocol:  mgmProto.RuleProtocol_ALL,
@@ -351,7 +407,6 @@ func (d *DefaultManager) getRuleGroupingSelector(rule *mgmProto.FirewallRule) st
 	return fmt.Sprintf("%v:%v:%v:%s:%v", strconv.Itoa(int(rule.Direction)), rule.Action, rule.Protocol, rule.Port, rule.PortInfo)
 }
 
-
 // extractRuleIP extracts the peer IP from a firewall rule.
 // If sourcePrefixes is populated (new management), decode the first entry and use its address.
 // Otherwise fall back to the deprecated PeerIP string field (old management).

client/internal/acl/manager_test.go

@@ -1,12 +1,13 @@
 package acl
 
 import (
+	"fmt"
 	"net/netip"
 	"testing"
 
-	"github.com/golang/mock/gomock"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
 
 	"github.com/netbirdio/netbird/client/firewall"
 	"github.com/netbirdio/netbird/client/iface"
@@ -86,7 +87,7 @@ func TestDefaultManager(t *testing.T) {
 		networkMap.FirewallRules = append(
 			networkMap.FirewallRules,
 			&mgmProto.FirewallRule{
-				PeerIP:    "10.93.0.3",
+				PeerIP:    "10.93.0.3", //nolint:staticcheck
 				Direction: mgmProto.RuleDirection_IN,
 				Action:    mgmProto.RuleAction_DROP,
 				Protocol:  mgmProto.RuleProtocol_ICMP,
@@ -485,3 +486,149 @@ func TestPortInfoEmpty(t *testing.T) {
 		})
 	}
 }
+
+// TestApplyFilteringSkipsUnchangedConfig verifies that an identical network map
+// re-applied is recognized as a no-op (hash unchanged), while a real change to
+// any firewall-relevant input forces a re-apply (hash changes). This is the
+// guard that prevents a full ruleset rebuild + flush on every redundant sync.
+func TestApplyFilteringSkipsUnchangedConfig(t *testing.T) {
+	t.Setenv("NB_WG_KERNEL_DISABLED", "true")
+	t.Setenv(firewall.EnvForceUserspaceFirewall, "true")
+
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+
+	ifaceMock := mocks.NewMockIFaceMapper(ctrl)
+	ifaceMock.EXPECT().IsUserspaceBind().Return(true).AnyTimes()
+	ifaceMock.EXPECT().SetFilter(gomock.Any())
+	network := netip.MustParsePrefix("172.0.0.1/32")
+	ifaceMock.EXPECT().Name().Return("lo").AnyTimes()
+	ifaceMock.EXPECT().Address().Return(wgaddr.Address{
+		IP:      network.Addr(),
+		Network: network,
+	}).AnyTimes()
+	ifaceMock.EXPECT().GetWGDevice().Return(nil).AnyTimes()
+
+	fw, err := firewall.NewFirewall(ifaceMock, nil, flowLogger, false, iface.DefaultMTU)
+	require.NoError(t, err)
+	defer func() {
+		require.NoError(t, fw.Close(nil))
+	}()
+
+	acl := NewDefaultManager(fw)
+
+	networkMap := &mgmProto.NetworkMap{
+		FirewallRules: []*mgmProto.FirewallRule{
+			{
+				PeerIP:    "10.93.0.1",
+				Direction: mgmProto.RuleDirection_IN,
+				Action:    mgmProto.RuleAction_ACCEPT,
+				Protocol:  mgmProto.RuleProtocol_TCP,
+				Port:      "22",
+			},
+		},
+		FirewallRulesIsEmpty: false,
+	}
+
+	acl.ApplyFiltering(networkMap, false)
+	require.True(t, acl.hasAppliedConfig, "config should be marked applied after first apply")
+	firstHash := acl.previousConfigHash
+	require.NotZero(t, firstHash)
+
+	// Re-applying the identical map must not change the recorded hash: the
+	// expensive rebuild path was skipped.
+	acl.ApplyFiltering(networkMap, false)
+	assert.Equal(t, firstHash, acl.previousConfigHash,
+		"identical re-apply must be a no-op (hash unchanged)")
+
+	// A real change must produce a different hash and re-apply.
+	networkMap.FirewallRules[0].Action = mgmProto.RuleAction_DROP
+	acl.ApplyFiltering(networkMap, false)
+	assert.NotEqual(t, firstHash, acl.previousConfigHash,
+		"changing a rule's action must force a re-apply (hash changed)")
+
+	// The dnsRouteFeatureFlag also participates in the hash.
+	changedHash := acl.previousConfigHash
+	acl.ApplyFiltering(networkMap, true)
+	assert.NotEqual(t, changedHash, acl.previousConfigHash,
+		"flipping dnsRouteFeatureFlag must force a re-apply (hash changed)")
+}
+
+func buildNetworkMap(peerRules, routeRules int) *mgmProto.NetworkMap {
+	nm := &mgmProto.NetworkMap{
+		FirewallRulesIsEmpty:       peerRules == 0,
+		RoutesFirewallRulesIsEmpty: routeRules == 0,
+	}
+	for i := range peerRules {
+		nm.FirewallRules = append(nm.FirewallRules, &mgmProto.FirewallRule{
+			PeerIP:    fmt.Sprintf("10.%d.%d.%d", i>>16&0xff, i>>8&0xff, i&0xff), //nolint:staticcheck
+			Direction: mgmProto.RuleDirection_IN,
+			Action:    mgmProto.RuleAction_ACCEPT,
+			Protocol:  mgmProto.RuleProtocol_TCP,
+			Port:      fmt.Sprintf("%d", 1024+i%64511),
+		})
+	}
+	for i := range routeRules {
+		nm.RoutesFirewallRules = append(nm.RoutesFirewallRules, &mgmProto.RouteFirewallRule{
+			Destination:  fmt.Sprintf("192.168.%d.0/24", i%256),
+			SourceRanges: []string{fmt.Sprintf("10.0.%d.0/24", i%256)},
+			Action:       mgmProto.RuleAction_ACCEPT,
+			Protocol:     mgmProto.RuleProtocol_ALL,
+		})
+	}
+	return nm
+}
+
+func BenchmarkFirewallConfigHash_Small(b *testing.B) {
+	d := &DefaultManager{}
+	nm := buildNetworkMap(10, 5)
+	b.ResetTimer()
+	for b.Loop() {
+		_, _ = d.firewallConfigHash(nm, false)
+	}
+}
+
+func BenchmarkFirewallConfigHash_Medium(b *testing.B) {
+	d := &DefaultManager{}
+	nm := buildNetworkMap(100, 50)
+	b.ResetTimer()
+	for b.Loop() {
+		_, _ = d.firewallConfigHash(nm, false)
+	}
+}
+
+func BenchmarkFirewallConfigHash_Large(b *testing.B) {
+	d := &DefaultManager{}
+	nm := buildNetworkMap(1000, 200)
+	b.ResetTimer()
+	for b.Loop() {
+		_, _ = d.firewallConfigHash(nm, false)
+	}
+}
+
+// TestFirewallConfigHashDeterministic verifies the hash is stable for equal
+// inputs and order-independent for the rule slices (management does not
+// guarantee rule order).
+func TestFirewallConfigHashDeterministic(t *testing.T) {
+	d := &DefaultManager{}
+
+	nm1 := &mgmProto.NetworkMap{
+		FirewallRules: []*mgmProto.FirewallRule{
+			{PeerIP: "10.0.0.1", Direction: mgmProto.RuleDirection_IN, Action: mgmProto.RuleAction_ACCEPT, Protocol: mgmProto.RuleProtocol_TCP, Port: "22"},
+			{PeerIP: "10.0.0.2", Direction: mgmProto.RuleDirection_IN, Action: mgmProto.RuleAction_DROP, Protocol: mgmProto.RuleProtocol_TCP, Port: "80"},
+		},
+	}
+	// Same rules, reversed order.
+	nm2 := &mgmProto.NetworkMap{
+		FirewallRules: []*mgmProto.FirewallRule{
+			nm1.FirewallRules[1],
+			nm1.FirewallRules[0],
+		},
+	}
+
+	h1, err := d.firewallConfigHash(nm1, false)
+	require.NoError(t, err)
+	h2, err := d.firewallConfigHash(nm2, false)
+	require.NoError(t, err)
+	assert.Equal(t, h1, h2, "hash must be order-independent for rule slices")
+}

client/internal/acl/mocks/iface_mapper.go

@@ -7,7 +7,7 @@ package mocks
 import (
 	reflect "reflect"
 
-	gomock "github.com/golang/mock/gomock"
+	gomock "go.uber.org/mock/gomock"
 	wgdevice "golang.zx2c4.com/wireguard/device"
 
 	"github.com/netbirdio/netbird/client/iface/device"

client/internal/auth/auth.go

@@ -3,6 +3,7 @@ package auth
 import (
 	"context"
 	"net/url"
+	"strings"
 	"sync"
 	"time"
 
@@ -21,6 +22,25 @@ import (
 	mgmProto "github.com/netbirdio/netbird/shared/management/proto"
 )
 
+// peerLoginExpiredMsg is the exact phrase the management server returns
+// when a previously SSO-enrolled peer's login has expired. Sourced from
+// shared/management/status/error.go (NewPeerLoginExpiredError). Matched
+// by substring so a future server-side rewording that keeps the phrase
+// still triggers the friendly fallback in Login().
+const peerLoginExpiredMsg = "peer login has expired"
+
+// errSetupKeyOnSSOExpiredPeer replaces the raw management error when the
+// user runs `netbird login -k <setup-key>` against a peer that was
+// originally enrolled via SSO. Wrapped in a PermissionDenied gRPC status
+// so callers' existing isPermissionDenied / isAuthError checks still
+// classify it correctly (early-exit from retry backoff, StatusNeedsLogin
+// in the server state machine).
+var errSetupKeyOnSSOExpiredPeer = status.Error(
+	codes.PermissionDenied,
+	"this peer was originally enrolled via SSO and its session has expired. "+
+		"Setup keys can only enrol new peers — run `netbird up` (interactive SSO) to re-login.",
+)
+
 // Auth manages authentication operations with the management server
 // It maintains a long-lived connection and automatically handles reconnection with backoff
 type Auth struct {
@@ -118,26 +138,37 @@ func (a *Auth) IsSSOSupported(ctx context.Context) (bool, error) {
 
 // GetOAuthFlow returns an OAuth flow (PKCE or Device) using the existing management connection
 // This avoids creating a new connection to the management server
-func (a *Auth) GetOAuthFlow(ctx context.Context, forceDeviceAuth bool) (OAuthFlow, error) {
+func (a *Auth) GetOAuthFlow(ctx context.Context, forceDeviceAuth bool, hint string) (OAuthFlow, error) {
 	var flow OAuthFlow
-	var err error
 
-	err = a.withRetry(ctx, func(client *mgm.GrpcClient) error {
+	err := a.withRetry(ctx, func(client *mgm.GrpcClient) error {
 		if forceDeviceAuth {
-			flow, err = a.getDeviceFlow(client)
-			return err
+			deviceFlow, err := a.getDeviceFlow(client)
+			if err != nil {
+				return err
+			}
+			deviceFlow.SetLoginHint(hint)
+			flow = deviceFlow
+			return nil
 		}
 
 		// Try PKCE flow first
-		flow, err = a.getPKCEFlow(client)
+		pkceFlow, err := a.getPKCEFlow(client)
 		if err != nil {
 			// If PKCE not supported, try Device flow
 			if s, ok := status.FromError(err); ok && (s.Code() == codes.NotFound || s.Code() == codes.Unimplemented) {
-				flow, err = a.getDeviceFlow(client)
-				return err
+				deviceFlow, err := a.getDeviceFlow(client)
+				if err != nil {
+					return err
+				}
+				deviceFlow.SetLoginHint(hint)
+				flow = deviceFlow
+				return nil
 			}
 			return err
 		}
+		pkceFlow.SetLoginHint(hint)
+		flow = pkceFlow
 		return nil
 	})
 
@@ -184,6 +215,15 @@ func (a *Auth) Login(ctx context.Context, setupKey string, jwtToken string) (err
 			log.Debugf("peer registration required")
 			_, err = a.registerPeer(client, ctx, setupKey, jwtToken, pubSSHKey)
 			if err != nil {
+				// The peer pub-key is already on file with the management
+				// server (originally enrolled via SSO) and the session has
+				// expired. The setup-key path can only enrol new peers, so
+				// retrying with -k will keep failing. Replace the raw mgm
+				// message with an actionable hint that tells the user to
+				// re-authenticate via SSO instead.
+				if setupKey != "" && jwtToken == "" && isPeerLoginExpired(err) {
+					err = errSetupKeyOnSSOExpiredPeer
+				}
 				isAuthError = isPermissionDenied(err)
 				return err
 			}
@@ -322,7 +362,7 @@ func (a *Auth) setSystemInfoFlags(info *system.Info) {
 		a.config.BlockLANAccess,
 		a.config.BlockInbound,
 		a.config.DisableIPv6,
-		a.config.LazyConnectionEnabled,
+		a.config.SyncMessageVersion,
 		a.config.EnableSSHRoot,
 		a.config.EnableSSHSFTP,
 		a.config.EnableSSHLocalPortForwarding,
@@ -474,3 +514,16 @@ func isLoginNeeded(err error) bool {
 func isRegistrationNeeded(err error) bool {
 	return isPermissionDenied(err)
 }
+
+// isPeerLoginExpired reports whether err is the management server's
+// "peer login has expired" PermissionDenied response. Used by Login to
+// detect the case where the caller passed a setup-key but the peer is
+// actually an SSO-enrolled record whose session needs refreshing — the
+// setup-key path cannot help there.
+func isPeerLoginExpired(err error) bool {
+	if !isPermissionDenied(err) {
+		return false
+	}
+	s, _ := status.FromError(err)
+	return strings.Contains(s.Message(), peerLoginExpiredMsg)
+}

client/internal/auth/auth_test.go

@@ -0,0 +1,80 @@
+package auth
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+func TestIsPeerLoginExpired(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{
+			name: "nil",
+			err:  nil,
+			want: false,
+		},
+		{
+			name: "plain error (not a gRPC status)",
+			err:  errors.New("network read: connection reset"),
+			want: false,
+		},
+		{
+			name: "PermissionDenied with different message",
+			err:  status.Error(codes.PermissionDenied, "user is blocked"),
+			want: false,
+		},
+		{
+			name: "Unauthenticated with the expected phrase",
+			// Wrong status code — must still return false.
+			err:  status.Error(codes.Unauthenticated, "peer login has expired, please log in once more"),
+			want: false,
+		},
+		{
+			name: "exact server message",
+			err:  status.Error(codes.PermissionDenied, "peer login has expired, please log in once more"),
+			want: true,
+		},
+		{
+			name: "phrase as substring",
+			// Future-proofing: if mgm reworords but keeps the phrase,
+			// the friendly fallback must still kick in.
+			err:  status.Error(codes.PermissionDenied, "session refused: peer login has expired (account=foo)"),
+			want: true,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := isPeerLoginExpired(tc.err); got != tc.want {
+				t.Fatalf("isPeerLoginExpired(%v) = %v, want %v", tc.err, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestErrSetupKeyOnSSOExpiredPeer(t *testing.T) {
+	// Sentinel must surface as PermissionDenied so the upstream
+	// isPermissionDenied / isAuthError checks classify it correctly
+	// (short-circuit retry backoff, set StatusNeedsLogin).
+	if !isPermissionDenied(errSetupKeyOnSSOExpiredPeer) {
+		t.Fatalf("errSetupKeyOnSSOExpiredPeer must be a PermissionDenied gRPC error")
+	}
+
+	// Message must actually mention SSO and `netbird up` so it is
+	// actionable for the end user. Loose substring checks keep the
+	// test resilient to copy edits.
+	s, _ := status.FromError(errSetupKeyOnSSOExpiredPeer)
+	msg := strings.ToLower(s.Message())
+	for _, want := range []string{"sso", "netbird up"} {
+		if !strings.Contains(msg, want) {
+			t.Errorf("sentinel message should contain %q, got %q", want, s.Message())
+		}
+	}
+}

client/internal/auth/device_flow.go

@@ -259,12 +259,18 @@ func (d *DeviceAuthorizationFlow) WaitToken(ctx context.Context, info AuthFlowIn
 	ticker := time.NewTicker(interval)
 	defer ticker.Stop()
 
+	log.Infof("device flow: waiting for user authorization, polling token endpoint every %s, code expires in %s", interval, timeout)
+
+	start := time.Now()
+	polls := 0
+
 	for {
 		select {
 		case <-waitCtx.Done():
 			return TokenInfo{}, waitCtx.Err()
 		case <-ticker.C:
 
+			polls++
 			tokenResponse, err := d.requestToken(info)
 			if err != nil {
 				return TokenInfo{}, fmt.Errorf("parsing token response failed with error: %v", err)
@@ -272,10 +278,12 @@ func (d *DeviceAuthorizationFlow) WaitToken(ctx context.Context, info AuthFlowIn
 
 			if tokenResponse.Error != "" {
 				if tokenResponse.Error == "authorization_pending" {
+					log.Tracef("device flow: authorization still pending after poll %d", polls)
 					continue
 				} else if tokenResponse.Error == "slow_down" {
 					interval += (3 * time.Second)
 					ticker.Reset(interval)
+					log.Infof("device flow: IdP requested slow_down, polling interval increased to %s", interval)
 					continue
 				}
 
@@ -291,11 +299,12 @@ func (d *DeviceAuthorizationFlow) WaitToken(ctx context.Context, info AuthFlowIn
 				UseIDToken:   d.providerConfig.UseIDToken,
 			}
 
-			err = isValidAccessToken(tokenInfo.GetTokenToUse(), d.providerConfig.Audience)
+			err = validateTokenAudience(tokenInfo.GetTokenToUse(), d.providerConfig.Audience)
 			if err != nil {
 				return TokenInfo{}, fmt.Errorf("validate access token failed with error: %v", err)
 			}
 
+			log.Infof("device flow: user authorization confirmed after %d polls in %s", polls, time.Since(start).Round(time.Second))
 			return tokenInfo, err
 		}
 	}

client/internal/auth/oauth.go

@@ -97,9 +97,7 @@ func authenticateWithPKCEFlow(ctx context.Context, config *profilemanager.Config
 		return nil, fmt.Errorf("getting pkce authorization flow info failed with error: %v", err)
 	}
 
-	if hint != "" {
-		pkceFlowInfo.SetLoginHint(hint)
-	}
+	pkceFlowInfo.SetLoginHint(hint)
 
 	return pkceFlowInfo, nil
 }
@@ -127,9 +125,7 @@ func authenticateWithDeviceCodeFlow(ctx context.Context, config *profilemanager.
 		}
 	}
 
-	if hint != "" {
-		deviceFlowInfo.SetLoginHint(hint)
-	}
+	deviceFlowInfo.SetLoginHint(hint)
 
 	return deviceFlowInfo, nil
 }

client/internal/auth/pending_flow.go

@@ -0,0 +1,89 @@
+package auth
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// PendingFlow stores an in-progress OAuth flow between the RPC that
+// initiates it (returns the verification URI to the UI) and the RPC
+// that waits for the user to complete it. The flow handle, the
+// device-code info, and the absolute expiry are kept together so the
+// waiting RPC can validate the device code and reuse the same flow.
+//
+// PendingFlow is safe for concurrent use; callers must not access the
+// stored fields directly.
+type PendingFlow struct {
+	mu         sync.Mutex
+	flow       OAuthFlow
+	info       AuthFlowInfo
+	expiresAt  time.Time
+	waitCancel context.CancelFunc
+}
+
+// NewPendingFlow returns an empty PendingFlow ready to be populated by Set.
+func NewPendingFlow() *PendingFlow {
+	return &PendingFlow{}
+}
+
+// Set stores the flow and its authorization info, computing the absolute
+// expiry from info.ExpiresIn (seconds, as returned by the IdP).
+func (p *PendingFlow) Set(flow OAuthFlow, info AuthFlowInfo) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.flow = flow
+	p.info = info
+	p.expiresAt = time.Now().Add(time.Duration(info.ExpiresIn) * time.Second)
+}
+
+// Get returns the stored flow, info, and whether a flow is currently
+// pending. Returns (nil, zero, false) after Clear or before Set.
+func (p *PendingFlow) Get() (OAuthFlow, AuthFlowInfo, bool) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if p.flow == nil {
+		return nil, AuthFlowInfo{}, false
+	}
+	return p.flow, p.info, true
+}
+
+// ExpiresAt returns the absolute expiry of the pending flow. Returns
+// the zero time when no flow is pending.
+func (p *PendingFlow) ExpiresAt() time.Time {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return p.expiresAt
+}
+
+// SetWaitCancel records the cancel function for the goroutine currently
+// blocked in WaitToken so a new RequestAuth can preempt it.
+func (p *PendingFlow) SetWaitCancel(cancel context.CancelFunc) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.waitCancel = cancel
+}
+
+// CancelWait invokes and clears the stored wait-cancel, if any. Safe to
+// call when no wait is in progress.
+func (p *PendingFlow) CancelWait() {
+	p.mu.Lock()
+	cancel := p.waitCancel
+	p.waitCancel = nil
+	p.mu.Unlock()
+	if cancel != nil {
+		cancel()
+	}
+}
+
+// Clear resets the pending flow to empty. Any stored wait-cancel is
+// dropped without being invoked — call CancelWait first if the waiting
+// goroutine must be stopped.
+func (p *PendingFlow) Clear() {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.flow = nil
+	p.info = AuthFlowInfo{}
+	p.expiresAt = time.Time{}
+	p.waitCancel = nil
+}

client/internal/auth/pkce_flow.go

@@ -188,6 +188,8 @@ func (p *PKCEAuthorizationFlow) WaitToken(ctx context.Context, info AuthFlowInfo
 	waitCtx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
 
+	log.Infof("pkce flow: waiting for authorization callback on %s, timeout %s", p.oAuthConfig.RedirectURL, timeout)
+
 	tokenChan := make(chan *oauth2.Token, 1)
 	errChan := make(chan error, 1)
 
@@ -221,6 +223,7 @@ func (p *PKCEAuthorizationFlow) WaitToken(ctx context.Context, info AuthFlowInfo
 func (p *PKCEAuthorizationFlow) startServer(server *http.Server, tokenChan chan<- *oauth2.Token, errChan chan<- error) {
 	mux := http.NewServeMux()
 	mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
+		log.Infof("pkce flow: received authorization callback from IdP")
 		cert := p.providerConfig.ClientCertPair
 		if cert != nil {
 			tr := &http.Transport{
@@ -271,11 +274,18 @@ func (p *PKCEAuthorizationFlow) handleRequest(req *http.Request) (*oauth2.Token,
 		return nil, fmt.Errorf("authentication failed: missing code")
 	}
 
-	return p.oAuthConfig.Exchange(
+	exchangeStart := time.Now()
+	token, err := p.oAuthConfig.Exchange(
 		req.Context(),
 		code,
 		oauth2.SetAuthURLParam("code_verifier", p.codeVerifier),
 	)
+	if err != nil {
+		return nil, err
+	}
+
+	log.Infof("pkce flow: authorization code exchanged for token in %s", time.Since(exchangeStart).Round(time.Millisecond))
+	return token, nil
 }
 
 func (p *PKCEAuthorizationFlow) parseOAuthToken(token *oauth2.Token) (TokenInfo, error) {
@@ -296,7 +306,7 @@ func (p *PKCEAuthorizationFlow) parseOAuthToken(token *oauth2.Token) (TokenInfo,
 		audience = p.providerConfig.ClientID
 	}
 
-	if err := isValidAccessToken(tokenInfo.GetTokenToUse(), audience); err != nil {
+	if err := validateTokenAudience(tokenInfo.GetTokenToUse(), audience); err != nil {
 		return TokenInfo{}, fmt.Errorf("authentication failed: invalid access token - %w", err)
 	}
 
@@ -310,6 +320,11 @@ func (p *PKCEAuthorizationFlow) parseOAuthToken(token *oauth2.Token) (TokenInfo,
 	return tokenInfo, nil
 }
 
+// parseEmailFromIDToken extracts the email (or name) claim from an ID token
+// without verifying its signature. The value is best-effort and used only as a
+// UX convenience (login hint prefill and display); it never drives an
+// authorization decision. The authoritative identity is established server-side
+// from the signature-verified token.
 func parseEmailFromIDToken(token string) (string, error) {
 	parts := strings.Split(token, ".")
 	if len(parts) < 2 {

client/internal/auth/sessionwatch/event.go

@@ -0,0 +1,82 @@
+package sessionwatch
+
+import (
+	"strconv"
+	"time"
+)
+
+// internal event kinds are no longer exposed: the watcher drives the Sink
+// directly (NotifyStateChange on deadline change/clear, PublishEvent at
+// each warning lead). Tests use a mock Sink to observe what the watcher
+// emits.
+
+// Metadata keys attached by the daemon to session-warning SystemEvents.
+// The UI tray reads these to build a locale-aware notification without
+// relying on the daemon's locale-less UserMessage string, and to
+// disambiguate the T-WarningLead notification from the T-FinalWarningLead
+// fallback that auto-opens the SessionAboutToExpire dialog.
+const (
+	// MetaSessionWarning is set to "true" on both warning events (T-10 and
+	// T-2) so the UI can detect a session-warning SystemEvent without
+	// matching on the message text. Use MetaSessionFinal to distinguish
+	// the two.
+	MetaSessionWarning = "session_warning"
+	// MetaSessionFinal is set to "true" on the T-FinalWarningLead event
+	// only. Consumers that need to auto-open the SessionAboutToExpire
+	// dialog gate on this; T-WarningLead events leave the field unset.
+	MetaSessionFinal = "session_final_warning"
+	// MetaSessionExpiresAt carries the absolute UTC deadline encoded with
+	// FormatExpiresAt; consumers must decode with ParseExpiresAt so a
+	// future format change stays a single edit.
+	MetaSessionExpiresAt = "session_expires_at"
+	// MetaSessionLeadMinutes carries the lead in whole minutes (WarningLead
+	// for the T-10 event, FinalWarningLead for the T-2 event) so the UI
+	// can show "expires in ~N minutes" without hardcoding either constant.
+	MetaSessionLeadMinutes = "lead_minutes"
+	// MetaSessionDeadlineRejected is attached to the ERROR/AUTHENTICATION
+	// SystemEvent the daemon emits when it discards a deadline from the
+	// management server (pre-epoch, too far in the future, or past the
+	// clock-skew tolerance). The value is the rejection reason string.
+	// userMessage is left empty; the UI detects the event via this key
+	// and builds a localized notification — same pattern as the session
+	// warnings above.
+	MetaSessionDeadlineRejected = "session_deadline_rejected"
+)
+
+// expiresAtLayout is the wire format used for MetaSessionExpiresAt.
+// Producer and consumers both go through FormatExpiresAt/ParseExpiresAt
+// so this layout stays a single source of truth.
+const expiresAtLayout = time.RFC3339
+
+// FormatExpiresAt encodes a deadline for MetaSessionExpiresAt. Always
+// emits UTC so a consumer in another timezone reads the same wall-clock
+// deadline.
+func FormatExpiresAt(t time.Time) string {
+	return t.UTC().Format(expiresAtLayout)
+}
+
+// ParseExpiresAt decodes the MetaSessionExpiresAt value back to a UTC
+// time. Returns an error when the field is empty or malformed; the
+// caller decides whether to fall back (zero value) or propagate.
+func ParseExpiresAt(s string) (time.Time, error) {
+	t, err := time.Parse(expiresAtLayout, s)
+	if err != nil {
+		return time.Time{}, err
+	}
+	return t.UTC(), nil
+}
+
+// FormatLeadMinutes encodes a lead duration for MetaSessionLeadMinutes
+// as the integer count of whole minutes. Sub-minute residuals are
+// truncated — the field is informational ("expires in ~N minutes") and
+// fractional minutes don't change what the UI displays.
+func FormatLeadMinutes(d time.Duration) string {
+	return strconv.Itoa(int(d / time.Minute))
+}
+
+// ParseLeadMinutes decodes a MetaSessionLeadMinutes value. Returns 0
+// and the parse error for malformed input; consumers that prefer a
+// silent fallback can simply ignore the error.
+func ParseLeadMinutes(s string) (int, error) {
+	return strconv.Atoi(s)
+}

client/internal/auth/sessionwatch/watcher.go

@@ -0,0 +1,382 @@
+// Package sessionwatch tracks the SSO session expiry deadline that the
+// management server publishes via LoginResponse / SyncResponse and fires
+// two warning events at fixed lead times before expiry: an interactive
+// T-WarningLead notification and a dismiss-gated T-FinalWarningLead
+// fallback dialog.
+//
+// The watcher is idempotent: Update may be called as often as the network
+// map snapshots arrive. Repeating the same deadline is a no-op; a new
+// deadline reschedules the timers and arms a fresh warning cycle.
+//
+// Warning firing is edge-detected. Each unique deadline value fires each
+// warning callback at most once.
+package sessionwatch
+
+import (
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+
+	cProto "github.com/netbirdio/netbird/client/proto"
+)
+
+const (
+	maxPastHorizon = 30 * 24 * time.Hour
+
+	// maxDeadlineHorizon caps how far in the future an accepted deadline
+	// can sit. A timestamp beyond this is almost certainly a protocol
+	// glitch, and silently arming a 100-year timer would hide the bug.
+	maxDeadlineHorizon = 10 * 365 * 24 * time.Hour
+
+	// WarningLead is how far before expiry the first (interactive)
+	// warning fires. Drives the T-10 OS notification with
+	// Extend/Dismiss actions.
+	WarningLead = 10 * time.Minute
+
+	// FinalWarningLead is how far before expiry the fallback final
+	// warning fires. Drives the auto-opened SessionAboutToExpire dialog,
+	// but only when the user has not dismissed the T-WarningLead warning
+	// for the same deadline. Must be strictly less than WarningLead.
+	FinalWarningLead = 2 * time.Minute
+)
+
+var (
+	// ErrDeadlineBeforeEpoch is returned by Update when the supplied
+	// deadline pre-dates 1970-01-01.
+	ErrDeadlineBeforeEpoch = errors.New("session deadline before unix epoch")
+
+	// ErrDeadlineTooFarFuture is returned by Update when the supplied
+	// deadline is more than maxDeadlineHorizon in the future.
+	ErrDeadlineTooFarFuture = errors.New("session deadline too far in the future")
+
+	// ErrDeadlineInPast is returned by Update when the supplied deadline
+	// is more than maxPastHorizon in the past.
+	ErrDeadlineInPast = errors.New("session deadline in the past")
+)
+
+// StatusRecorder is the side-effect surface the watcher drives on every
+// state transition. Production wires this to peer.Status (SetSessionExpiresAt
+// for deadline change/clear, PublishEvent for the two warnings); tests pass
+// a fake recorder so the same surface is observable without an engine.
+//
+// While the watcher runs, it owns the deadline propagated to the recorder:
+// every set, clear and sanity-check rejection routes the value through
+// SetSessionExpiresAt, so the SubscribeStatus snapshot the UI reads can
+// never drift from the watcher's timer state. (SetSessionExpiresAt fans
+// out its own state-change notification, so no separate notify is needed.)
+// The recorder is server-scoped and outlives this engine-scoped watcher;
+// Close deliberately leaves the recorder value in place so transient engine
+// restarts don't blank it — the client run loop clears it on real teardown.
+//
+// PublishEvent's signature mirrors peer.Status.PublishEvent: the watcher
+// composes the metadata internally so the wire format (MetaSession*) is
+// owned by sessionwatch, not the caller.
+type StatusRecorder interface {
+	SetSessionExpiresAt(deadline time.Time)
+	PublishEvent(
+		severity cProto.SystemEvent_Severity,
+		category cProto.SystemEvent_Category,
+		message string,
+		userMessage string,
+		metadata map[string]string,
+	)
+}
+
+// Watcher observes the latest session deadline and fires two warnings
+// before it expires: the interactive T-WarningLead notification, and the
+// fallback T-FinalWarningLead dialog (suppressed when the user dismissed
+// the first one for the same deadline). Safe for concurrent use.
+type Watcher struct {
+	lead      time.Duration
+	finalLead time.Duration
+
+	mu           sync.Mutex
+	current      time.Time
+	timer        *time.Timer
+	finalTimer   *time.Timer
+	firedAt      time.Time // deadline value the T-WarningLead callback last fired against
+	finalFiredAt time.Time // deadline value the T-FinalWarningLead callback last fired against
+	dismissedAt  time.Time // deadline value the user dismissed via Dismiss(); gates fireFinal
+	closed       bool
+	recorder     StatusRecorder
+}
+
+// New returns a watcher with the package defaults WarningLead and
+// FinalWarningLead. Pass nil for recorder to silence side effects (handy
+// in unit tests that exercise sanity checks without observing the publish
+// path).
+func New(recorder StatusRecorder) *Watcher {
+	return NewWithLeads(WarningLead, FinalWarningLead, recorder)
+}
+
+// NewWithLeads returns a watcher with custom lead times. Useful for tests.
+// final must be strictly less than lead; otherwise both timers fire in the
+// wrong order or simultaneously and the UI flow breaks. A zero final lead
+// disables the final-warning timer entirely (see armTimerLocked) so a
+// millisecond-scale deadline doesn't flush both timers in one tick.
+func NewWithLeads(lead, final time.Duration, recorder StatusRecorder) *Watcher {
+	return &Watcher{
+		lead:      lead,
+		finalLead: final,
+		recorder:  recorder,
+	}
+}
+
+// Update sets the latest deadline. Pass the zero time to clear (e.g. when
+// a Sync push from the server omits the field because login expiration
+// was disabled).
+//
+// Same-value updates are no-ops. A different non-zero value cancels any
+// pending timer, resets the "already fired" guards, and — when the
+// deadline lies in the future — arms fresh warning timers. A deadline
+// already in the past (within maxPastHorizon) is recorded as-is with no
+// timers: the session has expired and consumers render it that way.
+//
+// Returns one of the sentinel Err* values when the deadline fails the
+// sanity checks (pre-epoch, far future, or past beyond maxPastHorizon).
+// In every error case the watcher first clears its state so it stays
+// consistent with what the caller will push into its other sinks (e.g.
+// applySessionDeadline forces a zero deadline into the status recorder
+// after a non-nil error).
+func (w *Watcher) Update(deadline time.Time) error {
+	w.mu.Lock()
+	if w.closed {
+		w.mu.Unlock()
+		return nil
+	}
+
+	if deadline.IsZero() {
+		w.clearLocked()
+		return nil
+	}
+
+	now := time.Now()
+	switch {
+	case deadline.Before(time.Unix(0, 0)):
+		w.clearLocked()
+		return fmt.Errorf("%w: %v", ErrDeadlineBeforeEpoch, deadline)
+	case deadline.After(now.Add(maxDeadlineHorizon)):
+		w.clearLocked()
+		return fmt.Errorf("%w: %v", ErrDeadlineTooFarFuture, deadline)
+	case deadline.Before(now.Add(-maxPastHorizon)):
+		w.clearLocked()
+		return fmt.Errorf("%w: %v (now=%v)", ErrDeadlineInPast, deadline, now)
+	}
+
+	if deadline.Equal(w.current) {
+		w.mu.Unlock()
+		return nil
+	}
+
+	w.stopTimerLocked()
+	w.current = deadline
+	// Reset every per-deadline guard so a refreshed deadline arms a fresh
+	// warning cycle: both edge triggers and the user Dismiss decision
+	// (the user agreed to the old deadline expiring; a new deadline
+	// restarts the contract).
+	w.firedAt = time.Time{}
+	w.finalFiredAt = time.Time{}
+	w.dismissedAt = time.Time{}
+
+	if deadline.After(now) {
+		w.armTimerLocked(deadline)
+	}
+	recorder := w.recorder
+	w.mu.Unlock()
+	if recorder != nil {
+		recorder.SetSessionExpiresAt(deadline)
+	}
+	log.Infof("auth session deadline set to: %s (in %s)", deadline.Format(time.RFC3339), time.Until(deadline).Round(time.Second))
+	return nil
+}
+
+// Deadline returns the most recently observed deadline. Zero when no
+// deadline is currently tracked.
+func (w *Watcher) Deadline() time.Time {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	return w.current
+}
+
+// Dismiss records the user's "Dismiss" action against the current deadline
+// and suppresses the upcoming final-warning callback for that deadline.
+// Idempotent: repeated calls are no-ops. A subsequent Update with a fresh
+// deadline resets the dismissal so the final-warning cycle re-arms.
+//
+// No-op when the watcher holds no deadline or has been closed.
+func (w *Watcher) Dismiss() {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if w.closed || w.current.IsZero() {
+		return
+	}
+	if w.dismissedAt.Equal(w.current) {
+		return
+	}
+	w.dismissedAt = w.current
+	// Cancel the armed final-warning timer eagerly. fireFinal would also
+	// gate on dismissedAt, but stopping the timer avoids a wakeup with
+	// nothing to do and makes the intent visible.
+	if w.finalTimer != nil {
+		w.finalTimer.Stop()
+		w.finalTimer = nil
+	}
+	log.Infof("auth session final-warning dismissed for deadline %s", w.current.Format(time.RFC3339))
+}
+
+// Close stops any pending timer. Update calls after Close are ignored.
+// The recorder keeps its deadline: the watcher is engine-scoped and closes
+// on every engine restart (network change, sleep/wake, stream errors)
+// while the SSO deadline stays valid across those, so clearing here would
+// blank the UI's "expires in" row on every transient reconnect. The
+// client run loop clears the server-scoped recorder when it exits for
+// real (Down, profile switch, permanent login failure).
+func (w *Watcher) Close() {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if w.closed {
+		return
+	}
+	w.closed = true
+	w.stopTimerLocked()
+	w.current = time.Time{}
+	w.firedAt = time.Time{}
+	w.finalFiredAt = time.Time{}
+	w.dismissedAt = time.Time{}
+}
+
+// clearLocked drops the tracked deadline and notifies the recorder so
+// downstream consumers (SubscribeStatus stream, UI) drop their anchor.
+// The caller must hold w.mu; this helper releases it before invoking
+// the recorder.
+func (w *Watcher) clearLocked() {
+	if w.current.IsZero() {
+		w.mu.Unlock()
+		return
+	}
+	w.stopTimerLocked()
+	w.current = time.Time{}
+	w.firedAt = time.Time{}
+	w.finalFiredAt = time.Time{}
+	w.dismissedAt = time.Time{}
+	recorder := w.recorder
+	w.mu.Unlock()
+	if recorder != nil {
+		recorder.SetSessionExpiresAt(time.Time{})
+	}
+	log.Infof("auth session deadline cleared")
+}
+
+func (w *Watcher) stopTimerLocked() {
+	if w.timer != nil {
+		w.timer.Stop()
+		w.timer = nil
+	}
+	if w.finalTimer != nil {
+		w.finalTimer.Stop()
+		w.finalTimer = nil
+	}
+}
+
+func (w *Watcher) armTimerLocked(deadline time.Time) {
+	w.timer = armOneShotLocked(deadline.Add(-w.lead), func() { w.fire(deadline) })
+	// finalLead <= 0 disables the final-warning timer entirely. Used by
+	// tests that predate the final-warning fallback so a millisecond-scale
+	// deadline does not flush both timers at once.
+	if w.finalLead > 0 {
+		w.finalTimer = armOneShotLocked(deadline.Add(-w.finalLead), func() { w.fireFinal(deadline) })
+	}
+}
+
+func (w *Watcher) fire(armedFor time.Time) {
+	w.mu.Lock()
+	if w.closed || !w.current.Equal(armedFor) {
+		// Deadline moved while we were waiting (e.g. a successful extend).
+		// The reschedule path armed a fresh timer; this one is stale.
+		w.mu.Unlock()
+		return
+	}
+	if !w.firedAt.IsZero() && w.firedAt.Equal(armedFor) {
+		w.mu.Unlock()
+		return
+	}
+	w.firedAt = armedFor
+	recorder := w.recorder
+	w.mu.Unlock()
+	if recorder == nil {
+		return
+	}
+	log.Infof("auth session expiry soon warning fired")
+	publishWarning(recorder, armedFor, false)
+}
+
+// fireFinal mirrors fire for the T-FinalWarningLead timer with an extra
+// dismiss-gate: if the user dismissed the T-WarningLead notification for
+// this deadline, the final warning is suppressed entirely.
+func (w *Watcher) fireFinal(armedFor time.Time) {
+	w.mu.Lock()
+	if w.closed || !w.current.Equal(armedFor) {
+		w.mu.Unlock()
+		return
+	}
+	if !w.finalFiredAt.IsZero() && w.finalFiredAt.Equal(armedFor) {
+		w.mu.Unlock()
+		return
+	}
+	if w.dismissedAt.Equal(armedFor) {
+		w.mu.Unlock()
+		log.Infof("auth session final-warning skipped (dismissed by user)")
+		return
+	}
+	w.finalFiredAt = armedFor
+	recorder := w.recorder
+	w.mu.Unlock()
+	if recorder == nil {
+		return
+	}
+	log.Infof("auth session final-warning fired")
+	publishWarning(recorder, armedFor, true)
+}
+
+// armOneShotLocked schedules cb at fireAt. When fireAt is already in the
+// past it dispatches on the next scheduler tick so a state-change recorder
+// notification (invoked after w.mu is released) lands first. Caller must
+// hold w.mu.
+func armOneShotLocked(fireAt time.Time, cb func()) *time.Timer {
+	delay := time.Until(fireAt)
+	if delay <= 0 {
+		return time.AfterFunc(0, cb)
+	}
+	return time.AfterFunc(delay, cb)
+}
+
+// publishWarning composes the SystemEvent for a watcher-fired warning and
+// pushes it through the recorder. Severity is CRITICAL on both — bypassing
+// the user's Notifications toggle is deliberate: missing the warning
+// window forces the post-mortem SessionExpired flow (tunnel torn down,
+// lock icon, manual re-login), which is the UX we are trying to avoid.
+func publishWarning(recorder StatusRecorder, deadline time.Time, final bool) {
+	lead := WarningLead
+	message := "session expiry warning"
+	meta := map[string]string{
+		MetaSessionWarning:   "true",
+		MetaSessionExpiresAt: FormatExpiresAt(deadline),
+	}
+	if final {
+		lead = FinalWarningLead
+		message = "session expiry final warning"
+		meta[MetaSessionFinal] = "true"
+	}
+	meta[MetaSessionLeadMinutes] = FormatLeadMinutes(lead)
+
+	recorder.PublishEvent(
+		cProto.SystemEvent_CRITICAL,
+		cProto.SystemEvent_AUTHENTICATION,
+		message,
+		"",
+		meta,
+	)
+}

client/internal/auth/sessionwatch/watcher_test.go

@@ -0,0 +1,529 @@
+package sessionwatch
+
+import (
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	cProto "github.com/netbirdio/netbird/client/proto"
+)
+
+// fakeRecorder satisfies StatusRecorder and records every call so tests
+// can observe what the watcher emits. SetSessionExpiresAt and PublishEvent
+// land in the same ordered events slice (with the Kind distinguishing
+// them) so tests that care about ordering still work. lastDeadline holds
+// the most recent value passed to SetSessionExpiresAt so tests can assert
+// the recorder ended up cleared/set as expected.
+type fakeRecorder struct {
+	mu           sync.Mutex
+	events       []event
+	lastDeadline time.Time
+}
+
+type eventKind int
+
+const (
+	stateChange eventKind = iota
+	publish
+)
+
+type event struct {
+	kind eventKind
+	// Set only for publish events.
+	severity cProto.SystemEvent_Severity
+	category cProto.SystemEvent_Category
+	message  string
+	meta     map[string]string
+}
+
+// SetSessionExpiresAt mirrors peer.Status: a same-value write is a no-op,
+// a real change records the new value and fans out a state-change (the
+// production recorder calls notifyStateChange internally). The baseline
+// is the zero time, so an initial clear before any deadline is set emits
+// nothing — matching the real recorder.
+func (r *fakeRecorder) SetSessionExpiresAt(deadline time.Time) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.lastDeadline.Equal(deadline) {
+		return
+	}
+	r.lastDeadline = deadline
+	r.events = append(r.events, event{kind: stateChange})
+}
+
+func (r *fakeRecorder) deadline() time.Time {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.lastDeadline
+}
+
+func (r *fakeRecorder) PublishEvent(
+	severity cProto.SystemEvent_Severity,
+	category cProto.SystemEvent_Category,
+	message string,
+	_ string,
+	metadata map[string]string,
+) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.events = append(r.events, event{
+		kind:     publish,
+		severity: severity,
+		category: category,
+		message:  message,
+		meta:     metadata,
+	})
+}
+
+func (r *fakeRecorder) snapshot() []event {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	out := make([]event, len(r.events))
+	copy(out, r.events)
+	return out
+}
+
+func (e event) isFinalWarning() bool {
+	return e.kind == publish && e.meta[MetaSessionFinal] == "true"
+}
+
+func (e event) isWarning() bool {
+	return e.kind == publish && e.meta[MetaSessionWarning] == "true" && e.meta[MetaSessionFinal] != "true"
+}
+
+func countWhere(events []event, pred func(event) bool) int {
+	n := 0
+	for _, e := range events {
+		if pred(e) {
+			n++
+		}
+	}
+	return n
+}
+
+func waitForEvents(t *testing.T, r *fakeRecorder, want int) []event {
+	t.Helper()
+	deadline := time.Now().Add(500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if got := r.snapshot(); len(got) >= want {
+			return got
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	got := r.snapshot()
+	t.Fatalf("timed out waiting for %d events, got %d: %+v", want, len(got), got)
+	return nil
+}
+
+// newWatcher builds a watcher with the final timer disabled (finalLead=0),
+// matching the lead-only behaviour the pre-final-warning tests assume.
+func newWatcher(lead time.Duration, r *fakeRecorder) *Watcher {
+	return NewWithLeads(lead, 0, r)
+}
+
+func TestUpdateZeroBeforeAnythingIsNoop(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(50*time.Millisecond, r)
+	defer w.Close()
+
+	_ = w.Update(time.Time{})
+
+	if got := r.snapshot(); len(got) != 0 {
+		t.Fatalf("expected no events on initial zero, got %+v", got)
+	}
+}
+
+func TestUpdateNonZeroFiresStateChange(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(50*time.Millisecond, r)
+	defer w.Close()
+
+	d := time.Now().Add(time.Hour)
+	_ = w.Update(d)
+
+	events := waitForEvents(t, r, 1)
+	if events[0].kind != stateChange {
+		t.Fatalf("expected stateChange, got %+v", events[0])
+	}
+	if !w.Deadline().Equal(d) {
+		t.Fatalf("deadline mismatch: %v vs %v", w.Deadline(), d)
+	}
+}
+
+func TestSameDeadlineIsNoop(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(50*time.Millisecond, r)
+	defer w.Close()
+
+	d := time.Now().Add(time.Hour)
+	_ = w.Update(d)
+	_ = w.Update(d)
+	_ = w.Update(d)
+
+	events := waitForEvents(t, r, 1)
+	if len(events) != 1 {
+		t.Fatalf("expected exactly 1 event for repeated same deadline, got %d: %+v", len(events), events)
+	}
+}
+
+func TestWarningFiresOnceWithinLeadWindow(t *testing.T) {
+	r := &fakeRecorder{}
+	lead := 50 * time.Millisecond
+	w := newWatcher(lead, r)
+	defer w.Close()
+
+	// Deadline 80ms out — warning should fire after ~30ms.
+	d := time.Now().Add(80 * time.Millisecond)
+	_ = w.Update(d)
+
+	events := waitForEvents(t, r, 2)
+	if events[0].kind != stateChange {
+		t.Fatalf("event[0] should be stateChange, got %+v", events[0])
+	}
+	if !events[1].isWarning() {
+		t.Fatalf("event[1] should be a warning publish, got %+v", events[1])
+	}
+}
+
+func TestWarningFiresImmediatelyWhenAlreadyInsideWindow(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(time.Hour, r) // lead > delta => fire immediately
+	defer w.Close()
+
+	d := time.Now().Add(10 * time.Millisecond)
+	_ = w.Update(d)
+
+	events := waitForEvents(t, r, 2)
+	if !events[1].isWarning() {
+		t.Fatalf("expected immediate warning publish, got %+v", events[1])
+	}
+}
+
+func TestNewDeadlineCancelsPriorTimer(t *testing.T) {
+	r := &fakeRecorder{}
+	lead := 50 * time.Millisecond
+	w := newWatcher(lead, r)
+	defer w.Close()
+
+	first := time.Now().Add(80 * time.Millisecond) // would fire warning ~30ms in
+	_ = w.Update(first)
+
+	// Replace with a far-future deadline before the warning fires.
+	time.Sleep(5 * time.Millisecond)
+	second := time.Now().Add(time.Hour)
+	_ = w.Update(second)
+
+	// Wait past when first's warning would have fired.
+	time.Sleep(80 * time.Millisecond)
+
+	if n := countWhere(r.snapshot(), event.isWarning); n != 0 {
+		t.Fatalf("warning fired for cancelled deadline: %+v", r.snapshot())
+	}
+}
+
+func TestRefreshAfterFireArmsNewWarning(t *testing.T) {
+	r := &fakeRecorder{}
+	lead := 150 * time.Millisecond
+	w := newWatcher(lead, r)
+	defer w.Close()
+
+	// Warning fires ~20ms in; the deadline itself stays 150ms away so the
+	// replacement below lands well before it.
+	first := time.Now().Add(170 * time.Millisecond)
+	_ = w.Update(first)
+
+	// Wait for stateChange + warning of the first cycle.
+	waitForEvents(t, r, 2)
+
+	// Simulate a successful extend: brand new deadline.
+	second := time.Now().Add(60 * time.Millisecond)
+	_ = w.Update(second)
+
+	// 4 events total: stateChange, warning (first), stateChange, warning (second).
+	events := waitForEvents(t, r, 4)
+	if events[2].kind != stateChange {
+		t.Fatalf("event[2] should be stateChange for the new deadline, got %+v", events[2])
+	}
+	if !events[3].isWarning() {
+		t.Fatalf("event[3] should be a warning publish for the new deadline, got %+v", events[3])
+	}
+}
+
+func TestUpdateZeroAfterNonZeroClearsState(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(time.Hour, r)
+	defer w.Close()
+
+	d := time.Now().Add(2 * time.Hour)
+	_ = w.Update(d)
+	waitForEvents(t, r, 1)
+
+	_ = w.Update(time.Time{})
+
+	events := waitForEvents(t, r, 2)
+	if events[1].kind != stateChange {
+		t.Fatalf("expected stateChange on clear, got %+v", events[1])
+	}
+	if !w.Deadline().IsZero() {
+		t.Fatalf("Deadline should be zero after clear")
+	}
+}
+
+func TestUpdateRejectsBeforeEpoch(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(50*time.Millisecond, r)
+	defer w.Close()
+
+	good := time.Now().Add(time.Hour)
+	if err := w.Update(good); err != nil {
+		t.Fatalf("seed Update: %v", err)
+	}
+
+	err := w.Update(time.Unix(-100, 0))
+	if !errors.Is(err, ErrDeadlineBeforeEpoch) {
+		t.Fatalf("want ErrDeadlineBeforeEpoch, got %v", err)
+	}
+	if !w.Deadline().IsZero() {
+		t.Fatalf("rejected pre-epoch update must clear deadline; got %v", w.Deadline())
+	}
+}
+
+func TestUpdateRejectsTooFarFuture(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(50*time.Millisecond, r)
+	defer w.Close()
+
+	good := time.Now().Add(time.Hour)
+	if err := w.Update(good); err != nil {
+		t.Fatalf("seed Update: %v", err)
+	}
+
+	err := w.Update(time.Now().Add(50 * 365 * 24 * time.Hour))
+	if !errors.Is(err, ErrDeadlineTooFarFuture) {
+		t.Fatalf("want ErrDeadlineTooFarFuture, got %v", err)
+	}
+	if !w.Deadline().IsZero() {
+		t.Fatalf("rejected far-future update must clear deadline; got %v", w.Deadline())
+	}
+}
+
+func TestUpdateRecentPastRecordedAsExpired(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(50*time.Millisecond, r)
+	defer w.Close()
+
+	d := time.Now().Add(-1 * time.Hour)
+	if err := w.Update(d); err != nil {
+		t.Fatalf("recent-past Update should succeed, got %v", err)
+	}
+	if !w.Deadline().Equal(d) {
+		t.Fatalf("expected deadline to be recorded, got %v want %v", w.Deadline(), d)
+	}
+	if got := r.deadline(); !got.Equal(d) {
+		t.Fatalf("recorder deadline = %v, want %v", got, d)
+	}
+
+	time.Sleep(80 * time.Millisecond)
+	if n := countWhere(r.snapshot(), func(e event) bool { return e.kind == publish }); n != 0 {
+		t.Fatalf("no warning events may fire for an already-past deadline, got %+v", r.snapshot())
+	}
+}
+
+func TestUpdateAncientPastRejected(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(50*time.Millisecond, r)
+	defer w.Close()
+
+	good := time.Now().Add(time.Hour)
+	if err := w.Update(good); err != nil {
+		t.Fatalf("seed Update: %v", err)
+	}
+	// Drain the stateChange from the seed.
+	waitForEvents(t, r, 1)
+
+	err := w.Update(time.Now().Add(-31 * 24 * time.Hour))
+	if !errors.Is(err, ErrDeadlineInPast) {
+		t.Fatalf("want ErrDeadlineInPast, got %v", err)
+	}
+	if !w.Deadline().IsZero() {
+		t.Fatalf("rejected ancient-past update must clear the deadline, got %v", w.Deadline())
+	}
+	events := waitForEvents(t, r, 2)
+	if events[1].kind != stateChange {
+		t.Fatalf("expected stateChange on clear, got %+v", events[1])
+	}
+}
+
+func TestCloseSilencesUpdates(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(50*time.Millisecond, r)
+	w.Close()
+
+	if err := w.Update(time.Now().Add(time.Hour)); err != nil {
+		t.Fatalf("Update after Close: want nil, got %v", err)
+	}
+	if got := r.snapshot(); len(got) != 0 {
+		t.Fatalf("expected no events after Close, got %+v", got)
+	}
+}
+
+// TestCloseKeepsRecorderDeadline pins the reconnect-flap fix: the watcher
+// closes on every engine restart (network change, sleep/wake) while the
+// SSO deadline stays valid across those, so Close must leave the
+// server-scoped recorder's value in place. The client run loop clears the
+// recorder when it exits for real.
+func TestCloseKeepsRecorderDeadline(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(time.Hour, r)
+
+	d := time.Now().Add(2 * time.Hour)
+	if err := w.Update(d); err != nil {
+		t.Fatalf("seed Update: %v", err)
+	}
+	if got := r.deadline(); !got.Equal(d) {
+		t.Fatalf("recorder deadline after Update = %v, want %v", got, d)
+	}
+
+	w.Close()
+
+	if got := r.deadline(); !got.Equal(d) {
+		t.Fatalf("recorder deadline after Close = %v, want %v", got, d)
+	}
+}
+
+// TestCloseWithoutDeadlineLeavesRecorderUntouched guards the symmetric
+// case: closing a watcher that never held a deadline must not emit a
+// redundant clear (the recorder may legitimately hold a value written by
+// some other path; the watcher only owns what it set).
+func TestCloseWithoutDeadlineLeavesRecorderUntouched(t *testing.T) {
+	r := &fakeRecorder{}
+	w := newWatcher(time.Hour, r)
+
+	w.Close()
+
+	if got := r.snapshot(); len(got) != 0 {
+		t.Fatalf("expected no events from Close on an empty watcher, got %+v", got)
+	}
+}
+
+func TestFinalWarningFiresAfterRegularWarning(t *testing.T) {
+	r := &fakeRecorder{}
+	// Warning fires at deadline-80ms, final at deadline-30ms.
+	w := NewWithLeads(80*time.Millisecond, 30*time.Millisecond, r)
+	defer w.Close()
+
+	d := time.Now().Add(100 * time.Millisecond)
+	_ = w.Update(d)
+
+	// Expect stateChange + warning + final-warning.
+	events := waitForEvents(t, r, 3)
+
+	if countWhere(events, func(e event) bool { return e.kind == stateChange }) != 1 {
+		t.Fatalf("expected exactly 1 stateChange, got %+v", events)
+	}
+	if countWhere(events, event.isWarning) != 1 {
+		t.Fatalf("expected exactly 1 warning publish, got %+v", events)
+	}
+	if countWhere(events, event.isFinalWarning) != 1 {
+		t.Fatalf("expected exactly 1 final-warning publish, got %+v", events)
+	}
+
+	// Warning must precede final (same deadline, longer lead fires first).
+	var wIdx, fIdx int
+	for i, e := range events {
+		switch {
+		case e.isWarning():
+			wIdx = i
+		case e.isFinalWarning():
+			fIdx = i
+		}
+	}
+	if wIdx > fIdx {
+		t.Fatalf("warning must publish before final-warning, got order %+v", events)
+	}
+}
+
+func TestDismissSuppressesFinalWarning(t *testing.T) {
+	r := &fakeRecorder{}
+	w := NewWithLeads(80*time.Millisecond, 30*time.Millisecond, r)
+	defer w.Close()
+
+	d := time.Now().Add(100 * time.Millisecond)
+	_ = w.Update(d)
+
+	// Wait for the warning publish so we know we're inside the warning
+	// window, then dismiss before the final timer would fire.
+	deadline := time.Now().Add(500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if countWhere(r.snapshot(), event.isWarning) >= 1 {
+			break
+		}
+		time.Sleep(2 * time.Millisecond)
+	}
+	if countWhere(r.snapshot(), event.isWarning) < 1 {
+		t.Fatalf("warning did not publish in time, events=%+v", r.snapshot())
+	}
+
+	w.Dismiss()
+
+	// Now wait past when the final would have fired.
+	time.Sleep(120 * time.Millisecond)
+
+	if n := countWhere(r.snapshot(), event.isFinalWarning); n != 0 {
+		t.Fatalf("final-warning published after Dismiss(), events=%+v", r.snapshot())
+	}
+}
+
+func TestDismissResetByNewDeadline(t *testing.T) {
+	r := &fakeRecorder{}
+	w := NewWithLeads(80*time.Millisecond, 30*time.Millisecond, r)
+	defer w.Close()
+
+	first := time.Now().Add(100 * time.Millisecond)
+	_ = w.Update(first)
+
+	// Dismiss against the first deadline.
+	w.Dismiss()
+
+	// Replace with a fresh deadline before the first's timers complete.
+	time.Sleep(10 * time.Millisecond)
+	second := time.Now().Add(100 * time.Millisecond)
+	_ = w.Update(second)
+
+	// The second cycle must publish a final-warning (the dismiss state
+	// did not carry over).
+	deadline := time.Now().Add(500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if countWhere(r.snapshot(), event.isFinalWarning) >= 1 {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	if countWhere(r.snapshot(), event.isFinalWarning) < 1 {
+		t.Fatalf("final-warning did not publish on fresh deadline after Dismiss reset, events=%+v", r.snapshot())
+	}
+}
+
+func TestDismissBeforeUpdateIsNoop(t *testing.T) {
+	r := &fakeRecorder{}
+	w := NewWithLeads(80*time.Millisecond, 30*time.Millisecond, r)
+	defer w.Close()
+
+	// No deadline tracked yet; Dismiss must be a no-op (no panic, no state).
+	w.Dismiss()
+
+	d := time.Now().Add(100 * time.Millisecond)
+	_ = w.Update(d)
+
+	// Final warning should still publish — Dismiss only acts on the current
+	// deadline, and there was none at the time of the call.
+	deadline := time.Now().Add(500 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if countWhere(r.snapshot(), event.isFinalWarning) >= 1 {
+			return
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	t.Fatalf("final-warning did not publish after no-op pre-Update Dismiss, events=%+v", r.snapshot())
+}

client/internal/auth/util.go

@@ -20,14 +20,26 @@ func randomBytesInHex(count int) (string, error) {
 	return hex.EncodeToString(buf), nil
 }
 
-// isValidAccessToken is a simple validation of the access token
-func isValidAccessToken(token string, audience string) error {
+// validateTokenAudience checks that the token is a well-formed JWT whose
+// audience claim matches the expected audience.
+//
+// It does NOT verify the token's cryptographic signature and therefore must not
+// be treated as an authenticity check. The token is obtained by the client
+// directly from the IdP token endpoint over TLS, and its signature is verified
+// server-side by the management server against the IdP's JWKS
+// (see shared/auth/jwt/validator.go). This function is only a client-side
+// sanity check that the returned token targets the expected audience.
+func validateTokenAudience(token string, audience string) error {
 	if token == "" {
 		return fmt.Errorf("token received is empty")
 	}
 
-	encodedClaims := strings.Split(token, ".")[1]
-	claimsString, err := base64.RawURLEncoding.DecodeString(encodedClaims)
+	parts := strings.Split(token, ".")
+	if len(parts) != 3 {
+		return fmt.Errorf("token is not a well-formed JWT")
+	}
+
+	claimsString, err := base64.RawURLEncoding.DecodeString(parts[1])
 	if err != nil {
 		return err
 	}