[misc] Probe the agent-network endpoint with a GET instead of getent (#6867)

## Describe your changes

Use http get to trigger lazy connections as e2e will have single proxy
and status checks would fail without proper lazy wake-up

.github/workflows/frontend-ui.yml

@@ -86,7 +86,7 @@ jobs:
             ${{ runner.os }}-pnpm-
 
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install --frozen-lockfile --ignore-scripts
 
       - name: Generate Wails bindings
         run: pnpm run bindings

.github/workflows/golangci-lint.yml

@@ -45,7 +45,7 @@ jobs:
             display_name: Linux
     name: ${{ matrix.display_name }}
     runs-on: ${{ matrix.os }}
-    timeout-minutes: 15
+    timeout-minutes: 25
     steps:
       - name: Checkout code
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
@@ -79,4 +79,4 @@ jobs:
           skip-cache: true
           skip-save-cache: true
           cache-invalidation-interval: 0
-          args: --timeout=12m
+          args: --timeout=20m

client/android/client.go

@@ -247,6 +247,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
 			}

client/internal/auth/auth.go

@@ -351,6 +351,7 @@ func (a *Auth) setSystemInfoFlags(info *system.Info) {
 		a.config.BlockLANAccess,
 		a.config.BlockInbound,
 		a.config.DisableIPv6,
+		a.config.SyncMessageVersion,
 		a.config.EnableSSHRoot,
 		a.config.EnableSSHSFTP,
 		a.config.EnableSSHLocalPortForwarding,

client/internal/auth/sessionwatch/watcher.go

@@ -24,11 +24,7 @@ import (
 )
 
 const (
-	// Skew tolerates a small clock difference between the management
-	// server and this peer before treating a deadline as "in the past".
-	// Slightly above typical NTP drift; tight enough that the UI doesn't
-	// paint a stale expiry as if it were valid.
-	Skew = 30 * time.Second
+	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
@@ -57,7 +53,7 @@ var (
 	ErrDeadlineTooFarFuture = errors.New("session deadline too far in the future")
 
 	// ErrDeadlineInPast is returned by Update when the supplied deadline
-	// is more than Skew in the past.
+	// is more than maxPastHorizon in the past.
 	ErrDeadlineInPast = errors.New("session deadline in the past")
 )
 
@@ -66,15 +62,14 @@ var (
 // for deadline change/clear, PublishEvent for the two warnings); tests pass
 // a fake recorder so the same surface is observable without an engine.
 //
-// The watcher is the single owner of the deadline propagated to the
-// recorder: every set, clear, sanity-check rejection and Close 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 — without the Close-time clear a teardown (Down, or the Down+Up of
-// a profile switch) would leave the next session showing the previous one's
-// stale "expires in" value.
+// 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
@@ -135,10 +130,13 @@ func NewWithLeads(lead, final time.Duration, recorder StatusRecorder) *Watcher {
 // was disabled).
 //
 // Same-value updates are no-ops. A different non-zero value cancels any
-// pending timer, resets the "already fired" guard, and arms a new one.
+// 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 in the past beyond Skew).
+// 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
@@ -163,7 +161,7 @@ func (w *Watcher) Update(deadline time.Time) error {
 	case deadline.After(now.Add(maxDeadlineHorizon)):
 		w.clearLocked()
 		return fmt.Errorf("%w: %v", ErrDeadlineTooFarFuture, deadline)
-	case deadline.Before(now.Add(-Skew)):
+	case deadline.Before(now.Add(-maxPastHorizon)):
 		w.clearLocked()
 		return fmt.Errorf("%w: %v (now=%v)", ErrDeadlineInPast, deadline, now)
 	}
@@ -183,7 +181,9 @@ func (w *Watcher) Update(deadline time.Time) error {
 	w.finalFiredAt = time.Time{}
 	w.dismissedAt = time.Time{}
 
-	w.armTimerLocked(deadline)
+	if deadline.After(now) {
+		w.armTimerLocked(deadline)
+	}
 	recorder := w.recorder
 	w.mu.Unlock()
 	if recorder != nil {
@@ -227,30 +227,25 @@ func (w *Watcher) Dismiss() {
 	log.Infof("auth session final-warning dismissed for deadline %s", w.current.Format(time.RFC3339))
 }
 
-// Close stops any pending timer and drops the deadline on the status
-// recorder. Update calls after Close are ignored. Clearing the recorder
-// here is what keeps a teardown (Down, or the Down+Up of a profile switch)
-// from leaving the next session showing this one's stale "expires in"
-// value — the recorder is server-scoped and outlives this engine-scoped
-// watcher, so nothing else drops the anchor on teardown.
+// 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 {
-		w.mu.Unlock()
 		return
 	}
 	w.closed = true
 	w.stopTimerLocked()
-	hadDeadline := !w.current.IsZero()
 	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 && hadDeadline {
-		recorder.SetSessionExpiresAt(time.Time{})
-	}
 }
 
 // clearLocked drops the tracked deadline and notifies the recorder so

client/internal/auth/sessionwatch/watcher_test.go

@@ -224,11 +224,13 @@ func TestNewDeadlineCancelsPriorTimer(t *testing.T) {
 
 func TestRefreshAfterFireArmsNewWarning(t *testing.T) {
 	r := &fakeRecorder{}
-	lead := 30 * time.Millisecond
+	lead := 150 * time.Millisecond
 	w := newWatcher(lead, r)
 	defer w.Close()
 
-	first := time.Now().Add(50 * time.Millisecond)
+	// 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.
@@ -306,7 +308,29 @@ func TestUpdateRejectsTooFarFuture(t *testing.T) {
 	}
 }
 
-func TestUpdateInPastClearsDeadline(t *testing.T) {
+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()
@@ -318,12 +342,12 @@ func TestUpdateInPastClearsDeadline(t *testing.T) {
 	// Drain the stateChange from the seed.
 	waitForEvents(t, r, 1)
 
-	err := w.Update(time.Now().Add(-1 * time.Hour))
+	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("in-past update must clear the deadline, got %v", w.Deadline())
+		t.Fatalf("rejected ancient-past update must clear the deadline, got %v", w.Deadline())
 	}
 	events := waitForEvents(t, r, 2)
 	if events[1].kind != stateChange {
@@ -331,39 +355,25 @@ func TestUpdateInPastClearsDeadline(t *testing.T) {
 	}
 }
 
-func TestUpdateWithinSkewAccepted(t *testing.T) {
-	r := &fakeRecorder{}
-	w := newWatcher(50*time.Millisecond, r)
-	defer w.Close()
-
-	// 5 seconds in the past is within the 30s Skew tolerance — accept it.
-	d := time.Now().Add(-5 * time.Second)
-	if err := w.Update(d); err != nil {
-		t.Fatalf("within-skew Update should succeed, got %v", err)
-	}
-	if !w.Deadline().Equal(d) {
-		t.Fatalf("expected deadline to be applied, got %v want %v", w.Deadline(), d)
-	}
-}
-
 func TestCloseSilencesUpdates(t *testing.T) {
 	r := &fakeRecorder{}
 	w := newWatcher(50*time.Millisecond, r)
 	w.Close()
 
-	_ = w.Update(time.Now().Add(time.Hour))
-
-	time.Sleep(20 * time.Millisecond)
+	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)
 	}
 }
 
-// TestCloseClearsRecorderDeadline pins the profile-switch fix: a watcher
-// holding a live deadline must zero the recorder on Close so the next
-// engine's watcher (and the UI reading the shared server-scoped recorder)
-// doesn't start out showing the previous session's stale "expires in".
-func TestCloseClearsRecorderDeadline(t *testing.T) {
+// 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)
 
@@ -377,8 +387,8 @@ func TestCloseClearsRecorderDeadline(t *testing.T) {
 
 	w.Close()
 
-	if got := r.deadline(); !got.IsZero() {
-		t.Fatalf("recorder deadline after Close = %v, want zero", got)
+	if got := r.deadline(); !got.Equal(d) {
+		t.Fatalf("recorder deadline after Close = %v, want %v", got, d)
 	}
 }
 

client/internal/conn_mgr.go

@@ -34,6 +34,8 @@ const (
 // - Handling connection establishment based on peer signaling
 //
 // The implementation is not thread-safe; it is protected by engine.syncMsgMux.
+// The only exception is ActivatePeer, which is safe for concurrent use so the
+// DNS warm-up path can call it without contending on the engine mutex.
 type ConnMgr struct {
 	peerStore        *peerstore.Store
 	statusRecorder   *peer.Status
@@ -42,6 +44,10 @@ type ConnMgr struct {
 	rosenpassEnabled bool
 
 	lazyConnMgr *manager.Manager
+	// lazyConnMgrMu guards the lazyConnMgr pointer for readers outside the
+	// engine loop (ActivatePeer). Writers hold it in addition to
+	// engine.syncMsgMux; all other reads stay under engine.syncMsgMux only.
+	lazyConnMgrMu sync.RWMutex
 
 	wg            sync.WaitGroup
 	lazyCtx       context.Context
@@ -238,12 +244,20 @@ func (e *ConnMgr) RemovePeerConn(peerKey string) {
 	conn.Log.Infof("removed peer from lazy conn manager")
 }
 
+// ActivatePeer wakes an idle lazy connection. Unlike the rest of ConnMgr it is
+// safe for concurrent use: the lazy manager pointer is read under lazyConnMgrMu
+// and the manager itself is internally synchronized, so callers outside the
+// engine loop (DNS warm-up) do not need engine.syncMsgMux.
 func (e *ConnMgr) ActivatePeer(ctx context.Context, conn *peer.Conn) {
-	if !e.isStartedWithLazyMgr() {
+	e.lazyConnMgrMu.RLock()
+	lazyConnMgr := e.lazyConnMgr
+	started := lazyConnMgr != nil && e.lazyCtxCancel != nil
+	e.lazyConnMgrMu.RUnlock()
+	if !started {
 		return
 	}
 
-	if found := e.lazyConnMgr.ActivatePeer(conn.GetKey()); found {
+	if found := lazyConnMgr.ActivatePeer(conn.GetKey()); found {
 		if err := conn.Open(ctx); err != nil {
 			conn.Log.Errorf("failed to open connection: %v", err)
 		}
@@ -268,16 +282,21 @@ func (e *ConnMgr) Close() {
 
 	e.lazyCtxCancel()
 	e.wg.Wait()
+
+	e.lazyConnMgrMu.Lock()
 	e.lazyConnMgr = nil
+	e.lazyConnMgrMu.Unlock()
 }
 
 func (e *ConnMgr) initLazyManager(engineCtx context.Context) {
 	cfg := manager.Config{
 		InactivityThreshold: inactivityThresholdEnv(),
 	}
-	e.lazyConnMgr = manager.NewManager(cfg, engineCtx, e.peerStore, e.iface)
 
+	e.lazyConnMgrMu.Lock()
+	e.lazyConnMgr = manager.NewManager(cfg, engineCtx, e.peerStore, e.iface)
 	e.lazyCtx, e.lazyCtxCancel = context.WithCancel(engineCtx)
+	e.lazyConnMgrMu.Unlock()
 
 	e.wg.Add(1)
 	go func() {
@@ -316,7 +335,10 @@ func (e *ConnMgr) closeManager(ctx context.Context) {
 
 	e.lazyCtxCancel()
 	e.wg.Wait()
+
+	e.lazyConnMgrMu.Lock()
 	e.lazyConnMgr = nil
+	e.lazyConnMgrMu.Unlock()
 
 	for _, peerID := range e.peerStore.PeersPubKey() {
 		e.peerStore.PeerConnOpen(ctx, peerID)

client/internal/conn_mgr_test.go

@@ -1,10 +1,21 @@
 package internal
 
 import (
+	"context"
+	"net"
+	"net/netip"
 	"os"
+	"sync"
 	"testing"
+	"time"
 
+	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
+
+	"github.com/netbirdio/netbird/client/iface/wgaddr"
 	"github.com/netbirdio/netbird/client/internal/lazyconn"
+	"github.com/netbirdio/netbird/client/internal/peer"
+	"github.com/netbirdio/netbird/client/internal/peerstore"
+	"github.com/netbirdio/netbird/monotime"
 )
 
 func TestResolveLazyForce(t *testing.T) {
@@ -38,3 +49,58 @@ func TestResolveLazyForce(t *testing.T) {
 		})
 	}
 }
+
+type mockLazyWGIface struct{}
+
+func (mockLazyWGIface) RemovePeer(string) error { return nil }
+func (mockLazyWGIface) UpdatePeer(string, []netip.Prefix, time.Duration, *net.UDPAddr, *wgtypes.Key) error {
+	return nil
+}
+func (mockLazyWGIface) IsUserspaceBind() bool                    { return false }
+func (mockLazyWGIface) Address() wgaddr.Address                  { return wgaddr.Address{} }
+func (mockLazyWGIface) LastActivities() map[string]monotime.Time { return nil }
+func (mockLazyWGIface) MTU() uint16                              { return 1280 }
+
+// TestConnMgr_ActivatePeerConcurrentWithLifecycle exercises ActivatePeer from
+// non-engine goroutines (the DNS warm-up path) racing the manager lifecycle,
+// which stays on the engine loop. Run with -race: it fails if ActivatePeer
+// still requires engine.syncMsgMux for safety.
+func TestConnMgr_ActivatePeerConcurrentWithLifecycle(t *testing.T) {
+	t.Setenv(lazyconn.EnvLazyConn, "on")
+
+	status := peer.NewRecorder("https://mgm")
+	store := peerstore.NewConnStore()
+	connMgr := NewConnMgr(&EngineConfig{}, status, store, mockLazyWGIface{})
+
+	conn := newTestPeerConn(t, "peerA")
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	connMgr.Start(ctx)
+
+	done := make(chan struct{})
+	var wg sync.WaitGroup
+	for range 4 {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for {
+				select {
+				case <-done:
+					return
+				default:
+					connMgr.ActivatePeer(ctx, conn)
+				}
+			}
+		}()
+	}
+
+	// Let the activators spin against the started manager, then tear it down
+	// underneath them and let them spin against the stopped manager.
+	time.Sleep(100 * time.Millisecond)
+	connMgr.Close()
+	time.Sleep(50 * time.Millisecond)
+
+	close(done)
+	wg.Wait()
+}

client/internal/connect.go

@@ -257,7 +257,10 @@ func (c *ConnectClient) run(mobileDependency MobileDependency, runningChan chan
 		log.Errorf("failed to clean up temporary installer file: %v", err)
 	}
 
-	defer c.statusRecorder.ClientStop()
+	defer func() {
+		c.statusRecorder.SetSessionExpiresAt(time.Time{})
+		c.statusRecorder.ClientStop()
+	}()
 	operation := func() error {
 		// if context cancelled we not start new backoff cycle
 		if c.ctx.Err() != nil {
@@ -618,6 +621,7 @@ func createEngineConfig(key wgtypes.Key, config *profilemanager.Config, peerConf
 		BlockLANAccess:      config.BlockLANAccess,
 		BlockInbound:        config.BlockInbound,
 		DisableIPv6:         config.DisableIPv6,
+		SyncMessageVersion:  config.SyncMessageVersion,
 
 		LazyConnection: lazyconn.ParseState(config.LazyConnection),
 
@@ -693,6 +697,7 @@ func loginToManagement(ctx context.Context, client mgm.Client, pubSSHKey []byte,
 		config.BlockLANAccess,
 		config.BlockInbound,
 		config.DisableIPv6,
+		config.SyncMessageVersion,
 		config.EnableSSHRoot,
 		config.EnableSSHSFTP,
 		config.EnableSSHLocalPortForwarding,

client/internal/debug/debug.go

@@ -676,6 +676,7 @@ func (g *BundleGenerator) addCommonConfigFields(configContent *strings.Builder)
 	configContent.WriteString(fmt.Sprintf("BlockLANAccess: %v\n", g.internalConfig.BlockLANAccess))
 	configContent.WriteString(fmt.Sprintf("BlockInbound: %v\n", g.internalConfig.BlockInbound))
 	configContent.WriteString(fmt.Sprintf("DisableIPv6: %v\n", g.internalConfig.DisableIPv6))
+	configContent.WriteString(fmt.Sprintf("SyncMessageVersion: %v\n", g.internalConfig.SyncMessageVersion))
 
 	if g.internalConfig.DisableNotifications != nil {
 		configContent.WriteString(fmt.Sprintf("DisableNotifications: %v\n", *g.internalConfig.DisableNotifications))

client/internal/debug/debug_test.go

@@ -887,6 +887,8 @@ func TestAddConfig_AllFieldsCovered(t *testing.T) {
 		ClientCertKeyPath:             "/tmp/key",
 		LazyConnection:                "on",
 		MTU:                           1280,
+		DisableIPv6:                   true,
+		SyncMessageVersion:            func(v int) *int { return &v }(1),
 	}
 
 	for _, anonymize := range []bool{false, true} {

client/internal/dns/local/local.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"net"
 	"net/netip"
+	"os"
 	"slices"
 	"strings"
 	"sync"
@@ -36,7 +37,43 @@ type resolver interface {
 // record is left alone (it points at something outside our mesh, e.g.
 // a non-peer upstream).
 type PeerConnectivity interface {
-	IsConnectedByIP(ip string) (known, connected bool)
+	IsConnectedByIP(ip netip.Addr) (known, connected bool)
+}
+
+// PeerActivator wakes lazy-connection peers on demand. The local resolver calls
+// it with the tunnel IPs an answer points at, so a peer that is idle (lazily
+// disconnected) starts connecting at DNS-resolution time rather than racing the
+// client's first request packet. nil disables warm-up.
+type PeerActivator interface {
+	// ActivatePeersByIP triggers wake-up for the peer(s) owning addrs and blocks
+	// until one is connected or ctx (a short per-query budget) expires. It is a
+	// fast no-op for unknown or already-connected addresses.
+	ActivatePeersByIP(ctx context.Context, addrs []netip.Addr)
+}
+
+const (
+	defaultLazyWarmupTimeout = 2 * time.Second
+	envLazyWarmupTimeout     = "NB_DNS_LAZY_WARMUP_TIMEOUT"
+)
+
+// lazyWarmupTimeoutFromEnv returns the per-query budget for waking a
+// lazy-connection peer a DNS answer points at. Tunable via
+// NB_DNS_LAZY_WARMUP_TIMEOUT (a Go duration). Parsed once at construction time.
+func lazyWarmupTimeoutFromEnv() time.Duration {
+	v := os.Getenv(envLazyWarmupTimeout)
+	if v == "" {
+		return defaultLazyWarmupTimeout
+	}
+	d, err := time.ParseDuration(v)
+	if err != nil {
+		log.Warnf("invalid %s value %q, using default %s: %v", envLazyWarmupTimeout, v, defaultLazyWarmupTimeout, err)
+		return defaultLazyWarmupTimeout
+	}
+	if d <= 0 {
+		log.Warnf("non-positive %s value %q, using default %s", envLazyWarmupTimeout, v, defaultLazyWarmupTimeout)
+		return defaultLazyWarmupTimeout
+	}
+	return d
 }
 
 type Resolver struct {
@@ -51,6 +88,12 @@ type Resolver struct {
 	// filter and preserves the legacy "return whatever is registered"
 	// behaviour for callers that never wire a status source.
 	peerConn PeerConnectivity
+	// peerActivator, when non-nil, is called at resolution time to warm the
+	// lazy connection to the peer(s) an answer points at. nil disables warm-up.
+	peerActivator PeerActivator
+	// warmupTimeout is the per-query budget for the lazy-connection warm-up
+	// wait, resolved from the environment once at construction time.
+	warmupTimeout time.Duration
 
 	ctx    context.Context
 	cancel context.CancelFunc
@@ -59,11 +102,12 @@ type Resolver struct {
 func NewResolver() *Resolver {
 	ctx, cancel := context.WithCancel(context.Background())
 	return &Resolver{
-		records: make(map[dns.Question][]dns.RR),
-		domains: make(map[domain.Domain]struct{}),
-		zones:   make(map[domain.Domain]bool),
-		ctx:     ctx,
-		cancel:  cancel,
+		records:       make(map[dns.Question][]dns.RR),
+		domains:       make(map[domain.Domain]struct{}),
+		zones:         make(map[domain.Domain]bool),
+		warmupTimeout: lazyWarmupTimeoutFromEnv(),
+		ctx:           ctx,
+		cancel:        cancel,
 	}
 }
 
@@ -76,6 +120,14 @@ func (d *Resolver) SetPeerConnectivity(p PeerConnectivity) {
 	d.peerConn = p
 }
 
+// SetPeerActivator wires the DNS-time lazy-connection warm-up. Pass nil to
+// disable. Safe to call multiple times; the latest value wins.
+func (d *Resolver) SetPeerActivator(a PeerActivator) {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+	d.peerActivator = a
+}
+
 func (d *Resolver) MatchSubdomains() bool {
 	return true
 }
@@ -122,6 +174,9 @@ func (d *Resolver) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
 	replyMessage.RecursionAvailable = true
 
 	result := d.lookupRecords(logger, question)
+	// Warm before filtering: activation flips a lazily-idle target to connected,
+	// which then lets it survive the disconnected-peer filter below.
+	d.warmLazyPeers(question, result.records)
 	result.records = d.filterDisconnectedPeerAnswers(logger, question, result.records)
 	replyMessage.Authoritative = !result.hasExternalData
 	replyMessage.Answer = result.records
@@ -495,8 +550,8 @@ func (d *Resolver) filterDisconnectedPeerAnswers(logger *log.Entry, question dns
 	kept := make([]dns.RR, 0, len(records))
 	var dropped int
 	for _, rr := range records {
-		ip := extractRecordIP(rr)
-		if ip == "" {
+		ip, ok := extractRecordAddr(rr)
+		if !ok {
 			kept = append(kept, rr)
 			continue
 		}
@@ -518,22 +573,57 @@ func (d *Resolver) filterDisconnectedPeerAnswers(logger *log.Entry, question dns
 	return kept
 }
 
-// extractRecordIP returns the dotted-decimal / colon-hex IP carried by
-// an A or AAAA record, or "" for any other record type.
-func extractRecordIP(rr dns.RR) string {
+// warmLazyPeers triggers lazy-connection wake-up for the peers a resolved
+// answer points at and waits briefly for one to connect, so the caller's first
+// request doesn't race the connection establishment. Warm-up is scoped to
+// match-only (non-authoritative) zones — the synthesized private-service zones
+// and user-created zones whose records point at specific peers. The account's
+// peer zone is authoritative, so plain peer-name lookups never trigger warm-up;
+// otherwise resolving any peer's name would wake its idle connection, defeating
+// laziness mesh-wide. No-op when no activator is wired (lazy connections
+// disabled) or the answer carries no peer IPs.
+func (d *Resolver) warmLazyPeers(question dns.Question, records []dns.RR) {
+	if len(records) < 2 {
+		return
+	}
+	d.mu.RLock()
+	activator := d.peerActivator
+	var nonAuth, found bool
+	if activator != nil {
+		nonAuth, found = d.findZone(question.Name)
+	}
+	d.mu.RUnlock()
+	if activator == nil || !found || !nonAuth {
+		return
+	}
+
+	var addrs []netip.Addr
+	for _, rr := range records {
+		if addr, ok := extractRecordAddr(rr); ok {
+			addrs = append(addrs, addr)
+		}
+	}
+	if len(addrs) == 0 {
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(d.ctx, d.warmupTimeout)
+	defer cancel()
+	activator.ActivatePeersByIP(ctx, addrs)
+}
+
+// extractRecordAddr returns the IP address carried by an A or AAAA record.
+// ok is false for any other record type or a record with no address.
+func extractRecordAddr(rr dns.RR) (netip.Addr, bool) {
 	switch r := rr.(type) {
 	case *dns.A:
-		if r.A == nil {
-			return ""
-		}
-		return r.A.String()
+		addr, ok := netip.AddrFromSlice(r.A)
+		return addr.Unmap(), ok
 	case *dns.AAAA:
-		if r.AAAA == nil {
-			return ""
-		}
-		return r.AAAA.String()
+		addr, ok := netip.AddrFromSlice(r.AAAA)
+		return addr.Unmap(), ok
 	}
-	return ""
+	return netip.Addr{}, false
 }
 
 // Update replaces all zones and their records

client/internal/dns/local/local_test.go

@@ -37,8 +37,8 @@ type mockPeerConnectivity struct {
 	byIP map[string]struct{ known, connected bool }
 }
 
-func (m mockPeerConnectivity) IsConnectedByIP(ip string) (known, connected bool) {
-	v, ok := m.byIP[ip]
+func (m mockPeerConnectivity) IsConnectedByIP(ip netip.Addr) (known, connected bool) {
+	v, ok := m.byIP[ip.String()]
 	if !ok {
 		return false, false
 	}

client/internal/dns/local/warmup_test.go

@@ -0,0 +1,204 @@
+package local
+
+import (
+	"context"
+	"net"
+	"net/netip"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/miekg/dns"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/client/internal/dns/test"
+	nbdns "github.com/netbirdio/netbird/dns"
+)
+
+// recordingActivator records the addresses it was asked to warm and returns
+// immediately, so ServeDNS is not blocked by the test.
+type recordingActivator struct {
+	mu     sync.Mutex
+	called bool
+	addrs  []netip.Addr
+}
+
+func (r *recordingActivator) ActivatePeersByIP(_ context.Context, addrs []netip.Addr) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.called = true
+	r.addrs = append(r.addrs, addrs...)
+}
+
+func serveA(t *testing.T, resolver *Resolver, name string) *dns.Msg {
+	t.Helper()
+	var resp *dns.Msg
+	w := &test.MockResponseWriter{WriteMsgFunc: func(m *dns.Msg) error { resp = m; return nil }}
+	resolver.ServeDNS(w, new(dns.Msg).SetQuestion(name, dns.TypeA))
+	return resp
+}
+
+// serviceZone registers rec in a match-only (non-authoritative) zone, the shape
+// the synthesized private-service zones arrive in.
+func serviceZone(t *testing.T, resolver *Resolver, zone string, records ...nbdns.SimpleRecord) {
+	t.Helper()
+	resolver.Update([]nbdns.CustomZone{{
+		Domain:           zone,
+		Records:          records,
+		NonAuthoritative: true,
+	}})
+}
+
+func TestLocalResolver_WarmsLazyPeerOnResolve(t *testing.T) {
+	// Warm-up fires only for multi-record answers (the HA / round-robin shape of
+	// the synthesized private-service zones), so register two peer targets.
+	const name = "svc.proxy.netbird.cloud."
+	recs := []nbdns.SimpleRecord{
+		{Name: name, Type: 1, Class: nbdns.DefaultClass, TTL: 300, RData: "100.64.0.7"},
+		{Name: name, Type: 1, Class: nbdns.DefaultClass, TTL: 300, RData: "100.64.0.8"},
+	}
+	resolver := NewResolver()
+	serviceZone(t, resolver, "proxy.netbird.cloud", recs...)
+
+	act := &recordingActivator{}
+	resolver.SetPeerActivator(act)
+
+	resp := serveA(t, resolver, name)
+	require.NotNil(t, resp, "resolver must answer")
+	require.NotEmpty(t, resp.Answer, "answer must carry the A records")
+
+	act.mu.Lock()
+	defer act.mu.Unlock()
+	assert.True(t, act.called, "activator must be invoked for a multi-record service-zone answer")
+	assert.Contains(t, act.addrs, netip.MustParseAddr("100.64.0.7"), "activator must receive the first peer IP")
+	assert.Contains(t, act.addrs, netip.MustParseAddr("100.64.0.8"), "activator must receive the second peer IP")
+}
+
+func TestLocalResolver_NoWarmupForSingleRecord(t *testing.T) {
+	// A single-record answer does not trigger warm-up; the resolver only warms
+	// multi-record answers.
+	rec := nbdns.SimpleRecord{Name: "svc.proxy.netbird.cloud.", Type: 1, Class: nbdns.DefaultClass, TTL: 300, RData: "100.64.0.7"}
+	resolver := NewResolver()
+	serviceZone(t, resolver, "proxy.netbird.cloud", rec)
+
+	act := &recordingActivator{}
+	resolver.SetPeerActivator(act)
+
+	resp := serveA(t, resolver, rec.Name)
+	require.NotNil(t, resp, "resolver must answer")
+	require.NotEmpty(t, resp.Answer, "answer must carry the A record")
+
+	act.mu.Lock()
+	defer act.mu.Unlock()
+	assert.False(t, act.called, "activator must not be invoked for a single-record answer")
+}
+
+func TestLocalResolver_NoActivatorNoWarmup(t *testing.T) {
+	// With no activator wired the resolver behaves exactly as before.
+	rec := nbdns.SimpleRecord{Name: "svc.proxy.netbird.cloud.", Type: 1, Class: nbdns.DefaultClass, TTL: 300, RData: "100.64.0.7"}
+	resolver := NewResolver()
+	serviceZone(t, resolver, "proxy.netbird.cloud", rec)
+
+	resp := serveA(t, resolver, rec.Name)
+	require.NotNil(t, resp, "resolver must still answer without an activator")
+	require.NotEmpty(t, resp.Answer, "answer must carry the A record")
+}
+
+func TestLocalResolver_NoWarmupForMissingRecord(t *testing.T) {
+	// A query that resolves to nothing must not invoke the activator (no IPs).
+	resolver := NewResolver()
+	serviceZone(t, resolver, "proxy.netbird.cloud",
+		nbdns.SimpleRecord{Name: "svc.proxy.netbird.cloud.", Type: 1, Class: nbdns.DefaultClass, TTL: 300, RData: "100.64.0.7"})
+
+	act := &recordingActivator{}
+	resolver.SetPeerActivator(act)
+
+	serveA(t, resolver, "absent.proxy.netbird.cloud.")
+
+	act.mu.Lock()
+	defer act.mu.Unlock()
+	assert.False(t, act.called, "activator must not be invoked when there is no answer")
+}
+
+func TestLocalResolver_NoWarmupInAuthoritativeZone(t *testing.T) {
+	// The account's peer zone is authoritative; resolving a peer's name there
+	// must not wake its lazy connection — warm-up is scoped to match-only
+	// (non-authoritative) zones such as the synthesized private-service zones.
+	// Use a multi-record answer so the authoritative-zone scoping is the only
+	// reason warm-up is skipped, not the single-record guard.
+	const name = "peer.netbird.cloud."
+	recs := []nbdns.SimpleRecord{
+		{Name: name, Type: 1, Class: nbdns.DefaultClass, TTL: 300, RData: "100.64.0.9"},
+		{Name: name, Type: 1, Class: nbdns.DefaultClass, TTL: 300, RData: "100.64.0.10"},
+	}
+	resolver := NewResolver()
+	resolver.Update([]nbdns.CustomZone{{
+		Domain:  "netbird.cloud",
+		Records: recs,
+	}})
+
+	act := &recordingActivator{}
+	resolver.SetPeerActivator(act)
+
+	resp := serveA(t, resolver, name)
+	require.NotNil(t, resp, "resolver must answer")
+	require.NotEmpty(t, resp.Answer, "answer must carry the A records")
+
+	act.mu.Lock()
+	defer act.mu.Unlock()
+	assert.False(t, act.called, "activator must not be invoked for authoritative-zone answers")
+}
+
+func TestLazyWarmupTimeoutFromEnv(t *testing.T) {
+	tests := []struct {
+		name   string
+		value  string
+		envSet bool
+		want   time.Duration
+	}{
+		{name: "unset uses default", want: defaultLazyWarmupTimeout},
+		{name: "valid overrides", value: "5s", envSet: true, want: 5 * time.Second},
+		{name: "invalid falls back", value: "not-a-duration", envSet: true, want: defaultLazyWarmupTimeout},
+		{name: "negative falls back", value: "-1s", envSet: true, want: defaultLazyWarmupTimeout},
+		{name: "zero falls back", value: "0s", envSet: true, want: defaultLazyWarmupTimeout},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.envSet {
+				t.Setenv(envLazyWarmupTimeout, tt.value)
+			}
+			assert.Equal(t, tt.want, lazyWarmupTimeoutFromEnv())
+			assert.Equal(t, tt.want, NewResolver().warmupTimeout, "constructor must resolve the timeout once")
+		})
+	}
+}
+
+func TestExtractRecordAddr(t *testing.T) {
+	t.Run("A record yields unmapped v4", func(t *testing.T) {
+		// net.ParseIP returns the 16-byte v4-in-v6 form, the same shape
+		// miekg/dns stores after parsing an A record; the extracted address
+		// must compare equal to a plain v4 netip.Addr.
+		addr, ok := extractRecordAddr(&dns.A{A: net.ParseIP("100.64.0.7")})
+		require.True(t, ok)
+		assert.True(t, addr.Is4())
+		assert.Equal(t, netip.MustParseAddr("100.64.0.7"), addr)
+	})
+
+	t.Run("AAAA record yields v6", func(t *testing.T) {
+		addr, ok := extractRecordAddr(&dns.AAAA{AAAA: net.ParseIP("fd00::1")})
+		require.True(t, ok)
+		assert.Equal(t, netip.MustParseAddr("fd00::1"), addr)
+	})
+
+	t.Run("A record without address", func(t *testing.T) {
+		_, ok := extractRecordAddr(&dns.A{})
+		assert.False(t, ok)
+	})
+
+	t.Run("non-address record", func(t *testing.T) {
+		_, ok := extractRecordAddr(&dns.CNAME{Target: "target.netbird.cloud."})
+		assert.False(t, ok)
+	})
+}

client/internal/dns/mock_server.go

@@ -8,6 +8,7 @@ import (
 	"github.com/miekg/dns"
 
 	dnsconfig "github.com/netbirdio/netbird/client/internal/dns/config"
+	"github.com/netbirdio/netbird/client/internal/dns/local"
 	nbdns "github.com/netbirdio/netbird/dns"
 	"github.com/netbirdio/netbird/route"
 	"github.com/netbirdio/netbird/shared/management/domain"
@@ -92,6 +93,11 @@ func (m *MockServer) SetFirewall(Firewall) {
 	// Mock implementation - no-op
 }
 
+// SetPeerActivator mock implementation of SetPeerActivator from Server interface
+func (m *MockServer) SetPeerActivator(local.PeerActivator) {
+	// Mock implementation - no-op
+}
+
 // BeginBatch mock implementation of BeginBatch from Server interface
 func (m *MockServer) BeginBatch() {
 	// Mock implementation - no-op

client/internal/dns/server.go

@@ -82,6 +82,7 @@ type Server interface {
 	PopulateManagementDomain(mgmtURL *url.URL) error
 	SetRouteSources(selected, active func() route.HAMap)
 	SetFirewall(Firewall)
+	SetPeerActivator(local.PeerActivator)
 }
 
 type nsGroupsByDomain struct {
@@ -491,6 +492,13 @@ func (s *DefaultServer) SetFirewall(fw Firewall) {
 	}
 }
 
+// SetPeerActivator wires the DNS-time lazy-connection warm-up on the local
+// resolver. Injected after the connection manager exists (it does not at
+// DNS-server construction time). Pass nil to disable.
+func (s *DefaultServer) SetPeerActivator(a local.PeerActivator) {
+	s.localResolver.SetPeerActivator(a)
+}
+
 // Stop stops the server
 func (s *DefaultServer) Stop() {
 	s.ctxCancel()
@@ -1435,11 +1443,11 @@ type localPeerConnectivity struct {
 
 // IsConnectedByIP looks the IP up in the peerstore and surfaces both
 // the known and connected bits. Used by Resolver.filterDisconnectedPeerAnswers.
-func (l localPeerConnectivity) IsConnectedByIP(ip string) (known, connected bool) {
+func (l localPeerConnectivity) IsConnectedByIP(ip netip.Addr) (known, connected bool) {
 	if l.status == nil {
 		return false, false
 	}
-	state, ok := l.status.PeerStateByIP(ip)
+	state, ok := l.status.PeerStateByIP(ip.String())
 	if !ok {
 		return false, false
 	}

client/internal/dns_peer_activator.go

@@ -0,0 +1,76 @@
+package internal
+
+import (
+	"context"
+	"net/netip"
+	"time"
+
+	"github.com/netbirdio/netbird/client/internal/peer"
+	"github.com/netbirdio/netbird/client/internal/peerstore"
+)
+
+const dnsActivationPollInterval = 50 * time.Millisecond
+
+// dnsPeerActivator wakes lazy-connection peers from the DNS resolution path. It
+// implements dns/local.PeerActivator. DNS queries run on their own goroutines,
+// so it only touches state that is safe for concurrent use — ConnMgr.ActivatePeer,
+// peerstore.Store and peer.Status — and never takes the engine's syncMsgMux,
+// keeping DNS resolution from contending with network-map processing.
+type dnsPeerActivator struct {
+	connMgr   *ConnMgr
+	peerStore *peerstore.Store
+	status    *peer.Status
+	// ctx is the engine's long-lived context. The connection dial is tied to it
+	// (not the per-query DNS wait budget) so a handshake that outlasts the wait
+	// still completes in the background rather than being cancelled at the deadline.
+	ctx context.Context
+}
+
+// ActivatePeersByIP triggers wake-up for the peer(s) owning addrs and waits
+// until one is connected or ctx (the per-query DNS wait budget) expires.
+// Activation itself is tied to the engine's long-lived context so the dial
+// survives a wait that times out. Unknown or already-connected addresses are
+// skipped, so the steady-state (warm) path adds no latency.
+func (a *dnsPeerActivator) ActivatePeersByIP(ctx context.Context, addrs []netip.Addr) {
+	if a == nil || a.connMgr == nil {
+		return
+	}
+
+	var pending []string
+	for _, addr := range addrs {
+		ip := addr.String()
+		st, ok := a.status.PeerStateByIP(ip)
+		if !ok || st.ConnStatus == peer.StatusConnected {
+			continue
+		}
+		conn, ok := a.peerStore.PeerConn(st.PubKey)
+		if !ok {
+			continue
+		}
+		a.connMgr.ActivatePeer(a.ctx, conn)
+		pending = append(pending, ip)
+	}
+
+	if len(pending) == 0 {
+		return
+	}
+	a.waitConnected(ctx, pending)
+}
+
+// waitConnected blocks until any of ips reports a connected peer or ctx expires.
+func (a *dnsPeerActivator) waitConnected(ctx context.Context, ips []string) {
+	ticker := time.NewTicker(dnsActivationPollInterval)
+	defer ticker.Stop()
+	for {
+		for _, ip := range ips {
+			if st, ok := a.status.PeerStateByIP(ip); ok && st.ConnStatus == peer.StatusConnected {
+				return
+			}
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+	}
+}

client/internal/dns_peer_activator_test.go

@@ -0,0 +1,129 @@
+package internal
+
+import (
+	"context"
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/client/internal/peer"
+	"github.com/netbirdio/netbird/client/internal/peerstore"
+)
+
+func newTestPeerConn(t *testing.T, key string) *peer.Conn {
+	t.Helper()
+	conn, err := peer.NewConn(peer.ConnConfig{
+		Key:      key,
+		LocalKey: "local",
+		WgConfig: peer.WgConfig{
+			AllowedIps: []netip.Prefix{netip.MustParsePrefix("100.64.0.1/32")},
+		},
+	}, peer.ServiceDependencies{})
+	require.NoError(t, err)
+	return conn
+}
+
+func newTestDNSPeerActivator(t *testing.T) (*dnsPeerActivator, *peer.Status, *peerstore.Store) {
+	t.Helper()
+	status := peer.NewRecorder("https://mgm")
+	store := peerstore.NewConnStore()
+	// ConnMgr without Start: the lazy manager is nil, so ActivatePeer is a
+	// no-op — these tests exercise the activator's skip/wait logic.
+	connMgr := NewConnMgr(&EngineConfig{}, status, store, nil)
+	return &dnsPeerActivator{
+		connMgr:   connMgr,
+		peerStore: store,
+		status:    status,
+		ctx:       context.Background(),
+	}, status, store
+}
+
+func TestDNSPeerActivator_NilSafe(t *testing.T) {
+	var a *dnsPeerActivator
+	a.ActivatePeersByIP(context.Background(), []netip.Addr{netip.MustParseAddr("100.64.0.1")})
+}
+
+// TestDNSPeerActivator_SkipsUnknownAndConnectedPeers verifies the steady-state
+// (warm) path adds no latency: already-connected and unknown addresses never
+// enter the wait loop.
+func TestDNSPeerActivator_SkipsUnknownAndConnectedPeers(t *testing.T) {
+	a, status, store := newTestDNSPeerActivator(t)
+
+	require.NoError(t, status.AddPeer("peerA", "a.netbird.cloud", "100.64.0.1", "fd00::1"))
+	require.NoError(t, status.UpdatePeerState(peer.State{PubKey: "peerA", ConnStatus: peer.StatusConnected}))
+	store.AddPeerConn("peerA", newTestPeerConn(t, "peerA"))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	start := time.Now()
+	a.ActivatePeersByIP(ctx, []netip.Addr{
+		netip.MustParseAddr("100.64.0.1"),  // known, connected -> skipped
+		netip.MustParseAddr("fd00::1"),     // known via IPv6, connected -> skipped
+		netip.MustParseAddr("100.64.0.99"), // unknown -> skipped
+	})
+	require.Less(t, time.Since(start), time.Second, "no pending peer must mean no wait")
+}
+
+// TestDNSPeerActivator_WaitsForPendingPeerToConnect verifies the wait loop
+// returns as soon as a pending peer reports connected, well before the
+// per-query budget expires.
+func TestDNSPeerActivator_WaitsForPendingPeerToConnect(t *testing.T) {
+	a, status, store := newTestDNSPeerActivator(t)
+
+	require.NoError(t, status.AddPeer("peerA", "a.netbird.cloud", "100.64.0.1", ""))
+	store.AddPeerConn("peerA", newTestPeerConn(t, "peerA"))
+
+	go func() {
+		time.Sleep(150 * time.Millisecond)
+		_ = status.UpdatePeerState(peer.State{PubKey: "peerA", ConnStatus: peer.StatusConnected})
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	start := time.Now()
+	a.ActivatePeersByIP(ctx, []netip.Addr{netip.MustParseAddr("100.64.0.1")})
+	elapsed := time.Since(start)
+
+	require.GreaterOrEqual(t, elapsed, 100*time.Millisecond, "must wait for the pending peer")
+	require.Less(t, elapsed, 5*time.Second, "must return on connect, not at the deadline")
+}
+
+// TestDNSPeerActivator_ReturnsAtBudgetWhenPeerStaysIdle verifies a peer that
+// never connects releases the DNS response at the per-query budget instead of
+// blocking it indefinitely.
+func TestDNSPeerActivator_ReturnsAtBudgetWhenPeerStaysIdle(t *testing.T) {
+	a, status, store := newTestDNSPeerActivator(t)
+
+	require.NoError(t, status.AddPeer("peerA", "a.netbird.cloud", "100.64.0.1", ""))
+	store.AddPeerConn("peerA", newTestPeerConn(t, "peerA"))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
+	defer cancel()
+
+	start := time.Now()
+	a.ActivatePeersByIP(ctx, []netip.Addr{netip.MustParseAddr("100.64.0.1")})
+	elapsed := time.Since(start)
+
+	require.GreaterOrEqual(t, elapsed, 250*time.Millisecond, "must wait out the budget for a pending peer")
+	require.Less(t, elapsed, 5*time.Second, "must not block past the budget")
+}
+
+// TestDNSPeerActivator_NoWaitWithoutPeerConn verifies a known-but-idle peer
+// with no connection object in the store is not waited on: there is nothing to
+// activate, so waiting could only ever time out.
+func TestDNSPeerActivator_NoWaitWithoutPeerConn(t *testing.T) {
+	a, status, _ := newTestDNSPeerActivator(t)
+
+	require.NoError(t, status.AddPeer("peerA", "a.netbird.cloud", "100.64.0.1", ""))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	start := time.Now()
+	a.ActivatePeersByIP(ctx, []netip.Addr{netip.MustParseAddr("100.64.0.1")})
+	require.Less(t, time.Since(start), time.Second, "peer without a conn must not be waited on")
+}

client/internal/engine.go

@@ -64,7 +64,10 @@ import (
 	"github.com/netbirdio/netbird/route"
 	mgm "github.com/netbirdio/netbird/shared/management/client"
 	"github.com/netbirdio/netbird/shared/management/domain"
+	sharedgrpc "github.com/netbirdio/netbird/shared/management/grpc"
+	nbnetworkmap "github.com/netbirdio/netbird/shared/management/networkmap"
 	mgmProto "github.com/netbirdio/netbird/shared/management/proto"
+	types "github.com/netbirdio/netbird/shared/management/types"
 	"github.com/netbirdio/netbird/shared/netiputil"
 	auth "github.com/netbirdio/netbird/shared/relay/auth/hmac"
 	relayClient "github.com/netbirdio/netbird/shared/relay/client"
@@ -147,6 +150,7 @@ type EngineConfig struct {
 	BlockLANAccess      bool
 	BlockInbound        bool
 	DisableIPv6         bool
+	SyncMessageVersion  *int
 
 	// LazyConnection is the MDM-sourced lazy-connection override; StateUnset defers to
 	// the env var and management feature flag.
@@ -220,6 +224,13 @@ type Engine struct {
 	// networkSerial is the latest CurrentSerial (state ID) of the network sent by the Management service
 	networkSerial uint64
 
+	// latestComponents is the most-recent NetworkMapComponents decoded from
+	// a NetworkMapEnvelope (capability=3 peers only). Held alongside the
+	// NetworkMap that Calculate() produced from it so future incremental
+	// updates have a base to apply changes against. nil for legacy-format
+	// peers. Guarded by syncMsgMux.
+	latestComponents *types.NetworkMapComponents
+
 	networkMonitor *networkmonitor.NetworkMonitor
 
 	sshServer sshServer
@@ -654,6 +665,16 @@ func (e *Engine) Start(netbirdConfig *mgmProto.NetbirdConfig, mgmtURL *url.URL)
 	e.connMgr = NewConnMgr(e.config, e.statusRecorder, e.peerStore, wgIface)
 	e.connMgr.Start(e.ctx)
 
+	// Wire DNS-time lazy-connection warm-up now that the connection manager
+	// exists (it does not at DNS-server construction time). A DNS answer that
+	// points at an idle peer then wakes it before the client's first request.
+	e.dnsServer.SetPeerActivator(&dnsPeerActivator{
+		connMgr:   e.connMgr,
+		peerStore: e.peerStore,
+		status:    e.statusRecorder,
+		ctx:       e.ctx,
+	})
+
 	e.srWatcher = guard.NewSRWatcher(e.signal, e.relayManager, e.mobileDep.IFaceDiscover, iceCfg)
 	e.srWatcher.Start(peer.IsForceRelayed())
 
@@ -963,8 +984,12 @@ func (e *Engine) handleSync(update *mgmProto.SyncResponse) error {
 
 	e.ApplySessionDeadline(update.GetSessionExpiresAt())
 
-	if update.NetworkMap != nil && update.NetworkMap.PeerConfig != nil {
-		e.handleAutoUpdateVersion(update.NetworkMap.PeerConfig.AutoUpdate)
+	// Envelope sync responses carry PeerConfig at the top level; legacy
+	// NetworkMap syncs carry it under NetworkMap.PeerConfig.
+	if pc := update.GetPeerConfig(); pc != nil {
+		e.handleAutoUpdateVersion(pc.GetAutoUpdate())
+	} else if nm := update.GetNetworkMap(); nm != nil && nm.GetPeerConfig() != nil {
+		e.handleAutoUpdateVersion(nm.GetPeerConfig().GetAutoUpdate())
 	}
 
 	done := e.phase("netbird_config")
@@ -974,12 +999,47 @@ func (e *Engine) handleSync(update *mgmProto.SyncResponse) error {
 		return err
 	}
 
+	// Decode the network map from either the components envelope or the
+	// legacy proto.NetworkMap before the posture-check gating below, so the
+	// "is there a network map" decision covers both wire shapes.
+	var (
+		nm         *mgmProto.NetworkMap
+		components *types.NetworkMapComponents
+	)
+	if version := update.GetVersion(); version == int32(sharedgrpc.ComponentNetworkMap) {
+		// Components-format peer: decode the envelope back to typed
+		// components, run Calculate() locally, and convert to the wire
+		// NetworkMap shape the rest of the engine consumes. Components are
+		// retained so future incremental updates can apply deltas instead
+		// of doing a full reconstruction.
+		envelope := update.GetNetworkMapEnvelope()
+		if envelope == nil {
+			return fmt.Errorf("received a SyncReponse indicating use of components network map, but components are missing")
+		}
+
+		localKey := e.config.WgPrivateKey.PublicKey().String()
+		dnsName := ""
+		if pc := update.GetPeerConfig(); pc != nil {
+			// PeerConfig.Fqdn = "<dns_label>.<dns_domain>" — extract the
+			// shared domain by stripping the peer's own label prefix. Falls
+			// back to empty if the FQDN doesn't have the expected shape.
+			dnsName = extractDNSDomainFromFQDN(pc.GetFqdn())
+		}
+		result, err := nbnetworkmap.EnvelopeToNetworkMap(e.ctx, envelope, localKey, dnsName)
+		if err != nil {
+			return fmt.Errorf("decode network map envelope: %w", err)
+		}
+		nm = result.NetworkMap
+		components = result.Components
+	} else {
+		nm = update.GetNetworkMap()
+	}
+
 	// Posture checks are bound to the network map presence:
 	//   NetworkMap != nil, checks present -> apply the received checks
 	//   NetworkMap != nil, checks nil     -> posture checks were removed, clear them
 	//   NetworkMap == nil                 -> config-only update (e.g. relay token rotation),
 	//                                        leave the previously applied checks untouched
-	nm := update.GetNetworkMap()
 	if nm == nil {
 		return nil
 	}
@@ -992,6 +1052,14 @@ func (e *Engine) handleSync(update *mgmProto.SyncResponse) error {
 	}
 
 	done = e.phase("persist")
+	// Only retain the components view when the server sent the envelope
+	// path. A legacy proto.NetworkMap means components == nil; writing it
+	// here would clobber a previously-cached snapshot, breaking the
+	// incremental-delta base on a future envelope sync.
+	if components != nil {
+		e.latestComponents = components
+	}
+
 	e.persistSyncResponse(update)
 	done()
 
@@ -1005,6 +1073,19 @@ func (e *Engine) handleSync(update *mgmProto.SyncResponse) error {
 	return nil
 }
 
+// extractDNSDomainFromFQDN returns the trailing dotted domain part of the
+// receiving peer's FQDN — the same value the management server fills as
+// dnsName when it builds the legacy NetworkMap. "peer42.netbird.cloud" →
+// "netbird.cloud". An empty string is returned for unrecognized formats.
+func extractDNSDomainFromFQDN(fqdn string) string {
+	for i := 0; i < len(fqdn); i++ {
+		if fqdn[i] == '.' && i+1 < len(fqdn) {
+			return fqdn[i+1:]
+		}
+	}
+	return ""
+}
+
 // updateNetbirdConfig applies the management-provided NetBird configuration:
 // STUN/TURN and relay servers, flow logging and DNS settings. A nil config is a no-op,
 // which is the case for sync updates carrying only a network map.
@@ -1164,6 +1245,7 @@ func (e *Engine) applyInfoFlags(info *system.Info) {
 		e.config.BlockLANAccess,
 		e.config.BlockInbound,
 		e.config.DisableIPv6,
+		e.config.SyncMessageVersion,
 		e.config.EnableSSHRoot,
 		e.config.EnableSSHSFTP,
 		e.config.EnableSSHLocalPortForwarding,
@@ -2032,6 +2114,7 @@ func (e *Engine) readInitialSettings() ([]*route.Route, *nbdns.Config, bool, err
 		e.config.BlockLANAccess,
 		e.config.BlockInbound,
 		e.config.DisableIPv6,
+		e.config.SyncMessageVersion,
 		e.config.EnableSSHRoot,
 		e.config.EnableSSHSFTP,
 		e.config.EnableSSHLocalPortForwarding,

client/internal/engine_session_deadline_test.go

@@ -75,4 +75,14 @@ func TestApplySessionDeadline_ThreeState(t *testing.T) {
 		require.True(t, e.statusRecorder.GetSessionExpiresAt().IsZero(),
 			"invalid timestamp must clear the deadline")
 	})
+
+	t.Run("recently expired timestamp stays visible as expired", func(t *testing.T) {
+		e := newEngine()
+		expired := time.Now().Add(-5 * time.Minute).UTC().Truncate(time.Second)
+
+		e.ApplySessionDeadline(timestamppb.New(expired))
+
+		require.True(t, e.statusRecorder.GetSessionExpiresAt().Equal(expired),
+			"recently-expired deadline must stay on the recorder so consumers render it as expired")
+	})
 }

client/internal/peer/status.go

@@ -813,19 +813,14 @@ func (d *Status) SetSessionExpiresAt(deadline time.Time) {
 }
 
 // GetSessionExpiresAt returns the most recently recorded SSO session deadline,
-// or the zero value when no deadline is tracked. A deadline that has already
-// slipped into the past reports as "none": once the session has expired it is
-// no longer a meaningful countdown, and the sessionwatch.Watcher does not
-// arm a timer at the deadline itself to clear it (only the two pre-expiry
-// warnings). Without this guard the UI would keep painting a stale
-// "expires in …" against a moment that has passed until the next login,
-// extend, or teardown rewrote the value.
+// or the zero value when no deadline is tracked. A deadline in the past is
+// returned as-is: it means the session has expired, and consumers (tray row,
+// CLI status) render it as "expired" rather than hiding it — masking it as
+// "none" would blank the UI at the exact moment it should say the session
+// ended.
 func (d *Status) GetSessionExpiresAt() time.Time {
 	d.mux.Lock()
 	defer d.mux.Unlock()
-	if !d.sessionExpiresAt.IsZero() && d.sessionExpiresAt.Before(time.Now()) {
-		return time.Time{}
-	}
 	return d.sessionExpiresAt
 }
 

client/internal/profilemanager/config.go

@@ -96,6 +96,7 @@ type ConfigInput struct {
 	BlockLANAccess      *bool
 	BlockInbound        *bool
 	DisableIPv6         *bool
+	SyncMessageVersion  *int
 
 	DisableNotifications *bool
 
@@ -137,6 +138,7 @@ type Config struct {
 	BlockLANAccess      bool
 	BlockInbound        bool
 	DisableIPv6         bool
+	SyncMessageVersion  *int
 
 	DisableNotifications *bool
 
@@ -587,6 +589,12 @@ func (config *Config) apply(input ConfigInput) (updated bool, err error) {
 		updated = true
 	}
 
+	if input.SyncMessageVersion != nil && *input.SyncMessageVersion != *config.SyncMessageVersion {
+		log.Infof("setting SyncMessageVersion to %v", *input.SyncMessageVersion)
+		*config.SyncMessageVersion = *input.SyncMessageVersion
+		updated = true
+	}
+
 	if input.DisableNotifications != nil && (config.DisableNotifications == nil || *input.DisableNotifications != *config.DisableNotifications) {
 		if *input.DisableNotifications {
 			log.Infof("disabling notifications")

client/internal/routemanager/dynamic/route.go

@@ -185,7 +185,7 @@ func (r *Route) startResolver(ctx context.Context) {
 }
 
 func (r *Route) update(ctx context.Context) error {
-	resolved, err := r.resolveDomains()
+	resolved, err := r.resolveDomains(ctx)
 	if err != nil {
 		if len(resolved) == 0 {
 			return fmt.Errorf("resolve domains: %w", err)
@@ -199,9 +199,9 @@ func (r *Route) update(ctx context.Context) error {
 	return nil
 }
 
-func (r *Route) resolveDomains() (domainMap, error) {
+func (r *Route) resolveDomains(ctx context.Context) (domainMap, error) {
 	results := make(chan resolveResult)
-	go r.resolve(results)
+	go r.resolve(ctx, results)
 
 	resolved := domainMap{}
 	var merr *multierror.Error
@@ -217,7 +217,7 @@ func (r *Route) resolveDomains() (domainMap, error) {
 	return resolved, nberrors.FormatErrorOrNil(merr)
 }
 
-func (r *Route) resolve(results chan resolveResult) {
+func (r *Route) resolve(ctx context.Context, results chan resolveResult) {
 	var wg sync.WaitGroup
 
 	for _, d := range r.route.Domains {
@@ -225,10 +225,10 @@ func (r *Route) resolve(results chan resolveResult) {
 		go func(domain domain.Domain) {
 			defer wg.Done()
 
-			ips, err := r.getIPsFromResolver(domain)
+			ips, err := r.getIPsFromResolver(ctx, domain)
 			if err != nil {
 				log.Tracef("Failed to resolve domain %s with private resolver: %v", domain.SafeString(), err)
-				ips, err = net.LookupIP(domain.PunycodeString())
+				ips, err = lookupHostIPs(ctx, domain)
 				if err != nil {
 					results <- resolveResult{domain: domain, err: fmt.Errorf("resolve d %s: %w", domain.SafeString(), err)}
 					return
@@ -364,6 +364,20 @@ func determinePrefixChanges(oldPrefixes, newPrefixes []netip.Prefix) (toAdd, toR
 	return
 }
 
+// lookupHostIPs resolves d via the system resolver, honoring ctx cancellation.
+func lookupHostIPs(ctx context.Context, d domain.Domain) ([]net.IP, error) {
+	addrs, err := net.DefaultResolver.LookupIPAddr(ctx, d.PunycodeString())
+	if err != nil {
+		return nil, err
+	}
+
+	ips := make([]net.IP, 0, len(addrs))
+	for _, addr := range addrs {
+		ips = append(ips, addr.IP)
+	}
+	return ips, nil
+}
+
 func combinePrefixes(oldPrefixes, removedPrefixes, addedPrefixes []netip.Prefix) []netip.Prefix {
 	prefixSet := make(map[netip.Prefix]struct{})
 	for _, prefix := range oldPrefixes {

client/internal/routemanager/dynamic/route_generic.go

@@ -3,11 +3,12 @@
 package dynamic
 
 import (
+	"context"
 	"net"
 
 	"github.com/netbirdio/netbird/shared/management/domain"
 )
 
-func (r *Route) getIPsFromResolver(domain domain.Domain) ([]net.IP, error) {
-	return net.LookupIP(domain.PunycodeString())
+func (r *Route) getIPsFromResolver(ctx context.Context, domain domain.Domain) ([]net.IP, error) {
+	return lookupHostIPs(ctx, domain)
 }

client/internal/routemanager/dynamic/route_ios.go

@@ -3,6 +3,7 @@
 package dynamic
 
 import (
+	"context"
 	"fmt"
 	"net"
 	"time"
@@ -16,7 +17,7 @@ import (
 
 const dialTimeout = 10 * time.Second
 
-func (r *Route) getIPsFromResolver(domain domain.Domain) ([]net.IP, error) {
+func (r *Route) getIPsFromResolver(ctx context.Context, domain domain.Domain) ([]net.IP, error) {
 	privateClient, err := nbdns.GetClientPrivate(r.wgInterface, r.resolverAddr.Addr(), dialTimeout)
 	if err != nil {
 		return nil, fmt.Errorf("error while creating private client: %s", err)
@@ -32,7 +33,7 @@ func (r *Route) getIPsFromResolver(domain domain.Domain) ([]net.IP, error) {
 		msg := new(dns.Msg)
 		msg.SetQuestion(fqdn, qtype)
 
-		response, _, err := nbdns.ExchangeWithFallback(nil, privateClient, msg, r.resolverAddr.String())
+		response, _, err := nbdns.ExchangeWithFallback(ctx, privateClient, msg, r.resolverAddr.String())
 		if err != nil {
 			if queryErr == nil {
 				queryErr = fmt.Errorf("DNS query for %s (type %d) after %s: %w", domain.SafeString(), qtype, time.Since(startTime), err)

client/ios/NetBirdSDK/client.go

@@ -233,6 +233,9 @@ func (c *Client) DebugBundle(anonymize bool) (string, error) {
 		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
 			}

client/server/server.go

@@ -1081,7 +1081,10 @@ func (s *Server) Down(ctx context.Context, _ *proto.DownRequest) (*proto.DownRes
 
 	if err := s.cleanupConnection(); err != nil {
 		s.mutex.Unlock()
-		// todo review to update the status in case any type of error
+		if errors.Is(err, ErrServiceNotUp) {
+			log.Debugf("Down called while service not up: %v", err)
+			return nil, err
+		}
 		log.Errorf("failed to shut down properly: %v", err)
 		return nil, err
 	}
@@ -1154,7 +1157,7 @@ func (s *Server) cleanupConnection() error {
 	// making the run loop the sole owner of engine shutdown.
 	if engine != nil {
 		if err := engine.Stop(); err != nil {
-			return err
+			log.Errorf("failed to stop engine during cleanup: %v", err)
 		}
 	}
 

client/system/info.go

@@ -79,13 +79,15 @@ type Info struct {
 	EnableSSHLocalPortForwarding  bool
 	EnableSSHRemotePortForwarding bool
 	DisableSSHAuth                bool
+
+	SyncMessageVersion *int
 }
 
 func (i *Info) SetFlags(
 	rosenpassEnabled, rosenpassPermissive bool,
 	serverSSHAllowed *bool,
 	disableClientRoutes, disableServerRoutes,
-	disableDNS, disableFirewall, blockLANAccess, blockInbound, disableIPv6 bool,
+	disableDNS, disableFirewall, blockLANAccess, blockInbound, disableIPv6 bool, syncMessageVersion *int,
 	enableSSHRoot, enableSSHSFTP, enableSSHLocalPortForwarding, enableSSHRemotePortForwarding *bool,
 	disableSSHAuth *bool,
 ) {
@@ -103,6 +105,8 @@ func (i *Info) SetFlags(
 	i.BlockInbound = blockInbound
 	i.DisableIPv6 = disableIPv6
 
+	i.SyncMessageVersion = syncMessageVersion
+
 	if enableSSHRoot != nil {
 		i.EnableSSHRoot = *enableSSHRoot
 	}

client/ui/autostart_default.go

@@ -51,7 +51,7 @@ func autostartDisabledByMDM(policy *mdm.Policy) bool {
 // netbirdFootprintExists reports whether the machine already carries NetBird
 // daemon config or state, meaning this is not a genuinely fresh install. It is
 // the update-safety gate for the autostart default: upgrading users always
-// have a footprint, so an update can never trigger a login-item write.
+// have a footprint, so an update can never trigger a autostart entry write.
 func netbirdFootprintExists() bool {
 	candidates := []string{
 		profilemanager.DefaultConfigPath,
@@ -69,9 +69,23 @@ func netbirdFootprintExists() bool {
 // applyAutostartDefault runs the one-time launch-on-login default for genuinely
 // fresh installs. The autostartInitialized marker is persisted before any
 // enable attempt so a crash mid-flow degrades to "never enabled" instead of
-// retrying login-item writes on every launch. A user's later disable in
+// retrying autostart entry writes on every launch. A user's later disable in
 // Settings is never overridden: the marker guarantees at-most-once, ever.
 func applyAutostartDefault(ctx context.Context, autostart *services.Autostart, prefs *preferences.Store, prefsFileExisted bool) {
+	mdmDisabled := autostartDisabledByMDM(mdm.LoadPolicy())
+
+	if mdmDisabled {
+		if enabled, err := autostart.IsEnabled(ctx); err != nil {
+			log.Warnf("MDM disableAutostart: read autostart state: %v", err)
+		} else if enabled {
+			if err := autostart.SetEnabled(ctx, false); err != nil {
+				log.Warnf("MDM disableAutostart: force off failed: %v", err)
+			} else {
+				log.Info("MDM disableAutostart enforced: autostart turned off")
+			}
+		}
+	}
+
 	priorFootprint := netbirdFootprintExists() || prefsFileExisted
 
 	if prefs.Get().AutostartInitialized {
@@ -84,7 +98,7 @@ func applyAutostartDefault(ctx context.Context, autostart *services.Autostart, p
 
 	state := autostartDefaultState{
 		supported:    autostart.Supported(ctx),
-		mdmDisabled:  autostartDisabledByMDM(mdm.LoadPolicy()),
+		mdmDisabled:  mdmDisabled,
 		priorInstall: priorFootprint,
 	}
 	enable, reason := shouldEnableAutostartDefault(state)

client/ui/frontend/src/components/empty-state/DaemonOutdatedOverlay.tsx

@@ -1,10 +1,13 @@
+import { useEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { AlertTriangleIcon, DownloadIcon } from "lucide-react";
 import { Browser } from "@wailsio/runtime";
+import { Version } from "@bindings/services";
 import { Button } from "@/components/buttons/Button";
 import { useStatus } from "@/contexts/StatusContext.tsx";
 
 const RELEASES_URL = "https://github.com/netbirdio/netbird/releases/latest";
+const RC_RELEASES_URL = "https://pkgs.netbird.io/releases/rc";
 
 function openUrl(url: string) {
     Browser.OpenURL(url).catch(() => globalThis.open(url, "_blank"));
@@ -12,7 +15,26 @@ function openUrl(url: string) {
 
 export const DaemonOutdatedOverlay = () => {
     const { t } = useTranslation();
-    const { isDaemonOutdated } = useStatus();
+    const { status, isDaemonOutdated } = useStatus();
+
+    const [guiVersion, setGuiVersion] = useState<string>("-");
+    const clientVersion = status?.daemonVersion ?? "—";
+
+    const isRc = /-rc/i.test(guiVersion) || /-rc/i.test(clientVersion);
+    const downloadUrl = isRc ? RC_RELEASES_URL : RELEASES_URL;
+
+    useEffect(() => {
+        if (!isDaemonOutdated) return;
+        let cancelled = false;
+        Version.GUI()
+            .then((v) => {
+                if (!cancelled) setGuiVersion(v);
+            })
+            .catch((err) => console.error("[DaemonOutdatedOverlay] GUI version error", err));
+        return () => {
+            cancelled = true;
+        };
+    }, [isDaemonOutdated]);
 
     if (!isDaemonOutdated) return null;
 
@@ -38,10 +60,37 @@ export const DaemonOutdatedOverlay = () => {
                     <p className={"text-sm text-nb-gray-300"}>{t("daemon.outdated.description")}</p>
                 </div>
 
+                <div className={"flex flex-col items-center gap-0.5 text-center"}>
+                    <p className={"text-sm font-semibold text-nb-gray-100"}>
+                        {clientVersion === "development" ? (
+                            <span>
+                                {t("settings.about.clientName")}{" "}
+                                <span className={"font-mono text-yellow-400"}>
+                                    {t("settings.about.development")}
+                                </span>
+                            </span>
+                        ) : (
+                            t("settings.about.client", { version: clientVersion })
+                        )}
+                    </p>
+                    <p className={"text-sm font-medium text-nb-gray-250"}>
+                        {guiVersion === "development" ? (
+                            <span>
+                                {t("settings.about.guiName")}{" "}
+                                <span className={"font-mono text-yellow-400"}>
+                                    {t("settings.about.development")}
+                                </span>
+                            </span>
+                        ) : (
+                            t("settings.about.gui", { version: guiVersion })
+                        )}
+                    </p>
+                </div>
+
                 <div className={"wails-no-draggable"}>
-                    <Button variant={"primary"} size={"xs"} onClick={() => openUrl(RELEASES_URL)}>
+                    <Button variant={"primary"} size={"xs"} onClick={() => openUrl(downloadUrl)}>
                         <DownloadIcon size={14} />
-                        {t("update.card.getInstaller")}
+                        {t("daemon.outdated.download")}
                     </Button>
                 </div>
             </div>

client/ui/frontend/src/contexts/ProfileContext.tsx

@@ -28,6 +28,7 @@ type ProfileContextValue = {
     loaded: boolean;
     refresh: () => Promise<void>;
     switchProfile: (id: string) => Promise<void>;
+    switchProfileNoConnect: (id: string) => Promise<void>;
     addProfile: (name: string) => Promise<string>;
     removeProfile: (id: string) => Promise<void>;
     renameProfile: (id: string, newName: string) => Promise<void>;
@@ -112,6 +113,16 @@ export const ProfileProvider = ({ children }: { children: ReactNode }) => {
         [username, refresh],
     );
 
+    // Manage-profiles variant: switches without connecting, so the user can
+    // still adjust the management URL before bringing the connection up.
+    const switchProfileNoConnect = useCallback(
+        async (id: string) => {
+            await ProfileSwitcher.SwitchActiveNoConnect({ profileName: id, username });
+            await refresh();
+        },
+        [username, refresh],
+    );
+
     // addProfile creates a profile by display name and returns the
     // daemon-generated ID, so the caller can immediately address it by ID.
     const addProfile = useCallback(
@@ -158,6 +169,7 @@ export const ProfileProvider = ({ children }: { children: ReactNode }) => {
             loaded,
             refresh,
             switchProfile,
+            switchProfileNoConnect,
             addProfile,
             removeProfile,
             renameProfile,
@@ -171,6 +183,7 @@ export const ProfileProvider = ({ children }: { children: ReactNode }) => {
             loaded,
             refresh,
             switchProfile,
+            switchProfileNoConnect,
             addProfile,
             removeProfile,
             renameProfile,

client/ui/frontend/src/modules/profiles/ProfilesTab.tsx

@@ -45,7 +45,7 @@ export function ProfilesTab() {
         activeProfileId,
         loaded,
         username,
-        switchProfile,
+        switchProfileNoConnect,
         addProfile,
         removeProfile,
         renameProfile,
@@ -100,7 +100,7 @@ export function ProfilesTab() {
             confirmLabel: t("profile.switch.confirm"),
         });
         if (!ok) return;
-        await guarded(i18next.t("profile.error.switchTitle"), () => switchProfile(id));
+        await guarded(i18next.t("profile.error.switchTitle"), () => switchProfileNoConnect(id));
     };
 
     const handleDeregister = async (id: string, name: string) => {
@@ -129,14 +129,13 @@ export function ProfilesTab() {
         await guarded(i18next.t("profile.error.createTitle"), async () => {
             const id = await addProfile(name);
             // SetConfig is keyed by the new profile's ID, so it writes the
-            // not-yet-active profile. Write before switching so any reconnect
-            // targets the right deployment.
+            // not-yet-active profile before the switch makes it current.
             if (!isNetbirdCloud(managementUrl)) {
                 await SettingsSvc.SetConfig(
                     new SetConfigParams({ profileName: id, username, managementUrl }),
                 );
             }
-            await switchProfile(id);
+            await switchProfileNoConnect(id);
         });
     };
 

client/ui/frontend/src/modules/session/SessionExpirationDialog.tsx

@@ -73,6 +73,13 @@ export default function SessionExpirationDialog() {
 
         let offCancel: (() => void) | undefined;
 
+        // Return the dialog to its interactive state and dismiss the browser popup
+        const resetDialog = () => {
+            offCancel?.();
+            WindowManager.CloseBrowserLogin().catch(console.error);
+            setBusy(false);
+        };
+
         try {
             const start = await Session.RequestExtend({ hint: "" });
             const uri = start.verificationUriComplete || start.verificationUri;
@@ -105,25 +112,22 @@ export default function SessionExpirationDialog() {
             if (outcome.kind === "cancel") {
                 waitPromise.cancel?.();
                 waitPromise.catch(() => {});
+                resetDialog();
                 return;
             }
 
             // Another surface owns this flow; keep the dialog open to retry.
             if (outcome.result.preempted) {
+                resetDialog();
                 return;
             }
-
-            // Close before the popup so the restore can't flash this window back.
-            WindowManager.CloseSessionExpiration().catch(console.error);
+            WindowManager.CloseRenewFlow().catch(console.error);
         } catch (e) {
+            resetDialog();
             await errorDialog({
                 Title: t("sessionExpiration.extendFailedTitle"),
                 Message: formatErrorMessage(e),
             });
-        } finally {
-            offCancel?.();
-            WindowManager.CloseBrowserLogin().catch(console.error);
-            setBusy(false);
         }
     }, [busy, t]);
 
@@ -139,12 +143,11 @@ export default function SessionExpirationDialog() {
             });
             WindowManager.CloseSessionExpiration().catch(console.error);
         } catch (e) {
+            setBusy(false);
             await errorDialog({
                 Title: t("sessionExpiration.logoutFailedTitle"),
                 Message: formatErrorMessage(e),
             });
-        } finally {
-            setBusy(false);
         }
     }, [busy, t]);
 

client/ui/frontend/src/modules/welcome/WelcomeStepTray.tsx

@@ -22,6 +22,9 @@ type WelcomeStepTrayProps = {
 export function WelcomeStepTray({ onContinue }: Readonly<WelcomeStepTrayProps>) {
     const { t } = useTranslation();
     const trayScreenshot = trayScreenshotForOS();
+    // macOS has no tray — the icon sits in the menu bar, so the copy says so.
+    const titleKey = isMacOS() ? "welcome.titleMac" : "welcome.title";
+    const descriptionKey = isMacOS() ? "welcome.descriptionMac" : "welcome.description";
 
     return (
         <>
@@ -36,9 +39,9 @@ export function WelcomeStepTray({ onContinue }: Readonly<WelcomeStepTrayProps>)
 
             <div className={"flex w-full flex-col gap-1"}>
                 <DialogHeading id={"nb-welcome-title"} align={"left"}>
-                    {t("welcome.title")}
+                    {t(titleKey)}
                 </DialogHeading>
-                <DialogDescription align={"left"}>{t("welcome.description")}</DialogDescription>
+                <DialogDescription align={"left"}>{t(descriptionKey)}</DialogDescription>
             </div>
 
             <DialogActions>

client/ui/i18n/locales/_index.json

@@ -8,6 +8,7 @@
         {"code": "fr", "displayName": "Français", "englishName": "French"},
         {"code": "it", "displayName": "Italiano", "englishName": "Italian"},
         {"code": "pt", "displayName": "Português", "englishName": "Portuguese"},
-        {"code": "zh-CN", "displayName": "简体中文", "englishName": "Simplified Chinese"}
+        {"code": "zh-CN", "displayName": "简体中文", "englishName": "Simplified Chinese"},
+        {"code": "ja", "displayName": "日本語", "englishName": "Japanese"}
     ]
 }

client/ui/i18n/locales/de/common.json

@@ -1034,9 +1034,15 @@
     "welcome.title": {
         "message": "Suchen Sie NetBird in der Taskleiste"
     },
+    "welcome.titleMac": {
+        "message": "Suchen Sie NetBird in der Menüleiste"
+    },
     "welcome.description": {
         "message": "NetBird läuft in Ihrer Taskleiste. Klicken Sie auf das Symbol, um sich zu verbinden, Profile zu wechseln oder die Einstellungen zu öffnen."
     },
+    "welcome.descriptionMac": {
+        "message": "NetBird läuft in Ihrer Menüleiste. Klicken Sie auf das Symbol, um sich zu verbinden, Profile zu wechseln oder die Einstellungen zu öffnen."
+    },
     "welcome.continue": {
         "message": "Weiter"
     },
@@ -1293,10 +1299,13 @@
         "message": "Dokumentation"
     },
     "daemon.outdated.title": {
-        "message": "NetBird-Dienst ist veraltet"
+        "message": "NetBird Client ist veraltet"
     },
     "daemon.outdated.description": {
-        "message": "Aktualisieren Sie den NetBird-Dienst, um diese App zu verwenden."
+        "message": "Die neue GUI ist nicht mit Ihrem älteren Client kompatibel. Aktualisieren Sie Ihren Client, um die neue Anwendung zu verwenden."
+    },
+    "daemon.outdated.download": {
+        "message": "Neueste Version herunterladen"
     },
     "error.jwt_clock_skew": {
         "message": "Anmeldung fehlgeschlagen: Die Uhr dieses Geräts ist nicht mit dem Server synchron. Bitte synchronisieren Sie die Systemuhr und versuchen Sie es erneut."

client/ui/i18n/locales/en/common.json

@@ -1377,11 +1377,19 @@
     },
     "welcome.title": {
         "message": "Look for NetBird in your tray",
-        "description": "Heading on the first onboarding step, pointing the user to the tray icon. 'tray' = system tray / menu bar."
+        "description": "Heading on the first onboarding step, pointing the user to the tray icon. Shown on Windows and Linux; macOS uses welcome.titleMac."
+    },
+    "welcome.titleMac": {
+        "message": "Look for NetBird in your menu bar",
+        "description": "Heading on the first onboarding step on macOS, pointing the user to the menu bar icon. Use your language's Apple term for the macOS menu bar."
     },
     "welcome.description": {
         "message": "NetBird lives in your tray. Click the icon to connect, switch profiles, or open settings.",
-        "description": "Body of the first onboarding step explaining the tray icon."
+        "description": "Body of the first onboarding step explaining the tray icon. Shown on Windows and Linux; macOS uses welcome.descriptionMac."
+    },
+    "welcome.descriptionMac": {
+        "message": "NetBird lives in your menu bar. Click the icon to connect, switch profiles, or open settings.",
+        "description": "Body of the first onboarding step on macOS explaining the menu bar icon. Use your language's Apple term for the macOS menu bar."
     },
     "welcome.continue": {
         "message": "Continue",
@@ -1724,12 +1732,16 @@
         "description": "Documentation link on the daemon-unavailable overlay."
     },
     "daemon.outdated.title": {
-        "message": "NetBird Service Is Outdated",
-        "description": "Title of the overlay shown when the NetBird background service is too old to drive this UI."
+        "message": "NetBird Client Is Outdated",
+        "description": "Title of the overlay shown when the NetBird client (daemon) is too old to drive this UI."
     },
     "daemon.outdated.description": {
-        "message": "Update the NetBird service to use this app.",
-        "description": "Body of the daemon-outdated overlay telling the user to upgrade the service."
+        "message": "The new GUI isn't compatible with the older NetBird client. Update your client to use the new application.",
+        "description": "Body of the daemon-outdated overlay explaining that the GUI is newer than the client and the client must be updated."
+    },
+    "daemon.outdated.download": {
+        "message": "Download Latest",
+        "description": "Button on the daemon-outdated overlay that opens the download page for the latest release."
     },
     "error.jwt_clock_skew": {
         "message": "Sign-in failed: this device's clock is out of sync with the server. Please sync your system clock and try again.",

client/ui/i18n/locales/es/common.json

@@ -1034,9 +1034,15 @@
     "welcome.title": {
         "message": "Busque NetBird en su bandeja del sistema"
     },
+    "welcome.titleMac": {
+        "message": "Busque NetBird en su barra de menús"
+    },
     "welcome.description": {
         "message": "NetBird reside en su bandeja del sistema. Haga clic en el icono para conectarse, cambiar de perfil o abrir la configuración."
     },
+    "welcome.descriptionMac": {
+        "message": "NetBird reside en su barra de menús. Haga clic en el icono para conectarse, cambiar de perfil o abrir la configuración."
+    },
     "welcome.continue": {
         "message": "Continuar"
     },
@@ -1293,10 +1299,13 @@
         "message": "Documentación"
     },
     "daemon.outdated.title": {
-        "message": "El servicio de NetBird está desactualizado"
+        "message": "NetBird Client está desactualizado"
     },
     "daemon.outdated.description": {
-        "message": "Actualice el servicio de NetBird para usar esta aplicación."
+        "message": "La nueva GUI no es compatible con su cliente anterior. Actualice su cliente para usar la nueva aplicación."
+    },
+    "daemon.outdated.download": {
+        "message": "Descargar la última versión"
     },
     "error.jwt_clock_skew": {
         "message": "Error al iniciar sesión: el reloj de este dispositivo no está sincronizado con el servidor. Sincronice el reloj del sistema e inténtelo de nuevo."

client/ui/i18n/locales/fr/common.json

@@ -1034,9 +1034,15 @@
     "welcome.title": {
         "message": "Cherchez NetBird dans votre barre d’état système"
     },
+    "welcome.titleMac": {
+        "message": "Cherchez NetBird dans votre barre des menus"
+    },
     "welcome.description": {
         "message": "NetBird se trouve dans votre barre d’état système. Cliquez sur l’icône pour vous connecter, changer de profil ou ouvrir les paramètres."
     },
+    "welcome.descriptionMac": {
+        "message": "NetBird se trouve dans votre barre des menus. Cliquez sur l’icône pour vous connecter, changer de profil ou ouvrir les paramètres."
+    },
     "welcome.continue": {
         "message": "Continuer"
     },
@@ -1293,10 +1299,13 @@
         "message": "Documentation"
     },
     "daemon.outdated.title": {
-        "message": "Le service NetBird est obsolète"
+        "message": "Le Client NetBird est obsolète"
     },
     "daemon.outdated.description": {
-        "message": "Mettez à jour le service NetBird pour utiliser cette application."
+        "message": "La nouvelle GUI n'est pas compatible avec votre ancien client. Mettez à jour votre client pour utiliser la nouvelle application."
+    },
+    "daemon.outdated.download": {
+        "message": "Télécharger la dernière version"
     },
     "error.jwt_clock_skew": {
         "message": "Échec de la connexion : l’horloge de cet appareil n’est pas synchronisée avec le serveur. Veuillez synchroniser l’horloge de votre système et réessayer."

client/ui/i18n/locales/hu/common.json

@@ -1034,9 +1034,15 @@
     "welcome.title": {
         "message": "Keresse a NetBirdöt a tálcán"
     },
+    "welcome.titleMac": {
+        "message": "Keresse a NetBirdöt a menüsorban"
+    },
     "welcome.description": {
         "message": "A NetBird a tálcán fut. Kattintson az ikonra a csatlakozáshoz, profilváltáshoz vagy a beállítások megnyitásához."
     },
+    "welcome.descriptionMac": {
+        "message": "A NetBird a menüsorban fut. Kattintson az ikonra a csatlakozáshoz, profilváltáshoz vagy a beállítások megnyitásához."
+    },
     "welcome.continue": {
         "message": "Folytatás"
     },
@@ -1293,10 +1299,13 @@
         "message": "Dokumentáció"
     },
     "daemon.outdated.title": {
-        "message": "A NetBird szolgáltatás elavult"
+        "message": "A NetBird Kliens elavult"
     },
     "daemon.outdated.description": {
-        "message": "Frissítsd a NetBird szolgáltatást az alkalmazás használatához."
+        "message": "Az új GUI nem kompatibilis a régebbi klienseddel. Frissítsd a klienst az új alkalmazás használatához."
+    },
+    "daemon.outdated.download": {
+        "message": "Legújabb letöltése"
     },
     "error.jwt_clock_skew": {
         "message": "A bejelentkezés sikertelen: az eszköz órája eltér a szerverétől. Kérjük, szinkronizálja a rendszer óráját, majd próbálja újra."

client/ui/i18n/locales/it/common.json

@@ -1034,9 +1034,15 @@
     "welcome.title": {
         "message": "Cerchi NetBird nella tray"
     },
+    "welcome.titleMac": {
+        "message": "Cerchi NetBird nella barra dei menu"
+    },
     "welcome.description": {
         "message": "NetBird risiede nella tray. Clicchi sull'icona per connettersi, cambiare profilo o aprire le impostazioni."
     },
+    "welcome.descriptionMac": {
+        "message": "NetBird risiede nella barra dei menu. Clicchi sull'icona per connettersi, cambiare profilo o aprire le impostazioni."
+    },
     "welcome.continue": {
         "message": "Continua"
     },
@@ -1293,10 +1299,13 @@
         "message": "Documentazione"
     },
     "daemon.outdated.title": {
-        "message": "Il servizio NetBird è obsoleto"
+        "message": "NetBird Client è obsoleto"
     },
     "daemon.outdated.description": {
-        "message": "Aggiorna il servizio NetBird per usare questa app."
+        "message": "La nuova GUI non è compatibile con il tuo client precedente. Aggiorna il client per usare la nuova applicazione."
+    },
+    "daemon.outdated.download": {
+        "message": "Scarica l'ultima versione"
     },
     "error.jwt_clock_skew": {
         "message": "Accesso non riuscito: l'orologio di questo dispositivo non è sincronizzato con il server. Sincronizzi l'orologio di sistema e riprovi."

client/ui/i18n/locales/pt/common.json

@@ -1034,9 +1034,15 @@
     "welcome.title": {
         "message": "Procure o NetBird na sua bandeja"
     },
+    "welcome.titleMac": {
+        "message": "Procure o NetBird na sua barra de menus"
+    },
     "welcome.description": {
         "message": "O NetBird fica na sua bandeja. Clique no ícone para conectar, alternar perfis ou abrir as configurações."
     },
+    "welcome.descriptionMac": {
+        "message": "O NetBird fica na sua barra de menus. Clique no ícone para conectar, alternar perfis ou abrir as configurações."
+    },
     "welcome.continue": {
         "message": "Continuar"
     },
@@ -1293,10 +1299,13 @@
         "message": "Documentação"
     },
     "daemon.outdated.title": {
-        "message": "O serviço NetBird está desatualizado"
+        "message": "O NetBird Client está desatualizado"
     },
     "daemon.outdated.description": {
-        "message": "Atualize o serviço NetBird para usar este aplicativo."
+        "message": "A nova GUI não é compatível com o seu cliente mais antigo. Atualize o seu cliente para usar o novo aplicativo."
+    },
+    "daemon.outdated.download": {
+        "message": "Baixar a versão mais recente"
     },
     "error.jwt_clock_skew": {
         "message": "Falha no login: o relógio deste dispositivo está fora de sincronia com o servidor. Sincronize o relógio do sistema e tente novamente."

client/ui/i18n/locales/ru/common.json

@@ -1034,9 +1034,15 @@
     "welcome.title": {
         "message": "Найдите NetBird в системном трее"
     },
+    "welcome.titleMac": {
+        "message": "Найдите NetBird в строке меню"
+    },
     "welcome.description": {
         "message": "NetBird находится в системном трее. Нажмите на значок, чтобы подключиться, переключить профиль или открыть настройки."
     },
+    "welcome.descriptionMac": {
+        "message": "NetBird находится в строке меню. Нажмите на значок, чтобы подключиться, переключить профиль или открыть настройки."
+    },
     "welcome.continue": {
         "message": "Продолжить"
     },
@@ -1293,10 +1299,13 @@
         "message": "Документация"
     },
     "daemon.outdated.title": {
-        "message": "Служба NetBird устарела"
+        "message": "Клиент NetBird устарел"
     },
     "daemon.outdated.description": {
-        "message": "Обновите службу NetBird, чтобы использовать это приложение."
+        "message": "Новый GUI несовместим с вашим более старым клиентом. Обновите клиент, чтобы использовать новое приложение."
+    },
+    "daemon.outdated.download": {
+        "message": "Скачать последнюю версию"
     },
     "error.jwt_clock_skew": {
         "message": "Не удалось войти: часы этого устройства рассинхронизированы с сервером. Синхронизируйте системные часы и повторите попытку."

client/ui/i18n/locales/zh-CN/common.json

@@ -1034,9 +1034,15 @@
     "welcome.title": {
         "message": "在托盘中查找 NetBird"
     },
+    "welcome.titleMac": {
+        "message": "在菜单栏中查找 NetBird"
+    },
     "welcome.description": {
         "message": "NetBird 驻留在您的托盘中。点击图标即可连接、切换配置文件或打开设置。"
     },
+    "welcome.descriptionMac": {
+        "message": "NetBird 驻留在您的菜单栏中。点击图标即可连接、切换配置文件或打开设置。"
+    },
     "welcome.continue": {
         "message": "继续"
     },
@@ -1293,10 +1299,13 @@
         "message": "文档"
     },
     "daemon.outdated.title": {
-        "message": "NetBird 服务版本过旧"
+        "message": "NetBird 客户端版本过旧"
     },
     "daemon.outdated.description": {
-        "message": "请更新 NetBird 服务以使用此应用。"
+        "message": "新版 GUI 与您较旧的客户端不兼容。请更新客户端以使用新应用。"
+    },
+    "daemon.outdated.download": {
+        "message": "下载最新版本"
     },
     "error.jwt_clock_skew": {
         "message": "登录失败：此设备的时钟与服务器不同步。请同步您的系统时钟后重试。"

client/ui/services/autostart.go

@@ -10,7 +10,7 @@ import (
 	"github.com/wailsapp/wails/v3/pkg/application"
 )
 
-// Autostart facade over Wails' AutostartManager. The OS login-item registration
+// Autostart facade over Wails' AutostartManager. The OS autostart entry registration
 // is the single source of truth; nothing is mirrored to preferences.
 type Autostart struct {
 	mgr *application.AutostartManager

client/ui/services/profileswitcher.go

@@ -12,13 +12,15 @@ import (
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
 )
 
-// ProfileSwitcher holds the reconnect policy shared by the tray and React
-// frontend so both flip profiles identically. The policy keys off prevStatus
-// from DaemonFeed.Get at SwitchActive entry:
+// ProfileSwitcher holds the switch policy shared by the tray and React
+// frontend so both flip profiles identically. SwitchActive (plain selection:
+// header dropdown, tray submenu) always connects after the switch;
+// SwitchActiveNoConnect (manage-profiles screen) never does, so the user can
+// still adjust the management URL before connecting. prevStatus from
+// DaemonFeed.Get at entry only decides the teardown:
 //
-//	Connected/Connecting → Switch + Down + Up; optimistic Connecting paint.
-//	NeedsLogin/LoginFailed/SessionExpired → Switch + Down; clear stale error for re-login.
-//	Idle → Switch only.
+//	Connected/Connecting/NeedsLogin/LoginFailed/SessionExpired → Down first.
+//	Idle → no Down.
 type ProfileSwitcher struct {
 	profiles   *Profiles
 	connection *Connection
@@ -29,29 +31,40 @@ func NewProfileSwitcher(profiles *Profiles, connection *Connection, feed *Daemon
 	return &ProfileSwitcher{profiles: profiles, connection: connection, feed: feed}
 }
 
-// SwitchActive switches to the named profile applying the reconnect policy.
+// SwitchActive switches to the named profile and always connects afterwards.
 func (s *ProfileSwitcher) SwitchActive(ctx context.Context, p ProfileRef) error {
+	return s.switchActive(ctx, p, true)
+}
+
+// SwitchActiveNoConnect switches to the named profile without connecting,
+// tearing down any existing connection first.
+func (s *ProfileSwitcher) SwitchActiveNoConnect(ctx context.Context, p ProfileRef) error {
+	return s.switchActive(ctx, p, false)
+}
+
+func (s *ProfileSwitcher) switchActive(ctx context.Context, p ProfileRef, connect bool) error {
 	prevStatus := ""
-	if st, err := s.feed.Get(ctx); err == nil {
-		prevStatus = st.Status
-	} else {
-		log.Warnf("profileswitcher: get status: %v", err)
+	if s.feed != nil {
+		if st, err := s.feed.Get(ctx); err == nil {
+			prevStatus = st.Status
+		} else {
+			log.Warnf("profileswitcher: get status: %v", err)
+		}
 	}
 
-	wasActive := strings.EqualFold(prevStatus, StatusConnected) ||
-		strings.EqualFold(prevStatus, StatusConnecting)
-	needsDown := wasActive ||
+	needsDown := strings.EqualFold(prevStatus, StatusConnected) ||
+		strings.EqualFold(prevStatus, StatusConnecting) ||
 		strings.EqualFold(prevStatus, StatusNeedsLogin) ||
 		strings.EqualFold(prevStatus, StatusLoginFailed) ||
 		strings.EqualFold(prevStatus, StatusSessionExpired)
 
-	log.Infof("profileswitcher: switch profile=%q prevStatus=%q wasActive=%v needsDown=%v",
-		p.ProfileName, prevStatus, wasActive, needsDown)
+	log.Infof("profileswitcher: switch profile=%q prevStatus=%q connect=%v needsDown=%v",
+		p.ProfileName, prevStatus, connect, needsDown)
 
-	// Optimistic Connecting paint only when wasActive: those prevStatuses emit
-	// stale Connected + transient Idle pushes during Down that must be
-	// suppressed until Up resumes the stream (see DaemonFeed suppression table).
-	if wasActive {
+	// Optimistic Connecting paint plus stale-push suppression during Down (see
+	// DaemonFeed suppression table); also arms the login-watch that pops
+	// browser-login when the new profile turns out to need SSO.
+	if connect && s.feed != nil {
 		s.feed.BeginProfileSwitch()
 	}
 
@@ -76,9 +89,9 @@ func (s *ProfileSwitcher) SwitchActive(ctx context.Context, p ProfileRef) error
 		}
 	}
 
-	if wasActive {
+	if connect {
 		if err := s.connection.Up(ctx, UpParams(p)); err != nil {
-			return fmt.Errorf("reconnect %q: %w", p.ProfileName, err)
+			return fmt.Errorf("connect %q: %w", p.ProfileName, err)
 		}
 	}
 

client/ui/services/windowmanager.go

@@ -185,37 +185,38 @@ func (s *WindowManager) OpenBrowserLogin(uri string) {
 			startURL = "/#/dialog/browser-login?uri=" + url.QueryEscape(uri)
 		}
 		s.hideOtherWindowsLocked("browser-login")
-		// Prefer the main window's screen (multi-monitor); falls back to OS-default centering.
-		var screen *application.Screen
-		if s.mainWindow != nil {
-			if sc, err := s.mainWindow.GetScreen(); err == nil {
-				screen = sc
-			}
-		}
 		opts := DialogWindowOptions("browser-login", s.title("window.title.signIn"), startURL, s.linuxIcon)
 		// Not always-on-top: it would obscure the browser tab the user logs in through.
 		opts.AlwaysOnTop = false
 		opts.InitialPosition = application.WindowCentered
-		opts.Screen = screen
+		// Open on the active (where users cursor is) display, like the session-expiration dialog.
+		opts.Screen = s.getScreenBasedOnCursorPosition()
 		s.browserLogin = s.app.Window.NewWithOptions(opts)
 		bl := s.browserLogin
-		// Red-X close means cancel: emit the event so startLogin() tears down the SSO wait.
 		bl.OnWindowEvent(events.Common.WindowClosing, func(_ *application.WindowEvent) {
-			s.app.Event.Emit(EventBrowserLoginCancel)
 			s.mu.Lock()
-			s.browserLogin = nil
-			s.restoreHiddenWindowsLocked()
+			// Only a live user red-X still has this registered; programmatic closers
+			// nil s.browserLogin first and clean up themselves. Guarding here stops a
+			// stale close event from wiping a replacement popup's state.
+			userClosed := s.browserLogin == bl
+			if userClosed {
+				s.browserLogin = nil
+				s.restoreHiddenWindowsLocked()
+			}
 			s.mu.Unlock()
+			if userClosed {
+				s.app.Event.Emit(EventBrowserLoginCancel)
+			}
 		})
-		s.centerWhenReady(s.browserLogin)
+		s.centerOnCursorScreen(s.browserLogin)
 		return
 	}
 	if uri != "" {
 		s.browserLogin.SetURL("/#/dialog/browser-login?uri=" + url.QueryEscape(uri))
 	}
+	s.centerOnCursorScreen(s.browserLogin)
 	s.browserLogin.Show()
 	s.browserLogin.Focus()
-	s.centerWhenReady(s.browserLogin)
 }
 
 // BrowserLoginWindow returns the live SSO popup, or nil. While non-nil it is the
@@ -238,6 +239,15 @@ func (s *WindowManager) CloseBrowserLogin() {
 	s.mu.Lock()
 	w := s.browserLogin
 	s.browserLogin = nil
+	// The WindowClosing hook no-ops on a programmatic close, so restore here —
+	// but only if a popup was actually open. The frontend calls this even when no
+	// popup was ever shown (e.g. resetDialog() after an early RequestExtend failure,
+	// or connection.ts's catch path), and hiddenForLogin is shared with
+	// OpenInstallProgress, so an unconditional restore could re-show windows a
+	// still-running install-progress is hiding.
+	if w != nil {
+		s.restoreHiddenWindowsLocked()
+	}
 	s.mu.Unlock()
 	if w != nil {
 		w.Close()
@@ -279,6 +289,35 @@ func (s *WindowManager) CloseSessionExpiration() {
 	}
 }
 
+// CloseRenewFlow tears down the SSO session-renewal UI in a single call: it
+// closes the browser-login popup and the session-expiration window together.
+func (s *WindowManager) CloseRenewFlow() {
+	s.mu.Lock()
+	bl := s.browserLogin
+	se := s.sessionExpiration
+	s.browserLogin = nil
+	s.sessionExpiration = nil
+	if se != nil {
+		kept := s.hiddenForLogin[:0]
+		for _, w := range s.hiddenForLogin {
+			if w != se {
+				kept = append(kept, w)
+			}
+		}
+		s.hiddenForLogin = kept
+	}
+	s.restoreHiddenWindowsLocked()
+	s.mu.Unlock()
+
+	// Close after unlock so the re-entrant handlers can take s.mu.
+	if bl != nil {
+		bl.Close()
+	}
+	if se != nil {
+		se.Close()
+	}
+}
+
 // OpenInstallProgress shows the install-progress window and hides the rest for the duration
 // (restored on close). It owns its own result polling since the daemon restarts mid-install.
 func (s *WindowManager) OpenInstallProgress(version string) {

client/ui/tray.go

@@ -30,6 +30,8 @@ const (
 
 	statusError = "Error"
 
+	quitDownTimeout = 5 * time.Second
+
 	urlGitHubRepo     = "https://github.com/netbirdio/netbird"
 	urlGitHubReleases = "https://github.com/netbirdio/netbird/releases/latest"
 	urlDocs           = "https://docs.netbird.io"
@@ -315,8 +317,7 @@ func (t *Tray) relayoutMenu() {
 		if sessionDeadline.IsZero() {
 			t.sessionExpiresItem.SetHidden(true)
 		} else {
-			remaining := t.formatSessionRemaining(time.Until(sessionDeadline))
-			t.sessionExpiresItem.SetLabel(t.loc.T("tray.session.expiresIn", "remaining", remaining))
+			t.sessionExpiresItem.SetLabel(t.sessionRowLabel(sessionDeadline))
 			t.sessionExpiresItem.SetHidden(false)
 		}
 	}
@@ -446,11 +447,28 @@ func (t *Tray) buildMenu() *application.Menu {
 	menu.AddSeparator()
 	menu.Add(t.loc.T("tray.menu.quit")).
 		SetAccelerator("CmdOrCtrl+Q").
-		OnClick(func(*application.Context) { t.app.Quit() })
+		OnClick(func(*application.Context) { t.handleQuit() })
 
 	return menu
 }
 
+func (t *Tray) handleQuit() {
+	t.profileMu.Lock()
+	if t.switchCancel != nil {
+		t.switchCancel()
+		t.switchCancel = nil
+	}
+	t.profileMu.Unlock()
+	t.svc.DaemonFeed.CancelProfileSwitch()
+
+	ctx, cancel := context.WithTimeout(context.Background(), quitDownTimeout)
+	defer cancel()
+	if err := t.svc.Connection.Down(ctx); err != nil {
+		log.Errorf("disconnect on quit: %v", err)
+	}
+	t.app.Quit()
+}
+
 // handleConnect receives the clicked item from the buildMenu closure —
 // t.upItem is menuMu-guarded and must not be read here.
 func (t *Tray) handleConnect(upItem *application.MenuItem) {

client/ui/tray_session.go

@@ -64,11 +64,42 @@ func (t *Tray) applySessionExpiry(deadline *time.Time, connected bool) bool {
 	return changed
 }
 
-// runSessionExpiryTicker recomputes the "Expires in …" row label every 30s. Runs until process exit.
+// runSessionExpiryTicker recomputes the "Expires in …" row label until process exit.
+// The interval scales with the remaining time: coarse when the deadline is far off,
+// down to 10s in the final two minutes so the label doesn't lag the ceiling-rounded
+// countdown near expiry. The cached deadline is re-read every iteration, so an extend
+// or reconnect that moves it is picked up on the next tick.
 func (t *Tray) runSessionExpiryTicker() {
-	tk := time.NewTicker(30 * time.Second)
-	for range tk.C {
+	tm := time.NewTimer(sessionRefreshInterval(t.sessionRemaining()))
+	defer tm.Stop()
+	for range tm.C {
 		t.refreshSessionExpiresLabel()
+		tm.Reset(sessionRefreshInterval(t.sessionRemaining()))
+	}
+}
+
+// sessionRemaining returns the time left on the cached SSO deadline, or 0 when unknown.
+func (t *Tray) sessionRemaining() time.Duration {
+	t.sessionMu.Lock()
+	deadline := t.sessionExpiresAt
+	t.sessionMu.Unlock()
+	if deadline.IsZero() {
+		return 0
+	}
+	return time.Until(deadline)
+}
+
+// sessionRefreshInterval picks how long to wait before the next label recompute.
+func sessionRefreshInterval(remaining time.Duration) time.Duration {
+	switch {
+	case remaining <= 0:
+		return 30 * time.Second
+	case remaining <= 2*time.Minute:
+		return 10 * time.Second
+	case remaining <= time.Hour:
+		return 30 * time.Second
+	default:
+		return time.Minute
 	}
 }
 
@@ -87,30 +118,39 @@ func (t *Tray) refreshSessionExpiresLabel() {
 	if deadline.IsZero() {
 		return
 	}
-	remaining := t.formatSessionRemaining(time.Until(deadline))
-	item.SetLabel(t.loc.T("tray.session.expiresIn", "remaining", remaining))
+	item.SetLabel(t.sessionRowLabel(deadline))
+}
+
+func (t *Tray) sessionRowLabel(deadline time.Time) string {
+	remaining := time.Until(deadline)
+	if remaining <= 0 {
+		return t.loc.T("tray.status.sessionExpired")
+	}
+	return t.loc.T("tray.session.expiresIn", "remaining", t.formatSessionRemaining(remaining))
 }
 
 // formatSessionRemaining renders d as a localised long-form string picking the largest non-zero unit.
+// Each unit is rounded up so the label never claims less time than actually remains, matching the
+// upper-bound sense of the sub-minute "less than a minute" fragment.
 // Singular/plural keys are split per language for proper translation.
 func (t *Tray) formatSessionRemaining(d time.Duration) string {
 	switch {
 	case d < time.Minute:
 		return t.loc.T("tray.session.unit.lessThanMinute")
-	case d < time.Hour:
-		m := int(d / time.Minute)
+	case d <= 59*time.Minute:
+		m := ceilDiv(d, time.Minute)
 		if m == 1 {
 			return t.loc.T("tray.session.unit.minute")
 		}
 		return t.loc.T("tray.session.unit.minutes", "count", strconv.Itoa(m))
-	case d < 24*time.Hour:
-		h := int((d + 30*time.Minute) / time.Hour)
+	case d <= 23*time.Hour:
+		h := ceilDiv(d, time.Hour)
 		if h == 1 {
 			return t.loc.T("tray.session.unit.hour")
 		}
 		return t.loc.T("tray.session.unit.hours", "count", strconv.Itoa(h))
 	default:
-		days := int((d + 12*time.Hour) / (24 * time.Hour))
+		days := ceilDiv(d, 24*time.Hour)
 		if days == 1 {
 			return t.loc.T("tray.session.unit.day")
 		}
@@ -118,6 +158,11 @@ func (t *Tray) formatSessionRemaining(d time.Duration) string {
 	}
 }
 
+// ceilDiv divides d by unit rounding up, assuming d > 0.
+func ceilDiv(d, unit time.Duration) int {
+	return int((d + unit - time.Nanosecond) / unit)
+}
+
 // registerSessionWarningCategory wires the OS notification category and response handler for the expiry warning.
 // Errors are swallowed since the worst case is a plain notification without buttons.
 func (t *Tray) registerSessionWarningCategory() {
@@ -252,11 +297,9 @@ func (t *Tray) openSessionExpiration() {
 }
 
 // openSessionExtendFlow opens the SessionExpiration window seeded with the cached deadline's remaining time,
-// for the "Expires in …" tray row. No-ops when the deadline is unknown or elapsed.
+// for the "Expires in …" tray row. Once the deadline has elapsed the row reads "Session expired" and the
+// click routes to the login flow instead. No-op when the deadline is unknown.
 func (t *Tray) openSessionExtendFlow() {
-	if t.svc.WindowManager == nil {
-		return
-	}
 	t.sessionMu.Lock()
 	deadline := t.sessionExpiresAt
 	t.sessionMu.Unlock()
@@ -265,6 +308,14 @@ func (t *Tray) openSessionExtendFlow() {
 	}
 	seconds := int(time.Until(deadline).Seconds())
 	if seconds <= 0 {
+		if t.window != nil {
+			t.window.SetURL("/#/login")
+			t.window.Show()
+			t.window.Focus()
+		}
+		return
+	}
+	if t.svc.WindowManager == nil {
 		return
 	}
 	t.svc.WindowManager.OpenSessionExpiration(seconds)

combined/cmd/admin.go

@@ -0,0 +1,151 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/dexidp/dex/storage"
+	log "github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+
+	"github.com/netbirdio/netbird/formatter/hook"
+	admincmd "github.com/netbirdio/netbird/management/cmd/admin"
+	tokencmd "github.com/netbirdio/netbird/management/cmd/token"
+	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
+	"github.com/netbirdio/netbird/management/server/activity"
+	activitystore "github.com/netbirdio/netbird/management/server/activity/store"
+	"github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
+	"github.com/netbirdio/netbird/util"
+)
+
+// newAdminCommands creates the admin command tree with combined-specific resource openers.
+func newAdminCommands() *cobra.Command {
+	return admincmd.NewCommands(admincmd.Openers{
+		Resources: withAdminResources,
+		Store:     withAdminStoreOnly,
+		IDP:       withAdminIDPOnly,
+	})
+}
+
+func newLegacyTokenCommand() *cobra.Command {
+	cmd := tokencmd.NewCommands(tokencmd.StoreOpener(withAdminStoreOnly))
+	cmd.Deprecated = "use 'admin token' instead"
+	return cmd
+}
+
+// withAdminResources loads the combined YAML config, initializes stores, and calls fn.
+func withAdminResources(cmd *cobra.Command, fn func(ctx context.Context, resources admincmd.Resources) error) error {
+	return withAdminConfig(cmd, func(ctx context.Context, cfg *CombinedConfig) error {
+		mgmtConfig, err := adminManagementConfig(cfg)
+		if err != nil {
+			return err
+		}
+
+		managementStore, err := openAdminStore(ctx, cfg)
+		if err != nil {
+			return err
+		}
+		defer admincmd.CloseStore(ctx, managementStore)
+
+		idpStorage, idpStorageFile, err := admincmd.OpenIDPStorage(mgmtConfig)
+		if err != nil {
+			return err
+		}
+		defer admincmd.CloseIDPStorage(idpStorage)
+
+		eventStore, esErr := openAdminEventStore(ctx, cfg, mgmtConfig)
+		if esErr != nil {
+			_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Warning: audit events will not be recorded: %v\n", esErr)
+		}
+		if eventStore != nil {
+			defer func() {
+				if err := eventStore.Close(ctx); err != nil {
+					log.Debugf("close activity event store: %v", err)
+				}
+			}()
+		}
+
+		return fn(ctx, admincmd.Resources{Store: managementStore, IDPStorage: idpStorage, IDPStorageFile: idpStorageFile, EventStore: eventStore})
+	})
+}
+
+// withAdminStoreOnly opens only the management store for admin subcommands that do not
+// need embedded IdP storage.
+func withAdminStoreOnly(cmd *cobra.Command, fn func(ctx context.Context, s store.Store) error) error {
+	return withAdminConfig(cmd, func(ctx context.Context, cfg *CombinedConfig) error {
+		managementStore, err := openAdminStore(ctx, cfg)
+		if err != nil {
+			return err
+		}
+		defer admincmd.CloseStore(ctx, managementStore)
+
+		return fn(ctx, managementStore)
+	})
+}
+
+func withAdminIDPOnly(cmd *cobra.Command, fn func(ctx context.Context, idpStorage storage.Storage, storageFile string) error) error {
+	return withAdminConfig(cmd, func(ctx context.Context, cfg *CombinedConfig) error {
+		mgmtConfig, err := adminManagementConfig(cfg)
+		if err != nil {
+			return err
+		}
+		idpStorage, idpStorageFile, err := admincmd.OpenIDPStorage(mgmtConfig)
+		if err != nil {
+			return err
+		}
+		defer admincmd.CloseIDPStorage(idpStorage)
+
+		return fn(ctx, idpStorage, idpStorageFile)
+	})
+}
+
+func withAdminConfig(cmd *cobra.Command, fn func(ctx context.Context, cfg *CombinedConfig) error) error {
+	if err := util.InitLog("error", "console"); err != nil {
+		return fmt.Errorf("init log: %w", err)
+	}
+
+	ctx := context.WithValue(cmd.Context(), hook.ExecutionContextKey, hook.SystemSource) //nolint:staticcheck
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		return fmt.Errorf("load config: %w", err)
+	}
+	cfg.ApplyAdminDefaults()
+	applyServerStoreEnv(cfg.Server.Store)
+
+	return fn(ctx, cfg)
+}
+
+func adminManagementConfig(cfg *CombinedConfig) (*nbconfig.Config, error) {
+	mgmtConfig, err := cfg.ToManagementConfig()
+	if err != nil {
+		return nil, fmt.Errorf("create management config: %w", err)
+	}
+	return mgmtConfig, nil
+}
+
+func openAdminStore(ctx context.Context, cfg *CombinedConfig) (store.Store, error) {
+	managementStore, err := store.NewStore(ctx, types.Engine(cfg.Management.Store.Engine), cfg.Management.DataDir, nil, true)
+	if err != nil {
+		return nil, fmt.Errorf("create store: %w", err)
+	}
+	return managementStore, nil
+}
+
+func openAdminEventStore(ctx context.Context, cfg *CombinedConfig, config *nbconfig.Config) (activity.Store, error) {
+	if config.DataStoreEncryptionKey == "" {
+		return nil, fmt.Errorf("data store encryption key is not configured")
+	}
+	if err := applyActivityStoreEnv(cfg.Server.ActivityStore); err != nil {
+		return nil, fmt.Errorf("configure activity event store: %w", err)
+	}
+	eventStore, err := activitystore.NewSqlStore(ctx, config.Datadir, config.DataStoreEncryptionKey)
+	if err != nil {
+		return nil, fmt.Errorf("open activity event store: %w", err)
+	}
+	if eventStore == nil {
+		return nil, fmt.Errorf("open activity event store: returned nil store")
+	}
+	return eventStore, nil
+}

combined/cmd/admin_config_test.go

@@ -0,0 +1,47 @@
+package cmd
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
+)
+
+func TestApplyAdminDefaultsCopiesServerStoreWithoutExposedAddress(t *testing.T) {
+	cfg := DefaultConfig()
+	cfg.Server.ExposedAddress = ""
+	cfg.Server.DataDir = "/srv/netbird"
+	cfg.Server.Store = StoreConfig{
+		Engine: "postgres",
+		DSN:    "postgres://user:pass@example.com/netbird",
+	}
+
+	cfg.ApplyAdminDefaults()
+
+	require.Equal(t, "/srv/netbird", cfg.Management.DataDir)
+	require.Equal(t, "postgres", cfg.Management.Store.Engine)
+	require.Equal(t, cfg.Server.Store.DSN, cfg.Management.Store.DSN)
+}
+
+func TestOpenAdminEventStoreMissingEncryptionKeyReturnsNilInterface(t *testing.T) {
+	eventStore, err := openAdminEventStore(context.Background(), &CombinedConfig{}, &nbconfig.Config{})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "encryption key")
+	require.Nil(t, eventStore)
+}
+
+func TestApplyServerStoreEnv(t *testing.T) {
+	t.Setenv("NB_STORE_ENGINE_POSTGRES_DSN", "")
+	t.Setenv("NB_STORE_ENGINE_MYSQL_DSN", "")
+	t.Setenv("NB_STORE_ENGINE_SQLITE_FILE", "")
+
+	applyServerStoreEnv(StoreConfig{Engine: "postgres", DSN: "postgres-dsn", File: "store.db"})
+	require.Equal(t, "postgres-dsn", os.Getenv("NB_STORE_ENGINE_POSTGRES_DSN"))
+	require.Equal(t, "store.db", os.Getenv("NB_STORE_ENGINE_SQLITE_FILE"))
+
+	applyServerStoreEnv(StoreConfig{Engine: "mysql", DSN: "mysql-dsn"})
+	require.Equal(t, "mysql-dsn", os.Getenv("NB_STORE_ENGINE_MYSQL_DSN"))
+}

combined/cmd/config.go

@@ -6,8 +6,7 @@ import (
 	"net"
 	"net/netip"
 	"os"
-	"path"
-	"path/filepath"
+	filePath "path/filepath"
 	"strings"
 	"time"
 
@@ -74,6 +73,9 @@ type ServerConfig struct {
 	ActivityStore           StoreConfig        `yaml:"activityStore"`
 	AuthStore               StoreConfig        `yaml:"authStore"`
 	ReverseProxy            ReverseProxyConfig `yaml:"reverseProxy"`
+
+	SupportedSyncMessageVersions           *int           `yaml:"supportedSyncMessageVersions,omitempty"`
+	PerAccountSupportedSyncMessageVersions map[string]int `yaml:"perAccountSupportedSyncMessageVersions,omitempty"`
 }
 
 // TLSConfig contains TLS/HTTPS settings
@@ -300,6 +302,19 @@ func (c *CombinedConfig) ApplySimplifiedDefaults() {
 	c.autoConfigureClientSettings(exposedProto, exposedHost, exposedHostPort, hasExternalStuns, hasExternalRelay, hasExternalSignal)
 }
 
+// ApplyAdminDefaults applies the management settings needed by admin commands even
+// when the full server config is invalid and ApplySimplifiedDefaults cannot run.
+func (c *CombinedConfig) ApplyAdminDefaults() {
+	if c.Management.DataDir == "" || c.Management.DataDir == "/var/lib/netbird/" {
+		c.Management.DataDir = c.Server.DataDir
+	}
+	if c.Management.Store.Engine == "" || c.Management.Store.Engine == "sqlite" {
+		if c.Server.Store.Engine != "" || c.Server.Store.File != "" || c.Server.Store.DSN != "" {
+			c.Management.Store = c.Server.Store
+		}
+	}
+}
+
 // applyRelayDefaults configures the relay service if no external relay is configured.
 func (c *CombinedConfig) applyRelayDefaults(exposedProto, exposedHostPort string, hasExternalRelay, hasExternalStuns bool) {
 	if hasExternalRelay {
@@ -577,11 +592,11 @@ func (c *CombinedConfig) buildEmbeddedIdPConfig(mgmt ManagementConfig) (*idp.Emb
 			return nil, fmt.Errorf("authStore.dsn is required when authStore.engine is postgres")
 		}
 	} else {
-		authStorageFile = path.Join(mgmt.DataDir, "idp.db")
+		authStorageFile = filePath.Join(mgmt.DataDir, "idp.db")
 		if c.Server.AuthStore.File != "" {
 			authStorageFile = c.Server.AuthStore.File
-			if !filepath.IsAbs(authStorageFile) {
-				authStorageFile = filepath.Join(mgmt.DataDir, authStorageFile)
+			if !filePath.IsAbs(authStorageFile) {
+				authStorageFile = filePath.Join(mgmt.DataDir, authStorageFile)
 			}
 		}
 	}
@@ -696,16 +711,18 @@ func (c *CombinedConfig) ToManagementConfig() (*nbconfig.Config, error) {
 	httpConfig.AuthCallbackURL = callbackURL + types.ProxyCallbackEndpointFull
 
 	return &nbconfig.Config{
-		Stuns:                  stuns,
-		Relay:                  relayConfig,
-		Signal:                 signalConfig,
-		Datadir:                mgmt.DataDir,
-		DataStoreEncryptionKey: mgmt.Store.EncryptionKey,
-		HttpConfig:             httpConfig,
-		StoreConfig:            storeConfig,
-		ReverseProxy:           reverseProxy,
-		DisableDefaultPolicy:   mgmt.DisableDefaultPolicy,
-		EmbeddedIdP:            embeddedIdP,
+		Stuns:                              stuns,
+		Relay:                              relayConfig,
+		Signal:                             signalConfig,
+		Datadir:                            mgmt.DataDir,
+		DataStoreEncryptionKey:             mgmt.Store.EncryptionKey,
+		HttpConfig:                         httpConfig,
+		StoreConfig:                        storeConfig,
+		ReverseProxy:                       reverseProxy,
+		DisableDefaultPolicy:               mgmt.DisableDefaultPolicy,
+		EmbeddedIdP:                        embeddedIdP,
+		HighestSupportedSyncMessageVersion: c.Server.SupportedSyncMessageVersions,
+		PerAccountHighestSupportedSyncMessageVersion: c.Server.PerAccountSupportedSyncMessageVersions,
 	}, nil
 }
 
@@ -729,7 +746,7 @@ func ApplyEmbeddedIdPConfig(ctx context.Context, cfg *nbconfig.Config, mgmtPort
 		cfg.EmbeddedIdP.Storage.Type = "sqlite3"
 	}
 	if cfg.EmbeddedIdP.Storage.Config.File == "" && cfg.Datadir != "" {
-		cfg.EmbeddedIdP.Storage.Config.File = path.Join(cfg.Datadir, "idp.db")
+		cfg.EmbeddedIdP.Storage.Config.File = filePath.Join(cfg.Datadir, "idp.db")
 	}
 
 	issuer := cfg.EmbeddedIdP.Issuer

combined/cmd/root.go

@@ -31,6 +31,7 @@ import (
 	relayServer "github.com/netbirdio/netbird/relay/server"
 	"github.com/netbirdio/netbird/relay/server/listener"
 	"github.com/netbirdio/netbird/relay/server/listener/ws"
+	syncgrpc "github.com/netbirdio/netbird/shared/management/grpc"
 	sharedMetrics "github.com/netbirdio/netbird/shared/metrics"
 	"github.com/netbirdio/netbird/shared/relay/auth"
 	"github.com/netbirdio/netbird/shared/signal/proto"
@@ -64,7 +65,8 @@ func init() {
 	rootCmd.PersistentFlags().StringVarP(&configPath, "config", "c", "", "path to YAML configuration file (required)")
 	_ = rootCmd.MarkPersistentFlagRequired("config")
 
-	rootCmd.AddCommand(newTokenCommands())
+	rootCmd.AddCommand(newAdminCommands())
+	rootCmd.AddCommand(newLegacyTokenCommand())
 }
 
 func RootCmd() *cobra.Command {
@@ -122,6 +124,37 @@ func execute(cmd *cobra.Command, _ []string) error {
 }
 
 // initializeConfig loads and validates the configuration, then initializes logging.
+func applyServerStoreEnv(storeConfig StoreConfig) {
+	if dsn := storeConfig.DSN; dsn != "" {
+		switch strings.ToLower(storeConfig.Engine) {
+		case "postgres":
+			os.Setenv("NB_STORE_ENGINE_POSTGRES_DSN", dsn)
+		case "mysql":
+			os.Setenv("NB_STORE_ENGINE_MYSQL_DSN", dsn)
+		}
+	}
+	if file := storeConfig.File; file != "" {
+		os.Setenv("NB_STORE_ENGINE_SQLITE_FILE", file)
+	}
+}
+
+func applyActivityStoreEnv(storeConfig StoreConfig) error {
+	if engine := storeConfig.Engine; engine != "" {
+		engineLower := strings.ToLower(engine)
+		if engineLower == "postgres" && storeConfig.DSN == "" {
+			return fmt.Errorf("activityStore.dsn is required when activityStore.engine is postgres")
+		}
+		os.Setenv("NB_ACTIVITY_EVENT_STORE_ENGINE", engineLower)
+		if dsn := storeConfig.DSN; dsn != "" {
+			os.Setenv("NB_ACTIVITY_EVENT_POSTGRES_DSN", dsn)
+		}
+	}
+	if file := storeConfig.File; file != "" {
+		os.Setenv("NB_ACTIVITY_EVENT_SQLITE_FILE", file)
+	}
+	return nil
+}
+
 func initializeConfig() error {
 	var err error
 	config, err = LoadConfig(configPath)
@@ -137,30 +170,10 @@ func initializeConfig() error {
 		return fmt.Errorf("failed to initialize log: %w", err)
 	}
 
-	if dsn := config.Server.Store.DSN; dsn != "" {
-		switch strings.ToLower(config.Server.Store.Engine) {
-		case "postgres":
-			os.Setenv("NB_STORE_ENGINE_POSTGRES_DSN", dsn)
-		case "mysql":
-			os.Setenv("NB_STORE_ENGINE_MYSQL_DSN", dsn)
-		}
-	}
-	if file := config.Server.Store.File; file != "" {
-		os.Setenv("NB_STORE_ENGINE_SQLITE_FILE", file)
-	}
+	applyServerStoreEnv(config.Server.Store)
 
-	if engine := config.Server.ActivityStore.Engine; engine != "" {
-		engineLower := strings.ToLower(engine)
-		if engineLower == "postgres" && config.Server.ActivityStore.DSN == "" {
-			return fmt.Errorf("activityStore.dsn is required when activityStore.engine is postgres")
-		}
-		os.Setenv("NB_ACTIVITY_EVENT_STORE_ENGINE", engineLower)
-		if dsn := config.Server.ActivityStore.DSN; dsn != "" {
-			os.Setenv("NB_ACTIVITY_EVENT_POSTGRES_DSN", dsn)
-		}
-	}
-	if file := config.Server.ActivityStore.File; file != "" {
-		os.Setenv("NB_ACTIVITY_EVENT_SQLITE_FILE", file)
+	if err := applyActivityStoreEnv(config.Server.ActivityStore); err != nil {
+		return err
 	}
 
 	log.Infof("Starting combined NetBird server")
@@ -226,7 +239,7 @@ func (s *serverInstances) createRelayServer(cfg *CombinedConfig, tlsSupport bool
 	}
 
 	hashedSecret := sha256.Sum256([]byte(cfg.Relay.AuthSecret))
-	authenticator := auth.NewTimedHMACValidator(hashedSecret[:], 24*time.Hour)
+	authenticator := auth.NewTimedHMACValidator(hashedSecret[:])
 
 	relayCfg := relayServer.Config{
 		Meter:          s.metricsServer.Meter,
@@ -505,6 +518,16 @@ func createManagementServer(cfg *CombinedConfig, mgmtConfig *nbconfig.Config) (m
 	}
 	mgmtPort, _ := strconv.Atoi(portStr)
 
+	if err := syncgrpc.ValidateSyncMessageVersion(mgmtConfig.HighestSupportedSyncMessageVersion); err != nil {
+		return nil, err
+	}
+
+	for accountId, version := range mgmtConfig.PerAccountHighestSupportedSyncMessageVersion {
+		if err := syncgrpc.ValidateSyncMessageVersion(&version); err != nil {
+			return nil, fmt.Errorf("unrecognized sync message version in perAccountSupportedSyncMessageVersions for account %s %w", accountId, err)
+		}
+	}
+
 	mgmtSrv := newServer(
 		&mgmtServer.Config{
 			NbConfig:                mgmtConfig,

combined/cmd/token.go

@@ -1,63 +0,0 @@
-package cmd
-
-import (
-	"context"
-	"fmt"
-	"os"
-	"strings"
-
-	log "github.com/sirupsen/logrus"
-	"github.com/spf13/cobra"
-
-	"github.com/netbirdio/netbird/formatter/hook"
-	tokencmd "github.com/netbirdio/netbird/management/cmd/token"
-	"github.com/netbirdio/netbird/management/server/store"
-	"github.com/netbirdio/netbird/management/server/types"
-	"github.com/netbirdio/netbird/util"
-)
-
-// newTokenCommands creates the token command tree with combined-specific store opener.
-func newTokenCommands() *cobra.Command {
-	return tokencmd.NewCommands(withTokenStore)
-}
-
-// withTokenStore loads the combined YAML config, initializes the store, and calls fn.
-func withTokenStore(cmd *cobra.Command, fn func(ctx context.Context, s store.Store) error) error {
-	if err := util.InitLog("error", "console"); err != nil {
-		return fmt.Errorf("init log: %w", err)
-	}
-
-	ctx := context.WithValue(cmd.Context(), hook.ExecutionContextKey, hook.SystemSource) //nolint:staticcheck
-
-	cfg, err := LoadConfig(configPath)
-	if err != nil {
-		return fmt.Errorf("load config: %w", err)
-	}
-
-	if dsn := cfg.Server.Store.DSN; dsn != "" {
-		switch strings.ToLower(cfg.Server.Store.Engine) {
-		case "postgres":
-			os.Setenv("NB_STORE_ENGINE_POSTGRES_DSN", dsn)
-		case "mysql":
-			os.Setenv("NB_STORE_ENGINE_MYSQL_DSN", dsn)
-		}
-	}
-	if file := cfg.Server.Store.File; file != "" {
-		os.Setenv("NB_STORE_ENGINE_SQLITE_FILE", file)
-	}
-
-	datadir := cfg.Management.DataDir
-	engine := types.Engine(cfg.Management.Store.Engine)
-
-	s, err := store.NewStore(ctx, engine, datadir, nil, true)
-	if err != nil {
-		return fmt.Errorf("create store: %w", err)
-	}
-	defer func() {
-		if err := s.Close(ctx); err != nil {
-			log.Debugf("close store: %v", err)
-		}
-	}()
-
-	return fn(ctx, s)
-}

dns/nameserver.go

@@ -53,6 +53,7 @@ type NameServerGroup struct {
 	ID string `gorm:"primaryKey"`
 	// AccountID is a reference to Account that this object belongs
 	AccountID string `gorm:"index"`
+	PublicID  string `json:"-"`
 	// Name group name
 	Name string
 	// Description group description

docs/io.netbird.client.plist

@@ -66,6 +66,9 @@
     <key>disableAutoConnect</key>
     <false/>
 
+    <key>disableAutostart</key>
+    <false/>
+
     <key>disableClientRoutes</key>
     <false/>
 

docs/netbird-macos.mobileconfig

@@ -103,6 +103,8 @@
                                 <!--
                                 <key>disableAutoConnect</key>
                                 <false/>
+                                <key>disableAutostart</key>
+                                <false/>
                                 <key>disableClientRoutes</key>
                                 <false/>
                                 <key>disableServerRoutes</key>

docs/netbird-macos.sh

@@ -58,6 +58,7 @@ preSharedKey="$NULL"                       # secret; redacted in log
 allowServerSSH='true'
 blockInbound="$NULL"
 disableAutoConnect="$NULL"
+disableAutostart="$NULL"
 disableClientRoutes="$NULL"
 disableServerRoutes="$NULL"
 disableMetricsCollection="$NULL"
@@ -155,6 +156,7 @@ main() {
   is_set "$allowServerSSH"            && emit_bool    allowServerSSH            "$allowServerSSH"
   is_set "$blockInbound"              && emit_bool    blockInbound              "$blockInbound"
   is_set "$disableAutoConnect"        && emit_bool    disableAutoConnect        "$disableAutoConnect"
+  is_set "$disableAutostart"          && emit_bool    disableAutostart          "$disableAutostart"
   is_set "$disableClientRoutes"       && emit_bool    disableClientRoutes       "$disableClientRoutes"
   is_set "$disableServerRoutes"       && emit_bool    disableServerRoutes       "$disableServerRoutes"
   is_set "$disableMetricsCollection"  && emit_bool    disableMetricsCollection  "$disableMetricsCollection"

docs/netbird.adml

@@ -24,6 +24,9 @@
       <string id="DisableAutoConnect_Name">Disable auto-connect</string>
       <string id="DisableAutoConnect_Help">When enabled, the NetBird tunnel does not auto-connect at daemon startup. Equivalent to --disable-auto-connect.</string>
 
+      <string id="DisableAutostart_Name">Disable autostart</string>
+      <string id="DisableAutostart_Help">When enabled, the NetBird GUI is prevented from registering itself as an OS autostart entry on fresh installs, and any existing OS autostart entry registration is removed on the next GUI launch (Windows Registry Run key, macOS Login Item, Linux .desktop). Once the admin lifts the policy, the setting stays off until the user re-enables it in Settings.</string>
+
       <string id="DisableClientRoutes_Name">Disable client routes</string>
       <string id="DisableClientRoutes_Help">When enabled, this client will not consume routes advertised by routing peers. Equivalent to --disable-client-routes.</string>
 

docs/netbird.admx

@@ -64,6 +64,18 @@
       <disabledValue><decimal value="0" /></disabledValue>
     </policy>
 
+    <policy name="DisableAutostart"
+            class="Machine"
+            displayName="$(string.DisableAutostart_Name)"
+            explainText="$(string.DisableAutostart_Help)"
+            key="Software\Policies\NetBird"
+            valueName="DisableAutostart">
+      <parentCategory ref="NetBird" />
+      <supportedOn ref="SUPPORTED_NetBird_All" />
+      <enabledValue><decimal value="1" /></enabledValue>
+      <disabledValue><decimal value="0" /></disabledValue>
+    </policy>
+
     <policy name="DisableClientRoutes"
             class="Machine"
             displayName="$(string.DisableClientRoutes_Name)"

e2e/agentnetwork/chat_test.go

@@ -91,7 +91,14 @@ func availableProviders() []providerCase {
 		if region == "" {
 			region = "us-east-1"
 		}
-		ps = append(ps, providerCase{name: "bedrock", catalogID: "bedrock_api", upstream: "https://bedrock-runtime." + region + ".amazonaws.com", apiKey: k, model: "us.anthropic.claude-haiku-4-5", kind: harness.WireBedrock})
+		// A valid Bedrock inference-profile id (region prefix + date + version),
+		// overridable per account. `global.` profiles can be invoked from any
+		// region; set AWS_BEDROCK_MODEL to match the enabled profile for the token.
+		model := os.Getenv("AWS_BEDROCK_MODEL")
+		if model == "" {
+			model = "global.anthropic.claude-haiku-4-5-20251001-v1:0"
+		}
+		ps = append(ps, providerCase{name: "bedrock", catalogID: "bedrock_api", upstream: "https://bedrock-runtime." + region + ".amazonaws.com", apiKey: k, model: model, kind: harness.WireBedrock})
 	}
 	return ps
 }
@@ -108,8 +115,16 @@ func providerRequest(pc providerCase) api.AgentNetworkProviderRequest {
 		Enabled:     ptr(true),
 	}
 	if pc.kind != harness.WireVertex {
+		// The router matches the normalized catalog id. Bedrock's request model
+		// travels as a region-prefixed inference-profile id in the URL path
+		// (us.anthropic...), which the router strips before matching, so register
+		// the normalized form here or routing fails as model_not_routable.
+		modelID := pc.model
+		if pc.kind == harness.WireBedrock {
+			modelID = catalogModel(pc)
+		}
 		req.Models = &[]api.AgentNetworkProviderModel{
-			{Id: pc.model, InputPer1k: 0.001, OutputPer1k: 0.002},
+			{Id: modelID, InputPer1k: 0.001, OutputPer1k: 0.002},
 		}
 	}
 	return req
@@ -201,11 +216,12 @@ func TestProvidersMatrix(t *testing.T) {
 	t.Cleanup(func() { _ = cl.Terminate(context.Background()) })
 
 	require.NoError(t, cl.WaitConnected(ctx, 90*time.Second), "client must connect to management")
+	// Probe first: the GET resolves the endpoint (DNS error fails) and its first packet wakes the lazy proxy peer, so WaitProxyPeer sees it connected; any HTTP status counts.
+	proxyIP, err := cl.ResolveProxyIP(ctx, settings.Endpoint)
+	require.NoError(t, err, "resolve agent-network endpoint to proxy IP")
 	if err := cl.WaitProxyPeer(ctx, 180*time.Second); err != nil {
 		t.Fatalf("client did not see the proxy peer: %v\n=== proxy logs ===\n%s", err, px.Logs(context.Background()))
 	}
-	proxyIP, err := cl.ResolveProxyIP(ctx, settings.Endpoint)
-	require.NoError(t, err, "resolve agent-network endpoint to proxy IP")
 
 	for _, pc := range matrix {
 		pc := pc

e2e/agentnetwork/guardrail_test.go

@@ -4,6 +4,7 @@ package agentnetwork
 
 import (
 	"context"
+	"regexp"
 	"strings"
 	"testing"
 	"time"
@@ -15,13 +16,29 @@ import (
 	"github.com/netbirdio/netbird/shared/management/http/api"
 )
 
+// bedrockRegionPrefixes and bedrockVersionSuffix mirror the proxy's Bedrock
+// model normalization (region/inference-profile prefix + version suffix) so the
+// provider is registered under the same catalog key the router matches against.
+var (
+	bedrockRegionPrefixes = []string{"us.", "eu.", "apac.", "global."}
+	bedrockVersionSuffix  = regexp.MustCompile(`-(\d{8}-)?v\d+(:\d+)?$`)
+)
+
 // catalogModel returns the normalized catalog id the proxy stamps for a
-// path-routed provider's configured model — the form the guardrail allowlist is
-// compared against (region prefix / @version stripped).
+// path-routed provider's configured model — the form the router and guardrail
+// allowlist compare against (Bedrock region prefix + version stripped, Vertex
+// @version stripped).
 func catalogModel(pc providerCase) string {
 	switch pc.kind {
 	case harness.WireBedrock:
-		return strings.TrimPrefix(pc.model, "us.")
+		m := pc.model
+		for _, p := range bedrockRegionPrefixes {
+			if strings.HasPrefix(m, p) {
+				m = m[len(p):]
+				break
+			}
+		}
+		return bedrockVersionSuffix.ReplaceAllString(m, "")
 	case harness.WireVertex:
 		return strings.SplitN(pc.model, "@", 2)[0]
 	default:
@@ -147,11 +164,12 @@ func TestModelAllowlistEnforced(t *testing.T) {
 	t.Cleanup(func() { _ = cl.Terminate(context.Background()) })
 
 	require.NoError(t, cl.WaitConnected(ctx, 90*time.Second), "client must connect to management")
+	// Probe first: the GET resolves the endpoint (DNS error fails) and its first packet wakes the lazy proxy peer, so WaitProxyPeer sees it connected; any HTTP status counts.
+	proxyIP, err := cl.ResolveProxyIP(ctx, settings.Endpoint)
+	require.NoError(t, err, "resolve agent-network endpoint to proxy IP")
 	if err := cl.WaitProxyPeer(ctx, 180*time.Second); err != nil {
 		t.Fatalf("client did not see the proxy peer: %v\n=== proxy logs ===\n%s", err, px.Logs(context.Background()))
 	}
-	proxyIP, err := cl.ResolveProxyIP(ctx, settings.Endpoint)
-	require.NoError(t, err, "resolve agent-network endpoint to proxy IP")
 
 	for _, pc := range providers {
 		pc := pc

e2e/agentnetwork/skiptls_test.go

@@ -104,11 +104,12 @@ func TestProviderSkipTLSVerification(t *testing.T) {
 	t.Cleanup(func() { _ = cl.Terminate(context.Background()) })
 
 	require.NoError(t, cl.WaitConnected(ctx, 90*time.Second), "client must connect to management")
+	// Probe first: the GET resolves the endpoint (DNS error fails) and its first packet wakes the lazy proxy peer, so WaitProxyPeer sees it connected; any HTTP status counts.
+	proxyIP, err := cl.ResolveProxyIP(ctx, settings.Endpoint)
+	require.NoError(t, err, "resolve endpoint to proxy IP")
 	if err := cl.WaitProxyPeer(ctx, 180*time.Second); err != nil {
 		t.Fatalf("client did not see the proxy peer: %v\n=== proxy logs ===\n%s", err, px.Logs(context.Background()))
 	}
-	proxyIP, err := cl.ResolveProxyIP(ctx, settings.Endpoint)
-	require.NoError(t, err, "resolve endpoint to proxy IP")
 
 	// Positive: skip=true reaches the self-signed upstream. Retry to absorb
 	// tunnel/DNS jitter on the first call; success also proves the path works.

e2e/agentnetwork/vllm_test.go

@@ -106,11 +106,12 @@ func TestVLLMProvider(t *testing.T) {
 	t.Cleanup(func() { _ = cl.Terminate(context.Background()) })
 
 	require.NoError(t, cl.WaitConnected(ctx, 90*time.Second), "client must connect to management")
+	// Probe first: the GET resolves the endpoint (DNS error fails) and its first packet wakes the lazy proxy peer, so WaitProxyPeer sees it connected; any HTTP status counts.
+	proxyIP, err := cl.ResolveProxyIP(ctx, settings.Endpoint)
+	require.NoError(t, err, "resolve endpoint to proxy IP")
 	if err := cl.WaitProxyPeer(ctx, 180*time.Second); err != nil {
 		t.Fatalf("client did not see the proxy peer: %v\n=== proxy logs ===\n%s", err, px.Logs(context.Background()))
 	}
-	proxyIP, err := cl.ResolveProxyIP(ctx, settings.Endpoint)
-	require.NoError(t, err, "resolve endpoint to proxy IP")
 
 	before, _ := srv.ListAccessLogs(ctx)
 	sessionID := "e2e-session-vllm"

e2e/harness/client.go

@@ -4,6 +4,7 @@ package harness
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"os/exec"
@@ -167,22 +168,54 @@ func (cl *Client) pollStatus(ctx context.Context, timeout time.Duration, want st
 	return fmt.Errorf("timed out waiting for %q; last status:\n%s", want, last)
 }
 
-// ResolveProxyIP resolves the agent-network endpoint to the proxy peer's
-// NetBird IP from inside the client (via magic DNS).
+const (
+	// curlExitCouldNotResolve is curl's exit code for a DNS resolution failure, distinct from connection-level failures.
+	curlExitCouldNotResolve = 6
+	// dnsProbeRetryWindow bounds DNS-failure retries: the synthesized zone lands a beat after management connects, so early NXDOMAIN is propagation; a zone still absent after this window is a real failure.
+	dnsProbeRetryWindow   = 30 * time.Second
+	dnsProbeRetryInterval = 2 * time.Second
+)
+
+// ResolveProxyIP GETs https://<endpoint>/ from the client's netns: any HTTP status proves DNS + tunnel and wakes the lazy proxy peer; only DNS failures retry, within dnsProbeRetryWindow. Returns the connected IP for --resolve pinning.
 func (cl *Client) ResolveProxyIP(ctx context.Context, endpoint string) (string, error) {
-	code, reader, err := cl.container.Exec(ctx, []string{"getent", "hosts", endpoint}, tcexec.Multiplexed())
-	if err != nil {
-		return "", err
+	args := []string{
+		"run", "--rm",
+		"--network", "container:" + cl.container.GetContainerID(),
+		curlImage,
+		"-ksS", "-o", "/dev/null",
+		"--connect-timeout", "30", "--max-time", "60",
+		"-w", "%{remote_ip}",
+		"https://" + endpoint + "/",
 	}
-	out, _ := io.ReadAll(reader)
-	if code != 0 {
-		return "", fmt.Errorf("getent hosts %s exited %d", endpoint, code)
+	deadline := time.Now().Add(dnsProbeRetryWindow)
+	for {
+		cmd := exec.CommandContext(ctx, "docker", args...)
+		var stdout, stderr strings.Builder
+		cmd.Stdout = &stdout
+		cmd.Stderr = &stderr
+		err := cmd.Run()
+		if err == nil {
+			ip := strings.TrimSpace(stdout.String())
+			if ip == "" {
+				return "", fmt.Errorf("got an HTTP response from %s but no remote IP", endpoint)
+			}
+			return ip, nil
+		}
+
+		var exitErr *exec.ExitError
+		if !errors.As(err, &exitErr) || exitErr.ExitCode() != curlExitCouldNotResolve {
+			return "", fmt.Errorf("no HTTP response from %s: %w (%s)", endpoint, err, strings.TrimSpace(stderr.String()))
+		}
+		dnsErr := fmt.Errorf("DNS resolution failed for %s: %s", endpoint, strings.TrimSpace(stderr.String()))
+		if time.Until(deadline) < dnsProbeRetryInterval {
+			return "", dnsErr
+		}
+		select {
+		case <-ctx.Done():
+			return "", fmt.Errorf("%w (%w)", dnsErr, ctx.Err())
+		case <-time.After(dnsProbeRetryInterval):
+		}
 	}
-	fields := strings.Fields(string(out))
-	if len(fields) == 0 {
-		return "", fmt.Errorf("no address for %s", endpoint)
-	}
-	return fields[0], nil
 }
 
 // Wire shapes for Chat.

go.mod

@@ -113,7 +113,7 @@ require (
 	github.com/ti-mo/conntrack v0.5.1
 	github.com/ti-mo/netfilter v0.5.2
 	github.com/vmihailenco/msgpack/v5 v5.4.1
-	github.com/wailsapp/wails/v3 v3.0.0-alpha2.111
+	github.com/wailsapp/wails/v3 v3.0.0-alpha2.117
 	github.com/yusufpapurcu/wmi v1.2.4
 	github.com/zcalusic/sysinfo v1.1.3
 	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.67.0
@@ -303,7 +303,6 @@ require (
 	github.com/tklauser/numcpus v0.10.0 // indirect
 	github.com/vishvananda/netns v0.0.5 // indirect
 	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
-	github.com/wailsapp/wails/webview2 v1.0.27 // indirect
 	github.com/wlynxg/anet v0.0.5 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	github.com/zeebo/blake3 v0.2.3 // indirect

go.sum

@@ -660,10 +660,8 @@ github.com/vmihailenco/msgpack/v5 v5.4.1 h1:cQriyiUvjTwOHg8QZaPihLWeRAAVoCpE00IU
 github.com/vmihailenco/msgpack/v5 v5.4.1/go.mod h1:GaZTsDaehaPpQVyxrf5mtQlH+pc21PIudVV/E3rRQok=
 github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g=
 github.com/vmihailenco/tagparser/v2 v2.0.0/go.mod h1:Wri+At7QHww0WTrCBeu4J6bNtoV6mEfg5OIWRZA9qds=
-github.com/wailsapp/wails/v3 v3.0.0-alpha2.111 h1:MKx1nOnhnDuEGrRBmtxLOJq1NERwailu2cI4BvzWhi4=
-github.com/wailsapp/wails/v3 v3.0.0-alpha2.111/go.mod h1:wrdvmyeCsB/K3YqJDoH8E3MwcN8NXAMnEFaDTW46w60=
-github.com/wailsapp/wails/webview2 v1.0.27 h1:wjgAi/I8BBZ7kUGU8um3XF3ILEfzr96Q2Q1G4GPjMns=
-github.com/wailsapp/wails/webview2 v1.0.27/go.mod h1:zdM4jcO1IaC61RiJL5F1BzgoqBHFIdacz8gPr5exr0o=
+github.com/wailsapp/wails/v3 v3.0.0-alpha2.117 h1:udyjqPG3AIgkod5QDR/WblCkpV8R86BFPSrsWxSyt5Y=
+github.com/wailsapp/wails/v3 v3.0.0-alpha2.117/go.mod h1:74WH2FScMsgucZvHHvv7eOefDXCm/CjuIxqhhZgPhKg=
 github.com/wlynxg/anet v0.0.5 h1:J3VJGi1gvo0JwZ/P1/Yc/8p63SoW98B5dHkYDmpgvvU=
 github.com/wlynxg/anet v0.0.5/go.mod h1:eay5PRQr7fIVAMbTbchTnO9gG65Hg/uYGdc7mguHxoA=
 github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=

idp/dex/config.go

@@ -308,7 +308,7 @@ func (s *Storage) OpenStorage(logger *slog.Logger) (storage.Storage, error) {
 		if file == "" {
 			return nil, fmt.Errorf("sqlite3 storage requires 'file' config")
 		}
-		return (&sql.SQLite3{File: file}).Open(logger)
+		return newSQLite3(file).Open(logger)
 	case "postgres":
 		dsn, _ := s.Config["dsn"].(string)
 		if dsn == "" {

idp/dex/provider.go

@@ -20,7 +20,6 @@ import (
 	"github.com/dexidp/dex/server"
 	"github.com/dexidp/dex/server/signer"
 	"github.com/dexidp/dex/storage"
-	"github.com/dexidp/dex/storage/sql"
 	"github.com/go-jose/go-jose/v4"
 	"github.com/google/uuid"
 	"github.com/prometheus/client_golang/prometheus"
@@ -41,7 +40,7 @@ type Config struct {
 	GRPCAddr string
 }
 
-const localConnectorID = "local"
+const LocalConnectorID = "local"
 
 // Provider wraps a Dex server
 type Provider struct {
@@ -79,7 +78,7 @@ func NewProvider(ctx context.Context, config *Config) (*Provider, error) {
 
 	// Initialize SQLite storage
 	dbPath := filepath.Join(config.DataDir, "oidc.db")
-	sqliteConfig := &sql.SQLite3{File: dbPath}
+	sqliteConfig := newSQLite3(dbPath)
 	stor, err := sqliteConfig.Open(logger)
 	if err != nil {
 		return nil, fmt.Errorf("failed to open storage: %w", err)
@@ -495,18 +494,60 @@ func (p *Provider) Storage() storage.Storage {
 	return p.storage
 }
 
+// SetClientsMFAChain updates the MFAChain field on OAuth2 clients in Dex storage.
+// Pass a non-empty slice (e.g. []string{"default-totp"}) to enable MFA, or nil to disable it.
+func SetClientsMFAChain(ctx context.Context, st storage.Storage, clientIDs []string, mfaChain []string) error {
+	previousChains := make(map[string][]string, len(clientIDs))
+	for _, clientID := range clientIDs {
+		client, err := st.GetClient(ctx, clientID)
+		if err != nil {
+			return fmt.Errorf("failed to get client %s before MFA chain update: %w", clientID, err)
+		}
+		previousChains[clientID] = cloneMFAChain(client.MFAChain)
+	}
+
+	updatedClientIDs := make([]string, 0, len(clientIDs))
+	for _, clientID := range clientIDs {
+		if err := st.UpdateClient(ctx, clientID, func(old storage.Client) (storage.Client, error) {
+			old.MFAChain = cloneMFAChain(mfaChain)
+			return old, nil
+		}); err != nil {
+			if rollbackErr := rollbackClientsMFAChain(ctx, st, updatedClientIDs, previousChains); rollbackErr != nil {
+				return fmt.Errorf("failed to update MFA chain on client %s: %w (also failed to roll back previous MFA chains: %v)", clientID, err, rollbackErr)
+			}
+			return fmt.Errorf("failed to update MFA chain on client %s: %w", clientID, err)
+		}
+		updatedClientIDs = append(updatedClientIDs, clientID)
+	}
+	return nil
+}
+
+func rollbackClientsMFAChain(ctx context.Context, st storage.Storage, clientIDs []string, previousChains map[string][]string) error {
+	var rollbackErrs []error
+	for i := len(clientIDs) - 1; i >= 0; i-- {
+		clientID := clientIDs[i]
+		previousChain := cloneMFAChain(previousChains[clientID])
+		if err := st.UpdateClient(ctx, clientID, func(old storage.Client) (storage.Client, error) {
+			old.MFAChain = previousChain
+			return old, nil
+		}); err != nil {
+			rollbackErrs = append(rollbackErrs, fmt.Errorf("client %s: %w", clientID, err))
+		}
+	}
+	return errors.Join(rollbackErrs...)
+}
+
+func cloneMFAChain(chain []string) []string {
+	if chain == nil {
+		return nil
+	}
+	return append([]string(nil), chain...)
+}
+
 // SetClientsMFAChain updates the MFAChain field on the dashboard and CLI OAuth2 clients.
 // Pass a non-empty slice (e.g. []string{"default-totp"}) to enable MFA, or nil to disable it.
 func (p *Provider) SetClientsMFAChain(ctx context.Context, clientIDs []string, mfaChain []string) error {
-	for _, clientID := range clientIDs {
-		if err := p.storage.UpdateClient(ctx, clientID, func(old storage.Client) (storage.Client, error) {
-			old.MFAChain = mfaChain
-			return old, nil
-		}); err != nil {
-			return fmt.Errorf("failed to update MFA chain on client %s: %w", clientID, err)
-		}
-	}
-	return nil
+	return SetClientsMFAChain(ctx, p.storage, clientIDs, mfaChain)
 }
 
 // Handler returns the Dex server as an http.Handler for embedding in another server.
@@ -546,7 +587,7 @@ func (p *Provider) CreateUser(ctx context.Context, email, username, password str
 
 	// Encode the user ID in Dex's format: base64(protobuf{user_id, connector_id})
 	// This matches the format Dex uses in JWT tokens
-	encodedID := EncodeDexUserID(userID, localConnectorID)
+	encodedID := EncodeDexUserID(userID, LocalConnectorID)
 	return encodedID, nil
 }
 
@@ -625,7 +666,7 @@ func DecodeDexUserID(encodedID string) (userID, connectorID string, err error) {
 // local password connector.
 func IsLocalUserID(encodedID string) bool {
 	_, connectorID, err := DecodeDexUserID(encodedID)
-	return err == nil && connectorID == localConnectorID
+	return err == nil && connectorID == LocalConnectorID
 }
 
 // GetUser returns a user by email

idp/dex/provider_test.go

@@ -3,6 +3,8 @@ package dex
 import (
 	"context"
 	"encoding/json"
+	"errors"
+	"io"
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
@@ -11,11 +13,44 @@ import (
 	"testing"
 
 	"github.com/dexidp/dex/storage"
+	"github.com/dexidp/dex/storage/memory"
 	sqllib "github.com/dexidp/dex/storage/sql"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
+type updateFailingStorage struct {
+	storage.Storage
+	failClientID string
+}
+
+func (s *updateFailingStorage) UpdateClient(ctx context.Context, id string, updater func(storage.Client) (storage.Client, error)) error {
+	if id == s.failClientID {
+		return errors.New("forced update failure")
+	}
+	return s.Storage.UpdateClient(ctx, id, updater)
+}
+
+func TestSetClientsMFAChainRollsBackUpdatedClients(t *testing.T) {
+	ctx := context.Background()
+	st := memory.New(slog.New(slog.NewTextHandler(io.Discard, nil)))
+
+	require.NoError(t, st.CreateClient(ctx, storage.Client{ID: "client-1", MFAChain: []string{"old-1"}}))
+	require.NoError(t, st.CreateClient(ctx, storage.Client{ID: "client-2", MFAChain: []string{"old-2"}}))
+
+	err := SetClientsMFAChain(ctx, &updateFailingStorage{Storage: st, failClientID: "client-2"}, []string{"client-1", "client-2"}, []string{"new"})
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "failed to update MFA chain on client client-2")
+
+	client1, err := st.GetClient(ctx, "client-1")
+	require.NoError(t, err)
+	require.Equal(t, []string{"old-1"}, client1.MFAChain)
+
+	client2, err := st.GetClient(ctx, "client-2")
+	require.NoError(t, err)
+	require.Equal(t, []string{"old-2"}, client2.MFAChain)
+}
+
 func TestUserCreationFlow(t *testing.T) {
 	ctx := context.Background()
 

idp/dex/sqlite_cgo.go

@@ -0,0 +1,15 @@
+//go:build cgo
+
+package dex
+
+import (
+	sql "github.com/dexidp/dex/storage/sql"
+)
+
+// newSQLite3 builds the dex SQLite3 config. CGO builds use the upstream
+// struct that takes a File path. Non-CGO builds get an empty stub whose
+// Open() returns the dex "SQLite not available" error — correct behaviour
+// for binaries that can't link sqlite3 (e.g. cross-compiled ARM targets).
+func newSQLite3(file string) *sql.SQLite3 {
+	return &sql.SQLite3{File: file}
+}

idp/dex/sqlite_nocgo.go

@@ -0,0 +1,15 @@
+//go:build !cgo
+
+package dex
+
+import (
+	sql "github.com/dexidp/dex/storage/sql"
+)
+
+// newSQLite3 for non-CGO builds. The dex SQLite3 stub has no fields and its
+// Open() returns an error documenting the missing CGO support — correct
+// behaviour for cross-compiled artefacts that never actually run the
+// embedded IdP. The `file` argument is ignored.
+func newSQLite3(_ string) *sql.SQLite3 {
+	return &sql.SQLite3{}
+}

infrastructure_files/getting-started.sh

@@ -556,7 +556,7 @@ start_services_and_show_instructions() {
       echo "Creating proxy access token..."
       # Use docker exec with bash to run the token command directly
       PROXY_TOKEN=$($DOCKER_COMPOSE_COMMAND exec -T netbird-server \
-        /go/bin/netbird-server token create --name "default-proxy" --config /etc/netbird/config.yaml 2>/dev/null | grep "^Token:" | awk '{print $2}')
+        /go/bin/netbird-server admin token create --name "default-proxy" --config /etc/netbird/config.yaml 2>/dev/null | grep "^Token:" | awk '{print $2}')
 
       if [[ -z "$PROXY_TOKEN" ]]; then
         echo "ERROR: Failed to create proxy token. Check netbird-server logs." > /dev/stderr

management/cmd/admin.go

@@ -0,0 +1,177 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"path"
+	"path/filepath"
+
+	"github.com/dexidp/dex/storage"
+	log "github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+
+	"github.com/netbirdio/netbird/formatter/hook"
+	admincmd "github.com/netbirdio/netbird/management/cmd/admin"
+	tokencmd "github.com/netbirdio/netbird/management/cmd/token"
+	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
+	"github.com/netbirdio/netbird/management/server/activity"
+	activitystore "github.com/netbirdio/netbird/management/server/activity/store"
+	"github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/util"
+)
+
+var adminDatadir string
+
+// newAdminCommands creates the admin command tree with management-specific resource openers.
+func newAdminCommands() *cobra.Command {
+	cmd := admincmd.NewCommands(admincmd.Openers{
+		Resources: withAdminResources,
+		Store:     withAdminStoreOnly,
+		IDP:       withAdminIDPOnly,
+	})
+	cmd.PersistentFlags().StringVar(&adminDatadir, "datadir", "", "Override the data directory from config (used for store.db and the default idp.db)")
+	return cmd
+}
+
+func newLegacyTokenCommand() *cobra.Command {
+	cmd := tokencmd.NewCommands(tokencmd.StoreOpener(withAdminStoreOnly))
+	cmd.Deprecated = "use 'admin token' instead"
+	cmd.PersistentFlags().StringVar(&nbconfig.MgmtConfigPath, "config", defaultMgmtConfig, "Netbird config file location")
+	return cmd
+}
+
+// withAdminResources initializes logging, loads config, opens the management store
+// and embedded IdP storage, and calls fn.
+func withAdminResources(cmd *cobra.Command, fn func(ctx context.Context, resources admincmd.Resources) error) error {
+	return withAdminConfig(cmd, true, func(ctx context.Context, config *nbconfig.Config, datadir string) error {
+		managementStore, err := openAdminStore(ctx, config, datadir)
+		if err != nil {
+			return err
+		}
+		defer admincmd.CloseStore(ctx, managementStore)
+
+		idpStorage, idpStorageFile, err := admincmd.OpenIDPStorage(config)
+		if err != nil {
+			return err
+		}
+		defer admincmd.CloseIDPStorage(idpStorage)
+
+		eventStore, esErr := openAdminEventStore(ctx, config, datadir)
+		if esErr != nil {
+			_, _ = fmt.Fprintf(cmd.ErrOrStderr(), "Warning: audit events will not be recorded: %v\n", esErr)
+		}
+		if eventStore != nil {
+			defer func() {
+				if err := eventStore.Close(ctx); err != nil {
+					log.Debugf("close activity event store: %v", err)
+				}
+			}()
+		}
+
+		return fn(ctx, admincmd.Resources{Store: managementStore, IDPStorage: idpStorage, IDPStorageFile: idpStorageFile, EventStore: eventStore})
+	})
+}
+
+// withAdminStoreOnly opens only the management store for admin subcommands that do not
+// need embedded IdP storage.
+func withAdminStoreOnly(cmd *cobra.Command, fn func(ctx context.Context, s store.Store) error) error {
+	return withAdminConfig(cmd, false, func(ctx context.Context, config *nbconfig.Config, datadir string) error {
+		managementStore, err := openAdminStore(ctx, config, datadir)
+		if err != nil {
+			return err
+		}
+		defer admincmd.CloseStore(ctx, managementStore)
+
+		return fn(ctx, managementStore)
+	})
+}
+
+func withAdminIDPOnly(cmd *cobra.Command, fn func(ctx context.Context, idpStorage storage.Storage, storageFile string) error) error {
+	return withAdminConfig(cmd, true, func(ctx context.Context, config *nbconfig.Config, _ string) error {
+		idpStorage, idpStorageFile, err := admincmd.OpenIDPStorage(config)
+		if err != nil {
+			return err
+		}
+		defer admincmd.CloseIDPStorage(idpStorage)
+
+		return fn(ctx, idpStorage, idpStorageFile)
+	})
+}
+
+func withAdminConfig(cmd *cobra.Command, applyIDPDefaults bool, fn func(ctx context.Context, config *nbconfig.Config, datadir string) error) error {
+	if err := util.InitLog("error", "console"); err != nil {
+		return fmt.Errorf("init log: %w", err)
+	}
+
+	ctx := context.WithValue(cmd.Context(), hook.ExecutionContextKey, hook.SystemSource) //nolint:staticcheck
+
+	config, datadir, err := loadAdminMgmtConfig(ctx, applyIDPDefaults)
+	if err != nil {
+		return fmt.Errorf("load config: %w", err)
+	}
+
+	return fn(ctx, config, datadir)
+}
+
+func loadAdminMgmtConfig(ctx context.Context, applyIDPDefaults bool) (*nbconfig.Config, string, error) {
+	config := &nbconfig.Config{}
+	if _, err := util.ReadJsonWithEnvSub(nbconfig.MgmtConfigPath, config); err != nil {
+		return nil, "", err
+	}
+
+	if applyIDPDefaults {
+		if err := ApplyEmbeddedIdPConfig(ctx, config); err != nil {
+			return nil, "", err
+		}
+	}
+
+	datadir := config.Datadir
+	applyAdminDatadirOverride(config, &datadir)
+	return config, datadir, nil
+}
+
+func applyAdminDatadirOverride(config *nbconfig.Config, datadir *string) {
+	if adminDatadir == "" {
+		return
+	}
+
+	oldDatadir := *datadir
+	*datadir = adminDatadir
+	if config.EmbeddedIdP != nil && config.EmbeddedIdP.Storage.Type == "sqlite3" && isDefaultIDPStorageFile(config.EmbeddedIdP.Storage.Config.File, oldDatadir) {
+		config.EmbeddedIdP.Storage.Config.File = filepath.Join(*datadir, "idp.db")
+	}
+}
+
+func isDefaultIDPStorageFile(file, datadir string) bool {
+	if file == "" {
+		return true
+	}
+	defaultFile := filepath.Join(datadir, "idp.db")
+	legacyDefaultFile := path.Join(datadir, "idp.db")
+	legacySlashDefaultFile := path.Join(filepath.ToSlash(datadir), "idp.db")
+	return filepath.Clean(file) == filepath.Clean(defaultFile) ||
+		file == legacyDefaultFile ||
+		filepath.ToSlash(file) == legacySlashDefaultFile
+}
+
+func openAdminStore(ctx context.Context, config *nbconfig.Config, datadir string) (store.Store, error) {
+	managementStore, err := store.NewStore(ctx, config.StoreConfig.Engine, datadir, nil, true)
+	if err != nil {
+		return nil, fmt.Errorf("create store: %w", err)
+	}
+	return managementStore, nil
+}
+
+func openAdminEventStore(ctx context.Context, config *nbconfig.Config, datadir string) (activity.Store, error) {
+	if config.DataStoreEncryptionKey == "" {
+		return nil, fmt.Errorf("data store encryption key is not configured")
+	}
+	eventStore, err := activitystore.NewSqlStore(ctx, datadir, config.DataStoreEncryptionKey)
+	if err != nil {
+		return nil, fmt.Errorf("open activity event store: %w", err)
+	}
+	if eventStore == nil {
+		return nil, fmt.Errorf("open activity event store: returned nil store")
+	}
+	return eventStore, nil
+}

management/cmd/admin/admin.go

@@ -0,0 +1,577 @@
+// Package admincmd provides reusable cobra commands for self-hosted administrator helpers.
+// Both the management and combined binaries use these commands, each providing
+// their own opener to handle config loading and storage initialization.
+package admincmd
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/dexidp/dex/storage"
+	log "github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+	"golang.org/x/crypto/bcrypt"
+
+	"github.com/netbirdio/netbird/formatter/hook"
+	nbdex "github.com/netbirdio/netbird/idp/dex"
+	"github.com/netbirdio/netbird/management/cmd/proxy"
+	"github.com/netbirdio/netbird/management/cmd/token"
+	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
+	"github.com/netbirdio/netbird/management/server"
+	"github.com/netbirdio/netbird/management/server/activity"
+	"github.com/netbirdio/netbird/management/server/idp"
+	"github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
+)
+
+// Resources contains the storages required by the admin commands.
+type Resources struct {
+	Store          store.Store
+	IDPStorage     storage.Storage
+	IDPStorageFile string
+	EventStore     activity.Store
+}
+
+// Opener initializes command resources from the command context and calls fn.
+type Opener func(cmd *cobra.Command, fn func(ctx context.Context, resources Resources) error) error
+
+// StoreOpener initializes only the management store from the command context and calls fn.
+type StoreOpener func(cmd *cobra.Command, fn func(ctx context.Context, s store.Store) error) error
+
+// IDPOpener initializes only the embedded IdP storage from the command context and calls fn.
+type IDPOpener func(cmd *cobra.Command, fn func(ctx context.Context, idpStorage storage.Storage, storageFile string) error) error
+
+// Openers contains the resource openers needed by the admin command tree.
+type Openers struct {
+	Resources Opener
+	Store     StoreOpener
+	IDP       IDPOpener
+}
+
+type userSelector struct {
+	email  string
+	userID string
+}
+
+func (s userSelector) normalized() userSelector {
+	return userSelector{
+		email:  strings.TrimSpace(s.email),
+		userID: strings.TrimSpace(s.userID),
+	}
+}
+
+func (s userSelector) validate() error {
+	s = s.normalized()
+	if (s.email == "") == (s.userID == "") {
+		return fmt.Errorf("provide exactly one of --email or --user-id")
+	}
+	return nil
+}
+
+// NewCommands creates the admin command tree with the given resource openers.
+func NewCommands(openers Openers) *cobra.Command {
+	adminCmd := &cobra.Command{
+		Use:   "admin",
+		Short: "Self-hosted administrator helpers",
+		Long:  "Administrative helpers for self-hosted deployments using the embedded identity provider.",
+	}
+
+	userCmd := &cobra.Command{
+		Use:   "user",
+		Short: "Manage local embedded IdP users",
+	}
+
+	var passwordSelector userSelector
+	var password string
+	var passwordFile string
+	passwordCmd := &cobra.Command{
+		Use:     "change-password (--email email | --user-id id) (--password password | --password-file path)",
+		Aliases: []string{"set-password"},
+		Short:   "Change a local user's password",
+		Args:    cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if err := passwordSelector.validate(); err != nil {
+				return err
+			}
+			newPassword, err := resolvePasswordInput(cmd, password, passwordFile)
+			if err != nil {
+				return err
+			}
+			return openers.IDP(cmd, func(ctx context.Context, idpStorage storage.Storage, storageFile string) error {
+				return runChangePassword(ctx, idpStorage, cmd.OutOrStdout(), passwordSelector, newPassword, storageFile)
+			})
+		},
+	}
+	addUserSelectorFlags(passwordCmd, &passwordSelector)
+	passwordCmd.Flags().StringVar(&password, "password", "", "New password for the user")
+	passwordCmd.Flags().StringVar(&passwordFile, "password-file", "", "Read new password from file ('-' for stdin)")
+
+	var resetSelector userSelector
+	resetMFACmd := &cobra.Command{
+		Use:   "reset-mfa (--email email | --user-id id)",
+		Short: "Reset a local user's MFA enrollment",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if err := resetSelector.validate(); err != nil {
+				return err
+			}
+			return openers.IDP(cmd, func(ctx context.Context, idpStorage storage.Storage, storageFile string) error {
+				return runResetMFA(ctx, idpStorage, cmd.OutOrStdout(), resetSelector, storageFile)
+			})
+		},
+	}
+	addUserSelectorFlags(resetMFACmd, &resetSelector)
+
+	userCmd.AddCommand(passwordCmd, resetMFACmd)
+
+	mfaCmd := &cobra.Command{
+		Use:   "mfa",
+		Short: "Manage local MFA for embedded IdP users",
+	}
+
+	enableCmd := &cobra.Command{
+		Use:   "enable",
+		Short: "Enable MFA for local embedded IdP users",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return openers.Resources(cmd, func(ctx context.Context, resources Resources) error {
+				return runSetMFAEnabled(ctx, resources, cmd.OutOrStdout(), true)
+			})
+		},
+	}
+
+	disableCmd := &cobra.Command{
+		Use:   "disable",
+		Short: "Disable MFA for local embedded IdP users",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return openers.Resources(cmd, func(ctx context.Context, resources Resources) error {
+				return runSetMFAEnabled(ctx, resources, cmd.OutOrStdout(), false)
+			})
+		},
+	}
+
+	statusCmd := &cobra.Command{
+		Use:   "status",
+		Short: "Show local MFA status",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return openers.Resources(cmd, func(ctx context.Context, resources Resources) error {
+				return runMFAStatus(ctx, resources, cmd.OutOrStdout())
+			})
+		},
+	}
+
+	mfaCmd.AddCommand(enableCmd, disableCmd, statusCmd)
+	adminCmd.AddCommand(userCmd, mfaCmd)
+	if openers.Store != nil {
+		adminCmd.AddCommand(tokencmd.NewCommands(tokencmd.StoreOpener(openers.Store)))
+		adminCmd.AddCommand(proxycmd.NewCommands(proxycmd.StoreOpener(openers.Store)))
+	}
+	return adminCmd
+}
+
+// OpenEmbeddedIDPStorage opens the Dex storage configured for the embedded IdP.
+func OpenEmbeddedIDPStorage(cfg *idp.EmbeddedIdPConfig) (storage.Storage, error) {
+	if cfg == nil || !cfg.Enabled {
+		return nil, fmt.Errorf("admin commands require the embedded IdP to be enabled")
+	}
+
+	yamlConfig, err := cfg.ToYAMLConfig()
+	if err != nil {
+		return nil, fmt.Errorf("build embedded IdP config: %w", err)
+	}
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	st, err := yamlConfig.Storage.OpenStorage(logger)
+	if err != nil {
+		return nil, fmt.Errorf("open embedded IdP storage: %w", err)
+	}
+	return st, nil
+}
+
+// CloseStore closes the management store and logs cleanup errors at debug level.
+func CloseStore(ctx context.Context, s store.Store) {
+	if s == nil {
+		return
+	}
+	if err := s.Close(ctx); err != nil {
+		log.Debugf("close store: %v", err)
+	}
+}
+
+// OpenIDPStorage opens embedded IdP storage and returns its sqlite file path when applicable.
+func OpenIDPStorage(config *nbconfig.Config) (storage.Storage, string, error) {
+	if config == nil {
+		return nil, "", fmt.Errorf("management config is required")
+	}
+	idpStorage, err := OpenEmbeddedIDPStorage(config.EmbeddedIdP)
+	if err != nil {
+		return nil, "", err
+	}
+	return idpStorage, embeddedIDPStorageFile(config), nil
+}
+
+func embeddedIDPStorageFile(config *nbconfig.Config) string {
+	if config.EmbeddedIdP == nil || config.EmbeddedIdP.Storage.Type != "sqlite3" {
+		return ""
+	}
+	return config.EmbeddedIdP.Storage.Config.File
+}
+
+// CloseIDPStorage closes embedded IdP storage and logs cleanup errors at debug level.
+func CloseIDPStorage(s storage.Storage) {
+	if s == nil {
+		return
+	}
+	if err := s.Close(); err != nil {
+		log.Debugf("close embedded IdP storage: %v", err)
+	}
+}
+
+func addUserSelectorFlags(cmd *cobra.Command, selector *userSelector) {
+	cmd.Flags().StringVar(&selector.email, "email", "", "User email")
+	cmd.Flags().StringVar(&selector.userID, "user-id", "", "User ID")
+}
+
+func resolvePasswordInput(cmd *cobra.Command, password, passwordFile string) (string, error) {
+	if password != "" && passwordFile != "" {
+		return "", fmt.Errorf("provide only one of --password or --password-file")
+	}
+	if passwordFile == "" {
+		return password, nil
+	}
+
+	var data []byte
+	var err error
+	if passwordFile == "-" {
+		data, err = io.ReadAll(cmd.InOrStdin())
+	} else {
+		data, err = os.ReadFile(passwordFile)
+	}
+	if err != nil {
+		return "", fmt.Errorf("read password: %w", err)
+	}
+	return strings.TrimRight(string(data), "\r\n"), nil
+}
+
+func runChangePassword(ctx context.Context, idpStorage storage.Storage, w io.Writer, selector userSelector, password string, idpStorageFile string) error {
+	if idpStorage == nil {
+		return fmt.Errorf("embedded IdP storage is required")
+	}
+	selector = selector.normalized()
+	if err := selector.validate(); err != nil {
+		return err
+	}
+	if password == "" {
+		return fmt.Errorf("password is required")
+	}
+	if err := server.ValidatePassword(password); err != nil {
+		return fmt.Errorf("invalid password: %w", err)
+	}
+
+	user, err := findLocalUser(ctx, idpStorage, selector, idpStorageFile)
+	if err != nil {
+		return err
+	}
+
+	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+	if err != nil {
+		return fmt.Errorf("hash password: %w", err)
+	}
+
+	if err := idpStorage.UpdatePassword(ctx, user.Email, func(old storage.Password) (storage.Password, error) {
+		old.Hash = hash
+		return old, nil
+	}); err != nil {
+		return fmt.Errorf("update password for %s: %w", user.Email, err)
+	}
+
+	if err := deleteLocalAuthSession(ctx, idpStorage, user.UserID); err != nil {
+		return err
+	}
+
+	_, _ = fmt.Fprintf(w, "Password updated for %s.\n", user.Email)
+	return nil
+}
+
+func runResetMFA(ctx context.Context, idpStorage storage.Storage, w io.Writer, selector userSelector, idpStorageFile string) error {
+	if idpStorage == nil {
+		return fmt.Errorf("embedded IdP storage is required")
+	}
+	selector = selector.normalized()
+	if err := selector.validate(); err != nil {
+		return err
+	}
+
+	user, err := findLocalUser(ctx, idpStorage, selector, idpStorageFile)
+	if err != nil {
+		return err
+	}
+
+	reset := false
+	err = idpStorage.UpdateUserIdentity(ctx, user.UserID, idp.LocalConnectorID, func(old storage.UserIdentity) (storage.UserIdentity, error) {
+		reset = reset || len(old.MFASecrets) > 0 || len(old.WebAuthnCredentials) > 0
+		old.MFASecrets = map[string]*storage.MFASecret{}
+		old.WebAuthnCredentials = map[string][]storage.WebAuthnCredential{}
+		return old, nil
+	})
+	if errors.Is(err, storage.ErrNotFound) {
+		if err := deleteLocalAuthSession(ctx, idpStorage, user.UserID); err != nil {
+			return err
+		}
+		_, _ = fmt.Fprintf(w, "No MFA enrollment found for %s.\n", user.Email)
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("reset MFA for %s: %w", user.Email, err)
+	}
+
+	if err := deleteLocalAuthSession(ctx, idpStorage, user.UserID); err != nil {
+		return err
+	}
+
+	if reset {
+		_, _ = fmt.Fprintf(w, "MFA reset for %s. The user will re-enroll at next login.\n", user.Email)
+	} else {
+		_, _ = fmt.Fprintf(w, "No MFA enrollment found for %s.\n", user.Email)
+	}
+	return nil
+}
+
+func runSetMFAEnabled(ctx context.Context, resources Resources, w io.Writer, enabled bool) error {
+	if resources.Store == nil {
+		return fmt.Errorf("management store is required")
+	}
+	if resources.IDPStorage == nil {
+		return fmt.Errorf("embedded IdP storage is required")
+	}
+
+	accountID, settings, err := getSingleAccountSettings(ctx, resources.Store)
+	if err != nil {
+		return err
+	}
+
+	oldEnabled := settings.LocalMfaEnabled
+	newSettings := settings.Copy()
+	newSettings.LocalMfaEnabled = enabled
+
+	if err := setIDPClientsMFA(ctx, resources.IDPStorage, enabled); err != nil {
+		return err
+	}
+
+	if err := resources.Store.SaveAccountSettings(ctx, accountID, newSettings); err != nil {
+		if rollbackErr := setIDPClientsMFA(ctx, resources.IDPStorage, oldEnabled); rollbackErr != nil {
+			return fmt.Errorf("save local MFA account setting: %w (also failed to roll back embedded IdP MFA state: %v)", err, rollbackErr)
+		}
+		return fmt.Errorf("save local MFA account setting: %w", err)
+	}
+
+	if err := storeMFAActivity(ctx, resources.EventStore, accountID, enabled); err != nil {
+		_, _ = fmt.Fprintf(w, "Warning: failed to record audit event: %v\n", err)
+	}
+
+	state := "disabled"
+	if enabled {
+		state = "enabled"
+	}
+	_, _ = fmt.Fprintf(w, "Local MFA %s.\n", state)
+	return nil
+}
+
+func runMFAStatus(ctx context.Context, resources Resources, w io.Writer) error {
+	if resources.Store == nil {
+		return fmt.Errorf("management store is required")
+	}
+	if resources.IDPStorage == nil {
+		return fmt.Errorf("embedded IdP storage is required")
+	}
+
+	_, settings, err := getSingleAccountSettings(ctx, resources.Store)
+	if err != nil {
+		return err
+	}
+	accountStatus := "disabled"
+	if settings.LocalMfaEnabled {
+		accountStatus = "enabled"
+	}
+
+	clientStatus, err := idpClientsMFAStatus(ctx, resources.IDPStorage)
+	if err != nil {
+		return err
+	}
+
+	_, _ = fmt.Fprintf(w, "Account setting: %s\n", accountStatus)
+	_, _ = fmt.Fprintf(w, "Embedded IdP clients: %s\n", clientStatus)
+	return nil
+}
+
+func getSingleAccountSettings(ctx context.Context, s store.Store) (string, *types.Settings, error) {
+	count, err := s.GetAccountsCounter(ctx)
+	if err != nil {
+		return "", nil, fmt.Errorf("count accounts: %w", err)
+	}
+	if count != 1 {
+		return "", nil, fmt.Errorf("expected exactly one account, got %d; local MFA is supported only in single-account embedded IdP deployments", count)
+	}
+
+	accountID, err := s.GetAnyAccountID(ctx)
+	if err != nil {
+		return "", nil, fmt.Errorf("get account ID: %w", err)
+	}
+
+	settings, err := s.GetAccountSettings(ctx, store.LockingStrengthNone, accountID)
+	if err != nil {
+		return "", nil, fmt.Errorf("get account settings: %w", err)
+	}
+	if settings == nil {
+		settings = &types.Settings{}
+	}
+	return accountID, settings, nil
+}
+
+func storeMFAActivity(ctx context.Context, eventStore activity.Store, accountID string, enabled bool) error {
+	if eventStore == nil {
+		return nil
+	}
+	event := activity.AccountLocalMfaDisabled
+	if enabled {
+		event = activity.AccountLocalMfaEnabled
+	}
+	_, err := eventStore.Save(ctx, &activity.Event{
+		Timestamp:   time.Now().UTC(),
+		Activity:    event,
+		InitiatorID: string(hook.SystemSource),
+		TargetID:    accountID,
+		AccountID:   accountID,
+	})
+	if err != nil {
+		return fmt.Errorf("save local MFA audit event: %w", err)
+	}
+	return nil
+}
+
+func findLocalUser(ctx context.Context, idpStorage storage.Storage, selector userSelector, idpStorageFile string) (storage.Password, error) {
+	selector = selector.normalized()
+	if err := selector.validate(); err != nil {
+		return storage.Password{}, err
+	}
+
+	if selector.email != "" {
+		user, err := idpStorage.GetPassword(ctx, selector.email)
+		if errors.Is(err, storage.ErrNotFound) {
+			if empty, listErr := localUsersEmpty(ctx, idpStorage); listErr != nil {
+				return storage.Password{}, listErr
+			} else if empty {
+				return storage.Password{}, noLocalUsersError(idpStorageFile)
+			}
+			return storage.Password{}, fmt.Errorf("local user with email %q not found", selector.email)
+		}
+		if err != nil {
+			return storage.Password{}, fmt.Errorf("get local user by email %q: %w", selector.email, err)
+		}
+		return user, nil
+	}
+
+	rawUserID := selector.userID
+	if decodedUserID, _, err := nbdex.DecodeDexUserID(selector.userID); err == nil && decodedUserID != "" {
+		rawUserID = decodedUserID
+	}
+
+	users, err := idpStorage.ListPasswords(ctx)
+	if err != nil {
+		return storage.Password{}, fmt.Errorf("list local users: %w", err)
+	}
+	for _, user := range users {
+		if user.UserID == rawUserID || user.UserID == selector.userID {
+			return user, nil
+		}
+	}
+
+	if len(users) == 0 {
+		return storage.Password{}, noLocalUsersError(idpStorageFile)
+	}
+
+	return storage.Password{}, fmt.Errorf("local user with ID %q not found", selector.userID)
+}
+
+func localUsersEmpty(ctx context.Context, idpStorage storage.Storage) (bool, error) {
+	users, err := idpStorage.ListPasswords(ctx)
+	if err != nil {
+		return false, fmt.Errorf("list local users: %w", err)
+	}
+	return len(users) == 0, nil
+}
+
+func noLocalUsersError(idpStorageFile string) error {
+	location := ""
+	if idpStorageFile != "" {
+		location = fmt.Sprintf(" (%s)", idpStorageFile)
+	}
+	return fmt.Errorf("no local users exist in the embedded IdP storage%s; the management server may never have started with this config, or --datadir points at the wrong location", location)
+}
+
+func deleteLocalAuthSession(ctx context.Context, idpStorage storage.Storage, userID string) error {
+	err := idpStorage.DeleteAuthSession(ctx, userID, idp.LocalConnectorID)
+	if err == nil || errors.Is(err, storage.ErrNotFound) {
+		return nil
+	}
+	return fmt.Errorf("delete local auth session for user %s: %w", userID, err)
+}
+
+func setIDPClientsMFA(ctx context.Context, idpStorage storage.Storage, enabled bool) error {
+	var mfaChain []string
+	if enabled {
+		mfaChain = []string{idp.DefaultTOTPAuthenticatorID}
+	}
+
+	clientIDs := []string{idp.StaticClientCLI, idp.StaticClientDashboard}
+	if err := nbdex.SetClientsMFAChain(ctx, idpStorage, clientIDs, mfaChain); err != nil {
+		if errors.Is(err, storage.ErrNotFound) {
+			return fmt.Errorf("embedded IdP client not found; start the management server once before toggling MFA: %w", err)
+		}
+		return fmt.Errorf("update MFA chain on embedded IdP clients: %w", err)
+	}
+	return nil
+}
+
+func idpClientsMFAStatus(ctx context.Context, idpStorage storage.Storage) (string, error) {
+	clientIDs := []string{idp.StaticClientCLI, idp.StaticClientDashboard}
+	enabledCount := 0
+	for _, clientID := range clientIDs {
+		client, err := idpStorage.GetClient(ctx, clientID)
+		if errors.Is(err, storage.ErrNotFound) {
+			return "unknown", fmt.Errorf("embedded IdP client %q not found", clientID)
+		}
+		if err != nil {
+			return "unknown", fmt.Errorf("get embedded IdP client %q: %w", clientID, err)
+		}
+		if hasAuthenticator(client.MFAChain, idp.DefaultTOTPAuthenticatorID) {
+			enabledCount++
+		}
+	}
+
+	switch enabledCount {
+	case 0:
+		return "disabled", nil
+	case len(clientIDs):
+		return "enabled", nil
+	default:
+		return "partially enabled", nil
+	}
+}
+
+func hasAuthenticator(chain []string, authenticatorID string) bool {
+	for _, id := range chain {
+		if id == authenticatorID {
+			return true
+		}
+	}
+	return false
+}

management/cmd/admin/admin_test.go

@@ -0,0 +1,250 @@
+package admincmd
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"log/slog"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/dexidp/dex/storage"
+	"github.com/dexidp/dex/storage/memory"
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/crypto/bcrypt"
+
+	nbdex "github.com/netbirdio/netbird/idp/dex"
+	"github.com/netbirdio/netbird/management/server/idp"
+	mgmtstore "github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
+)
+
+func newTestIDPStorage(t *testing.T) storage.Storage {
+	t.Helper()
+
+	st := memory.New(slog.New(slog.NewTextHandler(io.Discard, nil)))
+	hash, err := bcrypt.GenerateFromPassword([]byte("OldPass1!"), bcrypt.DefaultCost)
+	require.NoError(t, err)
+
+	require.NoError(t, st.CreatePassword(context.Background(), storage.Password{
+		Email:    "user@example.com",
+		Username: "User",
+		UserID:   "user-1",
+		Hash:     hash,
+	}))
+	require.NoError(t, st.CreateUserIdentity(context.Background(), storage.UserIdentity{
+		UserID:      "user-1",
+		ConnectorID: idp.LocalConnectorID,
+		MFASecrets: map[string]*storage.MFASecret{
+			idp.DefaultTOTPAuthenticatorID: {
+				AuthenticatorID: idp.DefaultTOTPAuthenticatorID,
+				Type:            "TOTP",
+				Secret:          "otpauth://totp/NetBird:user@example.com?secret=ABC",
+				Confirmed:       true,
+				CreatedAt:       time.Now(),
+			},
+		},
+		WebAuthnCredentials: map[string][]storage.WebAuthnCredential{
+			"webauthn": {{CredentialID: []byte("credential")}},
+		},
+	}))
+	require.NoError(t, st.CreateAuthSession(context.Background(), storage.AuthSession{
+		UserID:      "user-1",
+		ConnectorID: idp.LocalConnectorID,
+		Nonce:       "nonce",
+	}))
+	require.NoError(t, st.CreateClient(context.Background(), storage.Client{ID: idp.StaticClientCLI, Name: "CLI"}))
+	require.NoError(t, st.CreateClient(context.Background(), storage.Client{ID: idp.StaticClientDashboard, Name: "Dashboard"}))
+
+	return st
+}
+
+func TestRunChangePassword(t *testing.T) {
+	ctx := context.Background()
+	st := newTestIDPStorage(t)
+	var out bytes.Buffer
+
+	err := runChangePassword(ctx, st, &out, userSelector{email: "user@example.com"}, "NewPass1!", "")
+	require.NoError(t, err)
+	require.Contains(t, out.String(), "Password updated")
+
+	user, err := st.GetPassword(ctx, "user@example.com")
+	require.NoError(t, err)
+	require.NoError(t, bcrypt.CompareHashAndPassword(user.Hash, []byte("NewPass1!")))
+
+	_, err = st.GetAuthSession(ctx, "user-1", idp.LocalConnectorID)
+	require.ErrorIs(t, err, storage.ErrNotFound)
+}
+
+func TestRunChangePasswordValidatesPassword(t *testing.T) {
+	st := newTestIDPStorage(t)
+	err := runChangePassword(context.Background(), st, io.Discard, userSelector{email: "user@example.com"}, "short", "")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "invalid password")
+}
+
+func TestRunResetMFA(t *testing.T) {
+	ctx := context.Background()
+	st := newTestIDPStorage(t)
+	var out bytes.Buffer
+
+	encodedUserID := nbdex.EncodeDexUserID("user-1", idp.LocalConnectorID)
+	err := runResetMFA(ctx, st, &out, userSelector{userID: encodedUserID}, "")
+	require.NoError(t, err)
+	require.Contains(t, out.String(), "MFA reset")
+
+	identity, err := st.GetUserIdentity(ctx, "user-1", idp.LocalConnectorID)
+	require.NoError(t, err)
+	require.Empty(t, identity.MFASecrets)
+	require.Empty(t, identity.WebAuthnCredentials)
+
+	_, err = st.GetAuthSession(ctx, "user-1", idp.LocalConnectorID)
+	require.ErrorIs(t, err, storage.ErrNotFound)
+}
+
+func TestRunResetMFAWithoutEnrollment(t *testing.T) {
+	ctx := context.Background()
+	st := newTestIDPStorage(t)
+	require.NoError(t, st.UpdateUserIdentity(ctx, "user-1", idp.LocalConnectorID, func(old storage.UserIdentity) (storage.UserIdentity, error) {
+		old.MFASecrets = nil
+		old.WebAuthnCredentials = nil
+		return old, nil
+	}))
+
+	var out bytes.Buffer
+	err := runResetMFA(ctx, st, &out, userSelector{email: "user@example.com"}, "")
+	require.NoError(t, err)
+	require.Contains(t, out.String(), "No MFA enrollment found")
+}
+
+func TestSetIDPClientsMFA(t *testing.T) {
+	ctx := context.Background()
+	st := newTestIDPStorage(t)
+
+	require.NoError(t, setIDPClientsMFA(ctx, st, true))
+	status, err := idpClientsMFAStatus(ctx, st)
+	require.NoError(t, err)
+	require.Equal(t, "enabled", status)
+
+	require.NoError(t, setIDPClientsMFA(ctx, st, false))
+	status, err = idpClientsMFAStatus(ctx, st)
+	require.NoError(t, err)
+	require.Equal(t, "disabled", status)
+}
+
+func newTestManagementStore(t *testing.T, localMFAEnabled bool) mgmtstore.Store {
+	t.Helper()
+	ctx := context.Background()
+	st, err := mgmtstore.NewStore(ctx, types.SqliteStoreEngine, t.TempDir(), nil, false)
+	require.NoError(t, err)
+	t.Cleanup(func() { require.NoError(t, st.Close(ctx)) })
+	require.NoError(t, st.SaveAccount(ctx, &types.Account{
+		Id:       "account-1",
+		Settings: &types.Settings{LocalMfaEnabled: localMFAEnabled},
+	}))
+	return st
+}
+
+func TestRunSetMFAEnabledDoesNotSaveWhenIDPUpdateFails(t *testing.T) {
+	ctx := context.Background()
+	managementStore := newTestManagementStore(t, false)
+	idpStorage := memory.New(slog.New(slog.NewTextHandler(io.Discard, nil)))
+
+	err := runSetMFAEnabled(ctx, Resources{Store: managementStore, IDPStorage: idpStorage}, io.Discard, true)
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "embedded IdP client")
+
+	settings, err := managementStore.GetAccountSettings(ctx, mgmtstore.LockingStrengthNone, "account-1")
+	require.NoError(t, err)
+	require.False(t, settings.LocalMfaEnabled)
+}
+
+func TestRunSetMFAEnabledUpdatesSettingsAfterIDP(t *testing.T) {
+	ctx := context.Background()
+	managementStore := newTestManagementStore(t, false)
+	idpStorage := newTestIDPStorage(t)
+
+	err := runSetMFAEnabled(ctx, Resources{Store: managementStore, IDPStorage: idpStorage}, io.Discard, true)
+	require.NoError(t, err)
+
+	settings, err := managementStore.GetAccountSettings(ctx, mgmtstore.LockingStrengthNone, "account-1")
+	require.NoError(t, err)
+	require.True(t, settings.LocalMfaEnabled)
+	clientStatus, err := idpClientsMFAStatus(ctx, idpStorage)
+	require.NoError(t, err)
+	require.Equal(t, "enabled", clientStatus)
+}
+
+func TestRunSetMFAEnabledSucceedsWithNilEventStore(t *testing.T) {
+	ctx := context.Background()
+	managementStore := newTestManagementStore(t, false)
+	idpStorage := newTestIDPStorage(t)
+	var out bytes.Buffer
+	var err error
+
+	require.NotPanics(t, func() {
+		err = runSetMFAEnabled(ctx, Resources{Store: managementStore, IDPStorage: idpStorage, EventStore: nil}, &out, true)
+	})
+	require.NoError(t, err)
+	require.Contains(t, out.String(), "Local MFA enabled")
+
+	settings, err := managementStore.GetAccountSettings(ctx, mgmtstore.LockingStrengthNone, "account-1")
+	require.NoError(t, err)
+	require.True(t, settings.LocalMfaEnabled)
+}
+
+func TestUserSelectorValidate(t *testing.T) {
+	require.NoError(t, userSelector{email: " user@example.com "}.validate())
+	require.NoError(t, userSelector{userID: "user-1"}.validate())
+	require.Error(t, userSelector{}.validate())
+	require.Error(t, userSelector{email: "user@example.com", userID: "user-1"}.validate())
+}
+
+func TestFindLocalUserNotFound(t *testing.T) {
+	st := newTestIDPStorage(t)
+	_, err := findLocalUser(context.Background(), st, userSelector{email: "missing@example.com"}, "")
+	require.Error(t, err)
+	require.True(t, strings.Contains(err.Error(), "not found"))
+}
+
+func TestFindLocalUserZeroUsersIncludesStoragePath(t *testing.T) {
+	st := memory.New(slog.New(slog.NewTextHandler(io.Discard, nil)))
+	_, err := findLocalUser(context.Background(), st, userSelector{email: "missing@example.com"}, "/var/lib/netbird/idp.db")
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "no local users exist")
+	require.Contains(t, err.Error(), "/var/lib/netbird/idp.db")
+}
+
+func TestUserCommandValidatesSelectorBeforeOpeningStorage(t *testing.T) {
+	opened := false
+	cmd := NewCommands(Openers{
+		IDP: func(cmd *cobra.Command, fn func(ctx context.Context, idpStorage storage.Storage, storageFile string) error) error {
+			opened = true
+			return nil
+		},
+	})
+	cmd.SetArgs([]string{"user", "change-password", "--password", "NewPass1!"})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+
+	err := cmd.Execute()
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "provide exactly one")
+	require.False(t, opened)
+}
+
+func TestResolvePasswordInputFromStdin(t *testing.T) {
+	cmd := &cobra.Command{}
+	cmd.SetIn(strings.NewReader("NewPass1!\n"))
+
+	password, err := resolvePasswordInput(cmd, "", "-")
+	require.NoError(t, err)
+	require.Equal(t, "NewPass1!", password)
+}
+
+func TestResolvePasswordInputRejectsMultipleSources(t *testing.T) {
+	_, err := resolvePasswordInput(&cobra.Command{}, "NewPass1!", "-")
+	require.Error(t, err)
+}

management/cmd/admin_config_test.go

@@ -0,0 +1,80 @@
+package cmd
+
+import (
+	"context"
+	"path"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
+	"github.com/netbirdio/netbird/management/server/idp"
+)
+
+func TestApplyAdminDatadirOverrideRelocatesDefaultIDPStorage(t *testing.T) {
+	oldDatadir := filepath.Join(t.TempDir(), "old")
+	newDatadir := filepath.Join(t.TempDir(), "new")
+
+	for _, defaultFile := range []string{
+		"",
+		filepath.Join(oldDatadir, "idp.db"),
+		path.Join(oldDatadir, "idp.db"),
+	} {
+		t.Run(defaultFile, func(t *testing.T) {
+			cfg := &nbconfig.Config{
+				EmbeddedIdP: &idp.EmbeddedIdPConfig{
+					Enabled: true,
+					Storage: idp.EmbeddedStorageConfig{
+						Type: "sqlite3",
+						Config: idp.EmbeddedStorageTypeConfig{
+							File: defaultFile,
+						},
+					},
+				},
+			}
+			datadir := oldDatadir
+			oldAdminDatadir := adminDatadir
+			adminDatadir = newDatadir
+			t.Cleanup(func() { adminDatadir = oldAdminDatadir })
+
+			applyAdminDatadirOverride(cfg, &datadir)
+
+			require.Equal(t, newDatadir, datadir)
+			require.Equal(t, filepath.Join(newDatadir, "idp.db"), cfg.EmbeddedIdP.Storage.Config.File)
+		})
+	}
+}
+
+func TestOpenAdminEventStoreMissingEncryptionKeyReturnsNilInterface(t *testing.T) {
+	eventStore, err := openAdminEventStore(context.Background(), &nbconfig.Config{}, t.TempDir())
+	require.Error(t, err)
+	require.Contains(t, err.Error(), "encryption key")
+	require.Nil(t, eventStore)
+}
+
+func TestApplyAdminDatadirOverrideKeepsExplicitIDPStorage(t *testing.T) {
+	oldDatadir := filepath.Join(t.TempDir(), "old")
+	newDatadir := filepath.Join(t.TempDir(), "new")
+	explicitFile := filepath.Join(t.TempDir(), "custom-idp.db")
+	cfg := &nbconfig.Config{
+		EmbeddedIdP: &idp.EmbeddedIdPConfig{
+			Enabled: true,
+			Storage: idp.EmbeddedStorageConfig{
+				Type: "sqlite3",
+				Config: idp.EmbeddedStorageTypeConfig{
+					File: explicitFile,
+				},
+			},
+		},
+	}
+	datadir := oldDatadir
+	oldAdminDatadir := adminDatadir
+	adminDatadir = newDatadir
+	t.Cleanup(func() { adminDatadir = oldAdminDatadir })
+
+	applyAdminDatadirOverride(cfg, &datadir)
+
+	require.Equal(t, newDatadir, datadir)
+	require.Equal(t, explicitFile, cfg.EmbeddedIdP.Storage.Config.File)
+}

management/cmd/management.go

@@ -13,6 +13,7 @@ import (
 	"os"
 	"os/signal"
 	"path"
+	"path/filepath"
 	"strings"
 	"syscall"
 
@@ -25,6 +26,7 @@ import (
 	"github.com/netbirdio/netbird/management/internals/server"
 	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
 	nbdomain "github.com/netbirdio/netbird/shared/management/domain"
+	"github.com/netbirdio/netbird/shared/management/grpc"
 	"github.com/netbirdio/netbird/util"
 	"github.com/netbirdio/netbird/util/crypt"
 )
@@ -153,8 +155,20 @@ func LoadMgmtConfig(ctx context.Context, mgmtConfigPath string) (*nbconfig.Confi
 
 	ApplyCommandLineOverrides(loadedConfig)
 
+	err := grpc.ValidateSyncMessageVersion(loadedConfig.HighestSupportedSyncMessageVersion)
+	if err != nil {
+		return nil, err
+	}
+
+	for account, version := range loadedConfig.PerAccountHighestSupportedSyncMessageVersion {
+		err := grpc.ValidateSyncMessageVersion(&version)
+		if err != nil {
+			return nil, fmt.Errorf("unrecognized sync message version for account %s, %w", account, err)
+		}
+	}
+
 	// Apply EmbeddedIdP config to HttpConfig if embedded IdP is enabled
-	err := ApplyEmbeddedIdPConfig(ctx, loadedConfig)
+	err = ApplyEmbeddedIdPConfig(ctx, loadedConfig)
 	if err != nil {
 		return nil, err
 	}
@@ -209,7 +223,7 @@ func ApplyEmbeddedIdPConfig(ctx context.Context, cfg *nbconfig.Config) error {
 		cfg.EmbeddedIdP.Storage.Type = "sqlite3"
 	}
 	if cfg.EmbeddedIdP.Storage.Config.File == "" && cfg.Datadir != "" {
-		cfg.EmbeddedIdP.Storage.Config.File = path.Join(cfg.Datadir, "idp.db")
+		cfg.EmbeddedIdP.Storage.Config.File = filepath.Join(cfg.Datadir, "idp.db")
 	}
 
 	issuer := cfg.EmbeddedIdP.Issuer

management/cmd/management_test.go

@@ -4,6 +4,9 @@ import (
 	"context"
 	"os"
 	"testing"
+
+	"github.com/netbirdio/netbird/shared/management/grpc"
+	"github.com/stretchr/testify/assert"
 )
 
 const (
@@ -20,34 +23,49 @@ const (
 		"AuthAudience": "https://stageapp/",
 		"AuthIssuer": "https://something.eu.auth0.com/",
 		"OIDCConfigEndpoint": "https://something.eu.auth0.com/.well-known/openid-configuration"
+	  },
+	  "HighestSupportedSyncMessageVersion": 1,
+	  "PerAccountHighestSupportedSyncMessageVersion": {
+	    "1": 0,
+		"2": 1
 	  }
 	}`
 )
 
-func Test_loadMgmtConfig(t *testing.T) {
-	tmpFile, err := createConfig()
-	if err != nil {
-		t.Fatalf("failed to create config: %s", err)
-	}
+func Test_LoadMgmtConfig(t *testing.T) {
+	tmpFile, err := createConfig(exampleConfig)
+	assert.NoError(t, err)
 
 	cfg, err := LoadMgmtConfig(context.Background(), tmpFile)
-	if err != nil {
-		t.Fatalf("failed to load management config: %s", err)
-	}
-	if cfg.Relay == nil {
-		t.Fatalf("config is nil")
-	}
-	if len(cfg.Relay.Addresses) == 0 {
-		t.Fatalf("relay address is empty")
-	}
+	assert.NoError(t, err)
+	assert.NotEmpty(t, cfg.Relay)
+	assert.NotEmpty(t, cfg.Relay.Addresses)
+	assert.Equal(t, int(grpc.ComponentNetworkMap), *cfg.HighestSupportedSyncMessageVersion)
+	assert.Equal(t, map[string]int{"1": int(grpc.Base), "2": int(grpc.ComponentNetworkMap)}, cfg.PerAccountHighestSupportedSyncMessageVersion)
 }
 
-func createConfig() (string, error) {
+func Test_LoadMgmtConfig_Empty(t *testing.T) {
+	tmpFile, err := createConfig(`{
+		"HttpConfig": {
+			"AuthAudience": "https://stageapp/",
+			"AuthIssuer": "https://something.eu.auth0.com/",
+			"OIDCConfigEndpoint": "https://something.eu.auth0.com/.well-known/openid-configuration"
+		}
+	}`)
+	assert.NoError(t, err)
+
+	cfg, err := LoadMgmtConfig(context.Background(), tmpFile)
+	assert.NoError(t, err)
+	assert.Nil(t, cfg.HighestSupportedSyncMessageVersion)
+	assert.Nil(t, cfg.PerAccountHighestSupportedSyncMessageVersion)
+}
+
+func createConfig(config string) (string, error) {
 	tmpfile, err := os.CreateTemp("", "config.json")
 	if err != nil {
 		return "", err
 	}
-	_, err = tmpfile.Write([]byte(exampleConfig))
+	_, err = tmpfile.Write([]byte(config))
 	if err != nil {
 		return "", err
 	}

management/cmd/proxy/proxy.go

@@ -0,0 +1,141 @@
+// Package proxycmd provides reusable cobra commands for managing reverse proxy instances.
+// Both the management and combined binaries use these commands, each providing
+// their own StoreOpener to handle config loading and store initialization.
+package proxycmd
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"io"
+	"strings"
+	"text/tabwriter"
+
+	"github.com/spf13/cobra"
+
+	rpproxy "github.com/netbirdio/netbird/management/internals/modules/reverseproxy/proxy"
+	"github.com/netbirdio/netbird/management/server/store"
+)
+
+// StoreOpener initializes a store from the command context and calls fn.
+type StoreOpener func(cmd *cobra.Command, fn func(ctx context.Context, s store.Store) error) error
+
+const disconnectAllConfirmation = "disconnect all proxies"
+
+// NewCommands creates the proxy command tree with the given store opener.
+// Returns the parent "proxy" command with the disconnect-all subcommand.
+func NewCommands(opener StoreOpener) *cobra.Command {
+	var dryRun bool
+	var force bool
+
+	proxyCmd := &cobra.Command{
+		Use:   "proxy",
+		Short: "Manage reverse proxy instances",
+		Long:  "Commands for inspecting and repairing the reverse proxy instances registered with the management server.",
+	}
+
+	disconnectAllCmd := &cobra.Command{
+		Use:   "disconnect-all",
+		Short: "Force-mark all reverse proxy instances as disconnected",
+		Long: "Lists all reverse proxy instances and force-marks them as disconnected, regardless of their session state. " +
+			"Use this to repair stale connection state, e.g. after an unclean management server shutdown. " +
+			"By default, it asks for manual confirmation before changing state. Use --dry-run to preview without changing state, or --force to skip confirmation. " +
+			"Run during a maintenance window; affected live proxies may stay hidden until their next heartbeat or reconnect/re-register.",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return opener(cmd, func(ctx context.Context, s store.Store) error {
+				return runDisconnectAll(ctx, s, cmd.OutOrStdout(), cmd.InOrStdin(), dryRun, force)
+			})
+		},
+	}
+	disconnectAllCmd.Flags().BoolVar(&dryRun, "dry-run", false, "List reverse proxy instances that would be disconnected without changing state")
+	disconnectAllCmd.Flags().BoolVar(&force, "force", false, "Skip the confirmation prompt and apply the repair")
+
+	proxyCmd.AddCommand(disconnectAllCmd)
+	return proxyCmd
+}
+
+func runDisconnectAll(ctx context.Context, s store.Store, out io.Writer, in io.Reader, dryRun, force bool) error {
+	proxies, err := s.GetAllProxies(ctx)
+	if err != nil {
+		return fmt.Errorf("list proxies: %w", err)
+	}
+
+	if len(proxies) == 0 {
+		_, _ = fmt.Fprintln(out, "No reverse proxy instances found.")
+		return nil
+	}
+
+	toDisconnect := 0
+	w := tabwriter.NewWriter(out, 0, 0, 2, ' ', 0)
+	_, _ = fmt.Fprintln(w, "ID\tCLUSTER\tIP\tACCOUNT\tSTATUS\tLAST SEEN")
+	_, _ = fmt.Fprintln(w, "--\t-------\t--\t-------\t------\t---------")
+
+	for _, p := range proxies {
+		if p.Status != rpproxy.StatusDisconnected {
+			toDisconnect++
+		}
+
+		account := "-"
+		if p.AccountID != nil {
+			account = *p.AccountID
+		}
+
+		_, _ = fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\t%s\n",
+			p.ID,
+			p.ClusterAddress,
+			p.IPAddress,
+			account,
+			p.Status,
+			p.LastSeen.Format("2006-01-02 15:04:05"),
+		)
+	}
+	if err := w.Flush(); err != nil {
+		return fmt.Errorf("write proxy list: %w", err)
+	}
+
+	if dryRun {
+		_, _ = fmt.Fprintf(out, "\nDry run: would force-mark %d of %d reverse proxy instance(s) as disconnected.\n", toDisconnect, len(proxies))
+		return nil
+	}
+
+	if !force {
+		confirmed, err := confirmDisconnectAll(out, in)
+		if err != nil {
+			return err
+		}
+		if !confirmed {
+			_, _ = fmt.Fprintln(out, "Aborted. No reverse proxy instances were changed.")
+			return nil
+		}
+	}
+
+	disconnected, err := s.DisconnectAllProxies(ctx)
+	if err != nil {
+		return fmt.Errorf("disconnect proxies: %w", err)
+	}
+
+	_, _ = fmt.Fprintf(out, "\nForce-marked %d of %d reverse proxy instance(s) as disconnected.\n", disconnected, len(proxies))
+	return nil
+}
+
+func confirmDisconnectAll(out io.Writer, in io.Reader) (bool, error) {
+	if in == nil {
+		in = strings.NewReader("")
+	}
+
+	_, _ = fmt.Fprintln(out, "\nWARNING: This command changes stored reverse proxy state for every non-disconnected instance.")
+	_, _ = fmt.Fprintln(out, "Run it during a maintenance window; affected live proxies may stay hidden until "+
+		"their next heartbeat or reconnect/re-register.")
+	_, _ = fmt.Fprintf(out, "Type %q to continue: ", disconnectAllConfirmation)
+
+	scanner := bufio.NewScanner(in)
+	if !scanner.Scan() {
+		if err := scanner.Err(); err != nil {
+			return false, fmt.Errorf("read confirmation: %w", err)
+		}
+		return false, nil
+	}
+
+	return strings.EqualFold(strings.TrimSpace(scanner.Text()), disconnectAllConfirmation), nil
+}

management/cmd/proxy/proxy_test.go

@@ -0,0 +1,180 @@
+package proxycmd
+
+import (
+	"bytes"
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/require"
+
+	rpproxy "github.com/netbirdio/netbird/management/internals/modules/reverseproxy/proxy"
+	"github.com/netbirdio/netbird/management/server/store"
+)
+
+func newTestStore(t *testing.T) store.Store {
+	t.Helper()
+
+	s, cleanup, err := store.NewTestStoreFromSQL(context.Background(), "", t.TempDir())
+	require.NoError(t, err)
+	t.Cleanup(cleanup)
+
+	return s
+}
+
+func seedProxies(t *testing.T, ctx context.Context, s store.Store) {
+	t.Helper()
+
+	accountID := "account-1"
+	alreadyDisconnectedAt := time.Now().Add(-time.Hour)
+	seed := []*rpproxy.Proxy{
+		{
+			ID:             "proxy-1",
+			SessionID:      "session-1",
+			ClusterAddress: "cluster-a.example.com",
+			IPAddress:      "10.0.0.1",
+			LastSeen:       time.Now(),
+			Status:         rpproxy.StatusConnected,
+		},
+		{
+			ID:             "proxy-2",
+			SessionID:      "session-2",
+			ClusterAddress: "cluster-b.example.com",
+			IPAddress:      "10.0.0.2",
+			AccountID:      &accountID,
+			LastSeen:       time.Now(),
+			Status:         rpproxy.StatusConnected,
+		},
+		{
+			ID:             "proxy-3",
+			SessionID:      "session-3",
+			ClusterAddress: "cluster-a.example.com",
+			IPAddress:      "10.0.0.3",
+			LastSeen:       time.Now().Add(-time.Hour),
+			Status:         rpproxy.StatusDisconnected,
+			DisconnectedAt: &alreadyDisconnectedAt,
+		},
+	}
+	for _, p := range seed {
+		require.NoError(t, s.SaveProxy(ctx, p))
+	}
+}
+
+func proxiesByID(t *testing.T, ctx context.Context, s store.Store) map[string]*rpproxy.Proxy {
+	t.Helper()
+
+	proxies, err := s.GetAllProxies(ctx)
+	require.NoError(t, err)
+	require.Len(t, proxies, 3)
+
+	byID := make(map[string]*rpproxy.Proxy, len(proxies))
+	for _, p := range proxies {
+		byID[p.ID] = p
+	}
+	return byID
+}
+
+func TestRunDisconnectAllWithConfirmation(t *testing.T) {
+	ctx := context.Background()
+	s := newTestStore(t)
+	seedProxies(t, ctx, s)
+
+	var out bytes.Buffer
+	require.NoError(t, runDisconnectAll(ctx, s, &out, strings.NewReader(disconnectAllConfirmation+"\n"), false, false))
+
+	output := out.String()
+	require.Contains(t, output, "proxy-1")
+	require.Contains(t, output, "proxy-2")
+	require.Contains(t, output, "proxy-3")
+	require.Contains(t, output, "cluster-a.example.com")
+	require.Contains(t, output, "account-1")
+	require.Contains(t, output, "Type \"disconnect all proxies\" to continue")
+	require.Contains(t, output, "Force-marked 2 of 3 reverse proxy instance(s) as disconnected.")
+
+	for _, p := range proxiesByID(t, ctx, s) {
+		require.Equal(t, rpproxy.StatusDisconnected, p.Status, "proxy %s should be disconnected", p.ID)
+		require.NotNil(t, p.DisconnectedAt, "proxy %s should have a disconnected timestamp", p.ID)
+	}
+}
+
+func TestRunDisconnectAllForceSkipsConfirmation(t *testing.T) {
+	ctx := context.Background()
+	s := newTestStore(t)
+	seedProxies(t, ctx, s)
+
+	var out bytes.Buffer
+	require.NoError(t, runDisconnectAll(ctx, s, &out, strings.NewReader(""), false, true))
+
+	output := out.String()
+	require.NotContains(t, output, "Type \"disconnect all proxies\" to continue")
+	require.Contains(t, output, "Force-marked 2 of 3 reverse proxy instance(s) as disconnected.")
+}
+
+func TestRunDisconnectAllAbortLeavesProxiesUnchanged(t *testing.T) {
+	ctx := context.Background()
+	s := newTestStore(t)
+	seedProxies(t, ctx, s)
+
+	var out bytes.Buffer
+	require.NoError(t, runDisconnectAll(ctx, s, &out, strings.NewReader("no\n"), false, false))
+
+	output := out.String()
+	require.Contains(t, output, "Type \"disconnect all proxies\" to continue")
+	require.Contains(t, output, "Aborted. No reverse proxy instances were changed.")
+
+	byID := proxiesByID(t, ctx, s)
+	require.Equal(t, rpproxy.StatusConnected, byID["proxy-1"].Status)
+	require.Equal(t, rpproxy.StatusConnected, byID["proxy-2"].Status)
+	require.Equal(t, rpproxy.StatusDisconnected, byID["proxy-3"].Status)
+}
+
+func TestRunDisconnectAllDryRunLeavesProxiesUnchanged(t *testing.T) {
+	ctx := context.Background()
+	s := newTestStore(t)
+	seedProxies(t, ctx, s)
+
+	var out bytes.Buffer
+	require.NoError(t, runDisconnectAll(ctx, s, &out, strings.NewReader(""), true, false))
+
+	output := out.String()
+	require.Contains(t, output, "Dry run: would force-mark 2 of 3 reverse proxy instance(s) as disconnected.")
+	require.NotContains(t, output, "Type \"disconnect all proxies\" to continue")
+
+	byID := proxiesByID(t, ctx, s)
+	require.Equal(t, rpproxy.StatusConnected, byID["proxy-1"].Status)
+	require.Equal(t, rpproxy.StatusConnected, byID["proxy-2"].Status)
+	require.Equal(t, rpproxy.StatusDisconnected, byID["proxy-3"].Status)
+}
+
+func TestNewCommandsDisconnectAllDryRun(t *testing.T) {
+	ctx := context.Background()
+	s := newTestStore(t)
+	seedProxies(t, ctx, s)
+
+	opened := false
+	cmd := NewCommands(func(cmd *cobra.Command, fn func(ctx context.Context, s store.Store) error) error {
+		opened = true
+		return fn(cmd.Context(), s)
+	})
+
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetIn(strings.NewReader(""))
+	cmd.SetArgs([]string{"disconnect-all", "--dry-run"})
+
+	require.NoError(t, cmd.ExecuteContext(ctx))
+	require.True(t, opened)
+	require.Contains(t, out.String(), "Dry run: would force-mark 2 of 3 reverse proxy instance(s) as disconnected.")
+}
+
+func TestRunDisconnectAllEmpty(t *testing.T) {
+	ctx := context.Background()
+	s := newTestStore(t)
+
+	var out bytes.Buffer
+	require.NoError(t, runDisconnectAll(ctx, s, &out, strings.NewReader(""), false, false))
+	require.Contains(t, out.String(), "No reverse proxy instances found.")
+}

management/cmd/root.go

@@ -83,7 +83,8 @@ func init() {
 
 	rootCmd.AddCommand(migrationCmd)
 
-	tc := newTokenCommands()
-	tc.PersistentFlags().StringVar(&nbconfig.MgmtConfigPath, "config", defaultMgmtConfig, "Netbird config file location")
-	rootCmd.AddCommand(tc)
+	ac := newAdminCommands()
+	ac.PersistentFlags().StringVar(&nbconfig.MgmtConfigPath, "config", defaultMgmtConfig, "Netbird config file location")
+	rootCmd.AddCommand(ac)
+	rootCmd.AddCommand(newLegacyTokenCommand())
 }

management/cmd/token.go

@@ -1,55 +0,0 @@
-package cmd
-
-import (
-	"context"
-	"fmt"
-
-	log "github.com/sirupsen/logrus"
-	"github.com/spf13/cobra"
-
-	"github.com/netbirdio/netbird/formatter/hook"
-	tokencmd "github.com/netbirdio/netbird/management/cmd/token"
-	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
-	"github.com/netbirdio/netbird/management/server/store"
-	"github.com/netbirdio/netbird/util"
-)
-
-var tokenDatadir string
-
-// newTokenCommands creates the token command tree with management-specific store opener.
-func newTokenCommands() *cobra.Command {
-	cmd := tokencmd.NewCommands(withTokenStore)
-	cmd.PersistentFlags().StringVar(&tokenDatadir, "datadir", "", "Override the data directory from config (where store.db is located)")
-	return cmd
-}
-
-// withTokenStore initializes logging, loads config, opens the store, and calls fn.
-func withTokenStore(cmd *cobra.Command, fn func(ctx context.Context, s store.Store) error) error {
-	if err := util.InitLog("error", "console"); err != nil {
-		return fmt.Errorf("init log: %w", err)
-	}
-
-	ctx := context.WithValue(cmd.Context(), hook.ExecutionContextKey, hook.SystemSource) //nolint:staticcheck
-
-	config, err := LoadMgmtConfig(ctx, nbconfig.MgmtConfigPath)
-	if err != nil {
-		return fmt.Errorf("load config: %w", err)
-	}
-
-	datadir := config.Datadir
-	if tokenDatadir != "" {
-		datadir = tokenDatadir
-	}
-
-	s, err := store.NewStore(ctx, config.StoreConfig.Engine, datadir, nil, true)
-	if err != nil {
-		return fmt.Errorf("create store: %w", err)
-	}
-	defer func() {
-		if err := s.Close(ctx); err != nil {
-			log.Debugf("close store: %v", err)
-		}
-	}()
-
-	return fn(ctx, s)
-}

management/internals/controllers/network_map/controller/controller.go

@@ -29,6 +29,7 @@ import (
 	"github.com/netbirdio/netbird/management/server/store"
 	"github.com/netbirdio/netbird/management/server/telemetry"
 	"github.com/netbirdio/netbird/management/server/types"
+	sharedgrpc "github.com/netbirdio/netbird/shared/management/grpc"
 	"github.com/netbirdio/netbird/shared/management/proto"
 	"github.com/netbirdio/netbird/shared/management/status"
 	"github.com/netbirdio/netbird/util"
@@ -56,6 +57,10 @@ type Controller struct {
 	proxyController port_forwarding.Controller
 
 	integratedPeerValidator integrated_validator.IntegratedValidator
+
+	serverSupportedSyncMessageVersion sharedgrpc.SyncMessageVersion
+
+	perAccountServerSupportedSyncMessageVersions map[string]sharedgrpc.SyncMessageVersion
 }
 
 type bufferUpdate struct {
@@ -90,8 +95,10 @@ func NewController(ctx context.Context, store store.Store, metrics telemetry.App
 		dnsDomain:               dnsDomain,
 		config:                  config,
 
-		proxyController:       proxyController,
-		EphemeralPeersManager: ephemeralPeersManager,
+		proxyController:                              proxyController,
+		EphemeralPeersManager:                        ephemeralPeersManager,
+		serverSupportedSyncMessageVersion:            sharedgrpc.SyncMessageVersionFromConfig(config.HighestSupportedSyncMessageVersion),
+		perAccountServerSupportedSyncMessageVersions: sharedgrpc.SyncMessageVersionsFromMap(config.PerAccountHighestSupportedSyncMessageVersion),
 	}
 }
 
@@ -222,18 +229,53 @@ func (c *Controller) sendUpdateAccountPeers(ctx context.Context, accountID strin
 			c.metrics.CountCalcPostureChecksDuration(time.Since(start))
 			start = time.Now()
 
-			remotePeerNetworkMap := account.GetPeerNetworkMapFromComponents(ctx, p.ID, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, c.accountManagerMetrics, groupIDToUserIDs)
+			peerGroups := account.GetPeerGroups(p.ID)
+			proxyNetworkMap := proxyNetworkMaps[p.ID]
+			var update *proto.SyncResponse
+
+			commonSyncMessageVersion := sharedgrpc.HighestCommonSyncMessageVersion(
+				c.perAccountOrGlobalSupportedSyncMessageVersions(accountID),
+				sharedgrpc.SyncMessageVersionFromConfig(&peer.Meta.SyncMessageVersion))
+
+			log.WithContext(ctx).
+				WithFields(log.Fields{
+					"sync_message_version":        commonSyncMessageVersion,
+					"server_sync_message_version": c.perAccountOrGlobalSupportedSyncMessageVersions(peer.AccountID),
+					"peer_sync_message_version":   sharedgrpc.SyncMessageVersionFromConfig(&peer.Meta.SyncMessageVersion),
+				}).Debug("common highest sync message version")
+
+			if commonSyncMessageVersion == sharedgrpc.ComponentNetworkMap {
+				components := account.GetPeerNetworkMapComponents(
+					ctx, p.ID, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, groupIDToUserIDs)
+
+				c.metrics.CountCalcPeerNetworkMapDuration(time.Since(start))
+
+				start = time.Now()
+				// proxyNetworkMap rides the envelope as a ProxyPatch sidecar;
+				// the client merges it into Calculate()'s output the same
+				// way the legacy server did via NetworkMap.Merge.
+				update = grpc.ToComponentSyncResponse(ctx, nil, c.config.HttpConfig, c.config.DeviceAuthorizationFlow, p, nil, nil, components, proxyNetworkMap, dnsDomain, postureChecks, account.Settings, extraSetting, maps.Keys(peerGroups), dnsFwdPort)
+				c.metrics.CountToComponentSyncResponseDuration(time.Since(start))
+
+				c.peersUpdateManager.SendUpdate(ctx, p.ID, &network_map.UpdateMessage{
+					Update:      update,
+					MessageType: network_map.MessageTypeNetworkMap,
+				})
+
+				return
+			}
+
+			nmap := account.GetPeerNetworkMapFromComponents(
+				ctx, p.ID, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, c.accountManagerMetrics, groupIDToUserIDs)
 
 			c.metrics.CountCalcPeerNetworkMapDuration(time.Since(start))
 
-			proxyNetworkMap, ok := proxyNetworkMaps[p.ID]
-			if ok {
-				remotePeerNetworkMap.Merge(proxyNetworkMap)
+			if proxyNetworkMap != nil {
+				nmap.Merge(proxyNetworkMap)
 			}
 
-			peerGroups := account.GetPeerGroups(p.ID)
 			start = time.Now()
-			update := grpc.ToSyncResponse(ctx, nil, c.config.HttpConfig, c.config.DeviceAuthorizationFlow, p, nil, nil, remotePeerNetworkMap, dnsDomain, postureChecks, dnsCache, account.Settings, extraSetting, maps.Keys(peerGroups), dnsFwdPort)
+			update = grpc.ToSyncResponse(ctx, nil, c.config.HttpConfig, c.config.DeviceAuthorizationFlow, p, nil, nil, nmap, dnsDomain, postureChecks, dnsCache, account.Settings, extraSetting, maps.Keys(peerGroups), dnsFwdPort)
 			c.metrics.CountToSyncResponseDuration(time.Since(start))
 
 			c.peersUpdateManager.SendUpdate(ctx, p.ID, &network_map.UpdateMessage{
@@ -251,6 +293,13 @@ func (c *Controller) sendUpdateAccountPeers(ctx context.Context, accountID strin
 	return nil
 }
 
+func (c *Controller) perAccountOrGlobalSupportedSyncMessageVersions(accountId string) sharedgrpc.SyncMessageVersion {
+	if perAccount, ok := c.perAccountServerSupportedSyncMessageVersions[accountId]; ok {
+		return perAccount
+	}
+	return c.serverSupportedSyncMessageVersion
+}
+
 // UpdatePeers updates all peers that belong to an account.
 // Should be called when changes have to be synced to peers.
 func (c *Controller) UpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) error {
@@ -352,18 +401,53 @@ func (c *Controller) sendUpdateForAffectedPeers(ctx context.Context, accountID s
 			c.metrics.CountCalcPostureChecksDuration(time.Since(start))
 			start = time.Now()
 
-			remotePeerNetworkMap := account.GetPeerNetworkMapFromComponents(ctx, p.ID, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, c.accountManagerMetrics, groupIDToUserIDs)
+			peerGroups := account.GetPeerGroups(p.ID)
+			proxyNetworkMap := proxyNetworkMaps[p.ID]
+			var update *proto.SyncResponse
+
+			commonSyncMessageVersion := sharedgrpc.HighestCommonSyncMessageVersion(
+				c.perAccountOrGlobalSupportedSyncMessageVersions(accountID),
+				sharedgrpc.SyncMessageVersionFromConfig(&peer.Meta.SyncMessageVersion))
+
+			log.WithContext(ctx).
+				WithFields(log.Fields{
+					"sync_message_version":        commonSyncMessageVersion,
+					"server_sync_message_version": c.perAccountOrGlobalSupportedSyncMessageVersions(peer.AccountID),
+					"peer_sync_message_version":   sharedgrpc.SyncMessageVersionFromConfig(&peer.Meta.SyncMessageVersion),
+				}).Debug("common highest sync message version")
+
+			if commonSyncMessageVersion == sharedgrpc.ComponentNetworkMap {
+				components := account.GetPeerNetworkMapComponents(
+					ctx, p.ID, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, groupIDToUserIDs)
+
+				c.metrics.CountCalcPeerNetworkMapDuration(time.Since(start))
+
+				start = time.Now()
+				// proxyNetworkMap rides the envelope as a ProxyPatch sidecar;
+				// the client merges it into Calculate()'s output the same
+				// way the legacy server did via NetworkMap.Merge.
+				update = grpc.ToComponentSyncResponse(ctx, nil, c.config.HttpConfig, c.config.DeviceAuthorizationFlow, p, nil, nil, components, proxyNetworkMap, dnsDomain, postureChecks, account.Settings, extraSetting, maps.Keys(peerGroups), dnsFwdPort)
+				c.metrics.CountToComponentSyncResponseDuration(time.Since(start))
+
+				c.peersUpdateManager.SendUpdate(ctx, p.ID, &network_map.UpdateMessage{
+					Update:      update,
+					MessageType: network_map.MessageTypeNetworkMap,
+				})
+
+				return
+			}
+
+			nmap := account.GetPeerNetworkMapFromComponents(
+				ctx, p.ID, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, c.accountManagerMetrics, groupIDToUserIDs)
 
 			c.metrics.CountCalcPeerNetworkMapDuration(time.Since(start))
 
-			proxyNetworkMap, ok := proxyNetworkMaps[p.ID]
-			if ok {
-				remotePeerNetworkMap.Merge(proxyNetworkMap)
+			if proxyNetworkMap != nil {
+				nmap.Merge(proxyNetworkMap)
 			}
 
-			peerGroups := account.GetPeerGroups(p.ID)
 			start = time.Now()
-			update := grpc.ToSyncResponse(ctx, nil, c.config.HttpConfig, c.config.DeviceAuthorizationFlow, p, nil, nil, remotePeerNetworkMap, dnsDomain, postureChecks, dnsCache, account.Settings, extraSetting, maps.Keys(peerGroups), dnsFwdPort)
+			update = grpc.ToSyncResponse(ctx, nil, c.config.HttpConfig, c.config.DeviceAuthorizationFlow, p, nil, nil, nmap, dnsDomain, postureChecks, dnsCache, account.Settings, extraSetting, maps.Keys(peerGroups), dnsFwdPort)
 			c.metrics.CountToSyncResponseDuration(time.Since(start))
 
 			c.peersUpdateManager.SendUpdate(ctx, p.ID, &network_map.UpdateMessage{
@@ -451,13 +535,7 @@ func (c *Controller) UpdateAccountPeer(ctx context.Context, accountId string, pe
 		return err
 	}
 
-	remotePeerNetworkMap := account.GetPeerNetworkMapFromComponents(ctx, peerId, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, c.accountManagerMetrics, groupIDToUserIDs)
-
-	proxyNetworkMap, ok := proxyNetworkMaps[peer.ID]
-	if ok {
-		remotePeerNetworkMap.Merge(proxyNetworkMap)
-	}
-
+	proxyNetworkMap := proxyNetworkMaps[peer.ID]
 	extraSettings, err := c.settingsManager.GetExtraSettings(ctx, peer.AccountID)
 	if err != nil {
 		return fmt.Errorf("failed to get extra settings: %v", err)
@@ -466,7 +544,45 @@ func (c *Controller) UpdateAccountPeer(ctx context.Context, accountId string, pe
 	peerGroups := account.GetPeerGroups(peerId)
 	dnsFwdPort := computeForwarderPort(maps.Values(account.Peers), network_map.DnsForwarderPortMinVersion)
 
-	update := grpc.ToSyncResponse(ctx, nil, c.config.HttpConfig, c.config.DeviceAuthorizationFlow, peer, nil, nil, remotePeerNetworkMap, dnsDomain, postureChecks, dnsCache, account.Settings, extraSettings, maps.Keys(peerGroups), dnsFwdPort)
+	var update *proto.SyncResponse
+
+	commonSyncMessageVersion := sharedgrpc.HighestCommonSyncMessageVersion(
+		c.perAccountOrGlobalSupportedSyncMessageVersions(accountId),
+		sharedgrpc.SyncMessageVersionFromConfig(&peer.Meta.SyncMessageVersion))
+
+	log.WithContext(ctx).
+		WithFields(log.Fields{
+			"sync_message_version":        commonSyncMessageVersion,
+			"server_sync_message_version": c.perAccountOrGlobalSupportedSyncMessageVersions(peer.AccountID),
+			"peer_sync_message_version":   sharedgrpc.SyncMessageVersionFromConfig(&peer.Meta.SyncMessageVersion),
+		}).Debug("common highest sync message version")
+
+	if commonSyncMessageVersion == sharedgrpc.ComponentNetworkMap {
+		components := account.GetPeerNetworkMapComponents(
+			ctx, peer.ID, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, groupIDToUserIDs)
+
+		// proxyNetworkMap rides the envelope as a ProxyPatch sidecar;
+		// the client merges it into Calculate()'s output the same
+		// way the legacy server did via NetworkMap.Merge.
+		update = grpc.ToComponentSyncResponse(ctx, nil, c.config.HttpConfig, c.config.DeviceAuthorizationFlow, peer, nil, nil, components, proxyNetworkMap, dnsDomain, postureChecks, account.Settings, extraSettings, maps.Keys(peerGroups), dnsFwdPort)
+
+		c.peersUpdateManager.SendUpdate(ctx, peer.ID, &network_map.UpdateMessage{
+			Update:      update,
+			MessageType: network_map.MessageTypeNetworkMap,
+		})
+
+		return nil
+	}
+
+	nmap := account.GetPeerNetworkMapFromComponents(
+		ctx, peer.ID, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, c.accountManagerMetrics, groupIDToUserIDs)
+
+	if proxyNetworkMap != nil {
+		nmap.Merge(proxyNetworkMap)
+	}
+
+	update = grpc.ToSyncResponse(ctx, nil, c.config.HttpConfig, c.config.DeviceAuthorizationFlow, peer, nil, nil, nmap, dnsDomain, postureChecks, dnsCache, account.Settings, extraSettings, maps.Keys(peerGroups), dnsFwdPort)
+
 	c.peersUpdateManager.SendUpdate(ctx, peer.ID, &network_map.UpdateMessage{
 		Update:      update,
 		MessageType: network_map.MessageTypeNetworkMap,
@@ -513,6 +629,65 @@ func (c *Controller) BufferUpdateAccountPeers(ctx context.Context, accountID str
 	return nil
 }
 
+// GetValidatedPeerWithComponents is the components-format counterpart of
+// GetValidatedPeerWithMap. It returns raw NetworkMapComponents for capable
+// peers along with the proxy NetworkMap fragment (BYOP / port-forwarding
+// data the legacy server folds in via NetworkMap.Merge). The gRPC layer
+// encodes both into the wire envelope. Callers must gate on capability
+// themselves before dispatching here — this method does NOT branch on it.
+func (c *Controller) GetValidatedPeerWithComponents(ctx context.Context, isRequiresApproval bool, accountID string, peer *nbpeer.Peer) (*nbpeer.Peer, *types.NetworkMapComponents, *types.NetworkMap, []*posture.Checks, int64, error) {
+	if isRequiresApproval {
+		network, err := c.repo.GetAccountNetwork(ctx, accountID)
+		if err != nil {
+			return nil, nil, nil, nil, 0, err
+		}
+		return peer, &types.NetworkMapComponents{Network: network.Copy()}, nil, nil, 0, nil
+	}
+
+	account, err := c.requestBuffer.GetAccountWithBackpressure(ctx, accountID)
+	if err != nil {
+		return nil, nil, nil, nil, 0, err
+	}
+
+	c.injectAllProxyPolicies(ctx, account)
+
+	approvedPeersMap, err := c.integratedPeerValidator.GetValidatedPeers(ctx, account.Id, maps.Values(account.Groups), maps.Values(account.Peers), account.Settings.Extra)
+	if err != nil {
+		return nil, nil, nil, nil, 0, err
+	}
+
+	postureChecks, err := c.getPeerPostureChecks(account, peer.ID)
+	if err != nil {
+		return nil, nil, nil, nil, 0, err
+	}
+
+	accountZones, err := c.repo.GetAccountZones(ctx, account.Id)
+	if err != nil {
+		return nil, nil, nil, nil, 0, err
+	}
+
+	// Fetch the proxy network map fragment for this peer alongside the
+	// components — same single-account-load path the streaming controller
+	// uses, so initial-sync delivers BYOP/forwarding patches synchronously
+	// instead of waiting for the next streaming push.
+	proxyNetworkMaps, err := c.proxyController.GetProxyNetworkMaps(ctx, account.Id, peer.ID, account.Peers)
+	if err != nil {
+		log.WithContext(ctx).Errorf("failed to get proxy network maps: %v", err)
+		return nil, nil, nil, nil, 0, err
+	}
+
+	dnsDomain := c.GetDNSDomain(account.Settings)
+	peersCustomZone := account.GetPeersCustomZone(ctx, dnsDomain)
+
+	resourcePolicies := account.GetResourcePoliciesMap()
+	routers := account.GetResourceRoutersMap()
+	groupIDToUserIDs := account.GetActiveGroupUsers()
+	components := account.GetPeerNetworkMapComponents(ctx, peer.ID, peersCustomZone, accountZones, approvedPeersMap, resourcePolicies, routers, groupIDToUserIDs)
+	dnsFwdPort := computeForwarderPort(maps.Values(account.Peers), network_map.DnsForwarderPortMinVersion)
+
+	return peer, components, proxyNetworkMaps[peer.ID], postureChecks, dnsFwdPort, nil
+}
+
 // BufferUpdateAffectedPeers accumulates peer IDs and flushes them after the buffer interval.
 func (c *Controller) BufferUpdateAffectedPeers(ctx context.Context, accountID string, peerIDs []string, reason types.UpdateReason) error {
 	if len(peerIDs) == 0 {

management/internals/controllers/network_map/interface.go

@@ -24,6 +24,7 @@ type Controller interface {
 	UpdateAccountPeer(ctx context.Context, accountId string, peerId string) error
 	BufferUpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) error
 	GetValidatedPeerWithMap(ctx context.Context, isRequiresApproval bool, accountID string, peerID string) (*types.NetworkMap, []*posture.Checks, int64, error)
+	GetValidatedPeerWithComponents(ctx context.Context, isRequiresApproval bool, accountID string, p *nbpeer.Peer) (*nbpeer.Peer, *types.NetworkMapComponents, *types.NetworkMap, []*posture.Checks, int64, error)
 	GetDNSDomain(settings *types.Settings) string
 	StartWarmup(context.Context)
 	GetNetworkMap(ctx context.Context, peerID string) (*types.NetworkMap, error)

management/internals/controllers/network_map/interface_mock.go

@@ -1,9 +1,9 @@
 // Code generated by MockGen. DO NOT EDIT.
-// Source: management/internals/controllers/network_map/interface.go
+// Source: ./interface.go
 //
 // Generated by this command:
 //
-//	mockgen -package network_map -destination=management/internals/controllers/network_map/interface_mock.go -source=management/internals/controllers/network_map/interface.go -build_flags=-mod=mod
+//	mockgen -package network_map -destination=interface_mock.go -source=./interface.go -build_flags=-mod=mod
 //
 
 // Package network_map is a generated GoMock package.
@@ -126,8 +126,27 @@ func (mr *MockControllerMockRecorder) GetNetworkMap(ctx, peerID any) *gomock.Cal
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetNetworkMap", reflect.TypeOf((*MockController)(nil).GetNetworkMap), ctx, peerID)
 }
 
+// GetValidatedPeerWithComponents mocks base method.
+func (m *MockController) GetValidatedPeerWithComponents(ctx context.Context, isRequiresApproval bool, accountID string, p *peer.Peer) (*peer.Peer, *types.NetworkMapComponents, *types.NetworkMap, []*posture.Checks, int64, error) {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "GetValidatedPeerWithComponents", ctx, isRequiresApproval, accountID, p)
+	ret0, _ := ret[0].(*peer.Peer)
+	ret1, _ := ret[1].(*types.NetworkMapComponents)
+	ret2, _ := ret[2].(*types.NetworkMap)
+	ret3, _ := ret[3].([]*posture.Checks)
+	ret4, _ := ret[4].(int64)
+	ret5, _ := ret[5].(error)
+	return ret0, ret1, ret2, ret3, ret4, ret5
+}
+
+// GetValidatedPeerWithComponents indicates an expected call of GetValidatedPeerWithComponents.
+func (mr *MockControllerMockRecorder) GetValidatedPeerWithComponents(ctx, isRequiresApproval, accountID, p any) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "GetValidatedPeerWithComponents", reflect.TypeOf((*MockController)(nil).GetValidatedPeerWithComponents), ctx, isRequiresApproval, accountID, p)
+}
+
 // GetValidatedPeerWithMap mocks base method.
-func (m *MockController) GetValidatedPeerWithMap(ctx context.Context, isRequiresApproval bool, accountID string, peerID string) (*types.NetworkMap, []*posture.Checks, int64, error) {
+func (m *MockController) GetValidatedPeerWithMap(ctx context.Context, isRequiresApproval bool, accountID, peerID string) (*types.NetworkMap, []*posture.Checks, int64, error) {
 	m.ctrl.T.Helper()
 	ret := m.ctrl.Call(m, "GetValidatedPeerWithMap", ctx, isRequiresApproval, accountID, peerID)
 	ret0, _ := ret[0].(*types.NetworkMap)
@@ -171,7 +190,7 @@ func (mr *MockControllerMockRecorder) OnPeerDisconnected(ctx, accountID, peerID
 }
 
 // OnPeersAdded mocks base method.
-func (m *MockController) OnPeersAdded(ctx context.Context, accountID string, peerIDs []string, affectedPeerIDs []string) error {
+func (m *MockController) OnPeersAdded(ctx context.Context, accountID string, peerIDs, affectedPeerIDs []string) error {
 	m.ctrl.T.Helper()
 	ret := m.ctrl.Call(m, "OnPeersAdded", ctx, accountID, peerIDs, affectedPeerIDs)
 	ret0, _ := ret[0].(error)
@@ -185,7 +204,7 @@ func (mr *MockControllerMockRecorder) OnPeersAdded(ctx, accountID, peerIDs, affe
 }
 
 // OnPeersDeleted mocks base method.
-func (m *MockController) OnPeersDeleted(ctx context.Context, accountID string, peerIDs []string, affectedPeerIDs []string) error {
+func (m *MockController) OnPeersDeleted(ctx context.Context, accountID string, peerIDs, affectedPeerIDs []string) error {
 	m.ctrl.T.Helper()
 	ret := m.ctrl.Call(m, "OnPeersDeleted", ctx, accountID, peerIDs, affectedPeerIDs)
 	ret0, _ := ret[0].(error)
@@ -199,7 +218,7 @@ func (mr *MockControllerMockRecorder) OnPeersDeleted(ctx, accountID, peerIDs, af
 }
 
 // OnPeersUpdated mocks base method.
-func (m *MockController) OnPeersUpdated(ctx context.Context, accountId string, peerIDs []string, affectedPeerIDs []string) error {
+func (m *MockController) OnPeersUpdated(ctx context.Context, accountId string, peerIDs, affectedPeerIDs []string) error {
 	m.ctrl.T.Helper()
 	ret := m.ctrl.Call(m, "OnPeersUpdated", ctx, accountId, peerIDs, affectedPeerIDs)
 	ret0, _ := ret[0].(error)

management/internals/modules/agentnetwork/catalog/catalog.go

@@ -197,6 +197,12 @@ type JSONMetadataInjection struct {
 	// enforces a 128-char limit per value; oversized values are
 	// truncated rather than failing the request. 0 disables the cap.
 	MaxValueLength int
+	// Sanitize, when true, replaces characters outside the destination's
+	// accepted set with '_' before emitting each value. AWS Bedrock's
+	// X-Amzn-Bedrock-Request-Metadata restricts values to a limited character
+	// class, so unsanitized group display names (e.g. containing spaces) would
+	// make Bedrock reject the request with 400.
+	Sanitize bool
 }
 
 // providers is the canonical list of supported Agent Network providers.
@@ -329,6 +335,18 @@ var providers = []Provider{
 			{ID: "amazon.nova-lite", Label: "Amazon Nova Lite (Bedrock)", InputPer1k: 0.00006, OutputPer1k: 0.00024, ContextWindow: 300000},
 			{ID: "amazon.nova-micro", Label: "Amazon Nova Micro (Bedrock)", InputPer1k: 0.000035, OutputPer1k: 0.00014, ContextWindow: 128000},
 		},
+		// Bedrock accepts a cost-allocation metadata header; stamp the caller's
+		// user + authorizing group so spend can be attributed in AWS Cost
+		// Management. Sanitized because Bedrock restricts the value character set.
+		IdentityInjection: &IdentityInjection{
+			JSONMetadata: &JSONMetadataInjection{
+				Header:         "X-Amzn-Bedrock-Request-Metadata",
+				UserKey:        "user",
+				GroupsKey:      "group",
+				MaxValueLength: 256,
+				Sanitize:       true,
+			},
+		},
 	},
 	{
 		ID:                 "vertex_ai_api",

management/internals/modules/agentnetwork/synthesizer.go

@@ -540,6 +540,7 @@ type identityInjectJSONMetadata struct {
 	UserKey        string `json:"user_key,omitempty"`
 	GroupsKey      string `json:"groups_key,omitempty"`
 	MaxValueLength int    `json:"max_value_length,omitempty"`
+	Sanitize       bool   `json:"sanitize,omitempty"`
 }
 
 // buildIdentityInjectConfigJSON walks the enabled providers and emits
@@ -583,9 +584,11 @@ func buildIdentityInjectConfigJSON(providers []*types.Provider, groupIndex map[s
 func buildIdentityInjectRule(p *types.Provider, entry catalog.Provider) (identityInjectProvider, bool) {
 	rule := identityInjectProvider{ProviderID: p.ID}
 	// Identity-stamping shape (one of HeaderPair / JSONMetadata). Skip the
-	// shape silently when the catalog entry doesn't declare one — extras
-	// can still apply, see below.
-	if entry.IdentityInjection != nil {
+	// shape silently when the catalog entry doesn't declare one, or when the
+	// operator disabled metadata for this provider — extras can still apply,
+	// see below. MetadataDisabled suppresses only the identity dimensions
+	// (user + authorizing group), not the catalog's routing ExtraHeaders.
+	if !p.MetadataDisabled && entry.IdentityInjection != nil {
 		switch {
 		case entry.IdentityInjection.HeaderPair != nil:
 			rule.HeaderPair = buildIdentityHeaderPair(p, entry.IdentityInjection.HeaderPair)
@@ -651,6 +654,7 @@ func buildIdentityJSONMetadata(p *types.Provider, jm *catalog.JSONMetadataInject
 		UserKey:        userKey,
 		GroupsKey:      groupsKey,
 		MaxValueLength: jm.MaxValueLength,
+		Sanitize:       jm.Sanitize,
 	}
 }
 

management/internals/modules/agentnetwork/synthesizer_test.go

@@ -698,6 +698,94 @@ func TestSynthesizeServices_IdentityInject_Portkey_NotCustomizable(t *testing.T)
 		"same fixed-schema guarantee for the groups dimension")
 }
 
+// TestSynthesizeServices_IdentityInject_Bedrock pins Bedrock's cost-allocation
+// metadata: a JSONMetadata shape emitting X-Amzn-Bedrock-Request-Metadata with
+// the reserved user/group keys, sanitized to Bedrock's accepted charset.
+func TestSynthesizeServices_IdentityInject_Bedrock(t *testing.T) {
+	ctx := context.Background()
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+	mockStore := store.NewMockStore(ctrl)
+
+	br := newSynthTestProvider()
+	br.ID = "prov-bedrock"
+	br.ProviderID = "bedrock_api"
+	br.UpstreamURL = "https://bedrock-runtime.us-east-1.amazonaws.com"
+	br.APIKey = "bedrock-bearer"
+	br.CreatedAt = time.Date(2026, 4, 2, 0, 0, 0, 0, time.UTC)
+
+	policy := newSynthTestPolicy(br.ID, "grp-eng", "")
+	policy.ID = "pol-bedrock"
+
+	expectSynthBaseInputs(mockStore, ctx, newSynthTestSettings(),
+		[]*types.Provider{br},
+		[]*types.Policy{policy},
+		[]*types.Guardrail{})
+
+	services, err := SynthesizeServices(ctx, mockStore, testAccountID)
+	require.NoError(t, err)
+	require.Len(t, services, 1)
+
+	var injectCfg identityInjectConfig
+	for _, m := range services[0].Targets[0].Options.Middlewares {
+		if m.ID == middlewareIDLLMIdentityInject {
+			require.NoError(t, json.Unmarshal(m.ConfigJSON, &injectCfg))
+			break
+		}
+	}
+	require.Len(t, injectCfg.Providers, 1)
+	entry := injectCfg.Providers[0]
+	require.NotNil(t, entry.JSONMetadata, "Bedrock uses the JSONMetadata shape for cost-allocation metadata")
+	assert.Nil(t, entry.HeaderPair, "shapes are mutually exclusive")
+	assert.Equal(t, "X-Amzn-Bedrock-Request-Metadata", entry.JSONMetadata.Header,
+		"the caller identity lands in Bedrock's cost-allocation metadata header")
+	assert.Equal(t, "user", entry.JSONMetadata.UserKey)
+	assert.Equal(t, "group", entry.JSONMetadata.GroupsKey)
+	assert.True(t, entry.JSONMetadata.Sanitize,
+		"Bedrock restricts the metadata value charset, so values must be sanitized")
+}
+
+// TestSynthesizeServices_MetadataDisabled_SuppressesInjection verifies the
+// per-provider opt-out: a provider with MetadataDisabled set emits no
+// identity-inject entry (Bedrock has no catalog ExtraHeaders, so the whole
+// entry is dropped).
+func TestSynthesizeServices_MetadataDisabled_SuppressesInjection(t *testing.T) {
+	ctx := context.Background()
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+	mockStore := store.NewMockStore(ctrl)
+
+	br := newSynthTestProvider()
+	br.ID = "prov-bedrock"
+	br.ProviderID = "bedrock_api"
+	br.UpstreamURL = "https://bedrock-runtime.us-east-1.amazonaws.com"
+	br.APIKey = "bedrock-bearer"
+	br.MetadataDisabled = true
+	br.CreatedAt = time.Date(2026, 4, 2, 0, 0, 0, 0, time.UTC)
+
+	policy := newSynthTestPolicy(br.ID, "grp-eng", "")
+	policy.ID = "pol-bedrock"
+
+	expectSynthBaseInputs(mockStore, ctx, newSynthTestSettings(),
+		[]*types.Provider{br},
+		[]*types.Policy{policy},
+		[]*types.Guardrail{})
+
+	services, err := SynthesizeServices(ctx, mockStore, testAccountID)
+	require.NoError(t, err)
+	require.Len(t, services, 1)
+
+	var injectCfg identityInjectConfig
+	for _, m := range services[0].Targets[0].Options.Middlewares {
+		if m.ID == middlewareIDLLMIdentityInject {
+			require.NoError(t, json.Unmarshal(m.ConfigJSON, &injectCfg))
+			break
+		}
+	}
+	assert.Empty(t, injectCfg.Providers,
+		"metadata_disabled must drop the provider's identity-inject entry")
+}
+
 // TestSynthesizeServices_IdentityInject_Vercel pins Vercel AI
 // Gateway's wiring: HeaderPair shape with fixed wire names dictated
 // by Vercel's Custom Reporting API (ai-reporting-user /

management/internals/modules/agentnetwork/types/provider.go

@@ -51,6 +51,12 @@ type Provider struct {
 	// private or self-signed certificate. The synthesiser propagates it into
 	// the router route so the proxy dials that provider's upstream insecurely.
 	SkipTLSVerification bool `gorm:"column:skip_tls_verification"`
+	// MetadataDisabled suppresses identity metadata injection for this provider.
+	// Metadata (the caller's user + authorizing group) is injected by default;
+	// when true the synthesiser omits the provider's identity-inject shape, so no
+	// user/group headers (e.g. Bedrock's X-Amzn-Bedrock-Request-Metadata) are
+	// stamped. Catalog ExtraHeaders (routing config) are unaffected.
+	MetadataDisabled bool `gorm:"column:metadata_disabled"`
 	// SessionPrivateKey + SessionPublicKey are the ed25519 keypair the
 	// synthesised reverse-proxy service uses to sign / verify session
 	// JWTs after a successful OIDC handshake. Generated once on
@@ -137,6 +143,9 @@ func (p *Provider) FromAPIRequest(req *api.AgentNetworkProviderRequest) {
 	if req.SkipTlsVerification != nil {
 		p.SkipTLSVerification = *req.SkipTlsVerification
 	}
+	if req.MetadataDisabled != nil {
+		p.MetadataDisabled = *req.MetadataDisabled
+	}
 	// Identity-header overrides for catalogs flagged Customizable.
 	// nil pointer = "field omitted on the wire" → leave the stored
 	// value untouched (per the openapi description). Empty string is
@@ -170,6 +179,7 @@ func (p *Provider) ToAPIResponse() *api.AgentNetworkProvider {
 		Models:              models,
 		Enabled:             p.Enabled,
 		SkipTlsVerification: p.SkipTLSVerification,
+		MetadataDisabled:    p.MetadataDisabled,
 		CreatedAt:           &created,
 		UpdatedAt:           &updated,
 	}

management/internals/modules/agentnetwork/types/provider_test.go

@@ -42,3 +42,38 @@ func TestProvider_SkipTLSVerification_RoundTrip(t *testing.T) {
 	assert.False(t, p.SkipTLSVerification, "explicit false must clear skip_tls_verification")
 	assert.False(t, p.ToAPIResponse().SkipTlsVerification, "response must reflect the cleared value")
 }
+
+// TestProvider_MetadataDisabled_RoundTrip covers the request→provider→response
+// mapping of metadata_disabled, with the same update semantics: nil preserves,
+// explicit false clears.
+func TestProvider_MetadataDisabled_RoundTrip(t *testing.T) {
+	enable := true
+	disable := false
+
+	base := func() *api.AgentNetworkProviderRequest {
+		return &api.AgentNetworkProviderRequest{
+			ProviderId:  "bedrock_api",
+			Name:        "bedrock",
+			UpstreamUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
+		}
+	}
+
+	p := NewProvider("acc-1")
+
+	req := base()
+	req.MetadataDisabled = &enable
+	p.FromAPIRequest(req)
+	assert.True(t, p.MetadataDisabled, "create with metadata_disabled=true must set the field")
+	assert.True(t, p.ToAPIResponse().MetadataDisabled, "response must surface metadata_disabled")
+
+	// Omitting the field on update leaves the stored value untouched.
+	p.FromAPIRequest(base())
+	assert.True(t, p.MetadataDisabled, "omitting metadata_disabled on update must preserve it")
+
+	// Explicit false clears it (re-enables metadata).
+	req = base()
+	req.MetadataDisabled = &disable
+	p.FromAPIRequest(req)
+	assert.False(t, p.MetadataDisabled, "explicit false must clear metadata_disabled")
+	assert.False(t, p.ToAPIResponse().MetadataDisabled, "response must reflect the cleared value")
+}

management/internals/server/config/config.go

@@ -61,6 +61,10 @@ type Config struct {
 	// EmbeddedIdP contains configuration for the embedded Dex OIDC provider.
 	// When set, Dex will be embedded in the management server and serve requests at /oauth2/
 	EmbeddedIdP *idp.EmbeddedIdPConfig
+
+	HighestSupportedSyncMessageVersion *int
+
+	PerAccountHighestSupportedSyncMessageVersion map[string]int
 }
 
 // GetAuthAudiences returns the audience from the http config and device authorization flow config

management/internals/shared/grpc/components_encoder.go

@@ -0,0 +1,769 @@
+package grpc
+
+import (
+	"encoding/base64"
+	"strconv"
+
+	nbdns "github.com/netbirdio/netbird/dns"
+	resourceTypes "github.com/netbirdio/netbird/management/server/networks/resources/types"
+	routerTypes "github.com/netbirdio/netbird/management/server/networks/routers/types"
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"github.com/netbirdio/netbird/management/server/types"
+	nbroute "github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/networkmap"
+	"github.com/netbirdio/netbird/shared/management/proto"
+)
+
+// wgKeyRawLen is the raw byte length of a WireGuard public key.
+const wgKeyRawLen = 32
+
+// ComponentsEnvelopeInput bundles the data the component-format encoder needs.
+// The envelope is fully self-contained — every field needed by the client's
+// local Calculate() comes from the components struct itself. The only
+// externally-supplied data is the receiving peer's PeerConfig (which is
+// computed alongside the components in the network_map controller and reused
+// from the legacy proto path) and the dns_domain string.
+type ComponentsEnvelopeInput struct {
+	Components       *types.NetworkMapComponents
+	PeerConfig       *proto.PeerConfig
+	DNSDomain        string
+	DNSForwarderPort int64
+	// UserIDClaim is the OIDC claim name the client should embed in
+	// SshAuth.UserIDClaim when reconstructing the NetworkMap. Empty value
+	// is OK — client treats empty as "no SshAuth to build".
+	UserIDClaim string
+	// ProxyPatch carries pre-expanded NetworkMap fragments injected by
+	// external controllers (BYOP/port-forwarding). Nil when no proxy data
+	// is present; encoder skips the field in that case.
+	ProxyPatch *proto.ProxyPatch
+}
+
+// EncodeNetworkMapEnvelope converts NetworkMapComponents into the component
+// wire envelope. The encoder is intentionally non-deterministic: it iterates
+// Go maps in their native (random) order. Indexes inside the envelope
+// (peer_indexes, source_group_ids, agent_version_idx, router_peer_indexes)
+// are self-consistent within a single encode, so the decoder reconstructs
+// the same typed objects regardless of emit order. Tests that need to
+// compare envelopes do so semantically via proto round-trip + canonicalize,
+// not byte-equal.
+//
+// Callers must NOT concatenate or merge envelopes from different encodes —
+// index spaces are local to a single envelope.
+func EncodeNetworkMapEnvelope(in ComponentsEnvelopeInput) *proto.NetworkMapEnvelope {
+	c := in.Components
+
+	// Graceful degrade when components is nil — matches the legacy path's
+	// behaviour for missing/unvalidated peers (return a NetworkMap with only
+	// Network populated). The receiver gets an envelope it can decode
+	// without crashing; AccountSettings stays non-nil so client-side
+	// dereferences are safe.
+	if c.IsEmpty() {
+		// Match legacy missing-peer minimum: a NetworkMap with only Network
+		// populated. The receiver gets enough to bootstrap (Network
+		// identifier, dns_domain, account_settings) and the peer itself.
+		return &proto.NetworkMapEnvelope{
+			Payload: &proto.NetworkMapEnvelope_Full{
+				Full: &proto.NetworkMapComponentsFull{
+					PeerConfig: in.PeerConfig,
+					// components.Peers always contains the target peer
+					Peers:            []*proto.PeerCompact{toPeerCompact(c.Peers[c.PeerID])},
+					DnsDomain:        in.DNSDomain,
+					DnsForwarderPort: in.DNSForwarderPort,
+					UserIdClaim:      in.UserIDClaim,
+					AccountSettings:  &proto.AccountSettingsCompact{},
+					ProxyPatch:       in.ProxyPatch,
+				},
+			},
+		}
+	}
+
+	// Phase 1: build dedup tables. Every routing peer (in c.RouterPeers) and
+	// every regular peer (in c.Peers) must be indexed before any encoder
+	// looks up indexes via e.peerOrder — otherwise routes / routers_map for
+	// peers that exist only in c.RouterPeers would silently lose their
+	// peer_index reference.
+	enc := newComponentEncoder(c)
+	enc.indexAllPeers()
+	routerIdxs := enc.indexRouterPeers(c.RouterPeers)
+
+	// Phase 2: gather every policy that any consumer references (peer-pair
+	// policies + resource-only policies) so encodeResourcePoliciesMap can
+	// translate every *Policy pointer to a wire index.
+	allPolicies := unionPolicies(c.Policies, c.ResourcePoliciesMap)
+	policies := enc.encodePolicies(allPolicies)
+
+	// Phase 3: emit. Order of struct field expressions no longer matters:
+	// every encoder either reads from the dedup tables or works on
+	// independent input.
+	full := &proto.NetworkMapComponentsFull{
+		Serial:              networkSerial(c.Network),
+		PeerConfig:          in.PeerConfig,
+		Network:             toAccountNetwork(c.Network),
+		AccountSettings:     toAccountSettingsCompact(c.AccountSettings),
+		DnsForwarderPort:    in.DNSForwarderPort,
+		UserIdClaim:         in.UserIDClaim,
+		ProxyPatch:          in.ProxyPatch,
+		DnsSettings:         enc.encodeDNSSettings(c.DNSSettings),
+		DnsDomain:           in.DNSDomain,
+		CustomZoneDomain:    c.CustomZoneDomain,
+		AgentVersions:       enc.agentVersions,
+		Peers:               enc.peers,
+		RouterPeerIndexes:   routerIdxs,
+		Policies:            policies,
+		Groups:              enc.encodeGroups(),
+		Routes:              enc.encodeRoutes(c.Routes),
+		NameserverGroups:    enc.encodeNameServerGroups(c.NameServerGroups),
+		AllDnsRecords:       encodeSimpleRecords(c.AllDNSRecords),
+		AccountZones:        encodeCustomZones(c.AccountZones),
+		NetworkResources:    enc.encodeNetworkResources(c.NetworkResources),
+		RoutersMap:          enc.encodeRoutersMap(c.RoutersMap),
+		ResourcePoliciesMap: enc.encodeResourcePoliciesMap(c.ResourcePoliciesMap),
+		GroupIdToUserIds:    enc.encodeGroupIDToUserIDs(c.GroupIDToUserIDs),
+		AllowedUserIds:      stringSetToSlice(c.AllowedUserIDs),
+		PostureFailedPeers:  enc.encodePostureFailedPeers(c.PostureFailedPeers),
+	}
+
+	return &proto.NetworkMapEnvelope{
+		Payload: &proto.NetworkMapEnvelope_Full{Full: full},
+	}
+}
+
+// networkSerial returns c.Network.CurrentSerial() with a nil guard. The
+// production path always populates c.Network, but the encoder is exported
+// and a hand-built components struct may omit it.
+func networkSerial(n *types.Network) uint64 {
+	if n == nil {
+		return 0
+	}
+	return n.CurrentSerial()
+}
+
+type componentEncoder struct {
+	components *types.NetworkMapComponents
+
+	peerOrder map[string]uint32
+	peers     []*proto.PeerCompact
+
+	agentVersionOrder map[string]uint32
+	agentVersions     []string
+}
+
+func newComponentEncoder(c *types.NetworkMapComponents) *componentEncoder {
+	return &componentEncoder{
+		components:        c,
+		peerOrder:         make(map[string]uint32, len(c.Peers)),
+		peers:             make([]*proto.PeerCompact, 0, len(c.Peers)),
+		agentVersionOrder: make(map[string]uint32),
+	}
+}
+
+func (e *componentEncoder) indexAllPeers() {
+	for _, p := range e.components.Peers {
+		if p == nil {
+			continue
+		}
+		e.appendPeer(p)
+	}
+}
+
+func (e *componentEncoder) appendPeer(p *nbpeer.Peer) uint32 {
+	if idx, ok := e.peerOrder[p.ID]; ok {
+		return idx
+	}
+	idx := uint32(len(e.peers))
+	e.peerOrder[p.ID] = idx
+	e.peers = append(e.peers, toPeerCompact(p))
+	return idx
+}
+
+// indexRouterPeers ensures every router peer is in the peer dedup table
+// (c.RouterPeers may contain peers not in c.Peers when validation rules drop
+// them) and returns their wire indexes for the RouterPeerIndexes field. Must
+// run before any encoder that resolves peer ids via e.peerOrder.
+func (e *componentEncoder) indexRouterPeers(routers map[string]*nbpeer.Peer) []uint32 {
+	if len(routers) == 0 {
+		return nil
+	}
+	out := make([]uint32, 0, len(routers))
+	for _, p := range routers {
+		if p == nil {
+			continue
+		}
+		out = append(out, e.appendPeer(p))
+	}
+	return out
+}
+
+func (e *componentEncoder) encodeGroups() []*proto.GroupCompact {
+	if len(e.components.Groups) == 0 {
+		return nil
+	}
+
+	out := make([]*proto.GroupCompact, 0, len(e.components.Groups))
+	for _, g := range e.components.Groups {
+		peerIdxs := make([]uint32, 0, len(g.Peers))
+		for _, peerID := range g.Peers {
+			if idx, ok := e.peerOrder[peerID]; ok {
+				peerIdxs = append(peerIdxs, idx)
+			}
+		}
+		out = append(out, &proto.GroupCompact{
+			Id:          g.PublicID,
+			PeerIndexes: peerIdxs,
+			IsAll:       g.IsGroupAll(),
+		})
+	}
+	return out
+}
+
+// encodePolicies flattens Policy{Rules} → []PolicyCompact. Returns the wire
+// list and a map from policy pointer to the indexes of its emitted rules in
+// that list — used by encodeResourcePoliciesMap to translate
+// ResourcePoliciesMap[resourceID][]*Policy into wire-side indexes.
+func (e *componentEncoder) encodePolicies(policies []*types.Policy) []*proto.PolicyCompact {
+	if len(policies) == 0 {
+		return nil
+	}
+
+	out := make([]*proto.PolicyCompact, 0, len(policies))
+
+	for _, pol := range policies {
+		if !pol.Enabled {
+			continue
+		}
+		for _, r := range pol.Rules {
+			if r == nil || !r.Enabled {
+				continue
+			}
+			out = append(out, e.encodePolicyRule(pol, r))
+		}
+	}
+	return out
+}
+
+// encodePolicyRule maps a single PolicyRule under pol to a PolicyCompact entry.
+func (e *componentEncoder) encodePolicyRule(pol *types.Policy, r *types.PolicyRule) *proto.PolicyCompact {
+	return &proto.PolicyCompact{
+		Id:                    pol.PublicID,
+		Action:                networkmap.GetProtoAction(string(r.Action)),
+		Protocol:              networkmap.GetProtoProtocol(string(r.Protocol)),
+		Bidirectional:         r.Bidirectional,
+		Ports:                 portsToUint32(r.Ports),
+		PortRanges:            portRangesToProto(r.PortRanges),
+		SourceGroupIds:        e.groupPublicXids(r.Sources),
+		DestinationGroupIds:   e.groupPublicXids(r.Destinations),
+		AuthorizedUser:        r.AuthorizedUser,
+		AuthorizedGroups:      e.encodeAuthorizedGroups(r.AuthorizedGroups),
+		SourceResource:        e.resourceToProto(r.SourceResource),
+		DestinationResource:   e.resourceToProto(r.DestinationResource),
+		SourcePostureCheckIds: e.postureCheckSeqs(pol.SourcePostureChecks),
+	}
+}
+
+// groupPublicXids maps the xid group IDs in src to their public xids,
+// dropping any group with invalid public xid.
+func (e *componentEncoder) groupPublicXids(src []string) []string {
+	if len(src) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(src))
+	for _, gid := range src {
+		if id, ok := e.groupPublicXid(gid); ok {
+			out = append(out, id)
+		}
+	}
+	return out
+}
+
+// unionPolicies merges c.Policies with every policy referenced by
+// c.ResourcePoliciesMap, deduplicating by pointer identity. Resource-only
+// policies (relevant to a NetworkResource but not to peer-pair traffic)
+// only live in ResourcePoliciesMap; without this union step they'd be lost
+// from the wire and the client's resource-policy lookup would come back
+// empty.
+func unionPolicies(policies []*types.Policy, resourcePolicies map[string][]*types.Policy) []*types.Policy {
+	// Fast path: non-router peers have no resource-only policies, so the
+	// "union" is identical to `policies`. Skip the dedup map allocation.
+	if len(resourcePolicies) == 0 {
+		return policies
+	}
+	seen := make(map[string]struct{}, len(policies))
+	out := make([]*types.Policy, 0, len(policies))
+	for _, p := range policies {
+		if p == nil {
+			continue
+		}
+		if _, ok := seen[p.ID]; ok {
+			continue
+		}
+		seen[p.ID] = struct{}{}
+		out = append(out, p)
+	}
+	for _, list := range resourcePolicies {
+		for _, p := range list {
+			if p == nil {
+				continue
+			}
+			if _, ok := seen[p.ID]; ok {
+				continue
+			}
+			seen[p.ID] = struct{}{}
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// encodeAuthorizedGroups translates rule.AuthorizedGroups (map keyed by
+// group xid → local-user names) to the wire form (map keyed by group
+// account_seq_id → UserNameList). Groups without a seq id are dropped —
+// matches how source/destination group references handle the same case.
+func (e *componentEncoder) encodeAuthorizedGroups(m map[string][]string) map[string]*proto.UserNameList {
+	if len(m) == 0 {
+		return nil
+	}
+	out := make(map[string]*proto.UserNameList, len(m))
+	for groupID, names := range m {
+		id, ok := e.groupPublicXid(groupID)
+		if !ok {
+			continue
+		}
+		out[id] = &proto.UserNameList{Names: names}
+	}
+	return out
+}
+
+func (e *componentEncoder) groupPublicXid(groupID string) (string, bool) {
+	g, ok := e.components.Groups[groupID]
+	if !ok {
+		return "", false
+	}
+	return g.PublicID, true
+}
+
+// resourceToProto translates types.Resource for the wire. For peer-typed
+// resources the peer id is converted to a peer index into the envelope's
+// peers array. For other resource types only the type string is shipped
+// today (Calculate's resource-typed rule path consults SourceResource only
+// for "peer" — other types fall through to group-based lookup).
+func (e *componentEncoder) resourceToProto(r types.Resource) *proto.ResourceCompact {
+	if r.ID == "" && r.Type == "" {
+		return nil
+	}
+	out := &proto.ResourceCompact{Type: string(r.Type)}
+	if r.Type == types.ResourceTypePeer && r.ID != "" {
+		if idx, ok := e.peerOrder[r.ID]; ok {
+			out.PeerIndexSet = true
+			out.PeerIndex = idx
+		}
+	}
+	return out
+}
+
+// postureCheckSeqs translates a slice of posture-check xids to their
+// public xids. Unresolvable xids are silently dropped — matches how group/peer
+// references handle the same case.
+func (e *componentEncoder) postureCheckSeqs(xids []string) []string {
+	if len(xids) == 0 || len(e.components.PostureCheckXIDToPublicID) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(xids))
+	for _, xid := range xids {
+		if seq, ok := e.components.PostureCheckXIDToPublicID[xid]; ok {
+			out = append(out, seq)
+		}
+	}
+	return out
+}
+
+// networkSeq translates a Network xid to its public id using
+// the NetworkMapComponents.NetworkXIDToPublicID lookup. Returns (0,false) when
+// the xid isn't known — callers decide whether to skip the parent record.
+func (e *componentEncoder) networkPublicId(xid string) (string, bool) {
+	if xid == "" {
+		return "", false
+	}
+	id, ok := e.components.NetworkXIDToPublicID[xid]
+	if !ok {
+		return "", false
+	}
+	return id, true
+}
+
+func (e *componentEncoder) encodeDNSSettings(s *types.DNSSettings) *proto.DNSSettingsCompact {
+	if s == nil || len(s.DisabledManagementGroups) == 0 {
+		return nil
+	}
+	out := &proto.DNSSettingsCompact{
+		DisabledManagementGroupIds: make([]string, 0, len(s.DisabledManagementGroups)),
+	}
+	for _, gid := range s.DisabledManagementGroups {
+		if id, ok := e.groupPublicXid(gid); ok {
+			out.DisabledManagementGroupIds = append(out.DisabledManagementGroupIds, id)
+		}
+	}
+	return out
+}
+
+func (e *componentEncoder) encodeRoutes(routes []*nbroute.Route) []*proto.RouteRaw {
+	if len(routes) == 0 {
+		return nil
+	}
+	out := make([]*proto.RouteRaw, 0, len(routes))
+	for _, r := range routes {
+		if r == nil {
+			continue
+		}
+		rr := &proto.RouteRaw{
+			Id:                    r.PublicID,
+			NetId:                 string(r.NetID),
+			Description:           r.Description,
+			KeepRoute:             r.KeepRoute,
+			NetworkType:           int32(r.NetworkType),
+			Masquerade:            r.Masquerade,
+			Metric:                int32(r.Metric),
+			Enabled:               r.Enabled,
+			SkipAutoApply:         r.SkipAutoApply,
+			Domains:               r.Domains.ToPunycodeList(),
+			GroupIds:              e.groupPublicXids(r.Groups),
+			AccessControlGroupIds: e.groupPublicXids(r.AccessControlGroups),
+			PeerGroupIds:          e.groupPublicXids(r.PeerGroups),
+		}
+		if r.Network.IsValid() {
+			rr.NetworkCidr = r.Network.String()
+		}
+		if r.Peer != "" {
+			if idx, ok := e.peerOrder[r.Peer]; ok {
+				rr.PeerIndexSet = true
+				rr.PeerIndex = idx
+			}
+		}
+		out = append(out, rr)
+	}
+	return out
+}
+
+func (e *componentEncoder) encodeNameServerGroups(nsgs []*nbdns.NameServerGroup) []*proto.NameServerGroupRaw {
+	if len(nsgs) == 0 {
+		return nil
+	}
+	out := make([]*proto.NameServerGroupRaw, 0, len(nsgs))
+	for _, nsg := range nsgs {
+		if nsg == nil {
+			continue
+		}
+		entry := &proto.NameServerGroupRaw{
+			Id:                   nsg.PublicID,
+			Nameservers:          encodeNameServers(nsg.NameServers),
+			GroupIds:             e.groupPublicXids(nsg.Groups),
+			Primary:              nsg.Primary,
+			Domains:              nsg.Domains,
+			Enabled:              nsg.Enabled,
+			SearchDomainsEnabled: nsg.SearchDomainsEnabled,
+		}
+		out = append(out, entry)
+	}
+	return out
+}
+
+func encodeNameServers(servers []nbdns.NameServer) []*proto.NameServer {
+	if len(servers) == 0 {
+		return nil
+	}
+	out := make([]*proto.NameServer, 0, len(servers))
+	for _, s := range servers {
+		out = append(out, &proto.NameServer{
+			IP:     s.IP.String(),
+			NSType: int64(s.NSType),
+			Port:   int64(s.Port),
+		})
+	}
+	return out
+}
+
+func encodeSimpleRecords(records []nbdns.SimpleRecord) []*proto.SimpleRecord {
+	if len(records) == 0 {
+		return nil
+	}
+	out := make([]*proto.SimpleRecord, 0, len(records))
+	for _, r := range records {
+		out = append(out, &proto.SimpleRecord{
+			Name:  r.Name,
+			Type:  int64(r.Type),
+			Class: r.Class,
+			TTL:   int64(r.TTL),
+			RData: r.RData,
+		})
+	}
+	return out
+}
+
+func encodeCustomZones(zones []nbdns.CustomZone) []*proto.CustomZone {
+	if len(zones) == 0 {
+		return nil
+	}
+	out := make([]*proto.CustomZone, 0, len(zones))
+	for _, z := range zones {
+		out = append(out, &proto.CustomZone{
+			Domain:               z.Domain,
+			Records:              encodeSimpleRecords(z.Records),
+			SearchDomainDisabled: z.SearchDomainDisabled,
+			NonAuthoritative:     z.NonAuthoritative,
+		})
+	}
+	return out
+}
+
+func (e *componentEncoder) encodeNetworkResources(resources []*resourceTypes.NetworkResource) []*proto.NetworkResourceRaw {
+	if len(resources) == 0 {
+		return nil
+	}
+	out := make([]*proto.NetworkResourceRaw, 0, len(resources))
+	for _, r := range resources {
+		if r == nil {
+			continue
+		}
+		entry := &proto.NetworkResourceRaw{
+			Id:          r.PublicID,
+			Name:        r.Name,
+			Description: r.Description,
+			Type:        string(r.Type),
+			Address:     r.Address,
+			DomainValue: r.Domain,
+			Enabled:     r.Enabled,
+		}
+		if id, ok := e.networkPublicId(r.NetworkID); ok {
+			entry.NetworkSeq = id
+		}
+		if r.Prefix.IsValid() {
+			entry.PrefixCidr = r.Prefix.String()
+		}
+		out = append(out, entry)
+	}
+	return out
+}
+
+func (e *componentEncoder) encodeRoutersMap(routersMap map[string]map[string]*routerTypes.NetworkRouter) map[string]*proto.NetworkRouterList {
+	if len(routersMap) == 0 {
+		return nil
+	}
+	out := make(map[string]*proto.NetworkRouterList, len(routersMap))
+	for networkXID, routers := range routersMap {
+		if len(routers) == 0 {
+			continue
+		}
+		id, ok := e.networkPublicId(networkXID)
+		if !ok {
+			continue
+		}
+		entries := make([]*proto.NetworkRouterEntry, 0, len(routers))
+		for peerID, r := range routers {
+			if r == nil {
+				continue
+			}
+			entry := &proto.NetworkRouterEntry{
+				Id:           r.PublicID,
+				PeerGroupIds: e.groupPublicXids(r.PeerGroups),
+				Masquerade:   r.Masquerade,
+				Metric:       int32(r.Metric),
+				Enabled:      r.Enabled,
+			}
+			if idx, ok := e.peerOrder[peerID]; ok {
+				entry.PeerIndexSet = true
+				entry.PeerIndex = idx
+			}
+			entries = append(entries, entry)
+		}
+		out[id] = &proto.NetworkRouterList{Entries: entries}
+	}
+	return out
+}
+
+func (e *componentEncoder) encodeResourcePoliciesMap(rpm map[string][]*types.Policy) map[string]*proto.PolicyIds {
+	if len(rpm) == 0 {
+		return nil
+	}
+	// resourceXIDToPublicID is local to one encode — built from components.NetworkResources
+	// (small slice). Network resources without seq id are dropped, matching how
+	// other components-without-seq are silently filtered.
+	resourceXIDToPublicID := make(map[string]string, len(e.components.NetworkResources))
+	for _, r := range e.components.NetworkResources {
+		if r != nil {
+			resourceXIDToPublicID[r.ID] = r.PublicID
+		}
+	}
+	out := make(map[string]*proto.PolicyIds, len(rpm))
+	for resourceXID, policies := range rpm {
+		resId, ok := resourceXIDToPublicID[resourceXID]
+		if !ok {
+			continue
+		}
+		ids := make([]string, 0, len(policies))
+		for _, pol := range policies {
+			ids = append(ids, pol.PublicID)
+		}
+		if len(ids) == 0 {
+			continue
+		}
+		out[resId] = &proto.PolicyIds{Ids: ids}
+	}
+	return out
+}
+
+func (e *componentEncoder) encodeGroupIDToUserIDs(m map[string][]string) map[string]*proto.UserIDList {
+	if len(m) == 0 {
+		return nil
+	}
+	out := make(map[string]*proto.UserIDList, len(m))
+	for groupID, userIDs := range m {
+		id, ok := e.groupPublicXid(groupID)
+		if !ok || len(userIDs) == 0 {
+			continue
+		}
+		out[id] = &proto.UserIDList{UserIds: userIDs}
+	}
+	return out
+}
+
+func stringSetToSlice(s map[string]struct{}) []string {
+	if len(s) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(s))
+	for k := range s {
+		out = append(out, k)
+	}
+	return out
+}
+
+func (e *componentEncoder) encodePostureFailedPeers(m map[string]map[string]struct{}) map[string]*proto.PeerIndexSet {
+	if len(m) == 0 {
+		return nil
+	}
+	out := make(map[string]*proto.PeerIndexSet, len(m))
+	for checkXID, failedPeerIDs := range m {
+		id, ok := e.components.PostureCheckXIDToPublicID[checkXID]
+		if !ok {
+			continue
+		}
+		idxs := make([]uint32, 0, len(failedPeerIDs))
+		for peerID := range failedPeerIDs {
+			if idx, ok := e.peerOrder[peerID]; ok {
+				idxs = append(idxs, idx)
+			}
+		}
+		if len(idxs) == 0 {
+			continue
+		}
+		out[id] = &proto.PeerIndexSet{PeerIndexes: idxs}
+	}
+	return out
+}
+
+// toAccountSettingsCompact always returns a non-nil message — the client
+// dereferences it unconditionally during Calculate(), so a nil here would
+// crash the receiver. A missing types.AccountSettingsInfo on the server
+// (which shouldn't happen in production but the encoder is exported)
+// degrades to login_expiration_enabled = false, which makes
+// LoginExpired() return false for every peer.
+func toAccountSettingsCompact(s *types.AccountSettingsInfo) *proto.AccountSettingsCompact {
+	if s == nil {
+		return &proto.AccountSettingsCompact{}
+	}
+	return &proto.AccountSettingsCompact{
+		PeerLoginExpirationEnabled: s.PeerLoginExpirationEnabled,
+		PeerLoginExpirationNs:      int64(s.PeerLoginExpiration),
+	}
+}
+
+func toAccountNetwork(n *types.Network) *proto.AccountNetwork {
+	if n == nil {
+		return nil
+	}
+	out := &proto.AccountNetwork{
+		Identifier: n.Identifier,
+		NetCidr:    n.Net.String(),
+		Dns:        n.Dns,
+		Serial:     n.CurrentSerial(),
+	}
+	if len(n.NetV6.IP) > 0 {
+		out.NetV6Cidr = n.NetV6.String()
+	}
+	return out
+}
+
+func toPeerCompact(p *nbpeer.Peer) *proto.PeerCompact {
+	pc := &proto.PeerCompact{
+		WgPubKey:               decodeWgKey(p.Key),
+		SshPubKey:              []byte(p.SSHKey),
+		DnsLabel:               p.DNSLabel,
+		AgentVersion:           p.Meta.WtVersion,
+		AddedWithSsoLogin:      p.UserID != "",
+		LoginExpirationEnabled: p.LoginExpirationEnabled,
+		SshEnabled:             p.SSHEnabled,
+		SupportsIpv6:           p.SupportsIPv6(),
+		SupportsSourcePrefixes: p.SupportsSourcePrefixes(),
+		ServerSshAllowed:       p.Meta.Flags.ServerSSHAllowed,
+	}
+	if p.LastLogin != nil {
+		pc.LastLoginUnixNano = p.LastLogin.UnixNano()
+	}
+	switch {
+	case !p.IP.IsValid():
+		// leave Ip nil
+	case p.IP.Is4() || p.IP.Is4In6():
+		ip := p.IP.Unmap().As4()
+		pc.Ip = ip[:]
+	default:
+		ip := p.IP.As16()
+		pc.Ip = ip[:]
+	}
+	if p.IPv6.IsValid() {
+		ip := p.IPv6.As16()
+		pc.Ipv6 = ip[:]
+	}
+	return pc
+}
+
+// decodeWgKey returns the raw 32 bytes of a base64-encoded WireGuard public
+// key, or nil for an empty / malformed key.
+func decodeWgKey(s string) []byte {
+	if s == "" {
+		return nil
+	}
+	out := make([]byte, wgKeyRawLen)
+	n, err := base64.StdEncoding.Decode(out, []byte(s))
+	if err != nil || n != wgKeyRawLen {
+		return nil
+	}
+	return out
+}
+
+func portsToUint32(ports []string) []uint32 {
+	if len(ports) == 0 {
+		return nil
+	}
+	out := make([]uint32, 0, len(ports))
+	for _, p := range ports {
+		v, err := strconv.ParseUint(p, 10, 16)
+		if err != nil {
+			continue
+		}
+		out = append(out, uint32(v))
+	}
+	return out
+}
+
+func portRangesToProto(ranges []types.RulePortRange) []*proto.PortInfo_Range {
+	if len(ranges) == 0 {
+		return nil
+	}
+	out := make([]*proto.PortInfo_Range, 0, len(ranges))
+	for _, r := range ranges {
+		out = append(out, &proto.PortInfo_Range{
+			Start: uint32(r.Start),
+			End:   uint32(r.End),
+		})
+	}
+	return out
+}

management/internals/shared/grpc/components_encoder_test.go

@@ -0,0 +1,785 @@
+package grpc
+
+import (
+	"bytes"
+	"cmp"
+	"net"
+	"net/netip"
+	"slices"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	goproto "google.golang.org/protobuf/proto"
+
+	nbdns "github.com/netbirdio/netbird/dns"
+	resourceTypes "github.com/netbirdio/netbird/management/server/networks/resources/types"
+	routerTypes "github.com/netbirdio/netbird/management/server/networks/routers/types"
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"github.com/netbirdio/netbird/management/server/types"
+	nbroute "github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/proto"
+)
+
+const testWgKeyA = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq="
+const testWgKeyB = "BBCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq="
+const testWgKeyC = "CBCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopq="
+
+// canonicalize rewrites a NetworkMapComponentsFull in place into a canonical
+// form: peers reordered by wg_pub_key, with the rest of the message rewritten
+// to reference the new peer indexes. Groups, policies, and router indexes are
+// also sorted. After canonicalize, two envelopes built from the same logical
+// input compare byte-equal via proto.Equal.
+//
+// This lives on the test side — the encoder itself emits in map-iteration
+// order. Test-side normalization is the contract for "two encodes are
+// equivalent".
+func canonicalize(full *proto.NetworkMapComponentsFull) {
+	if full == nil {
+		return
+	}
+
+	type peerEntry struct {
+		peer   *proto.PeerCompact
+		oldIdx uint32
+	}
+	entries := make([]peerEntry, len(full.Peers))
+	for i, p := range full.Peers {
+		entries[i] = peerEntry{peer: p, oldIdx: uint32(i)}
+	}
+	// DnsLabel is unique per peer; it tiebreaks on equal WgPubKey (e.g. both
+	// nil from malformed keys, or both empty for placeholders).
+	slices.SortFunc(entries, func(a, b peerEntry) int {
+		if c := bytes.Compare(a.peer.WgPubKey, b.peer.WgPubKey); c != 0 {
+			return c
+		}
+		return cmp.Compare(a.peer.DnsLabel, b.peer.DnsLabel)
+	})
+
+	remap := make(map[uint32]uint32, len(entries))
+	newPeers := make([]*proto.PeerCompact, len(entries))
+	for newIdx, e := range entries {
+		remap[e.oldIdx] = uint32(newIdx)
+		newPeers[newIdx] = e.peer
+	}
+	full.Peers = newPeers
+
+	full.RouterPeerIndexes = remapAndSort(full.RouterPeerIndexes, remap)
+	for _, g := range full.Groups {
+		g.PeerIndexes = remapAndSort(g.PeerIndexes, remap)
+	}
+	slices.SortFunc(full.Groups, func(a, b *proto.GroupCompact) int { return cmp.Compare(a.Id, b.Id) })
+
+	for _, r := range full.Routes {
+		if r.PeerIndexSet {
+			if newIdx, ok := remap[r.PeerIndex]; ok {
+				r.PeerIndex = newIdx
+			}
+		}
+		slices.Sort(r.GroupIds)
+		slices.Sort(r.AccessControlGroupIds)
+		slices.Sort(r.PeerGroupIds)
+	}
+	slices.SortFunc(full.Routes, func(a, b *proto.RouteRaw) int { return cmp.Compare(a.Id, b.Id) })
+
+	for _, list := range full.RoutersMap {
+		for _, entry := range list.Entries {
+			if entry.PeerIndexSet {
+				if newIdx, ok := remap[entry.PeerIndex]; ok {
+					entry.PeerIndex = newIdx
+				}
+			}
+			slices.Sort(entry.PeerGroupIds)
+		}
+		slices.SortFunc(list.Entries, func(a, b *proto.NetworkRouterEntry) int { return cmp.Compare(a.Id, b.Id) })
+	}
+
+	for _, set := range full.PostureFailedPeers {
+		set.PeerIndexes = remapAndSort(set.PeerIndexes, remap)
+	}
+
+	for _, p := range full.Policies {
+		slices.Sort(p.SourceGroupIds)
+		slices.Sort(p.DestinationGroupIds)
+	}
+	// Sort policies by (Id, source_group_ids, destination_group_ids) so that
+	// multiple PolicyCompact entries sharing the same Id (one per rule, when
+	// a Policy has multiple rules) still get a deterministic order. After
+	// sorting we remap indexes in ResourcePoliciesMap.
+	policyOldOrder := make(map[*proto.PolicyCompact]uint32, len(full.Policies))
+	for i, p := range full.Policies {
+		policyOldOrder[p] = uint32(i)
+	}
+	slices.SortFunc(full.Policies, func(a, b *proto.PolicyCompact) int {
+		if c := cmp.Compare(a.Id, b.Id); c != 0 {
+			return c
+		}
+		if c := slices.Compare(a.SourceGroupIds, b.SourceGroupIds); c != 0 {
+			return c
+		}
+		return slices.Compare(a.DestinationGroupIds, b.DestinationGroupIds)
+	})
+	policyRemap := make(map[uint32]uint32, len(full.Policies))
+	for newIdx, p := range full.Policies {
+		policyRemap[policyOldOrder[p]] = uint32(newIdx)
+	}
+	for _, idxs := range full.ResourcePoliciesMap {
+		slices.Sort(idxs.Ids)
+	}
+	for _, list := range full.GroupIdToUserIds {
+		slices.Sort(list.UserIds)
+	}
+	slices.Sort(full.AllowedUserIds)
+}
+
+func remapAndSort(idxs []uint32, remap map[uint32]uint32) []uint32 {
+	out := make([]uint32, 0, len(idxs))
+	for _, i := range idxs {
+		if newIdx, ok := remap[i]; ok {
+			out = append(out, newIdx)
+		}
+	}
+	slices.Sort(out)
+	return out
+}
+
+// envelopesEquivalent decodes both envelopes, canonicalizes them, and reports
+// whether they're proto.Equal. Use instead of byte-comparing marshaled output:
+// the encoder is intentionally non-deterministic.
+func envelopesEquivalent(a, b *proto.NetworkMapEnvelope) bool {
+	canonicalize(a.GetFull())
+	canonicalize(b.GetFull())
+	return goproto.Equal(a, b)
+}
+
+func newTestComponents() *types.NetworkMapComponents {
+	peerA := &nbpeer.Peer{
+		ID:       "peer-a",
+		Key:      testWgKeyA,
+		IP:       netip.AddrFrom4([4]byte{100, 64, 0, 1}),
+		DNSLabel: "peera",
+		SSHKey:   "ssh-a",
+		Status:   &nbpeer.PeerStatus{Connected: true, LastSeen: time.Now()},
+		Meta:     nbpeer.PeerSystemMeta{WtVersion: "0.40.0"},
+	}
+	peerB := &nbpeer.Peer{
+		ID:       "peer-b",
+		Key:      testWgKeyB,
+		IP:       netip.AddrFrom4([4]byte{100, 64, 0, 2}),
+		IPv6:     netip.AddrFrom16([16]byte{0xfd, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2}),
+		DNSLabel: "peerb",
+		Meta:     nbpeer.PeerSystemMeta{WtVersion: "0.25.0"},
+	}
+	peerC := &nbpeer.Peer{
+		ID:       "peer-c",
+		Key:      testWgKeyC,
+		IP:       netip.AddrFrom4([4]byte{100, 64, 0, 3}),
+		DNSLabel: "peerc",
+		Meta:     nbpeer.PeerSystemMeta{WtVersion: "0.40.0"},
+	}
+
+	return &types.NetworkMapComponents{
+		PeerID: "peer-a",
+		Network: &types.Network{
+			Identifier: "net-test",
+			Net:        net.IPNet{IP: net.IP{100, 64, 0, 0}, Mask: net.CIDRMask(10, 32)},
+			Serial:     7,
+		},
+		AccountSettings: &types.AccountSettingsInfo{
+			PeerLoginExpirationEnabled: true,
+			PeerLoginExpiration:        2 * time.Hour,
+		},
+		Peers: map[string]*nbpeer.Peer{
+			"peer-a": peerA,
+			"peer-b": peerB,
+			"peer-c": peerC,
+		},
+		Groups: map[string]*types.Group{
+			"group-src": {ID: "group-src", PublicID: "1", Name: "Src", Peers: []string{"peer-a"}},
+			"group-dst": {ID: "group-dst", PublicID: "2", Name: "Dst", Peers: []string{"peer-b", "peer-c"}},
+		},
+		Policies: []*types.Policy{
+			{
+				ID:       "pol-1",
+				PublicID: "10",
+				Enabled:  true,
+				Rules: []*types.PolicyRule{{
+					ID: "rule-1", Enabled: true, Action: types.PolicyTrafficActionAccept,
+					Protocol: types.PolicyRuleProtocolTCP, Bidirectional: true,
+					Ports:        []string{"22", "80"},
+					PortRanges:   []types.RulePortRange{{Start: 8000, End: 8100}},
+					Sources:      []string{"group-src"},
+					Destinations: []string{"group-dst"},
+				}},
+			},
+		},
+		RouterPeers: map[string]*nbpeer.Peer{"peer-c": peerC},
+	}
+}
+
+func TestEncodeNetworkMapEnvelope_Basic(t *testing.T) {
+	c := newTestComponents()
+	env := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{
+		Components: c,
+		DNSDomain:  "netbird.cloud",
+	})
+
+	require.NotNil(t, env)
+	full := env.GetFull()
+	require.NotNil(t, full, "envelope must contain Full payload")
+
+	assert.EqualValues(t, 7, full.Serial)
+	assert.Equal(t, "netbird.cloud", full.DnsDomain)
+
+	require.NotNil(t, full.Network)
+	assert.Equal(t, "net-test", full.Network.Identifier)
+	assert.Equal(t, "100.64.0.0/10", full.Network.NetCidr)
+
+	require.NotNil(t, full.AccountSettings)
+	assert.True(t, full.AccountSettings.PeerLoginExpirationEnabled)
+	assert.EqualValues(t, (2 * time.Hour).Nanoseconds(), full.AccountSettings.PeerLoginExpirationNs)
+
+	require.Len(t, full.Peers, 3)
+	byLabel := map[string]*proto.PeerCompact{}
+	for _, p := range full.Peers {
+		assert.Len(t, p.WgPubKey, 32, "wg key must be raw 32 bytes")
+		assert.Len(t, p.Ip, 4, "ipv4 must be raw 4 bytes")
+		byLabel[p.DnsLabel] = p
+	}
+	assert.Len(t, byLabel["peerb"].Ipv6, 16, "peer-b has ipv6 → 16 bytes")
+}
+
+func TestEncodeNetworkMapEnvelope_RepeatEncodesEquivalent(t *testing.T) {
+	c := newTestComponents()
+
+	expected := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c})
+
+	// Hammer it 100 times — Go map iteration is randomized per call, so each
+	// run produces different wire bytes, but the canonicalized form must
+	// match.
+	for i := 0; i < 100; i++ {
+		got := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c})
+		require.True(t, envelopesEquivalent(expected, got),
+			"encode #%d must be semantically equivalent to first encode", i)
+	}
+}
+
+func TestEncodeNetworkMapEnvelope_ConcurrentEncodesEquivalent(t *testing.T) {
+	c := newTestComponents()
+
+	expected := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c})
+
+	const goroutines = 50
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+	results := make([]*proto.NetworkMapEnvelope, goroutines)
+	for i := 0; i < goroutines; i++ {
+		i := i
+		go func() {
+			defer wg.Done()
+			results[i] = EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c})
+		}()
+	}
+	wg.Wait()
+
+	for i, got := range results {
+		require.NotNil(t, got, "goroutine %d returned nil", i)
+		require.True(t, envelopesEquivalent(expected, got),
+			"goroutine %d produced inequivalent envelope", i)
+	}
+}
+
+func TestEncodeNetworkMapEnvelope_GroupsByAccountPublicId(t *testing.T) {
+	c := newTestComponents()
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Len(t, full.Groups, 2)
+
+	groupByID := map[string]*proto.GroupCompact{}
+	for _, g := range full.Groups {
+		groupByID[g.Id] = g
+	}
+	require.Contains(t, groupByID, "1")
+	require.Contains(t, groupByID, "2")
+	assert.Len(t, groupByID["1"].PeerIndexes, 1)
+	assert.Len(t, groupByID["2"].PeerIndexes, 2)
+}
+
+func TestEncodeNetworkMapEnvelope_PolicyExpansion(t *testing.T) {
+	c := newTestComponents()
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Len(t, full.Policies, 1)
+	pc := full.Policies[0]
+	assert.EqualValues(t, "10", pc.Id)
+	assert.Equal(t, proto.RuleAction_ACCEPT, pc.Action)
+	assert.Equal(t, proto.RuleProtocol_TCP, pc.Protocol)
+	assert.True(t, pc.Bidirectional)
+	assert.Equal(t, []uint32{22, 80}, pc.Ports)
+	require.Len(t, pc.PortRanges, 1)
+	assert.EqualValues(t, 8000, pc.PortRanges[0].Start)
+	assert.EqualValues(t, 8100, pc.PortRanges[0].End)
+	assert.Equal(t, []string{"1"}, pc.SourceGroupIds)
+	assert.Equal(t, []string{"2"}, pc.DestinationGroupIds)
+}
+
+func TestEncodeNetworkMapEnvelope_RouterIndexes(t *testing.T) {
+	c := newTestComponents()
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Len(t, full.RouterPeerIndexes, 1)
+	idx := full.RouterPeerIndexes[0]
+	require.Less(t, int(idx), len(full.Peers))
+	assert.Equal(t, "peerc", full.Peers[idx].DnsLabel)
+}
+
+func TestEncodeNetworkMapEnvelope_DisabledPolicySkipped(t *testing.T) {
+	c := newTestComponents()
+	c.Policies[0].Enabled = false
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	assert.Empty(t, full.Policies)
+}
+
+func TestEncodeNetworkMapEnvelope_TwoPeersSameMalformedKey(t *testing.T) {
+	// Both peers have nil WgPubKey after decode; canonicalize must still
+	// produce a stable order using DnsLabel as a tiebreaker, so 100 encodes
+	// canonicalize identically.
+	c := newTestComponents()
+	c.Peers["peer-a"].Key = "garbage-a-!!!"
+	c.Peers["peer-b"].Key = "garbage-b-!!!"
+
+	expected := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c})
+	for i := 0; i < 100; i++ {
+		got := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c})
+		require.True(t, envelopesEquivalent(expected, got),
+			"encode #%d with two same-key peers must canonicalize equivalently", i)
+	}
+}
+
+func TestEncodeNetworkMapEnvelope_MalformedWgKey(t *testing.T) {
+	c := newTestComponents()
+	c.Peers["peer-a"].Key = "not-base64-!!!"
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Len(t, full.Peers, 3)
+
+	var byLabel = map[string]*proto.PeerCompact{}
+	for _, p := range full.Peers {
+		byLabel[p.DnsLabel] = p
+	}
+	assert.Nil(t, byLabel["peera"].WgPubKey, "peer with malformed key encodes nil WgPubKey")
+	assert.Len(t, byLabel["peerb"].WgPubKey, 32, "other peers retain their key")
+}
+
+func TestEncodeNetworkMapEnvelope_IPv6OnlyPeer(t *testing.T) {
+	c := newTestComponents()
+	v6Only := &nbpeer.Peer{
+		ID:       "peer-v6",
+		Key:      testWgKeyA,
+		IPv6:     netip.AddrFrom16([16]byte{0xfd, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 9}),
+		DNSLabel: "peerv6",
+		Meta:     nbpeer.PeerSystemMeta{WtVersion: "0.40.0"},
+	}
+	c.Peers["peer-v6"] = v6Only
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	var found *proto.PeerCompact
+	for _, p := range full.Peers {
+		if p.DnsLabel == "peerv6" {
+			found = p
+		}
+	}
+	require.NotNil(t, found, "ipv6-only peer must be present")
+	assert.Empty(t, found.Ip, "no IPv4 address → empty Ip")
+	assert.Len(t, found.Ipv6, 16)
+}
+
+func TestEncodeNetworkMapEnvelope_PeerWithoutIP(t *testing.T) {
+	c := newTestComponents()
+	c.Peers["peer-noip"] = &nbpeer.Peer{
+		ID:       "peer-noip",
+		Key:      testWgKeyA,
+		DNSLabel: "peernoip",
+		Meta:     nbpeer.PeerSystemMeta{WtVersion: "0.40.0"},
+	}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	var found *proto.PeerCompact
+	for _, p := range full.Peers {
+		if p.DnsLabel == "peernoip" {
+			found = p
+		}
+	}
+	require.NotNil(t, found)
+	assert.Empty(t, found.Ip)
+	assert.Empty(t, found.Ipv6)
+}
+
+func TestEncodeNetworkMapEnvelope_EmptyInput(t *testing.T) {
+	c := &types.NetworkMapComponents{
+		Network: &types.Network{Identifier: "x", Net: net.IPNet{IP: net.IP{100, 64, 0, 0}, Mask: net.CIDRMask(10, 32)}},
+	}
+
+	env := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c})
+
+	full := env.GetFull()
+	require.NotNil(t, full)
+	assert.Empty(t, full.Peers)
+	assert.Empty(t, full.Groups)
+	assert.Empty(t, full.Policies)
+	assert.Empty(t, full.RouterPeerIndexes)
+	require.NotNil(t, full.AccountSettings, "AccountSettingsCompact must always be emitted (client dereferences it unconditionally)")
+}
+
+func TestEncodeNetworkMapEnvelope_PeerLoginExpirationFields(t *testing.T) {
+	c := newTestComponents()
+	now := time.Date(2024, 1, 2, 3, 4, 5, 0, time.UTC)
+	c.Peers["peer-a"].UserID = "user-1"
+	c.Peers["peer-a"].LoginExpirationEnabled = true
+	c.Peers["peer-a"].LastLogin = &now
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	var pa *proto.PeerCompact
+	for _, p := range full.Peers {
+		if p.DnsLabel == "peera" {
+			pa = p
+		}
+	}
+	require.NotNil(t, pa)
+	assert.True(t, pa.AddedWithSsoLogin)
+	assert.True(t, pa.LoginExpirationEnabled)
+	assert.Equal(t, now.UnixNano(), pa.LastLoginUnixNano)
+
+	// peer-b has no UserID and no LastLogin → all fields zero-value.
+	var pb *proto.PeerCompact
+	for _, p := range full.Peers {
+		if p.DnsLabel == "peerb" {
+			pb = p
+		}
+	}
+	require.NotNil(t, pb)
+	assert.False(t, pb.AddedWithSsoLogin)
+	assert.False(t, pb.LoginExpirationEnabled)
+	assert.Zero(t, pb.LastLoginUnixNano)
+}
+
+func TestEncodeNetworkMapEnvelope_RoutesRoundTrip(t *testing.T) {
+	c := newTestComponents()
+	c.Routes = []*nbroute.Route{
+		{
+			ID:                  "route-peer",
+			PublicID:            "100",
+			NetID:               "net-A",
+			Description:         "via peer-c",
+			Network:             netip.MustParsePrefix("10.0.0.0/16"),
+			Peer:                "peer-c", // peer ID, not WG key
+			Groups:              []string{"group-src"},
+			AccessControlGroups: []string{"group-dst"},
+			Enabled:             true,
+		},
+		{
+			ID:         "route-peergroup",
+			PublicID:   "101",
+			NetID:      "net-B",
+			Network:    netip.MustParsePrefix("10.1.0.0/16"),
+			PeerGroups: []string{"group-src", "group-dst"},
+			Enabled:    true,
+		},
+	}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Len(t, full.Routes, 2)
+	byNetID := map[string]*proto.RouteRaw{}
+	for _, r := range full.Routes {
+		byNetID[r.NetId] = r
+	}
+
+	r1 := byNetID["net-A"]
+	require.NotNil(t, r1)
+	assert.True(t, r1.PeerIndexSet, "route with peer must set peer_index_set")
+	require.Less(t, int(r1.PeerIndex), len(full.Peers))
+	assert.Equal(t, "peerc", full.Peers[r1.PeerIndex].DnsLabel)
+	assert.Equal(t, []string{"1"}, r1.GroupIds, "group-src has AccountSeqID 1")
+	assert.Equal(t, []string{"2"}, r1.AccessControlGroupIds, "group-dst has AccountSeqID 2")
+	assert.Empty(t, r1.PeerGroupIds)
+
+	r2 := byNetID["net-B"]
+	require.NotNil(t, r2)
+	assert.False(t, r2.PeerIndexSet, "route with peer_groups must NOT set peer_index_set")
+	assert.ElementsMatch(t, []string{"1", "2"}, r2.PeerGroupIds)
+}
+
+func TestEncodeNetworkMapEnvelope_RouteWithMissingPeerLeavesIndexUnset(t *testing.T) {
+	c := newTestComponents()
+	c.Routes = []*nbroute.Route{{
+		ID:       "route-x",
+		PublicID: "100",
+		Peer:     "peer-not-in-components",
+		Network:  netip.MustParsePrefix("10.0.0.0/16"),
+		Enabled:  true,
+	}}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Len(t, full.Routes, 1)
+	assert.False(t, full.Routes[0].PeerIndexSet,
+		"missing peer reference must not pretend to point at peer index 0")
+}
+
+func TestEncodeNetworkMapEnvelope_ResourceOnlyPolicyShippedAndIndexed(t *testing.T) {
+	c := newTestComponents()
+	// Policy that exists ONLY in ResourcePoliciesMap, not in c.Policies. This
+	// is the I1 case — without unionPolicies the encoder would silently
+	// drop it from the wire.
+	resourceOnlyPolicy := &types.Policy{
+		ID: "pol-resource", PublicID: "99", Enabled: true,
+		Rules: []*types.PolicyRule{{
+			ID: "rule-r", Enabled: true, Action: types.PolicyTrafficActionAccept,
+			Protocol:     types.PolicyRuleProtocolTCP,
+			Sources:      []string{"group-src"},
+			Destinations: []string{"group-dst"},
+		}},
+	}
+	c.ResourcePoliciesMap = map[string][]*types.Policy{
+		"resource-x": {c.Policies[0], resourceOnlyPolicy}, // shared + resource-only
+	}
+	// Resource must appear in components.NetworkResources with a seq id —
+	// encoder uses that to translate the xid map key to uint32.
+	c.NetworkResources = []*resourceTypes.NetworkResource{
+		{ID: "resource-x", PublicID: "77", Name: "res-x", Enabled: true},
+	}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Len(t, full.Policies, 2, "encoded policies must include both peer-traffic and resource-only")
+
+	policyByID := map[string]*proto.PolicyCompact{}
+	policyIds := make([]string, 0)
+	for _, p := range full.Policies {
+		policyByID[p.Id] = p
+		policyIds = append(policyIds, p.Id)
+	}
+	require.Contains(t, policyByID, "10", "original peer-traffic policy id 10")
+	require.Contains(t, policyByID, "99", "resource-only policy id 99")
+
+	require.Contains(t, full.ResourcePoliciesMap, "77")
+	ids := full.ResourcePoliciesMap["77"].Ids
+	require.Len(t, ids, 2)
+	assert.ElementsMatch(t, policyIds, ids,
+		"resource policies map must reference both wire policy indexes")
+}
+
+func TestEncodeNetworkMapEnvelope_NameServerGroups(t *testing.T) {
+	c := newTestComponents()
+	c.NameServerGroups = []*nbdns.NameServerGroup{{
+		ID: "nsg-1", PublicID: "50", Name: "Main", Description: "primary",
+		NameServers: []nbdns.NameServer{{
+			IP: netip.MustParseAddr("8.8.8.8"), NSType: nbdns.UDPNameServerType, Port: 53,
+		}},
+		Groups:  []string{"group-src", "group-not-persisted"},
+		Primary: true, Enabled: true,
+		Domains: []string{"corp.example"},
+	}}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Len(t, full.NameserverGroups, 1)
+	nsg := full.NameserverGroups[0]
+	assert.EqualValues(t, "50", nsg.Id)
+	assert.True(t, nsg.Primary)
+	require.Len(t, nsg.Nameservers, 1)
+	assert.Equal(t, "8.8.8.8", nsg.Nameservers[0].IP)
+	assert.Equal(t, []string{"1"}, nsg.GroupIds)
+}
+
+func TestEncodeNetworkMapEnvelope_PostureFailedPeers(t *testing.T) {
+	c := newTestComponents()
+	c.PostureCheckXIDToPublicID = map[string]string{"check-1": "33"}
+	c.PostureFailedPeers = map[string]map[string]struct{}{
+		"check-1": {
+			"peer-a":              {},
+			"peer-b":              {},
+			"peer-not-in-account": {},
+		},
+	}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Contains(t, full.PostureFailedPeers, "33")
+	idxs := full.PostureFailedPeers["33"].PeerIndexes
+	assert.Len(t, idxs, 2, "missing peer is silently dropped (filterPostureFailedPeers guarantees presence in real data)")
+}
+
+func TestEncodeNetworkMapEnvelope_RoutersMap(t *testing.T) {
+	c := newTestComponents()
+	c.NetworkXIDToPublicID = map[string]string{"net-1": "5"}
+	c.RoutersMap = map[string]map[string]*routerTypes.NetworkRouter{
+		"net-1": {
+			"peer-c": {
+				ID: "router-1", PublicID: "200",
+				Peer: "peer-c", Masquerade: true, Metric: 10, Enabled: true,
+			},
+		},
+	}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Contains(t, full.RoutersMap, "5")
+	entries := full.RoutersMap["5"].Entries
+	require.Len(t, entries, 1)
+	e := entries[0]
+	assert.EqualValues(t, "200", e.Id)
+	assert.True(t, e.PeerIndexSet)
+	require.Less(t, int(e.PeerIndex), len(full.Peers))
+	assert.Equal(t, "peerc", full.Peers[e.PeerIndex].DnsLabel)
+	assert.True(t, e.Masquerade)
+	assert.EqualValues(t, 10, e.Metric)
+	assert.True(t, e.Enabled)
+}
+
+func TestEncodeNetworkMapEnvelope_RouterPeerNotInComponentsPeers(t *testing.T) {
+	// Router peer in c.RouterPeers but NOT in c.Peers (validation may have
+	// filtered it). indexRouterPeers runs before encodeRoutersMap, so the
+	// peer_index reference must still resolve.
+	c := newTestComponents()
+	delete(c.Peers, "peer-c")
+	routerPeer := &nbpeer.Peer{
+		ID: "peer-c", Key: testWgKeyC, IP: netip.AddrFrom4([4]byte{100, 64, 0, 3}),
+		DNSLabel: "peerc", Meta: nbpeer.PeerSystemMeta{WtVersion: "0.40.0"},
+	}
+	c.RouterPeers = map[string]*nbpeer.Peer{"peer-c": routerPeer}
+	c.NetworkXIDToPublicID = map[string]string{"net-1": "5"}
+	c.RoutersMap = map[string]map[string]*routerTypes.NetworkRouter{
+		"net-1": {"peer-c": {ID: "r-1", PublicID: "1", Peer: "peer-c", Enabled: true}},
+	}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Contains(t, full.RoutersMap, "5")
+	require.Len(t, full.RoutersMap["5"].Entries, 1)
+	e := full.RoutersMap["5"].Entries[0]
+	assert.True(t, e.PeerIndexSet, "router peer must be indexed even when not in c.Peers")
+}
+
+func TestEncodeNetworkMapEnvelope_GroupIDToUserIDs(t *testing.T) {
+	c := newTestComponents()
+	c.GroupIDToUserIDs = map[string][]string{
+		"group-src":     {"user-1", "user-2"},
+		"group-missing": {"user-4"}, // group not in components → drop
+	}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.Len(t, full.GroupIdToUserIds, 1, "only present groups survive")
+	require.Contains(t, full.GroupIdToUserIds, "1")
+	assert.ElementsMatch(t, []string{"user-1", "user-2"}, full.GroupIdToUserIds["1"].UserIds)
+}
+
+func TestToProxyPatch_EmptyInputReturnsNil(t *testing.T) {
+	assert.Nil(t, toProxyPatch(nil, "netbird.cloud", false, false))
+	assert.Nil(t, toProxyPatch(&types.NetworkMap{}, "netbird.cloud", false, false),
+		"empty NetworkMap (no peers, rules, routes etc) → nil patch so proto3 omits the field")
+}
+
+func TestToProxyPatch_PopulatesAllFields(t *testing.T) {
+	nm := &types.NetworkMap{
+		Peers: []*nbpeer.Peer{{
+			ID: "ext-peer", Key: testWgKeyA, IP: netip.AddrFrom4([4]byte{100, 64, 0, 9}),
+			DNSLabel: "extpeer", Meta: nbpeer.PeerSystemMeta{WtVersion: "0.40.0"},
+		}},
+		FirewallRules: []*types.FirewallRule{{
+			PeerIP: "100.64.0.9", Action: "accept", Direction: 0, Protocol: "tcp",
+		}},
+	}
+
+	patch := toProxyPatch(nm, "netbird.cloud", false, false)
+
+	require.NotNil(t, patch)
+	assert.Len(t, patch.Peers, 1)
+	assert.Len(t, patch.FirewallRules, 1)
+}
+
+// TestEncodeNetworkMapEnvelope_ProxyPatchPropagated covers the ProxyPatch
+// pass-through in both encoder branches (normal path + nil-Components
+// graceful-degrade). Guards against a regression that drops `ProxyPatch:`
+// from one of the envelope struct literals.
+func TestEncodeNetworkMapEnvelope_ProxyPatchPropagated(t *testing.T) {
+	patch := &proto.ProxyPatch{
+		ForwardingRules: []*proto.ForwardingRule{{
+			Protocol:          proto.RuleProtocol_TCP,
+			DestinationPort:   &proto.PortInfo{PortSelection: &proto.PortInfo_Port{Port: 80}},
+			TranslatedAddress: net.IPv4(10, 0, 0, 1).To4(),
+			TranslatedPort:    &proto.PortInfo{PortSelection: &proto.PortInfo_Port{Port: 8080}},
+		}},
+	}
+
+	t.Run("normal_path", func(t *testing.T) {
+		c := newTestComponents()
+		full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{
+			Components: c,
+			ProxyPatch: patch,
+		}).GetFull()
+
+		require.NotNil(t, full.ProxyPatch, "ProxyPatch must propagate through the normal encode path")
+		assert.Len(t, full.ProxyPatch.ForwardingRules, 1)
+	})
+
+	t.Run("empty_components_graceful_degrade", func(t *testing.T) {
+		full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{
+			Components: emptyNetworkMapComponents(),
+			ProxyPatch: patch,
+		}).GetFull()
+
+		require.NotNil(t, full.ProxyPatch, "ProxyPatch must propagate through the nil-Components branch too")
+		assert.Len(t, full.ProxyPatch.ForwardingRules, 1)
+	})
+}
+
+func TestEncodeNetworkMapEnvelope_NilComponentsGracefulDegrade(t *testing.T) {
+	// nil Components → minimal envelope, no crash. Matches the legacy
+	// behaviour for missing/unvalidated peers.
+	env := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{
+		Components: emptyNetworkMapComponents(),
+		DNSDomain:  "netbird.cloud",
+	})
+
+	require.NotNil(t, env)
+	full := env.GetFull()
+	require.NotNil(t, full)
+	require.NotNil(t, full.AccountSettings, "AccountSettings must always be non-nil")
+	assert.Equal(t, "netbird.cloud", full.DnsDomain)
+	assert.Len(t, full.Peers, 1)
+	assert.Empty(t, full.Policies)
+}
+
+func TestEncodeNetworkMapEnvelope_AccountSettingsAlwaysEmitted(t *testing.T) {
+	c := &types.NetworkMapComponents{
+		Network: &types.Network{Identifier: "x", Net: net.IPNet{IP: net.IP{100, 64, 0, 0}, Mask: net.CIDRMask(10, 32)}},
+		// AccountSettings deliberately nil
+	}
+
+	full := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{Components: c}).GetFull()
+
+	require.NotNil(t, full.AccountSettings, "client dereferences AccountSettings unconditionally during Calculate(); a nil here would crash the receiver")
+	assert.False(t, full.AccountSettings.PeerLoginExpirationEnabled)
+	assert.Zero(t, full.AccountSettings.PeerLoginExpirationNs)
+}
+
+func emptyNetworkMapComponents() *types.NetworkMapComponents {
+	return types.EmptyNetworkMapComponents(
+		&types.NetworkMapComponents{
+			PeerID: "peer-id", Peers: map[string]*nbpeer.Peer{"peer-id": {}}},
+	)
+}

management/internals/shared/grpc/components_envelope_response.go

@@ -0,0 +1,200 @@
+package grpc
+
+import (
+	"context"
+
+	integrationsConfig "github.com/netbirdio/management-integrations/integrations/config"
+
+	"github.com/netbirdio/netbird/client/ssh/auth"
+	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"github.com/netbirdio/netbird/management/server/posture"
+	"github.com/netbirdio/netbird/management/server/types"
+	sharedgrpc "github.com/netbirdio/netbird/shared/management/grpc"
+	"github.com/netbirdio/netbird/shared/management/networkmap"
+	"github.com/netbirdio/netbird/shared/management/proto"
+)
+
+// ToComponentSyncResponse builds a SyncResponse carrying the compact
+// NetworkMapEnvelope for capability-aware peers. The legacy proto.NetworkMap
+// field is intentionally left empty — capable peers ignore it and the
+// envelope alone is the authoritative wire shape.
+//
+// PeerConfig is computed once server-side using the receiving peer's own
+// account-level network metadata. EnableSSH inside PeerConfig is left at
+// peer.SSHEnabled (the peer's local setting); account-policy-driven SSH is
+// computed by the client from the envelope's GroupIDToUserIDs / AllowedUserIDs
+// inside Calculate(), so the SshConfig.SshEnabled bit may flip true on the
+// client even though the server-side PeerConfig reports false.
+func ToComponentSyncResponse(
+	ctx context.Context,
+	config *nbconfig.Config,
+	httpConfig *nbconfig.HttpServerConfig,
+	deviceFlowConfig *nbconfig.DeviceAuthorizationFlow,
+	peer *nbpeer.Peer,
+	turnCredentials *Token,
+	relayCredentials *Token,
+	components *types.NetworkMapComponents,
+	proxyPatch *types.NetworkMap,
+	dnsName string,
+	checks []*posture.Checks,
+	settings *types.Settings,
+	extraSettings *types.ExtraSettings,
+	peerGroups []string,
+	dnsFwdPort int64,
+) *proto.SyncResponse {
+	//
+	// 'component' parameter is expected to never be nil
+	// 'peer' parameter is expected to never be nil
+	//
+	// TODO (dmitri) consider using invariants?
+	//
+	enableSSH := computeSSHEnabledForPeer(components, peer)
+	peerConfig := toPeerConfig(peer, components.Network, dnsName, settings, httpConfig, deviceFlowConfig, enableSSH)
+
+	includeIPv6 := peer.SupportsIPv6() && peer.IPv6.IsValid()
+	useSourcePrefixes := peer.SupportsSourcePrefixes()
+
+	userIDClaim := auth.DefaultUserIDClaim
+	if httpConfig != nil && httpConfig.AuthUserIDClaim != "" {
+		userIDClaim = httpConfig.AuthUserIDClaim
+	}
+
+	envelope := EncodeNetworkMapEnvelope(ComponentsEnvelopeInput{
+		Components:       components,
+		PeerConfig:       peerConfig,
+		DNSDomain:        dnsName,
+		DNSForwarderPort: dnsFwdPort,
+		UserIDClaim:      userIDClaim,
+		ProxyPatch:       toProxyPatch(proxyPatch, dnsName, includeIPv6, useSourcePrefixes),
+	})
+
+	resp := &proto.SyncResponse{
+		PeerConfig:         peerConfig,
+		NetworkMapEnvelope: envelope,
+		Checks:             toProtocolChecks(ctx, checks),
+		Version:            int32(sharedgrpc.ComponentNetworkMap),
+	}
+
+	nbConfig := toNetbirdConfig(config, turnCredentials, relayCredentials, extraSettings, settings)
+	resp.NetbirdConfig = integrationsConfig.ExtendNetBirdConfig(peer.ID, peerGroups, nbConfig, extraSettings)
+
+	// settings == nil → field stays nil → "no info in this snapshot", client
+	// preserves the deadline it already had. settings non-nil → emit either a
+	// valid deadline or the explicit-zero "disabled" sentinel via
+	// encodeSessionExpiresAt.
+	if settings != nil {
+		resp.SessionExpiresAt = encodeSessionExpiresAt(
+			peer.SessionExpiresAt(settings.PeerLoginExpirationEnabled, settings.PeerLoginExpiration),
+		)
+	}
+
+	return resp
+}
+
+// toProxyPatch converts a proxy-injected *types.NetworkMap into the wire
+// patch the components envelope ships alongside. Returns nil when there are
+// no fragments to merge — proto3 omits a nil message field, so the receiver
+// sees no patch and skips the merge step entirely.
+//
+// We reuse the legacy proto-conversion helpers (toProtocolRoutes,
+// toProtocolFirewallRules, toProtocolRoutesFirewallRules,
+// appendRemotePeerConfig, ForwardingRule.ToProto) because the proxy
+// delivers fragments pre-expanded — there's no raw component shape to
+// derive them from. Components purity isn't violated: proxy data isn't
+// policy-graph-derived, it's externally injected post-Calculate, so the
+// client merges it on top of its locally-computed NetworkMap.
+func toProxyPatch(nm *types.NetworkMap, dnsName string, includeIPv6, useSourcePrefixes bool) *proto.ProxyPatch {
+	if nm == nil {
+		return nil
+	}
+	if len(nm.Peers) == 0 && len(nm.OfflinePeers) == 0 && len(nm.FirewallRules) == 0 &&
+		len(nm.Routes) == 0 && len(nm.RoutesFirewallRules) == 0 && len(nm.ForwardingRules) == 0 {
+		return nil
+	}
+
+	patch := &proto.ProxyPatch{
+		Peers:              networkmap.AppendRemotePeerConfig(nil, nm.Peers, dnsName, includeIPv6),
+		OfflinePeers:       networkmap.AppendRemotePeerConfig(nil, nm.OfflinePeers, dnsName, includeIPv6),
+		FirewallRules:      networkmap.ToProtocolFirewallRules(nm.FirewallRules, includeIPv6, useSourcePrefixes),
+		Routes:             networkmap.ToProtocolRoutes(nm.Routes),
+		RouteFirewallRules: networkmap.ToProtocolRoutesFirewallRules(nm.RoutesFirewallRules),
+	}
+	if len(nm.ForwardingRules) > 0 {
+		patch.ForwardingRules = make([]*proto.ForwardingRule, 0, len(nm.ForwardingRules))
+		for _, r := range nm.ForwardingRules {
+			patch.ForwardingRules = append(patch.ForwardingRules, r.ToProto())
+		}
+	}
+	return patch
+}
+
+// computeSSHEnabledForPeer mirrors the SSH-server-activation bit that
+// Calculate() folds into NetworkMap.EnableSSH. Components-format peers
+// receive a freshly-computed PeerConfig.SshConfig.SshEnabled at sync time;
+// without this helper the field would be incorrectly false for any peer
+// that's the destination of an SSH-enabling policy without having
+// peer.SSHEnabled set locally.
+//
+// Mirrors the two activation paths Calculate() uses:
+//  1. Explicit: rule.Protocol == NetbirdSSH and peer is in the rule's
+//     destinations.
+//  2. Legacy implicit: rule covers TCP/22 or TCP/22022 (or ALL), peer is in
+//     destinations, AND the peer has SSHEnabled set locally — this is the
+//     "allow-all/TCP-22 implies SSH activation for SSH-capable peers" path.
+//
+// The full SSH AuthorizedUsers map is still produced by the client when it
+// runs Calculate() over the envelope.
+func computeSSHEnabledForPeer(c *types.NetworkMapComponents, peer *nbpeer.Peer) bool {
+	if c == nil || peer == nil {
+		return false
+	}
+	// Mirror Calculate's `getAllPeersFromGroups` invariant: target peer must
+	// exist in c.Peers, otherwise no rule applies to it.
+	if _, ok := c.Peers[peer.ID]; !ok {
+		return false
+	}
+	for _, policy := range c.Policies {
+		if policy == nil || !policy.Enabled {
+			continue
+		}
+		for _, rule := range policy.Rules {
+			if ruleEnablesSSHForPeer(c, rule, peer) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// ruleEnablesSSHForPeer returns true when rule is active, targets peer, and
+// either explicitly authorises SSH or covers the legacy TCP/22 path while the
+// peer itself has SSH enabled locally.
+func ruleEnablesSSHForPeer(c *types.NetworkMapComponents, rule *types.PolicyRule, peer *nbpeer.Peer) bool {
+	if rule == nil || !rule.Enabled {
+		return false
+	}
+	if !peerInDestinations(c, rule, peer.ID) {
+		return false
+	}
+	if rule.Protocol == types.PolicyRuleProtocolNetbirdSSH {
+		return true
+	}
+	return peer.SSHEnabled && types.PolicyRuleImpliesLegacySSH(rule)
+}
+
+// peerInDestinations reports whether peerID is in any of rule.Destinations'
+// groups (or matches DestinationResource if it's a peer-typed resource —
+// for non-peer types Calculate falls through to group lookup, so we mirror
+// that exactly to avoid silent divergence).
+func peerInDestinations(c *types.NetworkMapComponents, rule *types.PolicyRule, peerID string) bool {
+	if rule.DestinationResource.Type == types.ResourceTypePeer && rule.DestinationResource.ID != "" {
+		return rule.DestinationResource.ID == peerID
+	}
+	for _, groupID := range rule.Destinations {
+		if c.IsPeerInGroup(peerID, groupID) {
+			return true
+		}
+	}
+	return false
+}

management/internals/shared/grpc/components_envelope_response_test.go

@@ -0,0 +1,184 @@
+package grpc
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"github.com/netbirdio/netbird/management/server/types"
+)
+
+// TestComputeSSHEnabledForPeer covers both Calculate-mirroring branches:
+// explicit NetbirdSSH protocol, and the legacy implicit case where a
+// TCP/22 (or 22022 / ALL / port-range-covering-22) rule activates SSH when
+// the destination peer has SSHEnabled=true locally.
+func TestComputeSSHEnabledForPeer(t *testing.T) {
+	const targetPeerID = "target"
+	const targetGroupID = "g_dst"
+
+	mkComponents := func(rule *types.PolicyRule, sshEnabled bool) (*types.NetworkMapComponents, *nbpeer.Peer) {
+		peer := &nbpeer.Peer{ID: targetPeerID, SSHEnabled: sshEnabled}
+		group := &types.Group{ID: targetGroupID, Name: "dst", Peers: []string{targetPeerID}}
+		return &types.NetworkMapComponents{
+			Peers:  map[string]*nbpeer.Peer{targetPeerID: peer},
+			Groups: map[string]*types.Group{targetGroupID: group},
+			Policies: []*types.Policy{{
+				ID:      "p",
+				Enabled: true,
+				Rules:   []*types.PolicyRule{rule},
+			}},
+		}, peer
+	}
+
+	cases := []struct {
+		name        string
+		peerSSH     bool
+		rule        types.PolicyRule
+		wantEnabled bool
+	}{
+		{
+			name:    "explicit-netbird-ssh-activates-regardless-of-peer-ssh",
+			peerSSH: false,
+			rule: types.PolicyRule{
+				Enabled: true, Protocol: types.PolicyRuleProtocolNetbirdSSH,
+				Destinations: []string{targetGroupID},
+			},
+			wantEnabled: true,
+		},
+		{
+			name:    "implicit-tcp-22-with-peer-ssh",
+			peerSSH: true,
+			rule: types.PolicyRule{
+				Enabled: true, Protocol: types.PolicyRuleProtocolTCP, Ports: []string{"22"},
+				Destinations: []string{targetGroupID},
+			},
+			wantEnabled: true,
+		},
+		{
+			name:    "implicit-tcp-22-without-peer-ssh-disabled",
+			peerSSH: false,
+			rule: types.PolicyRule{
+				Enabled: true, Protocol: types.PolicyRuleProtocolTCP, Ports: []string{"22"},
+				Destinations: []string{targetGroupID},
+			},
+			wantEnabled: false,
+		},
+		{
+			name:    "implicit-tcp-22022-with-peer-ssh",
+			peerSSH: true,
+			rule: types.PolicyRule{
+				Enabled: true, Protocol: types.PolicyRuleProtocolTCP, Ports: []string{"22022"},
+				Destinations: []string{targetGroupID},
+			},
+			wantEnabled: true,
+		},
+		{
+			name:    "implicit-all-protocol-with-peer-ssh",
+			peerSSH: true,
+			rule: types.PolicyRule{
+				Enabled: true, Protocol: types.PolicyRuleProtocolALL,
+				Destinations: []string{targetGroupID},
+			},
+			wantEnabled: true,
+		},
+		{
+			name:    "implicit-port-range-covers-22",
+			peerSSH: true,
+			rule: types.PolicyRule{
+				Enabled:      true,
+				Protocol:     types.PolicyRuleProtocolTCP,
+				PortRanges:   []types.RulePortRange{{Start: 20, End: 30}},
+				Destinations: []string{targetGroupID},
+			},
+			wantEnabled: true,
+		},
+		{
+			name:    "tcp-80-no-ssh",
+			peerSSH: true,
+			rule: types.PolicyRule{
+				Enabled: true, Protocol: types.PolicyRuleProtocolTCP, Ports: []string{"80"},
+				Destinations: []string{targetGroupID},
+			},
+			wantEnabled: false,
+		},
+		{
+			name:    "disabled-rule-skipped",
+			peerSSH: true,
+			rule: types.PolicyRule{
+				Enabled: false, Protocol: types.PolicyRuleProtocolNetbirdSSH,
+				Destinations: []string{targetGroupID},
+			},
+			wantEnabled: false,
+		},
+		{
+			name:    "peer-not-in-destinations",
+			peerSSH: true,
+			rule: types.PolicyRule{
+				Enabled: true, Protocol: types.PolicyRuleProtocolNetbirdSSH,
+				Destinations: []string{"g_other"}, // target not in this group
+			},
+			wantEnabled: false,
+		},
+		{
+			name:    "peer-typed-destination-resource-matches",
+			peerSSH: false,
+			rule: types.PolicyRule{
+				Enabled:             true,
+				Protocol:            types.PolicyRuleProtocolNetbirdSSH,
+				DestinationResource: types.Resource{ID: targetPeerID, Type: types.ResourceTypePeer},
+			},
+			wantEnabled: true,
+		},
+		{
+			name:    "non-peer-destination-resource-falls-through-to-groups",
+			peerSSH: false,
+			rule: types.PolicyRule{
+				Enabled:             true,
+				Protocol:            types.PolicyRuleProtocolNetbirdSSH,
+				DestinationResource: types.Resource{ID: targetPeerID, Type: "host"}, // wrong type
+				Destinations:        []string{targetGroupID},                        // saved by group fallback
+			},
+			wantEnabled: true,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c, peer := mkComponents(&tc.rule, tc.peerSSH)
+			got := computeSSHEnabledForPeer(c, peer)
+			assert.Equal(t, tc.wantEnabled, got)
+		})
+	}
+}
+
+// TestComputeSSHEnabledForPeer_TargetMissingFromComponents covers the
+// belt-and-suspenders presence guard mirroring Calculate's
+// getAllPeersFromGroups invariant.
+func TestComputeSSHEnabledForPeer_TargetMissingFromComponents(t *testing.T) {
+	peer := &nbpeer.Peer{ID: "missing", SSHEnabled: true}
+	c := &types.NetworkMapComponents{
+		Peers: map[string]*nbpeer.Peer{}, // target peer NOT present
+		Groups: map[string]*types.Group{
+			"g": {ID: "g", Peers: []string{"missing"}},
+		},
+		Policies: []*types.Policy{{
+			ID: "p", Enabled: true,
+			Rules: []*types.PolicyRule{{
+				Enabled: true, Protocol: types.PolicyRuleProtocolNetbirdSSH,
+				Destinations: []string{"g"},
+			}},
+		}},
+	}
+	assert.False(t, computeSSHEnabledForPeer(c, peer),
+		"missing target peer must short-circuit to false, not consult policies")
+}
+
+// TestComputeSSHEnabledForPeer_NilInputs guards the cheap nil-checks at
+// function entry — Calculate doesn't accept nil either, but the helper is
+// exported indirectly via ToComponentSyncResponse and may receive nil
+// components on graceful-degrade paths.
+func TestComputeSSHEnabledForPeer_NilInputs(t *testing.T) {
+	assert.False(t, computeSSHEnabledForPeer(nil, &nbpeer.Peer{ID: "x"}))
+	assert.False(t, computeSSHEnabledForPeer(&types.NetworkMapComponents{}, nil))
+}

management/internals/shared/grpc/conversion.go

@@ -10,24 +10,20 @@ import (
 
 	"github.com/hashicorp/go-version"
 	nbversion "github.com/netbirdio/netbird/version"
-	log "github.com/sirupsen/logrus"
-	goproto "google.golang.org/protobuf/proto"
 	"google.golang.org/protobuf/types/known/timestamppb"
 
 	integrationsConfig "github.com/netbirdio/management-integrations/integrations/config"
 
 	"github.com/netbirdio/netbird/client/ssh/auth"
 
-	nbdns "github.com/netbirdio/netbird/dns"
 	"github.com/netbirdio/netbird/management/internals/controllers/network_map/controller/cache"
 	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
 	nbpeer "github.com/netbirdio/netbird/management/server/peer"
 	"github.com/netbirdio/netbird/management/server/posture"
 	"github.com/netbirdio/netbird/management/server/types"
-	nbroute "github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/networkmap"
 	"github.com/netbirdio/netbird/shared/management/proto"
 	"github.com/netbirdio/netbird/shared/netiputil"
-	"github.com/netbirdio/netbird/shared/sshauth"
 )
 
 const (
@@ -169,8 +165,8 @@ func ToSyncResponse(ctx context.Context, config *nbconfig.Config, httpConfig *nb
 		PeerConfig: toPeerConfig(peer, networkMap.Network, dnsName, settings, httpConfig, deviceFlowConfig, networkMap.EnableSSH),
 		NetworkMap: &proto.NetworkMap{
 			Serial:     networkMap.Network.CurrentSerial(),
-			Routes:     toProtocolRoutes(networkMap.Routes),
-			DNSConfig:  toProtocolDNSConfig(networkMap.DNSConfig, dnsCache, dnsFwdPort),
+			Routes:     networkmap.ToProtocolRoutes(networkMap.Routes),
+			DNSConfig:  networkmap.ToProtocolDNSConfig(networkMap.DNSConfig, dnsCache, dnsFwdPort),
 			PeerConfig: toPeerConfig(peer, networkMap.Network, dnsName, settings, httpConfig, deviceFlowConfig, networkMap.EnableSSH),
 		},
 		Checks: toProtocolChecks(ctx, checks),
@@ -183,7 +179,7 @@ func ToSyncResponse(ctx context.Context, config *nbconfig.Config, httpConfig *nb
 	response.NetworkMap.PeerConfig = response.PeerConfig
 
 	remotePeers := make([]*proto.RemotePeerConfig, 0, len(networkMap.Peers)+len(networkMap.OfflinePeers))
-	remotePeers = appendRemotePeerConfig(remotePeers, networkMap.Peers, dnsName, includeIPv6)
+	remotePeers = networkmap.AppendRemotePeerConfig(remotePeers, networkMap.Peers, dnsName, includeIPv6)
 
 	if !shouldSkipSendingDeprecatedRemotePeers(peer.Meta.WtVersion) {
 		response.RemotePeers = remotePeers
@@ -193,13 +189,13 @@ func ToSyncResponse(ctx context.Context, config *nbconfig.Config, httpConfig *nb
 	response.RemotePeersIsEmpty = len(remotePeers) == 0
 	response.NetworkMap.RemotePeersIsEmpty = response.RemotePeersIsEmpty
 
-	response.NetworkMap.OfflinePeers = appendRemotePeerConfig(nil, networkMap.OfflinePeers, dnsName, includeIPv6)
+	response.NetworkMap.OfflinePeers = networkmap.AppendRemotePeerConfig(nil, networkMap.OfflinePeers, dnsName, includeIPv6)
 
-	firewallRules := toProtocolFirewallRules(networkMap.FirewallRules, includeIPv6, useSourcePrefixes)
+	firewallRules := networkmap.ToProtocolFirewallRules(networkMap.FirewallRules, includeIPv6, useSourcePrefixes)
 	response.NetworkMap.FirewallRules = firewallRules
 	response.NetworkMap.FirewallRulesIsEmpty = len(firewallRules) == 0
 
-	routesFirewallRules := toProtocolRoutesFirewallRules(networkMap.RoutesFirewallRules)
+	routesFirewallRules := networkmap.ToProtocolRoutesFirewallRules(networkMap.RoutesFirewallRules)
 	response.NetworkMap.RoutesFirewallRules = routesFirewallRules
 	response.NetworkMap.RoutesFirewallRulesIsEmpty = len(routesFirewallRules) == 0
 
@@ -212,7 +208,7 @@ func ToSyncResponse(ctx context.Context, config *nbconfig.Config, httpConfig *nb
 	}
 
 	if networkMap.AuthorizedUsers != nil {
-		hashedUsers, machineUsers := buildAuthorizedUsersProto(ctx, networkMap.AuthorizedUsers)
+		hashedUsers, machineUsers := networkmap.BuildAuthorizedUsersProto(ctx, networkMap.AuthorizedUsers)
 		userIDClaim := auth.DefaultUserIDClaim
 		if httpConfig != nil && httpConfig.AuthUserIDClaim != "" {
 			userIDClaim = httpConfig.AuthUserIDClaim
@@ -252,33 +248,6 @@ func encodeSessionExpiresAt(deadline time.Time) *timestamppb.Timestamp {
 	return timestamppb.New(deadline)
 }
 
-func buildAuthorizedUsersProto(ctx context.Context, authorizedUsers map[string]map[string]struct{}) ([][]byte, map[string]*proto.MachineUserIndexes) {
-	userIDToIndex := make(map[string]uint32)
-	var hashedUsers [][]byte
-	machineUsers := make(map[string]*proto.MachineUserIndexes, len(authorizedUsers))
-
-	for machineUser, users := range authorizedUsers {
-		indexes := make([]uint32, 0, len(users))
-		for userID := range users {
-			idx, exists := userIDToIndex[userID]
-			if !exists {
-				hash, err := sshauth.HashUserID(userID)
-				if err != nil {
-					log.WithContext(ctx).Errorf("failed to hash user id %s: %v", userID, err)
-					continue
-				}
-				idx = uint32(len(hashedUsers))
-				userIDToIndex[userID] = idx
-				hashedUsers = append(hashedUsers, hash[:])
-			}
-			indexes = append(indexes, idx)
-		}
-		machineUsers[machineUser] = &proto.MachineUserIndexes{Indexes: indexes}
-	}
-
-	return hashedUsers, machineUsers
-}
-
 func shouldSkipSendingDeprecatedRemotePeers(peerVersion string) bool {
 	if nbversion.IsDevelopmentVersion(peerVersion) {
 		return true
@@ -292,51 +261,6 @@ func shouldSkipSendingDeprecatedRemotePeers(peerVersion string) bool {
 	return precomputedDeprecatedRemotePeersConstraint.Check(peerNBVersion)
 }
 
-func appendRemotePeerConfig(dst []*proto.RemotePeerConfig, peers []*nbpeer.Peer, dnsName string, includeIPv6 bool) []*proto.RemotePeerConfig {
-	for _, rPeer := range peers {
-		allowedIPs := []string{rPeer.IP.String() + "/32"}
-		if includeIPv6 && rPeer.IPv6.IsValid() {
-			allowedIPs = append(allowedIPs, rPeer.IPv6.String()+"/128")
-		}
-		dst = append(dst, &proto.RemotePeerConfig{
-			WgPubKey:     rPeer.Key,
-			AllowedIps:   allowedIPs,
-			SshConfig:    &proto.SSHConfig{SshPubKey: []byte(rPeer.SSHKey)},
-			Fqdn:         rPeer.FQDN(dnsName),
-			AgentVersion: rPeer.Meta.WtVersion,
-		})
-	}
-	return dst
-}
-
-// toProtocolDNSConfig converts nbdns.Config to proto.DNSConfig using the cache
-func toProtocolDNSConfig(update nbdns.Config, cache *cache.DNSConfigCache, forwardPort int64) *proto.DNSConfig {
-	protoUpdate := &proto.DNSConfig{
-		ServiceEnable:    update.ServiceEnable,
-		CustomZones:      make([]*proto.CustomZone, 0, len(update.CustomZones)),
-		NameServerGroups: make([]*proto.NameServerGroup, 0, len(update.NameServerGroups)),
-		ForwarderPort:    forwardPort,
-	}
-
-	for _, zone := range update.CustomZones {
-		protoZone := convertToProtoCustomZone(zone)
-		protoUpdate.CustomZones = append(protoUpdate.CustomZones, protoZone)
-	}
-
-	for _, nsGroup := range update.NameServerGroups {
-		cacheKey := nsGroup.ID
-		if cachedGroup, exists := cache.GetNameServerGroup(cacheKey); exists {
-			protoUpdate.NameServerGroups = append(protoUpdate.NameServerGroups, cachedGroup)
-		} else {
-			protoGroup := convertToProtoNameServerGroup(nsGroup)
-			cache.SetNameServerGroup(cacheKey, protoGroup)
-			protoUpdate.NameServerGroups = append(protoUpdate.NameServerGroups, protoGroup)
-		}
-	}
-
-	return protoUpdate
-}
-
 func ToResponseProto(configProto nbconfig.Protocol) proto.HostConfig_Protocol {
 	switch configProto {
 	case nbconfig.UDP:
@@ -354,203 +278,6 @@ func ToResponseProto(configProto nbconfig.Protocol) proto.HostConfig_Protocol {
 	}
 }
 
-func toProtocolRoutes(routes []*nbroute.Route) []*proto.Route {
-	protoRoutes := make([]*proto.Route, 0, len(routes))
-	for _, r := range routes {
-		protoRoutes = append(protoRoutes, toProtocolRoute(r))
-	}
-	return protoRoutes
-}
-
-func toProtocolRoute(route *nbroute.Route) *proto.Route {
-	return &proto.Route{
-		ID:            string(route.ID),
-		NetID:         string(route.NetID),
-		Network:       route.Network.String(),
-		Domains:       route.Domains.ToPunycodeList(),
-		NetworkType:   int64(route.NetworkType),
-		Peer:          route.Peer,
-		Metric:        int64(route.Metric),
-		Masquerade:    route.Masquerade,
-		KeepRoute:     route.KeepRoute,
-		SkipAutoApply: route.SkipAutoApply,
-	}
-}
-
-// toProtocolFirewallRules converts the firewall rules to the protocol firewall rules.
-// When useSourcePrefixes is true, the compact SourcePrefixes field is populated
-// alongside the deprecated PeerIP for forward compatibility.
-// Wildcard rules ("0.0.0.0") are expanded into separate v4 and v6 SourcePrefixes
-// when includeIPv6 is true.
-func toProtocolFirewallRules(rules []*types.FirewallRule, includeIPv6, useSourcePrefixes bool) []*proto.FirewallRule {
-	result := make([]*proto.FirewallRule, 0, len(rules))
-	for i := range rules {
-		rule := rules[i]
-
-		fwRule := &proto.FirewallRule{
-			PolicyID:  []byte(rule.PolicyID),
-			PeerIP:    rule.PeerIP, //nolint:staticcheck // populated for backward compatibility
-			Direction: getProtoDirection(rule.Direction),
-			Action:    getProtoAction(rule.Action),
-			Protocol:  getProtoProtocol(rule.Protocol),
-			Port:      rule.Port,
-		}
-
-		if useSourcePrefixes && rule.PeerIP != "" {
-			result = append(result, populateSourcePrefixes(fwRule, rule, includeIPv6)...)
-		}
-
-		if shouldUsePortRange(fwRule) {
-			fwRule.PortInfo = rule.PortRange.ToProto()
-		}
-
-		result = append(result, fwRule)
-	}
-	return result
-}
-
-// populateSourcePrefixes sets SourcePrefixes on fwRule and returns any
-// additional rules needed (e.g. a v6 wildcard clone when the peer IP is unspecified).
-func populateSourcePrefixes(fwRule *proto.FirewallRule, rule *types.FirewallRule, includeIPv6 bool) []*proto.FirewallRule {
-	addr, err := netip.ParseAddr(rule.PeerIP)
-	if err != nil {
-		return nil
-	}
-
-	if !addr.IsUnspecified() {
-		fwRule.SourcePrefixes = [][]byte{netiputil.EncodeAddr(addr.Unmap())}
-		return nil
-	}
-
-	// IPv4Unspecified/0 is always valid, error is impossible.
-	v4Wildcard, _ := netiputil.EncodePrefix(netip.PrefixFrom(netip.IPv4Unspecified(), 0))
-	fwRule.SourcePrefixes = [][]byte{v4Wildcard}
-
-	if !includeIPv6 {
-		return nil
-	}
-
-	v6Rule := goproto.Clone(fwRule).(*proto.FirewallRule)
-	v6Rule.PeerIP = "::" //nolint:staticcheck // populated for backward compatibility
-	// IPv6Unspecified/0 is always valid, error is impossible.
-	v6Wildcard, _ := netiputil.EncodePrefix(netip.PrefixFrom(netip.IPv6Unspecified(), 0))
-	v6Rule.SourcePrefixes = [][]byte{v6Wildcard}
-	if shouldUsePortRange(v6Rule) {
-		v6Rule.PortInfo = rule.PortRange.ToProto()
-	}
-	return []*proto.FirewallRule{v6Rule}
-}
-
-// getProtoDirection converts the direction to proto.RuleDirection.
-func getProtoDirection(direction int) proto.RuleDirection {
-	if direction == types.FirewallRuleDirectionOUT {
-		return proto.RuleDirection_OUT
-	}
-	return proto.RuleDirection_IN
-}
-
-func toProtocolRoutesFirewallRules(rules []*types.RouteFirewallRule) []*proto.RouteFirewallRule {
-	result := make([]*proto.RouteFirewallRule, len(rules))
-	for i := range rules {
-		rule := rules[i]
-		result[i] = &proto.RouteFirewallRule{
-			SourceRanges: rule.SourceRanges,
-			Action:       getProtoAction(rule.Action),
-			Destination:  rule.Destination,
-			Protocol:     getProtoProtocol(rule.Protocol),
-			PortInfo:     getProtoPortInfo(rule),
-			IsDynamic:    rule.IsDynamic,
-			Domains:      rule.Domains.ToPunycodeList(),
-			PolicyID:     []byte(rule.PolicyID),
-			RouteID:      string(rule.RouteID),
-		}
-	}
-
-	return result
-}
-
-// getProtoAction converts the action to proto.RuleAction.
-func getProtoAction(action string) proto.RuleAction {
-	if action == string(types.PolicyTrafficActionDrop) {
-		return proto.RuleAction_DROP
-	}
-	return proto.RuleAction_ACCEPT
-}
-
-// getProtoProtocol converts the protocol to proto.RuleProtocol.
-func getProtoProtocol(protocol string) proto.RuleProtocol {
-	switch types.PolicyRuleProtocolType(protocol) {
-	case types.PolicyRuleProtocolALL:
-		return proto.RuleProtocol_ALL
-	case types.PolicyRuleProtocolTCP:
-		return proto.RuleProtocol_TCP
-	case types.PolicyRuleProtocolUDP:
-		return proto.RuleProtocol_UDP
-	case types.PolicyRuleProtocolICMP:
-		return proto.RuleProtocol_ICMP
-	default:
-		return proto.RuleProtocol_UNKNOWN
-	}
-}
-
-// getProtoPortInfo converts the port info to proto.PortInfo.
-func getProtoPortInfo(rule *types.RouteFirewallRule) *proto.PortInfo {
-	var portInfo proto.PortInfo
-	if rule.Port != 0 {
-		portInfo.PortSelection = &proto.PortInfo_Port{Port: uint32(rule.Port)}
-	} else if portRange := rule.PortRange; portRange.Start != 0 && portRange.End != 0 {
-		portInfo.PortSelection = &proto.PortInfo_Range_{
-			Range: &proto.PortInfo_Range{
-				Start: uint32(portRange.Start),
-				End:   uint32(portRange.End),
-			},
-		}
-	}
-	return &portInfo
-}
-
-func shouldUsePortRange(rule *proto.FirewallRule) bool {
-	return rule.Port == "" && (rule.Protocol == proto.RuleProtocol_UDP || rule.Protocol == proto.RuleProtocol_TCP)
-}
-
-// Helper function to convert nbdns.CustomZone to proto.CustomZone
-func convertToProtoCustomZone(zone nbdns.CustomZone) *proto.CustomZone {
-	protoZone := &proto.CustomZone{
-		Domain:               zone.Domain,
-		Records:              make([]*proto.SimpleRecord, 0, len(zone.Records)),
-		SearchDomainDisabled: zone.SearchDomainDisabled,
-		NonAuthoritative:     zone.NonAuthoritative,
-	}
-	for _, record := range zone.Records {
-		protoZone.Records = append(protoZone.Records, &proto.SimpleRecord{
-			Name:  record.Name,
-			Type:  int64(record.Type),
-			Class: record.Class,
-			TTL:   int64(record.TTL),
-			RData: record.RData,
-		})
-	}
-	return protoZone
-}
-
-// Helper function to convert nbdns.NameServerGroup to proto.NameServerGroup
-func convertToProtoNameServerGroup(nsGroup *nbdns.NameServerGroup) *proto.NameServerGroup {
-	protoGroup := &proto.NameServerGroup{
-		Primary:              nsGroup.Primary,
-		Domains:              nsGroup.Domains,
-		SearchDomainsEnabled: nsGroup.SearchDomainsEnabled,
-		NameServers:          make([]*proto.NameServer, 0, len(nsGroup.NameServers)),
-	}
-	for _, ns := range nsGroup.NameServers {
-		protoGroup.NameServers = append(protoGroup.NameServers, &proto.NameServer{
-			IP:     ns.IP.String(),
-			Port:   int64(ns.Port),
-			NSType: int64(ns.NSType),
-		})
-	}
-	return protoGroup
-}
-
 // buildJWTConfig constructs JWT configuration for SSH servers from management server config
 func buildJWTConfig(config *nbconfig.HttpServerConfig, deviceFlowConfig *nbconfig.DeviceAuthorizationFlow) *proto.JWTConfig {
 	if config == nil || config.AuthAudience == "" {

management/internals/shared/grpc/conversion_test.go

@@ -15,6 +15,7 @@ import (
 	"github.com/netbirdio/netbird/management/internals/controllers/network_map/controller/cache"
 	nbconfig "github.com/netbirdio/netbird/management/internals/server/config"
 	"github.com/netbirdio/netbird/management/server/types"
+	"github.com/netbirdio/netbird/shared/management/networkmap"
 )
 
 func TestToProtocolDNSConfigWithCache(t *testing.T) {
@@ -64,13 +65,13 @@ func TestToProtocolDNSConfigWithCache(t *testing.T) {
 	}
 
 	// First run with config1
-	result1 := toProtocolDNSConfig(config1, &cache, int64(network_map.DnsForwarderPort))
+	result1 := networkmap.ToProtocolDNSConfig(config1, &cache, int64(network_map.DnsForwarderPort))
 
 	// Second run with config2
-	result2 := toProtocolDNSConfig(config2, &cache, int64(network_map.DnsForwarderPort))
+	result2 := networkmap.ToProtocolDNSConfig(config2, &cache, int64(network_map.DnsForwarderPort))
 
 	// Third run with config1 again
-	result3 := toProtocolDNSConfig(config1, &cache, int64(network_map.DnsForwarderPort))
+	result3 := networkmap.ToProtocolDNSConfig(config1, &cache, int64(network_map.DnsForwarderPort))
 
 	// Verify that result1 and result3 are identical
 	if !reflect.DeepEqual(result1, result3) {
@@ -102,15 +103,14 @@ func BenchmarkToProtocolDNSConfig(b *testing.B) {
 
 			b.ResetTimer()
 			for i := 0; i < b.N; i++ {
-				toProtocolDNSConfig(testData, cache, int64(network_map.DnsForwarderPort))
+				networkmap.ToProtocolDNSConfig(testData, cache, int64(network_map.DnsForwarderPort))
 			}
 		})
 
 		b.Run(fmt.Sprintf("WithoutCache-Size%d", size), func(b *testing.B) {
 			b.ResetTimer()
 			for i := 0; i < b.N; i++ {
-				cache := &cache.DNSConfigCache{}
-				toProtocolDNSConfig(testData, cache, int64(network_map.DnsForwarderPort))
+				networkmap.ToProtocolDNSConfig(testData, nil, int64(network_map.DnsForwarderPort))
 			}
 		})
 	}