Merge main into embedded-vnc

shared/management/client/client_test.go

@@ -316,33 +316,87 @@ func TestClient_Sync(t *testing.T) {
 
 	select {
 	case resp := <-ch:
-		if resp.GetPeerConfig() == nil {
+		if resp.GetPeerConfig() == nil && resp.GetNetworkMap().GetPeerConfig() == nil {
 			t.Error("expecting non nil PeerConfig got nil")
 		}
 		if resp.GetNetbirdConfig() == nil {
 			t.Error("expecting non nil NetbirdConfig got nil")
 		}
-		// we test network map peers from 0.29.3 and dev builds
+		// Top-level RemotePeers is deprecated and must stay empty for
+		// v0.29.3+ (and dev) clients — the field rides inside NetworkMap
+		// (legacy) or the NetworkMapEnvelope (components) instead.
 		if len(resp.GetRemotePeers()) != 0 {
 			t.Error("expecting top-level RemotePeers to be empty for v0.29.3+ clients")
 		}
-		networkMap := resp.GetNetworkMap()
-		if len(networkMap.GetRemotePeers()) != 1 {
-			t.Errorf("expecting RemotePeers size %d got %d", 1, len(networkMap.GetRemotePeers()))
+		// Component-capable clients receive a NetworkMapEnvelope; the
+		// remote-peers list is encoded inside it. Decode it and check the
+		// envelope's peers slice. Legacy peers populate NetworkMap.RemotePeers;
+		// both shapes must surface exactly one remote peer.
+		remotePeerKeys := remotePeerKeysFromSync(resp, testKey.PublicKey().String())
+		if len(remotePeerKeys) != 1 {
+			t.Errorf("expecting RemotePeers size %d got %d", 1, len(remotePeerKeys))
 			return
 		}
-
-		if networkMap.GetRemotePeersIsEmpty() {
+		if resp.GetNetworkMap() != nil && resp.GetNetworkMap().GetRemotePeersIsEmpty() {
 			t.Error("expecting RemotePeers property to be false, got true")
 		}
-		if networkMap.GetRemotePeers()[0].GetWgPubKey() != remoteKey.PublicKey().String() {
-			t.Errorf("expecting RemotePeer public key %s got %s", remoteKey.PublicKey().String(), networkMap.GetRemotePeers()[0].GetWgPubKey())
+		if remotePeerKeys[0] != remoteKey.PublicKey().String() {
+			t.Errorf("expecting RemotePeer public key %s got %s", remoteKey.PublicKey().String(), remotePeerKeys[0])
 		}
 	case <-time.After(3 * time.Second):
 		t.Error("timeout waiting for test to finish")
 	}
 }
 
+// remotePeerKeysFromSync extracts the remote-peer WG keys from either the
+// legacy NetworkMap.RemotePeers list or the components NetworkMapEnvelope's
+// inner peers slice (filtering out the local receiving peer identified by
+// localKey, since the envelope's peers list is index-addressed and includes
+// the local peer alongside remotes).
+func remotePeerKeysFromSync(resp *mgmtProto.SyncResponse, localKey string) []string {
+	if rp := resp.GetRemotePeers(); len(rp) > 0 {
+		out := make([]string, 0, len(rp))
+		for _, p := range rp {
+			out = append(out, p.GetWgPubKey())
+		}
+		return out
+	}
+	if rp := resp.GetNetworkMap().GetRemotePeers(); len(rp) > 0 {
+		out := make([]string, 0, len(rp))
+		for _, p := range rp {
+			out = append(out, p.GetWgPubKey())
+		}
+		return out
+	}
+	env := resp.GetNetworkMapEnvelope().GetFull()
+	if env == nil {
+		return nil
+	}
+	out := make([]string, 0, len(env.GetPeers()))
+	for _, p := range env.GetPeers() {
+		key := wgKeyFromBytes(p.GetWgPubKey())
+		if key == "" || key == localKey {
+			continue
+		}
+		out = append(out, key)
+	}
+	return out
+}
+
+// wgKeyFromBytes mirrors the client-side decoder: the envelope ships raw 32
+// bytes; reconstruct the standard base64 key the test compares against.
+func wgKeyFromBytes(raw []byte) string {
+	if len(raw) == 0 {
+		return ""
+	}
+	var k wgtypes.Key
+	if len(raw) != len(k) {
+		return ""
+	}
+	copy(k[:], raw)
+	return k.String()
+}
+
 func Test_SystemMetaDataFromClient(t *testing.T) {
 	s, lis, mgmtMockServer, serverKey := startMockManagement(t)
 	defer s.GracefulStop()

shared/management/client/grpc.go

@@ -24,6 +24,7 @@ import (
 	"github.com/netbirdio/netbird/client/system"
 	"github.com/netbirdio/netbird/encryption"
 	"github.com/netbirdio/netbird/shared/management/domain"
+	nbmgmtgrpc "github.com/netbirdio/netbird/shared/management/grpc"
 	"github.com/netbirdio/netbird/shared/management/proto"
 	"github.com/netbirdio/netbird/util/wsproxy"
 )
@@ -186,16 +187,16 @@ func (c *GrpcClient) ready() bool {
 // Sync wraps the real client's Sync endpoint call and takes care of retries and encryption/decryption of messages
 // Blocking request. The result will be sent via msgHandler callback function
 func (c *GrpcClient) Sync(ctx context.Context, sysInfo *system.Info, msgHandler func(msg *proto.SyncResponse) error) error {
-	return c.withMgmtStream(ctx, func(ctx context.Context, serverPubKey wgtypes.Key) error {
-		return c.handleSyncStream(ctx, serverPubKey, sysInfo, msgHandler)
+	return c.withMgmtStream(ctx, func(ctx context.Context, serverPubKey wgtypes.Key, backOff backoff.BackOff) error {
+		return c.handleSyncStream(ctx, serverPubKey, sysInfo, msgHandler, backOff)
 	})
 }
 
 // Job wraps the real client's Job endpoint call and takes care of retries and encryption/decryption of messages
 // Blocking request. The result will be sent via msgHandler callback function
 func (c *GrpcClient) Job(ctx context.Context, msgHandler func(msg *proto.JobRequest) *proto.JobResponse) error {
-	return c.withMgmtStream(ctx, func(ctx context.Context, serverPubKey wgtypes.Key) error {
-		return c.handleJobStream(ctx, serverPubKey, msgHandler)
+	return c.withMgmtStream(ctx, func(ctx context.Context, serverPubKey wgtypes.Key, backOff backoff.BackOff) error {
+		return c.handleJobStream(ctx, serverPubKey, msgHandler, backOff)
 	})
 }
 
@@ -203,7 +204,7 @@ func (c *GrpcClient) Job(ctx context.Context, msgHandler func(msg *proto.JobRequ
 // It takes care of retries, connection readiness, and fetching server public key.
 func (c *GrpcClient) withMgmtStream(
 	ctx context.Context,
-	handler func(ctx context.Context, serverPubKey wgtypes.Key) error,
+	handler func(ctx context.Context, serverPubKey wgtypes.Key, backOff backoff.BackOff) error,
 ) error {
 	backOff := defaultBackoff(ctx)
 	operation := func() error {
@@ -223,7 +224,7 @@ func (c *GrpcClient) withMgmtStream(
 			return err
 		}
 
-		return handler(ctx, *serverPubKey)
+		return handler(ctx, *serverPubKey, backOff)
 	}
 
 	err := backoff.Retry(operation, backOff)
@@ -238,6 +239,7 @@ func (c *GrpcClient) handleJobStream(
 	ctx context.Context,
 	serverPubKey wgtypes.Key,
 	msgHandler func(msg *proto.JobRequest) *proto.JobResponse,
+	backOff backoff.BackOff,
 ) error {
 	ctx, cancelStream := context.WithCancel(ctx)
 	defer cancelStream()
@@ -255,6 +257,19 @@ func (c *GrpcClient) handleJobStream(
 
 	log.Debug("job stream handshake sent successfully")
 
+	// The stream is up, so reset the backoff. This matters for two reasons,
+	// both caused by the backoff lib not resetting its state on a successful
+	// connection:
+	//  1. Without a reset, after a connect followed by an error the next retry
+	//     starts from the accumulated (large) interval instead of retrying
+	//     promptly, delaying reconnection.
+	//  2. Worse, once the accumulated elapsed time exceeds MaxElapsedTime, the
+	//     next stream error makes NextBackOff() return Stop, so the retry loop
+	//     exits immediately. That error is then mislabeled unrecoverable and
+	//     bubbles up to trigger a full engine restart / data-plane teardown
+	//     instead of a silent reconnection.
+	backOff.Reset()
+
 	// Main loop: receive, process, respond
 	for {
 		jobReq, err := c.receiveJobRequest(ctx, stream, serverPubKey)
@@ -370,7 +385,7 @@ func (c *GrpcClient) sendJobResponse(
 	return nil
 }
 
-func (c *GrpcClient) handleSyncStream(ctx context.Context, serverPubKey wgtypes.Key, sysInfo *system.Info, msgHandler func(msg *proto.SyncResponse) error) error {
+func (c *GrpcClient) handleSyncStream(ctx context.Context, serverPubKey wgtypes.Key, sysInfo *system.Info, msgHandler func(msg *proto.SyncResponse) error, backOff backoff.BackOff) error {
 	ctx, cancelStream := context.WithCancel(ctx)
 	defer cancelStream()
 
@@ -389,6 +404,19 @@ func (c *GrpcClient) handleSyncStream(ctx context.Context, serverPubKey wgtypes.
 	c.notifyConnected()
 	c.setSyncStreamConnected()
 
+	// The stream is up, so reset the backoff. This matters for two reasons,
+	// both caused by the backoff lib not resetting its state on a successful
+	// connection:
+	//  1. Without a reset, after a connect followed by an error the next retry
+	//     starts from the accumulated (large) interval instead of retrying
+	//     promptly, delaying reconnection.
+	//  2. Worse, once the accumulated elapsed time exceeds MaxElapsedTime, the
+	//     next stream error makes NextBackOff() return Stop, so the retry loop
+	//     exits immediately. That error is then mislabeled unrecoverable and
+	//     bubbles up to trigger a full engine restart / data-plane teardown
+	//     instead of a silent reconnection.
+	backOff.Reset()
+
 	// blocking until error
 	err = c.receiveUpdatesEvents(stream, serverPubKey, msgHandler)
 	if err != nil {
@@ -1029,6 +1057,8 @@ func infoToMetaData(info *system.Info) *proto.PeerSystemMeta {
 		},
 
 		Capabilities: peerCapabilities(*info),
+
+		SyncMessageVersion: syncMessageVersion(*info),
 	}
 }
 
@@ -1042,3 +1072,10 @@ func peerCapabilities(info system.Info) []proto.PeerCapability {
 	}
 	return caps
 }
+
+func syncMessageVersion(info system.Info) int32 {
+	if info.SyncMessageVersion != nil {
+		return int32(*info.SyncMessageVersion)
+	}
+	return int32(nbmgmtgrpc.HighestSyncMessageVersion)
+}

shared/management/grpc/sync_message_versions.go

@@ -0,0 +1,67 @@
+package grpc
+
+import (
+	"errors"
+	"fmt"
+)
+
+type SyncMessageVersion uint16
+
+const (
+	Base SyncMessageVersion = iota
+	ComponentNetworkMap
+)
+
+const DefaultSyncMessageVersion = Base
+const HighestSyncMessageVersion = ComponentNetworkMap
+
+var ErrorUnrecognizedSyncMessageVersion = errors.New("unrecognized SyncMessageVersion")
+
+func ValidateSyncMessageVersion(v *int) error {
+	// empty list == we support all available versions
+	if v == nil {
+		return nil
+	}
+	if *v < 0 || *v > int(HighestSyncMessageVersion) {
+		return fmt.Errorf("sync message version must between 0 and %d, %w", HighestSyncMessageVersion, ErrorUnrecognizedSyncMessageVersion)
+	}
+	return nil
+}
+
+// returns SyncMessage version from config, or highest available version if the config is missing or
+// base if it is invalid
+// the assumption is ValidateSyncMessageVersion() has been called before using SyncMessageVersionFromConfig()
+func SyncMessageVersionFromConfig(v *int) SyncMessageVersion {
+	if v == nil {
+		return DefaultSyncMessageVersion
+	}
+	if *v < 0 || *v > int(HighestSyncMessageVersion) {
+		return Base
+	}
+
+	return SyncMessageVersion(*v)
+}
+
+// convert per-account supported versions to SyncMessageVersion
+// the assumption is ValidateSyncMessageVersion() has been called before using SyncMessageVersionsFromMap()
+func SyncMessageVersionsFromMap(toconvert map[string]int) map[string]SyncMessageVersion {
+	// no per-account overrides
+	if len(toconvert) == 0 {
+		return nil
+	}
+
+	toret := make(map[string]SyncMessageVersion)
+
+	for account, version := range toconvert {
+		toret[account] = SyncMessageVersionFromConfig(&version)
+	}
+	return toret
+}
+
+// return highest common sync message version, or Default (which is always available)
+func HighestCommonSyncMessageVersion(a SyncMessageVersion, b SyncMessageVersion) SyncMessageVersion {
+	if a > b {
+		return b
+	}
+	return a
+}

shared/management/grpc/sync_message_versions_test.go

@@ -0,0 +1,39 @@
+package grpc
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestValidation(t *testing.T) {
+	assert.NoError(t, ValidateSyncMessageVersion(nil))
+	assert.NoError(t, ValidateSyncMessageVersion(toIntPtr(0)))
+	assert.NoError(t, ValidateSyncMessageVersion(toIntPtr(1)))
+	assert.ErrorIs(t, ValidateSyncMessageVersion(toIntPtr(int(^uint(0)>>1))), ErrorUnrecognizedSyncMessageVersion)
+	assert.ErrorIs(t, ValidateSyncMessageVersion(toIntPtr(-1)), ErrorUnrecognizedSyncMessageVersion)
+}
+
+func TestVersionFromConfig(t *testing.T) {
+	assert.Equal(t, DefaultSyncMessageVersion, SyncMessageVersionFromConfig(nil))
+	assert.Equal(t, Base, SyncMessageVersionFromConfig(toIntPtr(0)))
+	assert.Equal(t, ComponentNetworkMap, SyncMessageVersionFromConfig(toIntPtr(1)))
+	assert.Equal(t, DefaultSyncMessageVersion, SyncMessageVersionFromConfig(toIntPtr(-1)))
+	assert.Equal(t, DefaultSyncMessageVersion, SyncMessageVersionFromConfig(toIntPtr(int(^uint(0)>>1))))
+}
+
+func TestPerAccountConversionStringToEnum(t *testing.T) {
+	assert.Equal(t, map[string]SyncMessageVersion{"1": HighestSyncMessageVersion}, SyncMessageVersionsFromMap(map[string]int{"1": 1}))
+	assert.Equal(t, map[string]SyncMessageVersion{"2": DefaultSyncMessageVersion}, SyncMessageVersionsFromMap(map[string]int{"2": -1}))
+}
+
+func TestCommonVersions(t *testing.T) {
+	assert.Equal(t, Base, HighestCommonSyncMessageVersion(Base, HighestSyncMessageVersion))
+	assert.Equal(t, Base, HighestCommonSyncMessageVersion(HighestSyncMessageVersion, Base))
+	assert.Equal(t, Base, HighestCommonSyncMessageVersion(Base, Base))
+	assert.Equal(t, HighestSyncMessageVersion, HighestCommonSyncMessageVersion(HighestSyncMessageVersion, HighestSyncMessageVersion))
+}
+
+func toIntPtr(v int) *int {
+	return &v
+}

shared/management/http/api/openapi.yml

@@ -376,9 +376,11 @@ components:
           type: boolean
           example: false
         agent_network_only:
-          description: Limits the dashboard to the Agent Network surface for this account. Set for accounts created via netbird.ai signups and can be disabled later.
+          description: Limits the dashboard to the Agent Network surface for this account. Set for accounts created via netbird.ai signups and can be disabled later. Enabling this requires dashboard_features.agent_network to be true in the same request.
           type: boolean
           example: false
+        dashboard_features:
+          $ref: '#/components/schemas/AccountDashboardFeatures'
         embedded_idp_enabled:
           description: Indicates whether the embedded identity provider (Dex) is enabled for this account. This is a read-only field.
           type: boolean
@@ -407,6 +409,14 @@ components:
         - regular_users_view_blocked
         - peer_expose_enabled
         - peer_expose_groups
+    AccountDashboardFeatures:
+      description: Per-account dashboard section visibility overrides. Omitted keys follow the default dashboard behavior.
+      type: object
+      properties:
+        agent_network:
+          description: Controls the Agent Network menu for the account regardless of the deployment feature flag. When true the menu is shown, when false it is hidden, and when omitted the default behavior applies. Must be true when agent_network_only is enabled.
+          type: boolean
+          example: true
     AccountExtraSettings:
       type: object
       properties:
@@ -5167,6 +5177,10 @@ components:
           type: boolean
           description: Whether upstream TLS certificate verification is skipped when the proxy dials this provider's URL. Intended for self-hosted / internal gateways behind a private or self-signed certificate.
           example: false
+        metadata_disabled:
+          type: boolean
+          description: Whether identity metadata injection is disabled for this provider. When enabled (the default), the proxy stamps the caller's user and authorizing group onto upstream requests as provider-specific metadata (e.g. AWS Bedrock's X-Amzn-Bedrock-Request-Metadata header). Set true to suppress it.
+          example: false
         created_at:
           type: string
           format: date-time
@@ -5187,6 +5201,7 @@ components:
         - models
         - enabled
         - skip_tls_verification
+        - metadata_disabled
         - created_at
         - updated_at
     AgentNetworkProviderRequest:
@@ -5243,6 +5258,10 @@ components:
           type: boolean
           description: Skip upstream TLS certificate verification when the proxy dials this provider's URL. For self-hosted / internal gateways behind a private or self-signed certificate. Defaults to false. When omitted on update, the stored value is left unchanged.
           example: false
+        metadata_disabled:
+          type: boolean
+          description: Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected). When omitted on update, the stored value is left unchanged.
+          example: false
       required:
         - provider_id
         - name
@@ -5816,13 +5835,48 @@ components:
         total_tokens:
           type: integer
           format: int64
-          description: Total tokens consumed.
+          description: Total tokens consumed, including prompt-cache tokens.
           example: 1840
+        cached_input_tokens:
+          type: integer
+          format: int64
+          description: Input tokens read from the provider's prompt cache. Additive to input_tokens for Anthropic-shape providers; a subset of input_tokens for OpenAI.
+          example: 0
+        cache_creation_tokens:
+          type: integer
+          format: int64
+          description: Input tokens written to the provider's prompt cache. Zero for providers without a cache-write bucket.
+          example: 30528
         cost_usd:
           type: number
           format: double
           description: Estimated USD cost of the request.
           example: 0.0231
+        input_cost_usd:
+          type: number
+          format: double
+          description: Cost of the non-cached input tokens. Base component of cost_usd.
+          example: 0.0048
+        cached_input_cost_usd:
+          type: number
+          format: double
+          description: Cost of the prompt-cache read tokens. Base component of cost_usd, and part of cache_cost_usd.
+          example: 0.0015
+        cache_creation_cost_usd:
+          type: number
+          format: double
+          description: Cost of the prompt-cache write tokens. Base component of cost_usd, and part of cache_cost_usd.
+          example: 0.1130
+        output_cost_usd:
+          type: number
+          format: double
+          description: Cost of the output tokens. Base component of cost_usd.
+          example: 0.0038
+        cache_cost_usd:
+          type: number
+          format: double
+          description: Portion of cost_usd billed for prompt-cache usage.
+          example: 0.1145
         stream:
           type: boolean
           description: Whether the request was a streaming completion.
@@ -5846,7 +5900,14 @@ components:
         - input_tokens
         - output_tokens
         - total_tokens
+        - cached_input_tokens
+        - cache_creation_tokens
+        - input_cost_usd
+        - cached_input_cost_usd
+        - cache_creation_cost_usd
+        - output_cost_usd
         - cost_usd
+        - cache_cost_usd
     AgentNetworkAccessLogsResponse:
       type: object
       properties:
@@ -5920,13 +5981,48 @@ components:
         total_tokens:
           type: integer
           format: int64
-          description: Total tokens across the session.
+          description: Total tokens across the session, including prompt-cache tokens.
           example: 12880
+        cached_input_tokens:
+          type: integer
+          format: int64
+          description: Total prompt-cache read tokens across the session.
+          example: 0
+        cache_creation_tokens:
+          type: integer
+          format: int64
+          description: Total prompt-cache write tokens across the session.
+          example: 30528
         cost_usd:
           type: number
           format: double
           description: Total estimated USD cost across the session.
           example: 0.1617
+        input_cost_usd:
+          type: number
+          format: double
+          description: Total cost of non-cached input tokens across the session.
+          example: 0.0210
+        cached_input_cost_usd:
+          type: number
+          format: double
+          description: Total cost of prompt-cache read tokens across the session.
+          example: 0.0015
+        cache_creation_cost_usd:
+          type: number
+          format: double
+          description: Total cost of prompt-cache write tokens across the session.
+          example: 0.1130
+        output_cost_usd:
+          type: number
+          format: double
+          description: Total cost of output tokens across the session.
+          example: 0.0262
+        cache_cost_usd:
+          type: number
+          format: double
+          description: Portion of cost_usd billed for prompt-cache usage across the session.
+          example: 0.1145
         providers:
           type: array
           items:
@@ -5953,7 +6049,14 @@ components:
         - input_tokens
         - output_tokens
         - total_tokens
+        - cached_input_tokens
+        - cache_creation_tokens
+        - input_cost_usd
+        - cached_input_cost_usd
+        - cache_creation_cost_usd
+        - output_cost_usd
         - cost_usd
+        - cache_cost_usd
         - decision
         - entries
     AgentNetworkAccessLogSessionsResponse:
@@ -6007,19 +6110,61 @@ components:
         total_tokens:
           type: integer
           format: int64
-          description: Total tokens in the bucket.
+          description: Total tokens in the bucket, including prompt-cache tokens.
           example: 184000
+        cached_input_tokens:
+          type: integer
+          format: int64
+          description: Total prompt-cache read tokens in the bucket.
+          example: 20000
+        cache_creation_tokens:
+          type: integer
+          format: int64
+          description: Total prompt-cache write tokens in the bucket.
+          example: 45000
+        input_cost_usd:
+          type: number
+          format: double
+          description: Total cost of non-cached input tokens in the bucket.
+          example: 1.12
+        cached_input_cost_usd:
+          type: number
+          format: double
+          description: Total cost of prompt-cache read tokens in the bucket.
+          example: 0.06
+        cache_creation_cost_usd:
+          type: number
+          format: double
+          description: Total cost of prompt-cache write tokens in the bucket.
+          example: 0.36
+        output_cost_usd:
+          type: number
+          format: double
+          description: Total cost of output tokens in the bucket.
+          example: 0.77
         cost_usd:
           type: number
           format: double
           description: Total estimated USD spend in the bucket.
           example: 2.31
+        cache_cost_usd:
+          type: number
+          format: double
+          description: Portion of cost_usd billed for prompt-cache usage in the bucket.
+          example: 0.42
       required:
         - period_start
         - input_tokens
         - output_tokens
         - total_tokens
+        - cached_input_tokens
+        - cache_creation_tokens
+        - input_cost_usd
+        - cached_input_cost_usd
+        - cache_creation_cost_usd
+        - output_cost_usd
         - cost_usd
+        - cache_cost_usd
     AgentNetworkSettings:
       type: object
       description: Per-account Agent Network gateway settings. One row per account; cluster and subdomain are auto-assigned on first provider create and immutable thereafter.

shared/management/http/api/types.gen.go

@@ -1612,6 +1612,12 @@ type Account struct {
 	Settings   AccountSettings   `json:"settings"`
 }
 
+// AccountDashboardFeatures Per-account dashboard section visibility overrides. Omitted keys follow the default dashboard behavior.
+type AccountDashboardFeatures struct {
+	// AgentNetwork Controls the Agent Network menu for the account regardless of the deployment feature flag. When true the menu is shown, when false it is hidden, and when omitted the default behavior applies. Must be true when agent_network_only is enabled.
+	AgentNetwork *bool `json:"agent_network,omitempty"`
+}
+
 // AccountExtraSettings defines model for AccountExtraSettings.
 type AccountExtraSettings struct {
 	// NetworkTrafficLogsEnabled Enables or disables network traffic logging. If enabled, all network traffic events from peers will be stored.
@@ -1647,7 +1653,7 @@ type AccountRequest struct {
 
 // AccountSettings defines model for AccountSettings.
 type AccountSettings struct {
-	// AgentNetworkOnly Limits the dashboard to the Agent Network surface for this account. Set for accounts created via netbird.ai signups and can be disabled later.
+	// AgentNetworkOnly Limits the dashboard to the Agent Network surface for this account. Set for accounts created via netbird.ai signups and can be disabled later. Enabling this requires dashboard_features.agent_network to be true in the same request.
 	AgentNetworkOnly *bool `json:"agent_network_only,omitempty"`
 
 	// AutoUpdateAlways When true, updates are installed automatically in the background. When false, updates require user interaction from the UI.
@@ -1656,6 +1662,9 @@ type AccountSettings struct {
 	// AutoUpdateVersion Set Clients auto-update version. "latest", "disabled", or a specific version (e.g "0.50.1")
 	AutoUpdateVersion *string `json:"auto_update_version,omitempty"`
 
+	// DashboardFeatures Per-account dashboard section visibility overrides. Omitted keys follow the default dashboard behavior.
+	DashboardFeatures *AccountDashboardFeatures `json:"dashboard_features,omitempty"`
+
 	// DnsDomain Allows to define a custom dns domain for the account
 	DnsDomain *string `json:"dns_domain,omitempty"`
 
@@ -1723,6 +1732,21 @@ type AccountSettings struct {
 
 // AgentNetworkAccessLog One per-request agent-network (LLM) access log entry with flattened, queryable LLM dimensions.
 type AgentNetworkAccessLog struct {
+	// CacheCostUsd Portion of cost_usd billed for prompt-cache usage.
+	CacheCostUsd float64 `json:"cache_cost_usd"`
+
+	// CacheCreationCostUsd Cost of the prompt-cache write tokens. Base component of cost_usd, and part of cache_cost_usd.
+	CacheCreationCostUsd float64 `json:"cache_creation_cost_usd"`
+
+	// CacheCreationTokens Input tokens written to the provider's prompt cache. Zero for providers without a cache-write bucket.
+	CacheCreationTokens int64 `json:"cache_creation_tokens"`
+
+	// CachedInputCostUsd Cost of the prompt-cache read tokens. Base component of cost_usd, and part of cache_cost_usd.
+	CachedInputCostUsd float64 `json:"cached_input_cost_usd"`
+
+	// CachedInputTokens Input tokens read from the provider's prompt cache. Additive to input_tokens for Anthropic-shape providers; a subset of input_tokens for OpenAI.
+	CachedInputTokens int64 `json:"cached_input_tokens"`
+
 	// CostUsd Estimated USD cost of the request.
 	CostUsd float64 `json:"cost_usd"`
 
@@ -1744,6 +1768,9 @@ type AgentNetworkAccessLog struct {
 	// Id Unique identifier for the access log entry.
 	Id string `json:"id"`
 
+	// InputCostUsd Cost of the non-cached input tokens. Base component of cost_usd.
+	InputCostUsd float64 `json:"input_cost_usd"`
+
 	// InputTokens Input (prompt) tokens consumed.
 	InputTokens int64 `json:"input_tokens"`
 
@@ -1753,6 +1780,9 @@ type AgentNetworkAccessLog struct {
 	// Model Requested LLM model.
 	Model *string `json:"model,omitempty"`
 
+	// OutputCostUsd Cost of the output tokens. Base component of cost_usd.
+	OutputCostUsd float64 `json:"output_cost_usd"`
+
 	// OutputTokens Output (completion) tokens produced.
 	OutputTokens int64 `json:"output_tokens"`
 
@@ -1792,7 +1822,7 @@ type AgentNetworkAccessLog struct {
 	// Timestamp Timestamp when the request was made.
 	Timestamp time.Time `json:"timestamp"`
 
-	// TotalTokens Total tokens consumed.
+	// TotalTokens Total tokens consumed, including prompt-cache tokens.
 	TotalTokens int64 `json:"total_tokens"`
 
 	// UserId NetBird user id of the authenticated caller, if applicable.
@@ -1801,6 +1831,21 @@ type AgentNetworkAccessLog struct {
 
 // AgentNetworkAccessLogSession A session-grouped view of agent-network access logs — all requests sharing a session id (or a single session-less request) folded into one summary plus its ordered entries.
 type AgentNetworkAccessLogSession struct {
+	// CacheCostUsd Portion of cost_usd billed for prompt-cache usage across the session.
+	CacheCostUsd float64 `json:"cache_cost_usd"`
+
+	// CacheCreationCostUsd Total cost of prompt-cache write tokens across the session.
+	CacheCreationCostUsd float64 `json:"cache_creation_cost_usd"`
+
+	// CacheCreationTokens Total prompt-cache write tokens across the session.
+	CacheCreationTokens int64 `json:"cache_creation_tokens"`
+
+	// CachedInputCostUsd Total cost of prompt-cache read tokens across the session.
+	CachedInputCostUsd float64 `json:"cached_input_cost_usd"`
+
+	// CachedInputTokens Total prompt-cache read tokens across the session.
+	CachedInputTokens int64 `json:"cached_input_tokens"`
+
 	// CostUsd Total estimated USD cost across the session.
 	CostUsd float64 `json:"cost_usd"`
 
@@ -1816,12 +1861,18 @@ type AgentNetworkAccessLogSession struct {
 	// GroupIds Union of the authorising group ids across the session's entries.
 	GroupIds *[]string `json:"group_ids,omitempty"`
 
+	// InputCostUsd Total cost of non-cached input tokens across the session.
+	InputCostUsd float64 `json:"input_cost_usd"`
+
 	// InputTokens Total input (prompt) tokens across the session.
 	InputTokens int64 `json:"input_tokens"`
 
 	// Models Distinct models seen in the session.
 	Models *[]string `json:"models,omitempty"`
 
+	// OutputCostUsd Total cost of output tokens across the session.
+	OutputCostUsd float64 `json:"output_cost_usd"`
+
 	// OutputTokens Total output (completion) tokens across the session.
 	OutputTokens int64 `json:"output_tokens"`
 
@@ -1837,7 +1888,7 @@ type AgentNetworkAccessLogSession struct {
 	// StartedAt Timestamp of the session's earliest request.
 	StartedAt time.Time `json:"started_at"`
 
-	// TotalTokens Total tokens across the session.
+	// TotalTokens Total tokens across the session, including prompt-cache tokens.
 	TotalTokens int64 `json:"total_tokens"`
 
 	// UserId NetBird user id of the session's caller.
@@ -2218,6 +2269,9 @@ type AgentNetworkProvider struct {
 	// IdentityHeaderUserId Wire header name the proxy stamps with the caller's display identity (user email or peer name) when the catalog entry's HeaderPair is `customizable`. Empty disables stamping for this dimension. Ignored when the catalog entry has a fixed HeaderPair (e.g. LiteLLM, Portkey). Used today by Bifrost: typical values are `x-bf-lh-netbird_user_id` (always-on log metadata) or `x-bf-dim-netbird_user_id` (Prometheus / OTEL — requires the label to be pre-declared in the gateway's `client.prometheus_labels` config).
 	IdentityHeaderUserId *string `json:"identity_header_user_id,omitempty"`
 
+	// MetadataDisabled Whether identity metadata injection is disabled for this provider. When enabled (the default), the proxy stamps the caller's user and authorizing group onto upstream requests as provider-specific metadata (e.g. AWS Bedrock's X-Amzn-Bedrock-Request-Metadata header). Set true to suppress it.
+	MetadataDisabled bool `json:"metadata_disabled"`
+
 	// Models Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
 	Models []AgentNetworkProviderModel `json:"models"`
 
@@ -2269,6 +2323,9 @@ type AgentNetworkProviderRequest struct {
 	// IdentityHeaderUserId Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. When omitted on a request, the stored value is left unchanged; pass an empty string explicitly to clear it (which disables stamping for this dimension).
 	IdentityHeaderUserId *string `json:"identity_header_user_id,omitempty"`
 
+	// MetadataDisabled Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected). When omitted on update, the stored value is left unchanged.
+	MetadataDisabled *bool `json:"metadata_disabled,omitempty"`
+
 	// Models Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
 	Models *[]AgentNetworkProviderModel `json:"models,omitempty"`
 
@@ -2332,19 +2389,40 @@ type AgentNetworkSettingsRequest struct {
 
 // AgentNetworkUsageBucket One aggregated agent-network usage time bucket (UTC). The bucket width is set by the request's granularity.
 type AgentNetworkUsageBucket struct {
+	// CacheCostUsd Portion of cost_usd billed for prompt-cache usage in the bucket.
+	CacheCostUsd float64 `json:"cache_cost_usd"`
+
+	// CacheCreationCostUsd Total cost of prompt-cache write tokens in the bucket.
+	CacheCreationCostUsd float64 `json:"cache_creation_cost_usd"`
+
+	// CacheCreationTokens Total prompt-cache write tokens in the bucket.
+	CacheCreationTokens int64 `json:"cache_creation_tokens"`
+
+	// CachedInputCostUsd Total cost of prompt-cache read tokens in the bucket.
+	CachedInputCostUsd float64 `json:"cached_input_cost_usd"`
+
+	// CachedInputTokens Total prompt-cache read tokens in the bucket.
+	CachedInputTokens int64 `json:"cached_input_tokens"`
+
 	// CostUsd Total estimated USD spend in the bucket.
 	CostUsd float64 `json:"cost_usd"`
 
+	// InputCostUsd Total cost of non-cached input tokens in the bucket.
+	InputCostUsd float64 `json:"input_cost_usd"`
+
 	// InputTokens Total input (prompt) tokens in the bucket.
 	InputTokens int64 `json:"input_tokens"`
 
+	// OutputCostUsd Total cost of output tokens in the bucket.
+	OutputCostUsd float64 `json:"output_cost_usd"`
+
 	// OutputTokens Total output (completion) tokens in the bucket.
 	OutputTokens int64 `json:"output_tokens"`
 
 	// PeriodStart Start of the bucket in YYYY-MM-DD (UTC) — the day, the week start (Monday), or the month start, depending on granularity.
 	PeriodStart string `json:"period_start"`
 
-	// TotalTokens Total tokens in the bucket.
+	// TotalTokens Total tokens in the bucket, including prompt-cache tokens.
 	TotalTokens int64 `json:"total_tokens"`
 }
 

shared/management/networkmap/decode.go

@@ -0,0 +1,528 @@
+package networkmap
+
+import (
+	"encoding/base64"
+	"fmt"
+	"net"
+	"net/netip"
+	"strconv"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+
+	nbdns "github.com/netbirdio/netbird/dns"
+	nbroute "github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/domain"
+	"github.com/netbirdio/netbird/shared/management/proto"
+	"github.com/netbirdio/netbird/shared/management/types"
+)
+
+// DecodeEnvelope converts a NetworkMapEnvelope into a NetworkMapComponents
+// the client can run Calculate() over. Every ID-reference on the wire is a
+// xid from corresponding public_id field.
+//
+// ID scheme on the client side:
+//
+//	Peers              base64(wg_pub_key)          // stable across snapshots
+func DecodeEnvelope(env *proto.NetworkMapEnvelope) (*types.NetworkMapComponents, error) {
+	full := env.GetFull()
+	if full == nil {
+		return nil, fmt.Errorf("envelope has no Full payload")
+	}
+
+	c := &types.NetworkMapComponents{
+		PeerID:              "", // engine fills its own peer id from PeerConfig
+		Network:             decodeAccountNetwork(full.Network),
+		AccountSettings:     decodeAccountSettings(full.AccountSettings),
+		CustomZoneDomain:    full.CustomZoneDomain,
+		Peers:               make(map[string]*types.ComponentPeer, len(full.Peers)),
+		Groups:              make(map[string]*types.ComponentGroup, len(full.Groups)),
+		Policies:            make([]*types.Policy, 0, len(full.Policies)),
+		Routes:              make([]*nbroute.Route, 0, len(full.Routes)),
+		NameServerGroups:    make([]*nbdns.NameServerGroup, 0, len(full.NameserverGroups)),
+		AllDNSRecords:       decodeSimpleRecords(full.AllDnsRecords),
+		AccountZones:        decodeCustomZones(full.AccountZones),
+		ResourcePoliciesMap: make(map[string][]*types.Policy),
+		RoutersMap:          make(map[string]map[string]*types.ComponentRouter),
+		NetworkResources:    make([]*types.ComponentResource, 0, len(full.NetworkResources)),
+		RouterPeers:         make(map[string]*types.ComponentPeer),
+		AllowedUserIDs:      stringSliceToSet(full.AllowedUserIds),
+		PostureFailedPeers:  make(map[string]map[string]struct{}, len(full.PostureFailedPeers)),
+		GroupIDToUserIDs:    make(map[string][]string, len(full.GroupIdToUserIds)),
+	}
+
+	if full.DnsSettings != nil {
+		c.DNSSettings = &types.DNSSettings{
+			DisabledManagementGroups: full.DnsSettings.DisabledManagementGroupIds,
+		}
+	} else {
+		c.DNSSettings = &types.DNSSettings{}
+	}
+
+	// Phase 1: peers. The envelope's peers slice is index-addressed on the
+	// wire; we re-key by the peer's WireGuard public key (base64) so the
+	// in-memory components struct uses a stable identifier across
+	// snapshots. peerIDByIndex lets downstream phases resolve wire indexes
+	// back to that key. A peer with a missing or malformed wg_pub_key is
+	// skipped (and its index keeps "" so any cross-reference falls into the
+	// same missing-peer branch downstream) — matches legacy behaviour, which
+	// degrades gracefully rather than aborting the whole sync on a single
+	// bad row.
+	peerIDByIndex := make([]string, len(full.Peers))
+	for idx, pc := range full.Peers {
+		if pc == nil {
+			log.Warnf("envelope: peers[%d] is nil, skipping", idx)
+			continue
+		}
+		if len(pc.WgPubKey) != 32 {
+			log.Warnf("envelope: peers[%d] wg_pub_key length %d (want 32), skipping", idx, len(pc.WgPubKey))
+			continue
+		}
+		peerID := base64.StdEncoding.EncodeToString(pc.WgPubKey)
+		peer := decodePeerCompact(pc, peerID)
+		c.Peers[peerID] = peer
+		peerIDByIndex[idx] = peerID
+	}
+
+	// Phase 2: groups.
+	for i, gc := range full.Groups {
+		if gc == nil {
+			return nil, fmt.Errorf("invalid envelope: groups[%d] is nil", i)
+		}
+		groupID := gc.Id
+		peerIDs := make([]string, 0, len(gc.PeerIndexes))
+		for _, idx := range gc.PeerIndexes {
+			if int(idx) < len(peerIDByIndex) {
+				peerIDs = append(peerIDs, peerIDByIndex[idx])
+			} else {
+				log.WithField("peer idx", idx).Error("unrecognized peer idx during decoding")
+			}
+		}
+		group := &types.ComponentGroup{
+			ID:       groupID,
+			PublicID: gc.Id,
+			Peers:    peerIDs,
+		}
+		if gc.IsAll {
+			group.Name = types.GroupAllName
+		}
+		c.Groups[groupID] = group
+	}
+
+	// Phase 3: policies (PolicyCompact = one rule per entry; current data
+	// model is 1 rule per policy).
+	policyByID := make(map[string]*types.Policy, len(full.Policies))
+	for i, pc := range full.Policies {
+		if pc == nil {
+			return nil, fmt.Errorf("invalid envelope: policies[%d] is nil", i)
+		}
+		policy := decodePolicyCompact(pc, pc.Id, peerIDByIndex)
+		c.Policies = append(c.Policies, policy)
+		policyByID[pc.Id] = policy
+	}
+
+	// Phase 4: routes.
+	for i, rr := range full.Routes {
+		if rr == nil {
+			return nil, fmt.Errorf("invalid envelope: routes[%d] is nil", i)
+		}
+		c.Routes = append(c.Routes, decodeRouteRaw(rr, peerIDByIndex))
+	}
+
+	// Phase 5: NSGs.
+	for i, nsg := range full.NameserverGroups {
+		if nsg == nil {
+			return nil, fmt.Errorf("invalid envelope: nameserver_groups[%d] is nil", i)
+		}
+		c.NameServerGroups = append(c.NameServerGroups, decodeNameServerGroupRaw(nsg))
+	}
+
+	// Phase 6: network resources.
+	for i, nr := range full.NetworkResources {
+		if nr == nil {
+			return nil, fmt.Errorf("invalid envelope: network_resources[%d] is nil", i)
+		}
+		c.NetworkResources = append(c.NetworkResources, decodeNetworkResource(nr))
+	}
+
+	// Phase 7: routers_map (outer key = network seq id, inner key = peer-id
+	// reconstructed from peer_index). Synthesized network id is "net_<seq>".
+	for networkID, list := range full.RoutersMap {
+		inner := make(map[string]*types.ComponentRouter, len(list.Entries))
+		for _, entry := range list.Entries {
+			if !entry.PeerIndexSet {
+				continue
+			}
+			if int(entry.PeerIndex) >= len(peerIDByIndex) {
+				log.WithField("peer idx", entry.PeerIndex).Error("unrecognized peer id when decoding router map")
+				continue
+			}
+			peerID := peerIDByIndex[entry.PeerIndex]
+			inner[peerID] = &types.ComponentRouter{
+				NetworkID:  networkID,
+				PublicID:   entry.Id,
+				Peer:       peerID,
+				PeerGroups: entry.PeerGroupIds,
+				Masquerade: entry.Masquerade,
+				Metric:     int(entry.Metric),
+				Enabled:    entry.Enabled,
+			}
+		}
+		if len(inner) > 0 {
+			c.RoutersMap[networkID] = inner
+		}
+	}
+
+	// Phase 8: resource_policies_map (resource seq id → list of *types.Policy
+	// pointers from the decoded policies slice). Resource ID is synthesized
+	// the same way as in decodeNetworkResource.
+	for resourceID, ids := range full.ResourcePoliciesMap {
+		if len(ids.Ids) == 0 {
+			continue
+		}
+		policies := make([]*types.Policy, 0, len(ids.Ids))
+		for _, id := range ids.Ids {
+			if p, ok := policyByID[id]; ok {
+				policies = append(policies, p)
+			} else {
+				log.WithField("policy id", id).Error("unrecognized policy when decoding resource policies")
+			}
+		}
+		if len(policies) > 0 {
+			c.ResourcePoliciesMap[resourceID] = policies
+		}
+	}
+
+	// Phase 9: group_id_to_user_ids — wire keys are seq ids, synth to strings.
+	for groupId, list := range full.GroupIdToUserIds {
+		c.GroupIDToUserIDs[groupId] = append([]string(nil), list.UserIds...)
+	}
+
+	// Phase 10: posture_failed_peers — wire keys are posture-check seq ids,
+	// values are peer indexes that need to be turned into peer ids. PolicyRule
+	// SourcePostureChecks (also synth ids) reference the same key space.
+	for checkID, set := range full.PostureFailedPeers {
+		failed := make(map[string]struct{}, len(set.PeerIndexes))
+		for _, idx := range set.PeerIndexes {
+			if int(idx) < len(peerIDByIndex) {
+				failed[peerIDByIndex[idx]] = struct{}{}
+			} else {
+				log.WithField("peer idx", idx).Error("unrecognized peer when decoding posture failed peers")
+			}
+		}
+		if len(failed) > 0 {
+			c.PostureFailedPeers[checkID] = failed
+		}
+	}
+
+	// Phase 11: router_peer_indexes — peers that act as routers. They're
+	// already in c.Peers (router peers are appended to the global peers
+	// list by the encoder); RouterPeers is the subset.
+	for _, idx := range full.RouterPeerIndexes {
+		if int(idx) < len(peerIDByIndex) {
+			peerID := peerIDByIndex[idx]
+			c.RouterPeers[peerID] = c.Peers[peerID]
+		}
+	}
+
+	return c, nil
+}
+
+func decodeAccountNetwork(an *proto.AccountNetwork) *types.Network {
+	if an == nil {
+		return nil
+	}
+	n := &types.Network{
+		Identifier: an.Identifier,
+		Dns:        an.Dns,
+		Serial:     an.Serial,
+	}
+	if an.NetCidr != "" {
+		if _, ipnet, err := net.ParseCIDR(an.NetCidr); err == nil && ipnet != nil {
+			n.Net = *ipnet
+		}
+	}
+	if an.NetV6Cidr != "" {
+		if _, ipnet, err := net.ParseCIDR(an.NetV6Cidr); err == nil && ipnet != nil {
+			n.NetV6 = *ipnet
+		}
+	}
+	return n
+}
+
+func decodeAccountSettings(as *proto.AccountSettingsCompact) *types.AccountSettingsInfo {
+	if as == nil {
+		return &types.AccountSettingsInfo{}
+	}
+	return &types.AccountSettingsInfo{
+		PeerLoginExpirationEnabled: as.PeerLoginExpirationEnabled,
+		PeerLoginExpiration:        time.Duration(as.PeerLoginExpirationNs),
+	}
+}
+
+func decodePeerCompact(pc *proto.PeerCompact, peerID string) *types.ComponentPeer {
+	peer := &types.ComponentPeer{
+		ID:                     peerID,
+		Key:                    peerID,
+		SSHKey:                 string(pc.SshPubKey),
+		SSHEnabled:             pc.SshEnabled,
+		DNSLabel:               pc.DnsLabel,
+		LoginExpirationEnabled: pc.LoginExpirationEnabled,
+		AgentVersion:           pc.AgentVersion,
+		SupportsSourcePrefixes: pc.SupportsSourcePrefixes,
+		SupportsIPv6:           pc.SupportsIpv6,
+		ServerSSHAllowed:       pc.ServerSshAllowed,
+		AddedWithSSOLogin:      pc.AddedWithSsoLogin,
+	}
+	if pc.LastLoginUnixNano != 0 {
+		peer.LastLogin = time.Unix(0, pc.LastLoginUnixNano)
+	}
+	switch len(pc.Ip) {
+	case 4:
+		peer.IP = netip.AddrFrom4([4]byte{pc.Ip[0], pc.Ip[1], pc.Ip[2], pc.Ip[3]})
+	case 16:
+		var a [16]byte
+		copy(a[:], pc.Ip)
+		peer.IP = netip.AddrFrom16(a)
+	}
+	if len(pc.Ipv6) == 16 {
+		var a [16]byte
+		copy(a[:], pc.Ipv6)
+		peer.IPv6 = netip.AddrFrom16(a)
+	}
+	return peer
+}
+
+func decodePolicyCompact(pc *proto.PolicyCompact, policyID string, peerIDByIndex []string) *types.Policy {
+	rule := &types.PolicyRule{
+		ID:                  policyID, // 1 rule per policy → reuse synthesized id
+		PolicyID:            policyID,
+		Enabled:             true,
+		Action:              actionFromProto(pc.Action),
+		Protocol:            protocolFromProto(pc.Protocol),
+		Bidirectional:       pc.Bidirectional,
+		Ports:               uint32SliceToStrings(pc.Ports),
+		PortRanges:          portRangesFromProto(pc.PortRanges),
+		Sources:             pc.SourceGroupIds,
+		Destinations:        pc.DestinationGroupIds,
+		AuthorizedUser:      pc.AuthorizedUser,
+		AuthorizedGroups:    authorizedGroupsFromProto(pc.AuthorizedGroups),
+		SourceResource:      resourceFromProto(pc.SourceResource, peerIDByIndex),
+		DestinationResource: resourceFromProto(pc.DestinationResource, peerIDByIndex),
+	}
+	return &types.Policy{
+		ID:                  policyID,
+		PublicID:            pc.Id,
+		Enabled:             true,
+		Rules:               []*types.PolicyRule{rule},
+		SourcePostureChecks: pc.SourcePostureCheckIds,
+	}
+}
+
+// resourceFromProto rebuilds types.Resource. For peer-typed resources the
+// peer reference is reconstructed from the envelope's peer index — wire
+// format ships no xid for peers, so we use the synthesized peer id.
+func resourceFromProto(r *proto.ResourceCompact, peerIDByIndex []string) types.Resource {
+	if r == nil {
+		return types.Resource{}
+	}
+	out := types.Resource{Type: types.ResourceType(r.Type)}
+	if r.PeerIndexSet && int(r.PeerIndex) < len(peerIDByIndex) {
+		out.ID = peerIDByIndex[r.PeerIndex]
+	}
+	return out
+}
+
+// authorizedGroupsFromProto inverts encodeAuthorizedGroups: the wire form
+// keys by group account_seq_id, the typed PolicyRule field keys by group
+// xid string. We rebuild using the same synthetic scheme the rest of the
+// decoder uses ("g<seq>").
+func authorizedGroupsFromProto(m map[string]*proto.UserNameList) map[string][]string {
+	if len(m) == 0 {
+		return nil
+	}
+	out := make(map[string][]string, len(m))
+	for id, list := range m {
+		if list == nil {
+			continue
+		}
+		out[id] = append([]string(nil), list.Names...)
+	}
+	return out
+}
+
+func decodeRouteRaw(rr *proto.RouteRaw, peerIDByIndex []string) *nbroute.Route {
+	r := &nbroute.Route{
+		ID:                  nbroute.ID(rr.Id),
+		PublicID:            rr.Id,
+		NetID:               nbroute.NetID(rr.NetId),
+		Description:         rr.Description,
+		Domains:             domainsFromPunycode(rr.Domains),
+		KeepRoute:           rr.KeepRoute,
+		NetworkType:         nbroute.NetworkType(rr.NetworkType),
+		Masquerade:          rr.Masquerade,
+		Metric:              int(rr.Metric),
+		Enabled:             rr.Enabled,
+		Groups:              rr.GroupIds,
+		AccessControlGroups: rr.AccessControlGroupIds,
+		PeerGroups:          rr.PeerGroupIds,
+		SkipAutoApply:       rr.SkipAutoApply,
+	}
+	if rr.NetworkCidr != "" {
+		if p, err := netip.ParsePrefix(rr.NetworkCidr); err == nil {
+			r.Network = p
+		}
+	}
+	if rr.PeerIndexSet && int(rr.PeerIndex) < len(peerIDByIndex) {
+		r.Peer = peerIDByIndex[rr.PeerIndex]
+	}
+	return r
+}
+
+func decodeNameServerGroupRaw(nsg *proto.NameServerGroupRaw) *nbdns.NameServerGroup {
+	out := &nbdns.NameServerGroup{
+		ID:                   nsg.Id,
+		PublicID:             nsg.Id,
+		Groups:               nsg.GroupIds,
+		Primary:              nsg.Primary,
+		Domains:              nsg.Domains,
+		Enabled:              nsg.Enabled,
+		SearchDomainsEnabled: nsg.SearchDomainsEnabled,
+		NameServers:          make([]nbdns.NameServer, 0, len(nsg.Nameservers)),
+	}
+	for _, ns := range nsg.Nameservers {
+		if addr, err := netip.ParseAddr(ns.IP); err == nil {
+			out.NameServers = append(out.NameServers, nbdns.NameServer{
+				IP:     addr,
+				NSType: nbdns.NameServerType(ns.NSType),
+				Port:   int(ns.Port),
+			})
+		}
+	}
+	return out
+}
+
+func decodeNetworkResource(nr *proto.NetworkResourceRaw) *types.ComponentResource {
+	out := &types.ComponentResource{
+		ID:          nr.Id,
+		PublicID:    nr.Id,
+		NetworkID:   nr.NetworkSeq,
+		Name:        nr.Name,
+		Description: nr.Description,
+		Type:        types.ComponentResourceType(nr.Type),
+		Address:     nr.Address,
+		Domain:      nr.DomainValue,
+		Enabled:     nr.Enabled,
+	}
+	if nr.PrefixCidr != "" {
+		if p, err := netip.ParsePrefix(nr.PrefixCidr); err == nil {
+			out.Prefix = p
+		}
+	}
+	return out
+}
+
+func decodeSimpleRecords(records []*proto.SimpleRecord) []nbdns.SimpleRecord {
+	out := make([]nbdns.SimpleRecord, 0, len(records))
+	for _, r := range records {
+		out = append(out, nbdns.SimpleRecord{
+			Name:  r.Name,
+			Type:  int(r.Type),
+			Class: r.Class,
+			TTL:   int(r.TTL),
+			RData: r.RData,
+		})
+	}
+	return out
+}
+
+func decodeCustomZones(zones []*proto.CustomZone) []nbdns.CustomZone {
+	out := make([]nbdns.CustomZone, 0, len(zones))
+	for _, z := range zones {
+		out = append(out, nbdns.CustomZone{
+			Domain:               z.Domain,
+			Records:              decodeSimpleRecords(z.Records),
+			SearchDomainDisabled: z.SearchDomainDisabled,
+			NonAuthoritative:     z.NonAuthoritative,
+		})
+	}
+	return out
+}
+
+func uint32SliceToStrings(ports []uint32) []string {
+	if len(ports) == 0 {
+		return nil
+	}
+	out := make([]string, len(ports))
+	for i, p := range ports {
+		out[i] = strconv.FormatUint(uint64(p), 10)
+	}
+	return out
+}
+
+func portRangesFromProto(ranges []*proto.PortInfo_Range) []types.RulePortRange {
+	if len(ranges) == 0 {
+		return nil
+	}
+	out := make([]types.RulePortRange, 0, len(ranges))
+	for _, r := range ranges {
+		if r == nil || r.Start > 65535 || r.End > 65535 {
+			continue
+		}
+		out = append(out, types.RulePortRange{
+			Start: uint16(r.Start),
+			End:   uint16(r.End),
+		})
+	}
+	return out
+}
+
+func actionFromProto(a proto.RuleAction) types.PolicyTrafficActionType {
+	if a == proto.RuleAction_DROP {
+		return types.PolicyTrafficActionDrop
+	}
+	return types.PolicyTrafficActionAccept
+}
+
+func protocolFromProto(p proto.RuleProtocol) types.PolicyRuleProtocolType {
+	switch p {
+	case proto.RuleProtocol_TCP:
+		return types.PolicyRuleProtocolTCP
+	case proto.RuleProtocol_UDP:
+		return types.PolicyRuleProtocolUDP
+	case proto.RuleProtocol_ICMP:
+		return types.PolicyRuleProtocolICMP
+	case proto.RuleProtocol_ALL:
+		return types.PolicyRuleProtocolALL
+	case proto.RuleProtocol_NETBIRD_SSH:
+		return types.PolicyRuleProtocolNetbirdSSH
+	default:
+		return types.PolicyRuleProtocolALL
+	}
+}
+
+func stringSliceToSet(s []string) map[string]struct{} {
+	if len(s) == 0 {
+		return nil
+	}
+	out := make(map[string]struct{}, len(s))
+	for _, v := range s {
+		out[v] = struct{}{}
+	}
+	return out
+}
+
+// domainsFromPunycode is a thin wrapper that converts a punycode list back to
+// the domain.List type the route.Route struct expects. It accepts the
+// punycode strings as-is (no extra decoding) — symmetric with
+// route.Domains.ToPunycodeList() used in the encoder.
+func domainsFromPunycode(punycoded []string) domain.List {
+	if len(punycoded) == 0 {
+		return nil
+	}
+	out := make(domain.List, 0, len(punycoded))
+	for _, d := range punycoded {
+		out = append(out, domain.Domain(d))
+	}
+	return out
+}

shared/management/networkmap/encode.go

@@ -0,0 +1,322 @@
+// Package networkmap contains the shared NetworkMap helpers that both the
+// management server and the client agent need.
+//
+// The proto-conversion helpers (types.NetworkMap → proto.NetworkMap) live
+// here so the client can run the same conversion locally after deriving its
+// NetworkMap from a NetworkMapEnvelope, without taking a dependency on the
+// server-side conversion package (which pulls in cloud integrations and is
+// otherwise an unwanted internal import on the client).
+//
+// The helpers are pure functions over inputs — no caches, no IO, no logging
+// beyond a context-aware error log when an individual user-id hash fails.
+package networkmap
+
+import (
+	"context"
+
+	log "github.com/sirupsen/logrus"
+	goproto "google.golang.org/protobuf/proto"
+
+	nbdns "github.com/netbirdio/netbird/dns"
+	"net/netip"
+
+	nbroute "github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/proto"
+	"github.com/netbirdio/netbird/shared/management/types"
+	"github.com/netbirdio/netbird/shared/netiputil"
+	"github.com/netbirdio/netbird/shared/sshauth"
+)
+
+// ToProtocolRoutes converts a slice of typed routes to their proto form.
+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
+}
+
+// ToProtocolRoute converts one typed route to its proto form.
+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 form.
+// 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/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
+	}
+
+	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
+	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
+}
+
+// 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
+	case types.PolicyRuleProtocolNetbirdSSH:
+		return proto.RuleProtocol_NETBIRD_SSH
+	default:
+		return proto.RuleProtocol_UNKNOWN
+	}
+}
+
+// GetProtoPortInfo converts route-firewall-rule 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
+}
+
+// ShouldUsePortRange reports whether the firewall rule should use a port
+// range rather than a single port (TCP/UDP without a single port).
+func ShouldUsePortRange(rule *proto.FirewallRule) bool {
+	return rule.Port == "" && (rule.Protocol == proto.RuleProtocol_UDP || rule.Protocol == proto.RuleProtocol_TCP)
+}
+
+// ToProtocolRoutesFirewallRules converts a slice of typed route-firewall
+// rules to proto.
+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
+}
+
+// ConvertToProtoCustomZone converts an nbdns.CustomZone to its proto form.
+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
+}
+
+// ConvertToProtoNameServerGroup converts a NameServerGroup to its proto form.
+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
+}
+
+// DNSConfigCache is the cache contract for amortising NameServerGroup
+// proto-conversion across peers in the same account. Server uses a concrete
+// implementation; client passes nil (no cross-peer caching needed when
+// rebuilding a single NetworkMap from an envelope).
+type DNSConfigCache interface {
+	GetNameServerGroup(key string) (*proto.NameServerGroup, bool)
+	SetNameServerGroup(key string, value *proto.NameServerGroup)
+}
+
+// ToProtocolDNSConfig converts nbdns.Config to proto.DNSConfig. If cache is
+// non-nil, NameServerGroup proto values are cached by NSG.ID across calls —
+// the server amortises this across peers, the client passes nil.
+func ToProtocolDNSConfig(update nbdns.Config, 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 {
+		protoUpdate.CustomZones = append(protoUpdate.CustomZones, ConvertToProtoCustomZone(zone))
+	}
+
+	for _, nsGroup := range update.NameServerGroups {
+		if cache != nil {
+			if cachedGroup, exists := cache.GetNameServerGroup(nsGroup.ID); exists {
+				protoUpdate.NameServerGroups = append(protoUpdate.NameServerGroups, cachedGroup)
+				continue
+			}
+		}
+		protoGroup := ConvertToProtoNameServerGroup(nsGroup)
+		if cache != nil {
+			cache.SetNameServerGroup(nsGroup.ID, protoGroup)
+		}
+		protoUpdate.NameServerGroups = append(protoUpdate.NameServerGroups, protoGroup)
+	}
+
+	return protoUpdate
+}
+
+// AppendRemotePeerConfig appends typed peers as proto.RemotePeerConfig
+// entries to dst and returns the result.
+func AppendRemotePeerConfig(dst []*proto.RemotePeerConfig, peers []*types.ComponentPeer, 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.AgentVersion,
+		})
+	}
+	return dst
+}
+
+// BuildAuthorizedUsersProto deduplicates user-IDs into a hashed list and
+// builds per-machine-user index maps. Returns (hashedUsers, machineUsers).
+// Errors from individual hash failures are logged via the provided context;
+// they leave the offending user out of the result but don't abort the build.
+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).WithError(err).Error("failed to hash user id")
+					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
+}

shared/management/networkmap/envelope.go

@@ -0,0 +1,189 @@
+package networkmap
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+
+	"github.com/netbirdio/netbird/shared/management/proto"
+	"github.com/netbirdio/netbird/shared/management/types"
+)
+
+// EnvelopeResult is what the client engine consumes after receiving a
+// component-format NetworkMap. Both fields are populated:
+//
+//   - NetworkMap is the *proto.NetworkMap shape the engine reads today via
+//     update.GetNetworkMap() — built from the envelope's components by
+//     running Calculate() locally + converting back through the shared
+//     proto helpers + merging the optional ProxyPatch.
+//   - Components is the *types.NetworkMapComponents the engine retains so
+//     future incremental delta updates have a base to apply changes
+//     against. The client keeps it under its sync lock.
+type EnvelopeResult struct {
+	NetworkMap *proto.NetworkMap
+	Components *types.NetworkMapComponents
+}
+
+// EnvelopeToNetworkMap is the full client-side pipeline: decode the
+// component envelope back to a typed NetworkMapComponents, run Calculate()
+// locally to produce the typed NetworkMap, convert it to the wire form the
+// engine consumes, and fold in any ProxyPatch the server attached.
+//
+// localPeerKey is the receiving peer's WG pub key (used to derive
+// includeIPv6 / useSourcePrefixes from the receiving peer's own record in
+// the components struct, mirroring legacy ToSyncResponse behaviour).
+//
+// dnsName is the account's DNS domain ("netbird.cloud" etc.); used when
+// rebuilding the per-peer FQDNs that proto.RemotePeerConfig carries.
+func EnvelopeToNetworkMap(ctx context.Context, env *proto.NetworkMapEnvelope, localPeerKey, dnsName string) (*EnvelopeResult, error) {
+	components, err := DecodeEnvelope(env)
+	if err != nil {
+		return nil, fmt.Errorf("decode envelope: %w", err)
+	}
+
+	// Find the receiving peer in the decoded components by WG key.
+	// c.Peers is keyed by canonical base64 of the raw 32-byte pub key
+	// (decoder re-encodes the bytes off the wire). The caller may pass a
+	// non-canonical encoding (some persisted production keys carry
+	// non-zero trailing padding bits that survived a legacy import), so
+	// round-trip through raw bytes once to canonicalize before lookup.
+	canonicalKey := canonicalizeWgKey(localPeerKey)
+	localPeer := components.Peers[canonicalKey]
+	if localPeer == nil {
+		return nil, fmt.Errorf("receiving peer (wg_key prefix %q) not found among %d decoded peers — components have no PeerID, Calculate would return empty", trimKey(localPeerKey), len(components.Peers))
+	}
+	components.PeerID = canonicalKey
+
+	includeIPv6 := localPeer.SupportsIPv6 && localPeer.IPv6.IsValid()
+	useSourcePrefixes := localPeer.SupportsSourcePrefixes
+
+	typedNM := components.Calculate(ctx)
+
+	full := env.GetFull()
+	dnsFwdPort := int64(0)
+	if full != nil {
+		dnsFwdPort = full.DnsForwarderPort
+	}
+
+	protoNM := &proto.NetworkMap{
+		Serial: typedNM.Network.CurrentSerial(),
+	}
+	if full != nil {
+		protoNM.PeerConfig = full.PeerConfig
+	}
+	protoNM.Routes = ToProtocolRoutes(typedNM.Routes)
+	protoNM.DNSConfig = ToProtocolDNSConfig(typedNM.DNSConfig, nil, dnsFwdPort)
+
+	remotePeers := AppendRemotePeerConfig(nil, typedNM.Peers, dnsName, includeIPv6)
+	protoNM.RemotePeers = remotePeers
+	protoNM.RemotePeersIsEmpty = len(remotePeers) == 0
+
+	protoNM.OfflinePeers = AppendRemotePeerConfig(nil, typedNM.OfflinePeers, dnsName, includeIPv6)
+
+	firewallRules := ToProtocolFirewallRules(typedNM.FirewallRules, includeIPv6, useSourcePrefixes)
+	protoNM.FirewallRules = firewallRules
+	protoNM.FirewallRulesIsEmpty = len(firewallRules) == 0
+
+	routesFirewallRules := ToProtocolRoutesFirewallRules(typedNM.RoutesFirewallRules)
+	protoNM.RoutesFirewallRules = routesFirewallRules
+	protoNM.RoutesFirewallRulesIsEmpty = len(routesFirewallRules) == 0
+
+	if typedNM.AuthorizedUsers != nil {
+		hashedUsers, machineUsers := BuildAuthorizedUsersProto(ctx, typedNM.AuthorizedUsers)
+		userIDClaim := ""
+		if full != nil {
+			userIDClaim = full.UserIdClaim
+		}
+		protoNM.SshAuth = &proto.SSHAuth{
+			AuthorizedUsers: hashedUsers,
+			MachineUsers:    machineUsers,
+			UserIDClaim:     userIDClaim,
+		}
+	}
+
+	if typedNM.ForwardingRules != nil {
+		forwardingRules := make([]*proto.ForwardingRule, 0, len(typedNM.ForwardingRules))
+		for _, rule := range typedNM.ForwardingRules {
+			forwardingRules = append(forwardingRules, rule.ToProto())
+		}
+		protoNM.ForwardingRules = forwardingRules
+	}
+
+	// Merge the proxy patch the server attached. Mirrors the legacy
+	// NetworkMap.Merge step that the server runs after Calculate().
+	if full != nil && full.ProxyPatch != nil {
+		mergeProxyPatch(protoNM, full.ProxyPatch)
+	}
+
+	return &EnvelopeResult{
+		NetworkMap: protoNM,
+		Components: components,
+	}, nil
+}
+
+// mergeProxyPatch folds a ProxyPatch's pre-expanded fragments into the
+// proto.NetworkMap that Calculate() produced. Mirrors types.NetworkMap.Merge
+// — same six collections, deduplicated where the legacy merge dedupes.
+func mergeProxyPatch(nm *proto.NetworkMap, patch *proto.ProxyPatch) {
+	nm.RemotePeers = appendUniquePeers(nm.RemotePeers, patch.Peers)
+	nm.OfflinePeers = appendUniquePeers(nm.OfflinePeers, patch.OfflinePeers)
+	nm.FirewallRules = append(nm.FirewallRules, patch.FirewallRules...)
+	nm.Routes = append(nm.Routes, patch.Routes...)
+	nm.RoutesFirewallRules = append(nm.RoutesFirewallRules, patch.RouteFirewallRules...)
+	nm.ForwardingRules = append(nm.ForwardingRules, patch.ForwardingRules...)
+	if len(nm.RemotePeers) > 0 {
+		nm.RemotePeersIsEmpty = false
+	}
+	if len(nm.FirewallRules) > 0 {
+		nm.FirewallRulesIsEmpty = false
+	}
+	if len(nm.RoutesFirewallRules) > 0 {
+		nm.RoutesFirewallRulesIsEmpty = false
+	}
+}
+
+// appendUniquePeers dedupes by WgPubKey — mirrors legacy
+// mergeUniquePeersByID's intent (legacy keyed off Peer.ID; in proto form the
+// closest stable identifier is WgPubKey).
+func appendUniquePeers(dst, extra []*proto.RemotePeerConfig) []*proto.RemotePeerConfig {
+	if len(extra) == 0 {
+		return dst
+	}
+	seen := make(map[string]struct{}, len(dst))
+	for _, p := range dst {
+		if p == nil {
+			continue
+		}
+		seen[p.WgPubKey] = struct{}{}
+	}
+	for _, p := range extra {
+		if p == nil {
+			continue
+		}
+		if _, ok := seen[p.WgPubKey]; ok {
+			continue
+		}
+		seen[p.WgPubKey] = struct{}{}
+		dst = append(dst, p)
+	}
+	return dst
+}
+
+func trimKey(s string) string {
+	if len(s) > 12 {
+		return s[:12]
+	}
+	return s
+}
+
+// canonicalizeWgKey normalises a base64-encoded WireGuard public key so it
+// matches the canonical encoding emitted by the envelope decoder. Returns
+// the input unchanged when it does not decode to 32 raw bytes (caller will
+// hit a miss in the peer map and surface the error).
+func canonicalizeWgKey(s string) string {
+	raw, err := base64.StdEncoding.DecodeString(s)
+	if err != nil || len(raw) != 32 {
+		return s
+	}
+	return base64.StdEncoding.EncodeToString(raw)
+}

shared/management/networkmap/envelope_test.go

@@ -0,0 +1,294 @@
+package networkmap_test
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"fmt"
+	"net"
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	goproto "google.golang.org/protobuf/proto"
+
+	mgmtgrpc "github.com/netbirdio/netbird/management/internals/shared/grpc"
+	"github.com/netbirdio/netbird/management/server/types"
+	nbnetworkmap "github.com/netbirdio/netbird/shared/management/networkmap"
+	"github.com/netbirdio/netbird/shared/management/proto"
+)
+
+// TestEnvelopeToNetworkMap_RoundTrip exercises the full client-side pipeline:
+// build a small components struct, encode an envelope, marshal/unmarshal the
+// wire bytes, decode back via EnvelopeToNetworkMap, and verify the result is
+// non-empty and consistent.
+func TestEnvelopeToNetworkMap_RoundTrip(t *testing.T) {
+	c, localPeerKey := buildSmokeComponents(t)
+
+	envelope := mgmtgrpc.EncodeNetworkMapEnvelope(mgmtgrpc.ComponentsEnvelopeInput{
+		Components: c,
+		DNSDomain:  "netbird.cloud",
+	})
+
+	wire, err := goproto.Marshal(envelope)
+	require.NoError(t, err, "marshal envelope")
+
+	var decoded proto.NetworkMapEnvelope
+	require.NoError(t, goproto.Unmarshal(wire, &decoded), "unmarshal envelope")
+
+	result, err := nbnetworkmap.EnvelopeToNetworkMap(context.Background(), &decoded, localPeerKey, "netbird.cloud")
+	require.NoError(t, err, "EnvelopeToNetworkMap")
+	require.NotNil(t, result)
+	require.NotNil(t, result.NetworkMap, "decoded NetworkMap must be non-nil")
+	require.NotNil(t, result.Components, "Components must be retained for future delta updates")
+	require.NotNil(t, result.Components.AccountSettings)
+	require.NotEmpty(t, result.NetworkMap.RemotePeers, "two-peer allow policy should produce one remote peer")
+	require.NotEmpty(t, result.NetworkMap.FirewallRules, "two-peer allow policy should produce firewall rules")
+}
+
+// TestCalculate_FirewallRuleProtocol_NeverNetbirdSSH guards against the
+// scenario where a rule with Protocol=NetbirdSSH leaks the enum value into
+// proto.FirewallRule.Protocol. Calculate() must rewrite NetbirdSSH → TCP
+// before forming firewall rules. Without that rewrite, agents fall into
+// UNKNOWN-protocol handling, which on some platforms downgrades to
+// allow-all — a real security regression.
+func TestCalculate_FirewallRuleProtocol_NeverNetbirdSSH(t *testing.T) {
+	c, localPeerKey := buildSmokeComponents(t)
+	// Replace the smoke policy with a NetbirdSSH-protocol allow.
+	c.Policies = []*types.Policy{{
+		ID: "pol-ssh", PublicID: "2", Enabled: true,
+		Rules: []*types.PolicyRule{{
+			ID:            "rule-ssh",
+			Enabled:       true,
+			Action:        types.PolicyTrafficActionAccept,
+			Protocol:      types.PolicyRuleProtocolNetbirdSSH,
+			Bidirectional: true,
+			Sources:       []string{"group-all"},
+			Destinations:  []string{"group-all"},
+		}},
+	}}
+
+	envelope := mgmtgrpc.EncodeNetworkMapEnvelope(mgmtgrpc.ComponentsEnvelopeInput{
+		Components: c,
+		DNSDomain:  "netbird.cloud",
+	})
+	wire, err := goproto.Marshal(envelope)
+	require.NoError(t, err)
+	var decoded proto.NetworkMapEnvelope
+	require.NoError(t, goproto.Unmarshal(wire, &decoded))
+
+	result, err := nbnetworkmap.EnvelopeToNetworkMap(context.Background(), &decoded, localPeerKey, "netbird.cloud")
+	require.NoError(t, err)
+	require.NotEmpty(t, result.NetworkMap.FirewallRules, "ssh policy should produce firewall rules")
+	for i, fr := range result.NetworkMap.FirewallRules {
+		require.NotEqualf(t, proto.RuleProtocol_NETBIRD_SSH, fr.Protocol,
+			"FirewallRules[%d].Protocol must be the rewritten TCP, not NETBIRD_SSH", i)
+	}
+}
+
+func TestEnvelopeToNetworkMap_NilEnvelope(t *testing.T) {
+	_, err := nbnetworkmap.EnvelopeToNetworkMap(context.Background(), nil, "key", "netbird.cloud")
+	require.Error(t, err, "nil envelope must produce an error rather than panic")
+}
+
+func TestEnvelopeToNetworkMap_FullPayloadMissing(t *testing.T) {
+	env := &proto.NetworkMapEnvelope{}
+	_, err := nbnetworkmap.EnvelopeToNetworkMap(context.Background(), env, "key", "netbird.cloud")
+	require.Error(t, err, "envelope with no Full payload must produce an error")
+}
+
+// TestDecodeEnvelope_MalformedWgKeyPeerSkipped feeds an envelope where one
+// peer has a wg_pub_key that is not 32 bytes long. The decoder must skip
+// that peer (keeping the rest of the snapshot usable) instead of aborting
+// the whole sync — mirrors legacy behaviour that tolerates an occasional
+// bad row.
+func TestDecodeEnvelope_MalformedWgKeyPeerSkipped(t *testing.T) {
+	c, localPeerKey := buildSmokeComponents(t)
+	envelope := mgmtgrpc.EncodeNetworkMapEnvelope(mgmtgrpc.ComponentsEnvelopeInput{
+		Components: c,
+		DNSDomain:  "netbird.cloud",
+	})
+	require.NotNil(t, envelope.GetFull())
+
+	full := envelope.GetFull()
+	require.Len(t, full.Peers, 2, "smoke fixture should have two peers")
+
+	// Truncate the second peer's wg_pub_key so it fails the length gate.
+	for _, p := range full.Peers {
+		if base64.StdEncoding.EncodeToString(p.WgPubKey) != localPeerKey {
+			p.WgPubKey = p.WgPubKey[:31]
+		}
+	}
+
+	wire, err := goproto.Marshal(envelope)
+	require.NoError(t, err, "marshal envelope")
+	var decoded proto.NetworkMapEnvelope
+	require.NoError(t, goproto.Unmarshal(wire, &decoded), "unmarshal envelope")
+
+	result, err := nbnetworkmap.EnvelopeToNetworkMap(context.Background(), &decoded, localPeerKey, "netbird.cloud")
+	require.NoError(t, err, "EnvelopeToNetworkMap must tolerate one bad peer key")
+	require.NotNil(t, result)
+	require.NotNil(t, result.Components)
+	require.Len(t, result.Components.Peers, 1, "the well-formed peer survives, the malformed one is dropped")
+}
+
+// TestEnvelopeRoundTrip_AllGroupShortCircuitParity reproduces prod accounts
+// with several groups literally named "All" where the "All"-named group does
+// not contain every peer. Server-side Calculate short-circuits destination
+// expansion at the first group named "All" (getUniquePeerIDsFromGroupsIDs),
+// ignoring the remaining destination groups. The wire must preserve enough
+// group identity for the decoded components to short-circuit identically —
+// otherwise the client unions all destination groups and emits extra
+// firewall rules the server never produced.
+func TestEnvelopeRoundTrip_AllGroupShortCircuitParity(t *testing.T) {
+	ctx := context.Background()
+
+	peers := map[string]*types.ComponentPeer{}
+	for i, id := range []string{"peer-T", "peer-S", "peer-ALL", "peer-O"} {
+		peers[id] = &types.ComponentPeer{
+			ID:           id,
+			Key:          randomWgKey(t),
+			IP:           netip.AddrFrom4([4]byte{100, 64, 0, byte(i + 1)}),
+			DNSLabel:     id,
+			AgentVersion: "0.40.0",
+		}
+	}
+
+	c := &types.NetworkMapComponents{
+		PeerID: "peer-T",
+		Network: &types.Network{
+			Identifier: "net-all-groups",
+			Net:        net.IPNet{IP: net.IP{100, 64, 0, 0}, Mask: net.CIDRMask(10, 32)},
+			Serial:     1,
+		},
+		AccountSettings: &types.AccountSettingsInfo{},
+		DNSSettings:     &types.DNSSettings{},
+		Peers:           peers,
+		Groups: map[string]*types.ComponentGroup{
+			"g-src": {ID: "g-src", PublicID: "1", Name: "staff", Peers: []string{"peer-T", "peer-S"}},
+			"g-all": {ID: "g-all", PublicID: "2", Name: "All", Peers: []string{"peer-ALL"}},
+			"g-two": {ID: "g-two", PublicID: "3", Name: "second", Peers: []string{"peer-T", "peer-O"}},
+		},
+		Policies: []*types.Policy{{
+			ID: "pol-multi-dest", PublicID: "10", Enabled: true,
+			Rules: []*types.PolicyRule{{
+				ID:           "rule-multi-dest",
+				Enabled:      true,
+				Action:       types.PolicyTrafficActionAccept,
+				Protocol:     types.PolicyRuleProtocolALL,
+				Sources:      []string{"g-src"},
+				Destinations: []string{"g-all", "g-two"},
+			}},
+		}},
+	}
+
+	serverNM := c.Calculate(ctx)
+	require.NotNil(t, serverNM)
+
+	envelope := mgmtgrpc.EncodeNetworkMapEnvelope(mgmtgrpc.ComponentsEnvelopeInput{
+		Components: c,
+		DNSDomain:  "netbird.cloud",
+	})
+	wire, err := goproto.Marshal(envelope)
+	require.NoError(t, err, "marshal envelope")
+	var decodedEnv proto.NetworkMapEnvelope
+	require.NoError(t, goproto.Unmarshal(wire, &decodedEnv), "unmarshal envelope")
+
+	result, err := nbnetworkmap.EnvelopeToNetworkMap(ctx, &decodedEnv, peers["peer-T"].Key, "netbird.cloud")
+	require.NoError(t, err, "EnvelopeToNetworkMap")
+	clientNM := result.NetworkMap
+
+	serverRules := make([]string, 0, len(serverNM.FirewallRules))
+	for _, r := range serverNM.FirewallRules {
+		serverRules = append(serverRules, fmt.Sprintf("%s/%d", r.PeerIP, r.Direction))
+	}
+	clientRules := make([]string, 0, len(clientNM.FirewallRules))
+	for _, r := range clientNM.FirewallRules {
+		clientRules = append(clientRules, fmt.Sprintf("%s/%d", r.PeerIP, r.Direction)) // nolint:staticcheck
+	}
+	require.ElementsMatch(t, serverRules, clientRules,
+		"client-side Calculate must expand destination groups exactly like the server")
+
+	serverPeers := make([]string, 0, len(serverNM.Peers))
+	for _, p := range serverNM.Peers {
+		serverPeers = append(serverPeers, p.Key)
+	}
+	clientPeers := make([]string, 0, len(clientNM.RemotePeers))
+	for _, p := range clientNM.RemotePeers {
+		clientPeers = append(clientPeers, p.WgPubKey)
+	}
+	require.ElementsMatch(t, serverPeers, clientPeers,
+		"client-side Calculate must connect the same remote peers as the server")
+}
+
+// buildSmokeComponents returns a minimal NetworkMapComponents (2 peers, 1
+// group, 1 allow policy) plus the receiving peer's WG public key. Sufficient
+// to validate the encode → marshal → decode → Calculate pipeline produces
+// non-empty output.
+func buildSmokeComponents(t *testing.T) (*types.NetworkMapComponents, string) {
+	t.Helper()
+
+	peerAKey := randomWgKey(t)
+	peerBKey := randomWgKey(t)
+
+	peerA := &types.ComponentPeer{
+		ID:           "peer-A",
+		Key:          peerAKey,
+		IP:           netip.AddrFrom4([4]byte{100, 64, 0, 1}),
+		DNSLabel:     "peerA",
+		AgentVersion: "0.40.0",
+	}
+	peerB := &types.ComponentPeer{
+		ID:           "peer-B",
+		Key:          peerBKey,
+		IP:           netip.AddrFrom4([4]byte{100, 64, 0, 2}),
+		DNSLabel:     "peerB",
+		AgentVersion: "0.40.0",
+	}
+
+	group := &types.ComponentGroup{
+		ID: "group-all", PublicID: "1", Name: "All",
+		Peers: []string{"peer-A", "peer-B"},
+	}
+
+	policy := &types.Policy{
+		ID: "pol-allow", PublicID: "1", Enabled: true,
+		Rules: []*types.PolicyRule{{
+			ID:            "rule-allow",
+			Enabled:       true,
+			Action:        types.PolicyTrafficActionAccept,
+			Protocol:      types.PolicyRuleProtocolALL,
+			Bidirectional: true,
+			Sources:       []string{"group-all"},
+			Destinations:  []string{"group-all"},
+		}},
+	}
+
+	c := &types.NetworkMapComponents{
+		PeerID: "peer-A",
+		Network: &types.Network{
+			Identifier: "net-smoke",
+			Net:        net.IPNet{IP: net.IP{100, 64, 0, 0}, Mask: net.CIDRMask(10, 32)},
+			Serial:     1,
+		},
+		AccountSettings: &types.AccountSettingsInfo{},
+		DNSSettings:     &types.DNSSettings{},
+		Peers: map[string]*types.ComponentPeer{
+			"peer-A": peerA,
+			"peer-B": peerB,
+		},
+		Groups: map[string]*types.ComponentGroup{
+			"group-all": group,
+		},
+		Policies: []*types.Policy{policy},
+	}
+	return c, peerAKey
+}
+
+func randomWgKey(t *testing.T) string {
+	t.Helper()
+	var raw [32]byte
+	_, err := rand.Read(raw[:])
+	require.NoError(t, err)
+	return base64.StdEncoding.EncodeToString(raw[:])
+}

shared/management/proto/management.proto

@@ -150,6 +150,14 @@ message SyncResponse {
   //                              SSO-registered; client clears its anchor
   //   set, valid timestamp     → new absolute UTC deadline
   google.protobuf.Timestamp sessionExpiresAt = 7;
+
+  // NetworkMapEnvelope carries the component-based wire format for peers that
+  // advertise PeerCapabilityComponentNetworkMap. When set, NetworkMap (field 5)
+  // is left empty: management ships components and the client runs Calculate()
+  // locally instead of receiving an expanded NetworkMap.
+  NetworkMapEnvelope NetworkMapEnvelope = 8;
+
+  int32 Version = 9;
 }
 
 message  SyncMetaRequest {
@@ -231,6 +239,8 @@ enum PeerCapability {
   PeerCapabilitySourcePrefixes = 1;
   // Client handles IPv6 overlay addresses and firewall rules.
   PeerCapabilityIPv6Overlay = 2;
+  // Client receives NetworkMap as components and assembles it locally.
+  PeerCapabilityComponentNetworkMap = 3;
 }
 
 // PeerSystemMeta is machine meta data like OS and version.
@@ -254,6 +264,7 @@ message PeerSystemMeta {
   Flags flags = 17;
 
   repeated PeerCapability capabilities = 18;
+  int32 syncMessageVersion = 19;
 }
 
 message LoginResponse {
@@ -658,6 +669,13 @@ enum RuleProtocol {
   UDP = 3;
   ICMP = 4;
   CUSTOM = 5;
+  // NETBIRD_SSH (types.PolicyRuleProtocolType "netbird-ssh") is the marker
+  // policy rule that drives SSH-server activation in Calculate(). The legacy
+  // proto.FirewallRule path doesn't ship this value (Calculate already
+  // expands SSH rules into TCP/22 before encoding), but the components path
+  // ships RAW policies — the client must see this protocol to derive
+  // AuthorizedUsers locally.
+  NETBIRD_SSH = 6;
 }
 
 enum RuleDirection {
@@ -798,3 +816,435 @@ message StopExposeRequest {
 }
 
 message StopExposeResponse {}
+
+// =====================================================================
+// Component-based NetworkMap wire format (PeerCapabilityComponentNetworkMap).
+//
+// Peers that advertise this capability receive NetworkMap building blocks
+// (peers + groups + policies + routes + dns + ssh + forwarding) and run the
+// expansion (Calculate) locally instead of receiving a fully-expanded
+// NetworkMap from the server.
+// =====================================================================
+
+// NetworkMapEnvelope wraps either a full snapshot or a delta. Only Full is
+// emitted today; Delta is reserved for the incremental-update work.
+message NetworkMapEnvelope {
+  oneof payload {
+    NetworkMapComponentsFull full = 1;
+    NetworkMapComponentsDelta delta = 2;
+  }
+}
+
+// NetworkMapComponentsFull is the full per-peer component snapshot. The
+// client decodes it into a types.NetworkMapComponents and runs Calculate()
+// locally to produce the same NetworkMap the legacy server path would have
+// produced. Every field carries RAW component data — no server-side
+// expansion (firewall rules, DNS config, SSH auth, route firewall rules,
+// forwarding rules) is shipped; the client computes those itself.
+message NetworkMapComponentsFull {
+  uint64 serial = 1;
+
+  // Peer config for the receiving peer (legacy proto.PeerConfig kept as-is —
+  // it carries the receiving peer's own overlay address, FQDN, SSH config).
+  PeerConfig peer_config = 2;
+
+  // Account-level network metadata (id, IPv4/IPv6 overlay subnets, DNS,
+  // serial). Mirrors types.Network.
+  AccountNetwork network = 3;
+
+  // Account-level settings the client needs for its local Calculate().
+  AccountSettingsCompact account_settings = 4;
+
+  // Account DNS settings (mirrors types.DNSSettings).
+  DNSSettingsCompact dns_settings = 5;
+
+  // Domain shared across all peers in this account, e.g. "netbird.cloud".
+  // Each peer's FQDN is dns_label + "." + dns_domain.
+  string dns_domain = 6;
+
+  // Custom-zone domain for this peer's view (c.CustomZoneDomain). Empty when
+  // the peer has no custom zone records.
+  string custom_zone_domain = 7;
+
+  // Deduplicated agent versions; PeerCompact.agent_version_idx indexes here.
+  // Empty string at index 0 if any peer has no version.
+  repeated string agent_versions = 8;
+
+  // All peers (deduplicated). The client splits peers into online / offline
+  // locally using account_settings.peer_login_expiration on receive.
+  repeated PeerCompact peers = 9;
+
+  // Indexes into peers for the subset that may act as routers.
+  repeated uint32 router_peer_indexes = 10;
+
+  // Policies that affect the receiving peer.
+  repeated PolicyCompact policies = 11;
+
+  // Groups in unspecified order — clients key off id (public_id).
+  repeated GroupCompact groups = 12;
+
+  // Routes relevant to this peer, raw shape (mirrors []*route.Route).
+  repeated RouteRaw routes = 13;
+
+  // Nameserver groups (mirrors []*nbdns.NameServerGroup).
+  repeated NameServerGroupRaw nameserver_groups = 14;
+
+  // All DNS records the client needs to assemble its custom zone. Reuses
+  // the existing SimpleRecord wire shape.
+  repeated SimpleRecord all_dns_records = 15;
+
+  // Custom zones (typically the peer's own zone). Reuses the existing
+  // CustomZone wire shape.
+  repeated CustomZone account_zones = 16;
+
+  // Network resources (mirrors []*resourceTypes.NetworkResource).
+  repeated NetworkResourceRaw network_resources = 17;
+
+  // Routers per network. Outer key: network public_id. Each entry is
+  // the set of routers backing that network for this peer's view.
+  map<string, NetworkRouterList> routers_map = 18;
+
+  // For each NetworkResource public_id, the indexes into policies[]
+  // that apply to it.
+  map<string, PolicyIds> resource_policies_map = 19;
+
+  // Group-id (public_id) → user ids authorized for SSH on members.
+  map<string, UserIDList> group_id_to_user_ids = 20;
+
+  // Account-level allowed user ids (used by Calculate() when assembling SSH
+  // authorized users for the receiving peer).
+  repeated string allowed_user_ids = 21;
+
+  // Per posture-check public_id, the set of peer indexes that failed
+  // the check. Server-side evaluation result; clients do not re-evaluate.
+  map<string, PeerIndexSet> posture_failed_peers = 22;
+
+  // Account-level DNS forwarder port (mirrors the legacy
+  // proto.DNSConfig.ForwarderPort). Computed by the controller from peer
+  // versions; clients fold it into their Calculate() DNS output.
+  int64 dns_forwarder_port = 23;
+
+  // Pre-expanded NetworkMap fragments injected post-Calculate by external
+  // controllers (BYOP / port-forwarding proxies). The receiving client
+  // merges these into its locally-computed NetworkMap the same way the
+  // legacy server does via NetworkMap.Merge — so downstream consumers see
+  // a unified merged result regardless of source.
+  ProxyPatch proxy_patch = 24;
+
+  // SSH UserIDClaim — server-side HttpServerConfig.AuthUserIDClaim, or
+  // "sub" by default. Populated in proto.SSHAuth.UserIDClaim when the
+  // client rebuilds the NetworkMap from this envelope. Empty when the
+  // account has no AuthorizedUsers (and thus no SshAuth to populate).
+  string user_id_claim = 25;
+
+  // Reserved for future component additions (incremental_serial, parent_seq,
+  // etc.) without forcing a renumber.
+  reserved 26 to 50;
+}
+
+// ProxyPatch carries NetworkMap fragments that don't fit the component-graph
+// model — they're pre-expanded by external controllers (BYOP /
+// port-forwarding proxies) and injected post-Calculate. Fields use the
+// legacy wire types because the proxy delivers them pre-formed; there is
+// no raw component shape to convert from. Empty when no proxy is active.
+message ProxyPatch {
+  repeated RemotePeerConfig peers = 1;
+  repeated RemotePeerConfig offline_peers = 2;
+  repeated FirewallRule firewall_rules = 3;
+  repeated Route routes = 4;
+  repeated RouteFirewallRule route_firewall_rules = 5;
+  repeated ForwardingRule forwarding_rules = 6;
+}
+
+// AccountSettingsCompact carries the account-level settings the client needs
+// to evaluate locally. Mirrors the subset of types.AccountSettingsInfo that
+// Calculate() actually reads — login-expiration (used to filter expired
+// peers). Inactivity expiration is purely server-side bookkeeping and is not
+// shipped.
+message AccountSettingsCompact {
+  bool peer_login_expiration_enabled = 1;
+  // Login expiration window. Unit is nanoseconds (matches time.Duration).
+  int64 peer_login_expiration_ns = 2;
+}
+
+// AccountNetwork is the account-level overlay metadata. Mirrors types.Network
+// so the client can populate NetworkMap.Network without a server round-trip.
+message AccountNetwork {
+  string identifier = 1;
+  // IPv4 overlay subnet in CIDR form (e.g. "100.64.0.0/16").
+  string net_cidr = 2;
+  // IPv6 ULA overlay subnet in CIDR form (e.g. "fd00:4e42::/64"). Empty when
+  // the account has no IPv6 overlay yet.
+  string net_v6_cidr = 3;
+  string dns = 4;
+  uint64 serial = 5;
+}
+
+// NetworkMapComponentsDelta is reserved for the incremental update
+// protocol. Field numbers 1–100 are pre-allocated to keep room for the
+// planned event types without needing a renumber.
+message NetworkMapComponentsDelta {
+  reserved 1 to 100;
+}
+
+// PeerCompact is the wire-shape of a remote peer used by the component
+// format. It carries every field of types.Peer that the client's local
+// Calculate() reads — including the trio needed to evaluate
+// LoginExpired() (added_with_sso_login + login_expiration_enabled +
+// last_login_unix_nano). Fields the client does not consume (Status,
+// CreatedAt, etc.) are not shipped.
+message PeerCompact {
+  // Raw 32-byte WireGuard public key (no base64 wrapping).
+  bytes wg_pub_key = 1;
+
+  // Raw 4-byte IPv4 overlay address. Always a /32 host route, so no prefix
+  // byte is needed.
+  bytes ip = 2;
+
+  // Raw 16-byte IPv6 overlay address; always a /128 host route. Empty when
+  // the peer has no IPv6 overlay address.
+  bytes ipv6 = 3;
+
+  // Raw SSH public key bytes (or empty).
+  bytes ssh_pub_key = 4;
+
+  // DNS label without the account's domain suffix. Full FQDN is
+  // dns_label + "." + NetworkMapComponentsFull.dns_domain.
+  string dns_label = 5;
+
+  string agent_version = 6;
+
+  // True iff the peer was added via SSO login (i.e., types.Peer.UserID is
+  // non-empty). Combined with login_expiration_enabled and
+  // last_login_unix_nano this lets the client reproduce
+  // (*Peer).LoginExpired() locally.
+  bool added_with_sso_login = 7;
+
+  // True when the peer's login can expire — mirrors
+  // types.Peer.LoginExpirationEnabled.
+  bool login_expiration_enabled = 8;
+
+  // Unix-nanosecond timestamp of the peer's last login. 0 when the peer has
+  // never logged in (server stores nil; client treats 0 as "epoch", which
+  // makes a fresh peer immediately expired iff login_expiration_enabled is
+  // true — the same semantics as types.Peer.GetLastLogin).
+  int64 last_login_unix_nano = 9;
+
+  // True when the peer has an SSH server enabled locally. Used by the
+  // legacy SSH path in Calculate() (`policyRuleImpliesLegacySSH`): a rule
+  // with protocol ALL/TCP-with-SSH-ports activates SSH for the receiving
+  // peer when this bit is set, even without an explicit NetbirdSSH rule.
+  bool ssh_enabled = 10;
+
+  // Mirror of types.Peer.SupportsIPv6() — !Meta.Flags.DisableIPv6 &&
+  // HasCapability(PeerCapabilityIPv6Overlay). Used by the local peer's
+  // Calculate() when deciding whether to emit IPv6 firewall rules
+  // (appendIPv6FirewallRule) against this peer's IPv6 address.
+  bool supports_ipv6 = 11;
+
+  // Mirror of types.Peer.SupportsSourcePrefixes() —
+  // HasCapability(PeerCapabilitySourcePrefixes). Determines whether the
+  // local peer's Calculate() emits SourcePrefixes alongside legacy PeerIP
+  // fields in proto.FirewallRule.
+  bool supports_source_prefixes = 12;
+
+  // Mirror of types.Peer.Meta.Flags.ServerSSHAllowed. Read by Calculate()
+  // when expanding TCP port-22 firewall rules — the native SSH companion
+  // (port 22022) is only added when this flag is set and the peer agent
+  // version supports it.
+  bool server_ssh_allowed = 13;
+}
+
+// PolicyCompact is the compact form of a policy rule. Group references use
+// the public_ids; the client resolves
+// them against NetworkMapComponentsFull.groups. Direction is derived per-peer
+// on the client (ingress when the peer is in destination_group_ids, egress
+// when in source_group_ids; both when bidirectional).
+message PolicyCompact {
+  // public_id. Used as a stable reference for
+  // ResourcePoliciesMap.indexes and future delta updates.
+  string id = 1;
+
+  RuleAction action = 2;
+  RuleProtocol protocol = 3;
+  bool bidirectional = 4;
+
+  // Single ports referenced by the rule.
+  repeated uint32 ports = 5;
+
+  // Port ranges (start..end) referenced by the rule.
+  repeated PortInfo.Range port_ranges = 6;
+
+  // Group ids (public_ids) of source / destination groups.
+  repeated string source_group_ids = 7;
+  repeated string destination_group_ids = 8;
+
+  // SSH authorization fields. PolicyRule.AuthorizedGroups maps the rule's
+  // applicable group ids (public_ids) to a list of local-user names —
+  // when a peer in one of those groups is the SSH destination, the named
+  // local users gain access. AuthorizedUser is the single-user form
+  // (legacy: rule scopes SSH to one specific user id).
+  //
+  // Both fields are only consumed by Calculate() when the rule's protocol
+  // is NetbirdSSH (or the legacy implicit-SSH heuristic).
+  map<string, UserNameList> authorized_groups = 9;
+  string authorized_user = 10;
+
+  // Resource-typed rule sources/destinations. When a rule targets a specific
+  // peer (rather than groups), Calculate() reads SourceResource /
+  // DestinationResource — without these the rule's connection resources
+  // can't be produced on the client. ResourceCompact's peer_index refers to
+  // NetworkMapComponentsFull.peers; type is the raw ResourceType string
+  // ("peer", "host", "subnet", "domain"). Only "peer" is meaningful for
+  // Calculate's resource-typed rule path today.
+  ResourceCompact source_resource = 11;
+  ResourceCompact destination_resource = 12;
+
+  // Posture-check ids gating this policy's source peers. Calculate()
+  // reads them when filtering rule peers (peers that fail any listed check
+  // are dropped from sourcePeers). Match keys in
+  // NetworkMapComponentsFull.posture_failed_peers.
+  repeated string source_posture_check_ids = 13;
+}
+
+// ResourceCompact mirrors types.Resource. Used by PolicyCompact to carry
+// rule.SourceResource / rule.DestinationResource when the rule targets a
+// specific resource (typically a peer) rather than groups.
+// peer_index_set tells whether peer_index is valid (proto3 uint32 cannot
+// disambiguate "0" from "unset"); set only when type == "peer".
+message ResourceCompact {
+  string type = 1;
+  bool peer_index_set = 2;
+  uint32 peer_index = 3;
+  reserved 4; // future: host/subnet/domain references when needed
+}
+
+// UserNameList is a list of local-user names — used as the value type in
+// PolicyCompact.authorized_groups.
+message UserNameList {
+  repeated string names = 1;
+}
+
+// GroupCompact is the wire-shape of a group: public id, optional
+// name, and indexes into NetworkMapComponentsFull.peers identifying members.
+message GroupCompact {
+  // id comes from PublicID. Used by PolicyCompact.source_group_ids / destination_group_ids.
+  string id = 1;
+
+  // Indexes into NetworkMapComponentsFull.peers.
+  repeated uint32 peer_indexes = 2;
+
+  // True when the group is named "All" (types.Group.IsGroupAll). The
+  // client-side Calculate short-circuits group→peer expansion on such
+  // groups exactly like the server does; without this bit the decoded
+  // groups lose that property and the two sides expand policy
+  // destinations differently.
+  bool is_all = 3;
+}
+
+// DNSSettingsCompact mirrors types.DNSSettings.
+message DNSSettingsCompact {
+  // Group ids (public_id) whose DNS management is disabled.
+  repeated string disabled_management_group_ids = 1;
+}
+
+// RouteRaw mirrors *route.Route (the domain type), trimmed to fields that
+// types.NetworkMapComponents.Calculate() reads. Group references are
+// public_ids; the routing peer (when set) is referenced by index into
+// NetworkMapComponentsFull.peers.
+message RouteRaw {
+  string id = 1; // public_id
+  string net_id = 2;
+  string description = 3;
+
+  // Either network_cidr (e.g. "10.0.0.0/16") or domains is set, not both.
+  string network_cidr = 4;
+  repeated string domains = 5;
+  bool keep_route = 6;
+
+  // Routing peer reference: peer_index_set tells whether peer_index is valid
+  // (proto3 uint32 cannot disambiguate "0" from "unset"). Mutually exclusive
+  // with peer_group_ids.
+  //
+  // peer_index decodes back to types.Peer.ID (the peer's xid string), NOT
+  // to its WireGuard public key. This matches the server-side data flow:
+  // c.Routes carry route.Peer = peer.ID, and getRoutingPeerRoutes mutates
+  // it to peer.Key only after the route has been admitted to the network
+  // map. Decoders MUST set Route.Peer = peer.ID; the legacy Calculate()
+  // path will substitute the WG key downstream.
+  bool peer_index_set = 7;
+  uint32 peer_index = 8;
+  repeated string peer_group_ids = 9;
+
+  int32 network_type = 10;
+  bool masquerade = 11;
+  int32 metric = 12;
+  bool enabled = 13;
+  repeated string group_ids = 14;
+  repeated string access_control_group_ids = 15;
+  bool skip_auto_apply = 16;
+}
+
+// NameServerGroupRaw mirrors *nbdns.NameServerGroup. Distinct from the
+// legacy NameServerGroup (which is the wire-trimmed shape consumed by
+// proto.DNSConfig and lacks the Name/Description/Groups/Enabled fields).
+message NameServerGroupRaw {
+  string id = 1;
+  // Reuses the legacy NameServer wire shape (IP as string).
+  repeated NameServer nameservers = 2;
+  // Group ids the NSG distributes nameservers to.
+  repeated string group_ids = 3;
+  bool primary = 4;
+  repeated string domains = 5;
+  bool enabled = 6;
+  bool search_domains_enabled = 7;
+}
+
+// NetworkResourceRaw mirrors *resourceTypes.NetworkResource.
+//
+message NetworkResourceRaw {
+  string id = 1;
+  string network_seq = 2;
+  string name = 3;
+  string description = 4;
+  // Resource type: "host" / "subnet" / "domain".
+  string type = 5;
+  string address = 6;
+  string domain_value = 7;  // resource.Domain
+  string prefix_cidr = 8;
+  bool enabled = 9;
+}
+
+// NetworkRouterList carries the routers backing one network.
+message NetworkRouterList {
+  // Routers in this network, keyed by peer_index (the routing peer).
+  repeated NetworkRouterEntry entries = 1;
+}
+
+// NetworkRouterEntry mirrors a single *routerTypes.NetworkRouter; the routing
+// peer is referenced by index into NetworkMapComponentsFull.peers.
+message NetworkRouterEntry {
+  string id = 1;
+  uint32 peer_index = 2;
+  bool peer_index_set = 3;
+  repeated string peer_group_ids = 4;
+  bool masquerade = 5;
+  int32 metric = 6;
+  bool enabled = 7;
+}
+
+message PolicyIds {
+  repeated string ids = 1;
+}
+
+// UserIDList is a list of user ids — used as the value type in
+// NetworkMapComponentsFull.group_id_to_user_ids.
+message UserIDList {
+  repeated string user_ids = 1;
+}
+
+// PeerIndexSet is a set of peer indexes — used as the value type in
+// NetworkMapComponentsFull.posture_failed_peers.
+message PeerIndexSet {
+  repeated uint32 peer_indexes = 1;
+}

shared/management/types/component_types.go

@@ -0,0 +1,103 @@
+package types
+
+import (
+	"net/netip"
+	"time"
+)
+
+// ComponentPeer is the self-contained peer representation used by
+// NetworkMapComponents and the calculated NetworkMap. It carries exactly the
+// subset of peer data that crosses the components wire format, so the shared
+// calculation layer stays independent of the management server's domain
+// types.
+type ComponentPeer struct {
+	ID                     string
+	Key                    string
+	IP                     netip.Addr
+	IPv6                   netip.Addr
+	DNSLabel               string
+	SSHKey                 string
+	SSHEnabled             bool
+	ServerSSHAllowed       bool
+	AgentVersion           string
+	SupportsSourcePrefixes bool
+	SupportsIPv6           bool
+	LoginExpirationEnabled bool
+	AddedWithSSOLogin      bool
+	LastLogin              time.Time
+}
+
+// FQDN returns the peer's FQDN combined of the peer's DNS label and the system's DNS domain.
+func (p *ComponentPeer) FQDN(dnsDomain string) string {
+	if dnsDomain == "" {
+		return ""
+	}
+	return p.DNSLabel + "." + dnsDomain
+}
+
+// LoginExpired indicates whether the peer's login has expired, mirroring the
+// server-side peer semantics: only SSO-added peers with login expiration
+// enabled can expire.
+func (p *ComponentPeer) LoginExpired(expiresIn time.Duration) (bool, time.Duration) {
+	if !p.AddedWithSSOLogin || !p.LoginExpirationEnabled {
+		return false, 0
+	}
+	timeLeft := time.Until(p.LastLogin.Add(expiresIn))
+	return timeLeft <= 0, timeLeft
+}
+
+// GroupAllName is the reserved name of the default group that contains every peer in an account.
+const GroupAllName = "All"
+
+// ComponentGroup is the self-contained group representation used by
+// NetworkMapComponents: just the membership view the network-map calculation
+// needs, without the server's storage fields.
+type ComponentGroup struct {
+	ID       string
+	PublicID string
+	Name     string
+	Peers    []string
+}
+
+// IsGroupAll checks if the group is a default "All" group.
+func (g *ComponentGroup) IsGroupAll() bool {
+	return g.Name == GroupAllName
+}
+
+// ComponentRouter is the self-contained network-router representation used by
+// NetworkMapComponents.
+type ComponentRouter struct {
+	NetworkID  string
+	PublicID   string
+	Peer       string
+	PeerGroups []string
+	Masquerade bool
+	Metric     int
+	Enabled    bool
+}
+
+// ComponentResourceType mirrors the network-resource type enum on the
+// components wire format.
+type ComponentResourceType string
+
+const (
+	ComponentResourceHost   ComponentResourceType = "host"
+	ComponentResourceSubnet ComponentResourceType = "subnet"
+	ComponentResourceDomain ComponentResourceType = "domain"
+)
+
+// ComponentResource is the self-contained network-resource representation
+// used by NetworkMapComponents.
+type ComponentResource struct {
+	ID          string
+	PublicID    string
+	NetworkID   string
+	AccountID   string
+	Name        string
+	Description string
+	Type        ComponentResourceType
+	Address     string
+	Domain      string
+	Prefix      netip.Prefix
+	Enabled     bool
+}

shared/management/types/dns_settings.go

@@ -0,0 +1,16 @@
+package types
+
+// DNSSettings defines dns settings at the account level
+type DNSSettings struct {
+	// DisabledManagementGroups groups whose DNS management is disabled
+	DisabledManagementGroups []string `gorm:"serializer:json"`
+}
+
+// Copy returns a copy of the DNS settings
+func (d DNSSettings) Copy() DNSSettings {
+	settings := DNSSettings{
+		DisabledManagementGroups: make([]string, len(d.DisabledManagementGroups)),
+	}
+	copy(settings.DisabledManagementGroups, d.DisabledManagementGroups)
+	return settings
+}

shared/management/types/firewall_helpers.go

@@ -0,0 +1,129 @@
+package types
+
+import (
+	"strconv"
+
+	"github.com/netbirdio/netbird/version"
+)
+
+const (
+	firewallRuleMinPortRangesVer = "0.48.0"
+	firewallRuleMinNativeSSHVer  = "0.60.0"
+
+	nativeSSHPortString  = "22022"
+	nativeSSHPortNumber  = 22022
+	defaultSSHPortString = "22"
+	defaultSSHPortNumber = 22
+)
+
+type supportedFeatures struct {
+	nativeSSH  bool
+	portRanges bool
+}
+
+type LookupMap map[string]struct{}
+
+func PolicyRuleImpliesLegacySSH(rule *PolicyRule) bool {
+	return rule.Protocol == PolicyRuleProtocolALL || (rule.Protocol == PolicyRuleProtocolTCP && (portsIncludesSSH(rule.Ports) || portRangeIncludesSSH(rule.PortRanges)))
+}
+
+func portRangeIncludesSSH(portRanges []RulePortRange) bool {
+	for _, pr := range portRanges {
+		if (pr.Start <= defaultSSHPortNumber && pr.End >= defaultSSHPortNumber) || (pr.Start <= nativeSSHPortNumber && pr.End >= nativeSSHPortNumber) {
+			return true
+		}
+	}
+	return false
+}
+
+func portsIncludesSSH(ports []string) bool {
+	for _, port := range ports {
+		if port == defaultSSHPortString || port == nativeSSHPortString {
+			return true
+		}
+	}
+	return false
+}
+
+// ExpandPortsAndRanges expands Ports and PortRanges of a rule into individual firewall rules.
+func ExpandPortsAndRanges(base FirewallRule, rule *PolicyRule, peer *ComponentPeer) []*FirewallRule {
+	features := peerSupportedFirewallFeatures(peer.AgentVersion)
+
+	var expanded []*FirewallRule
+
+	for _, port := range rule.Ports {
+		fr := base
+		fr.Port = port
+		expanded = append(expanded, &fr)
+	}
+
+	for _, portRange := range rule.PortRanges {
+		if len(rule.Ports) > 0 {
+			break
+		}
+		fr := base
+
+		if features.portRanges {
+			fr.PortRange = portRange
+		} else {
+			if portRange.Start != portRange.End {
+				continue
+			}
+			fr.Port = strconv.FormatUint(uint64(portRange.Start), 10)
+		}
+		expanded = append(expanded, &fr)
+	}
+
+	if shouldCheckRulesForNativeSSH(features.nativeSSH, rule, peer) || rule.Protocol == PolicyRuleProtocolNetbirdSSH {
+		expanded = addNativeSSHRule(base, expanded)
+	}
+
+	return expanded
+}
+
+func addNativeSSHRule(base FirewallRule, expanded []*FirewallRule) []*FirewallRule {
+	shouldAdd := false
+	for _, fr := range expanded {
+		if isPortInRule(nativeSSHPortString, 22022, fr) {
+			return expanded
+		}
+		if isPortInRule(defaultSSHPortString, 22, fr) {
+			shouldAdd = true
+		}
+	}
+	if !shouldAdd {
+		return expanded
+	}
+
+	fr := base
+	fr.Port = nativeSSHPortString
+	return append(expanded, &fr)
+}
+
+func isPortInRule(portString string, portInt uint16, rule *FirewallRule) bool {
+	return rule.Port == portString || (rule.PortRange.Start <= portInt && portInt <= rule.PortRange.End)
+}
+
+func shouldCheckRulesForNativeSSH(supportsNative bool, rule *PolicyRule, peer *ComponentPeer) bool {
+	return supportsNative && peer.SSHEnabled && peer.ServerSSHAllowed && rule.Protocol == PolicyRuleProtocolTCP
+}
+
+func peerSupportedFirewallFeatures(peerVer string) supportedFeatures {
+	if version.IsDevelopmentVersion(peerVer) {
+		return supportedFeatures{true, true}
+	}
+
+	var features supportedFeatures
+
+	meetMinVer, err := version.MeetsMinVersion(firewallRuleMinNativeSSHVer, peerVer)
+	features.nativeSSH = err == nil && meetMinVer
+
+	if features.nativeSSH {
+		features.portRanges = true
+	} else {
+		meetMinVer, err = version.MeetsMinVersion(firewallRuleMinPortRangesVer, peerVer)
+		features.portRanges = err == nil && meetMinVer
+	}
+
+	return features
+}

shared/management/types/firewall_rule.go

@@ -0,0 +1,181 @@
+package types
+
+import (
+	"context"
+	"fmt"
+	"reflect"
+	"strconv"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+
+	nbroute "github.com/netbirdio/netbird/route"
+)
+
+const (
+	FirewallRuleDirectionIN  = 0
+	FirewallRuleDirectionOUT = 1
+)
+
+// FirewallRule is a rule of the firewall.
+type FirewallRule struct {
+	// PolicyID is the ID of the policy this rule is derived from
+	PolicyID string
+
+	// PeerIP of the peer
+	PeerIP string
+
+	// Direction of the traffic
+	Direction int
+
+	// Action of the traffic
+	Action string
+
+	// Protocol of the traffic
+	Protocol string
+
+	// Port of the traffic
+	Port string
+
+	// PortRange represents the range of ports for a firewall rule
+	PortRange RulePortRange
+}
+
+// Equal checks if two firewall rules are equal.
+func (r *FirewallRule) Equal(other *FirewallRule) bool {
+	return reflect.DeepEqual(r, other)
+}
+
+// GenerateRouteFirewallRules generates a list of firewall rules for a given route.
+// For static routes, source ranges match the destination family (v4 or v6).
+// For dynamic routes (domain-based), separate v4 and v6 rules are generated
+// so the routing peer's forwarding chain allows both address families.
+func GenerateRouteFirewallRules(ctx context.Context, route *nbroute.Route, rule *PolicyRule, groupPeers []*ComponentPeer, direction int, includeIPv6 bool) []*RouteFirewallRule {
+	rulesExists := make(map[string]struct{})
+	rules := make([]*RouteFirewallRule, 0)
+
+	v4Sources, v6Sources := splitPeerSourcesByFamily(groupPeers)
+
+	isV6Route := route.Network.Addr().Is6()
+
+	// Skip v6 destination routes entirely for peers without IPv6 support
+	if isV6Route && !includeIPv6 {
+		return rules
+	}
+
+	// Pick sources matching the destination family
+	sourceRanges := v4Sources
+	if isV6Route {
+		sourceRanges = v6Sources
+	}
+
+	baseRule := RouteFirewallRule{
+		PolicyID:     rule.PolicyID,
+		RouteID:      route.ID,
+		SourceRanges: sourceRanges,
+		Action:       string(rule.Action),
+		Destination:  route.Network.String(),
+		Protocol:     string(rule.Protocol),
+		Domains:      route.Domains,
+		IsDynamic:    route.IsDynamic(),
+	}
+
+	if len(rule.Ports) == 0 {
+		rules = append(rules, generateRulesWithPortRanges(baseRule, rule, rulesExists)...)
+	} else {
+		rules = append(rules, generateRulesWithPorts(ctx, baseRule, rule, rulesExists)...)
+	}
+
+	// Generate v6 counterpart for dynamic routes and 0.0.0.0/0 exit node routes.
+	isDefaultV4 := !isV6Route && route.Network.Bits() == 0
+	if includeIPv6 && (route.IsDynamic() || isDefaultV4) && len(v6Sources) > 0 {
+		v6Rule := baseRule
+		v6Rule.SourceRanges = v6Sources
+		if isDefaultV4 {
+			v6Rule.Destination = "::/0"
+			v6Rule.RouteID = route.ID + "-v6-default"
+		}
+		if len(rule.Ports) == 0 {
+			rules = append(rules, generateRulesWithPortRanges(v6Rule, rule, rulesExists)...)
+		} else {
+			rules = append(rules, generateRulesWithPorts(ctx, v6Rule, rule, rulesExists)...)
+		}
+	}
+
+	return rules
+}
+
+// splitPeerSourcesByFamily separates peer IPs into v4 (/32) and v6 (/128) source ranges.
+func splitPeerSourcesByFamily(groupPeers []*ComponentPeer) (v4, v6 []string) {
+	v4 = make([]string, 0, len(groupPeers))
+	v6 = make([]string, 0, len(groupPeers))
+	for _, peer := range groupPeers {
+		if peer == nil {
+			continue
+		}
+		v4 = append(v4, fmt.Sprintf(AllowedIPsFormat, peer.IP))
+		if peer.IPv6.IsValid() {
+			v6 = append(v6, fmt.Sprintf(AllowedIPsV6Format, peer.IPv6))
+		}
+	}
+	return
+}
+
+// generateRulesForPeer generates rules for a given peer based on ports and port ranges.
+func generateRulesWithPortRanges(baseRule RouteFirewallRule, rule *PolicyRule, rulesExists map[string]struct{}) []*RouteFirewallRule {
+	rules := make([]*RouteFirewallRule, 0)
+
+	ruleIDBase := generateRuleIDBase(rule, baseRule)
+	if len(rule.Ports) == 0 {
+		if len(rule.PortRanges) == 0 {
+			if _, ok := rulesExists[ruleIDBase]; !ok {
+				rulesExists[ruleIDBase] = struct{}{}
+				rules = append(rules, &baseRule)
+			}
+		} else {
+			for _, portRange := range rule.PortRanges {
+				ruleID := fmt.Sprintf("%s%d-%d", ruleIDBase, portRange.Start, portRange.End)
+				if _, ok := rulesExists[ruleID]; !ok {
+					rulesExists[ruleID] = struct{}{}
+					pr := baseRule
+					pr.PortRange = portRange
+					rules = append(rules, &pr)
+				}
+			}
+		}
+		return rules
+	}
+
+	return rules
+}
+
+// generateRulesWithPorts generates rules when specific ports are provided.
+func generateRulesWithPorts(ctx context.Context, baseRule RouteFirewallRule, rule *PolicyRule, rulesExists map[string]struct{}) []*RouteFirewallRule {
+	rules := make([]*RouteFirewallRule, 0)
+	ruleIDBase := generateRuleIDBase(rule, baseRule)
+
+	for _, port := range rule.Ports {
+		ruleID := ruleIDBase + port
+		if _, ok := rulesExists[ruleID]; ok {
+			continue
+		}
+		rulesExists[ruleID] = struct{}{}
+
+		pr := baseRule
+		p, err := strconv.ParseUint(port, 10, 16)
+		if err != nil {
+			log.WithContext(ctx).Errorf("failed to parse port %s for rule: %s", port, rule.ID)
+			continue
+		}
+
+		pr.Port = uint16(p)
+		rules = append(rules, &pr)
+	}
+
+	return rules
+}
+
+// generateRuleIDBase generates the base rule ID for checking duplicates.
+func generateRuleIDBase(rule *PolicyRule, baseRule RouteFirewallRule) string {
+	return rule.ID + strings.Join(baseRule.SourceRanges, ",") + strconv.Itoa(FirewallRuleDirectionIN) + baseRule.Protocol + baseRule.Action
+}

shared/management/types/firewall_rule_test.go

@@ -0,0 +1,196 @@
+package types
+
+import (
+	"context"
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/domain"
+)
+
+func TestSplitPeerSourcesByFamily(t *testing.T) {
+	peers := []*ComponentPeer{
+		{
+			IP:   netip.MustParseAddr("100.64.0.1"),
+			IPv6: netip.MustParseAddr("fd00::1"),
+		},
+		{
+			IP: netip.MustParseAddr("100.64.0.2"),
+		},
+		{
+			IP:   netip.MustParseAddr("100.64.0.3"),
+			IPv6: netip.MustParseAddr("fd00::3"),
+		},
+		nil,
+	}
+
+	v4, v6 := splitPeerSourcesByFamily(peers)
+
+	assert.Equal(t, []string{"100.64.0.1/32", "100.64.0.2/32", "100.64.0.3/32"}, v4)
+	assert.Equal(t, []string{"fd00::1/128", "fd00::3/128"}, v6)
+}
+
+func TestGenerateRouteFirewallRules_V4Route(t *testing.T) {
+	peers := []*ComponentPeer{
+		{
+			IP:   netip.MustParseAddr("100.64.0.1"),
+			IPv6: netip.MustParseAddr("fd00::1"),
+		},
+		{
+			IP: netip.MustParseAddr("100.64.0.2"),
+		},
+	}
+
+	r := &route.Route{
+		ID:      "route1",
+		Network: netip.MustParsePrefix("10.0.0.0/24"),
+	}
+	rule := &PolicyRule{
+		PolicyID: "policy1",
+		ID:       "rule1",
+		Action:   PolicyTrafficActionAccept,
+		Protocol: PolicyRuleProtocolALL,
+	}
+
+	rules := GenerateRouteFirewallRules(context.Background(), r, rule, peers, FirewallRuleDirectionIN, true)
+
+	require.Len(t, rules, 1)
+	assert.Equal(t, []string{"100.64.0.1/32", "100.64.0.2/32"}, rules[0].SourceRanges, "v4 route should only have v4 sources")
+	assert.Equal(t, "10.0.0.0/24", rules[0].Destination)
+}
+
+func TestGenerateRouteFirewallRules_V6Route(t *testing.T) {
+	peers := []*ComponentPeer{
+		{
+			IP:   netip.MustParseAddr("100.64.0.1"),
+			IPv6: netip.MustParseAddr("fd00::1"),
+		},
+		{
+			IP: netip.MustParseAddr("100.64.0.2"),
+		},
+	}
+
+	r := &route.Route{
+		ID:      "route1",
+		Network: netip.MustParsePrefix("2001:db8::/32"),
+	}
+	rule := &PolicyRule{
+		PolicyID: "policy1",
+		ID:       "rule1",
+		Action:   PolicyTrafficActionAccept,
+		Protocol: PolicyRuleProtocolALL,
+	}
+
+	rules := GenerateRouteFirewallRules(context.Background(), r, rule, peers, FirewallRuleDirectionIN, true)
+
+	require.Len(t, rules, 1)
+	assert.Equal(t, []string{"fd00::1/128"}, rules[0].SourceRanges, "v6 route should only have v6 sources")
+}
+
+func TestGenerateRouteFirewallRules_DynamicRoute_DualStack(t *testing.T) {
+	peers := []*ComponentPeer{
+		{
+			IP:   netip.MustParseAddr("100.64.0.1"),
+			IPv6: netip.MustParseAddr("fd00::1"),
+		},
+		{
+			IP: netip.MustParseAddr("100.64.0.2"),
+		},
+	}
+
+	r := &route.Route{
+		ID:          "route1",
+		NetworkType: route.DomainNetwork,
+		Domains:     domain.List{"example.com"},
+	}
+	rule := &PolicyRule{
+		PolicyID: "policy1",
+		ID:       "rule1",
+		Action:   PolicyTrafficActionAccept,
+		Protocol: PolicyRuleProtocolALL,
+	}
+
+	rules := GenerateRouteFirewallRules(context.Background(), r, rule, peers, FirewallRuleDirectionIN, true)
+
+	require.Len(t, rules, 2, "dynamic route should produce both v4 and v6 rules")
+	assert.Equal(t, []string{"100.64.0.1/32", "100.64.0.2/32"}, rules[0].SourceRanges)
+	assert.Equal(t, []string{"fd00::1/128"}, rules[1].SourceRanges)
+	assert.Equal(t, rules[0].Domains, rules[1].Domains)
+	assert.True(t, rules[0].IsDynamic)
+	assert.True(t, rules[1].IsDynamic)
+}
+
+func TestGenerateRouteFirewallRules_DynamicRoute_NoV6Peers(t *testing.T) {
+	peers := []*ComponentPeer{
+		{IP: netip.MustParseAddr("100.64.0.1")},
+		{IP: netip.MustParseAddr("100.64.0.2")},
+	}
+
+	r := &route.Route{
+		ID:          "route1",
+		NetworkType: route.DomainNetwork,
+		Domains:     domain.List{"example.com"},
+	}
+	rule := &PolicyRule{
+		PolicyID: "policy1",
+		ID:       "rule1",
+		Action:   PolicyTrafficActionAccept,
+		Protocol: PolicyRuleProtocolALL,
+	}
+
+	rules := GenerateRouteFirewallRules(context.Background(), r, rule, peers, FirewallRuleDirectionIN, true)
+
+	require.Len(t, rules, 1, "no v6 peers means only v4 rule")
+	assert.Equal(t, []string{"100.64.0.1/32", "100.64.0.2/32"}, rules[0].SourceRanges)
+}
+
+func TestGenerateRouteFirewallRules_IncludeIPv6False(t *testing.T) {
+	peers := []*ComponentPeer{
+		{
+			IP:   netip.MustParseAddr("100.64.0.1"),
+			IPv6: netip.MustParseAddr("fd00::1"),
+		},
+		{
+			IP:   netip.MustParseAddr("100.64.0.2"),
+			IPv6: netip.MustParseAddr("fd00::2"),
+		},
+	}
+
+	t.Run("v6 route excluded", func(t *testing.T) {
+		r := &route.Route{
+			ID:      "route1",
+			Network: netip.MustParsePrefix("2001:db8::/32"),
+		}
+		rule := &PolicyRule{
+			PolicyID: "policy1",
+			ID:       "rule1",
+			Action:   PolicyTrafficActionAccept,
+			Protocol: PolicyRuleProtocolALL,
+		}
+
+		rules := GenerateRouteFirewallRules(context.Background(), r, rule, peers, FirewallRuleDirectionIN, false)
+		assert.Empty(t, rules, "v6 route should produce no rules when includeIPv6 is false")
+	})
+
+	t.Run("dynamic route only v4", func(t *testing.T) {
+		r := &route.Route{
+			ID:          "route1",
+			NetworkType: route.DomainNetwork,
+			Domains:     domain.List{"example.com"},
+		}
+		rule := &PolicyRule{
+			PolicyID: "policy1",
+			ID:       "rule1",
+			Action:   PolicyTrafficActionAccept,
+			Protocol: PolicyRuleProtocolALL,
+		}
+
+		rules := GenerateRouteFirewallRules(context.Background(), r, rule, peers, FirewallRuleDirectionIN, false)
+		require.Len(t, rules, 1, "dynamic route with includeIPv6=false should produce only v4 rule")
+		assert.Equal(t, []string{"100.64.0.1/32", "100.64.0.2/32"}, rules[0].SourceRanges)
+	})
+}

shared/management/types/network.go

@@ -0,0 +1,397 @@
+package types
+
+import (
+	"encoding/binary"
+	"fmt"
+	"math/rand"
+	"net"
+	"net/netip"
+	"slices"
+	"sync"
+	"time"
+
+	"github.com/c-robinson/iplib"
+	"github.com/rs/xid"
+	"golang.org/x/exp/maps"
+
+	nbdns "github.com/netbirdio/netbird/dns"
+	"github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/proto"
+	"github.com/netbirdio/netbird/shared/management/status"
+)
+
+const (
+	// SubnetSize is a size of the subnet of the global network, e.g.  100.77.0.0/16
+	SubnetSize = 16
+	// NetSize is a global network size 100.64.0.0/10
+	NetSize = 10
+
+	// AllowedIPsFormat generates Wireguard AllowedIPs format (e.g. 100.64.30.1/32)
+	AllowedIPsFormat = "%s/32"
+	// AllowedIPsV6Format generates AllowedIPs format for v6 (e.g. fd12:3456:7890::1/128)
+	AllowedIPsV6Format = "%s/128"
+
+	// IPv6SubnetSize is the prefix length of per-account IPv6 subnets.
+	// Each account gets a /64 from its unique /48 ULA prefix.
+	IPv6SubnetSize = 64
+)
+
+type NetworkMap struct {
+	Peers               []*ComponentPeer
+	Network             *Network
+	Routes              []*route.Route
+	DNSConfig           nbdns.Config
+	OfflinePeers        []*ComponentPeer
+	FirewallRules       []*FirewallRule
+	RoutesFirewallRules []*RouteFirewallRule
+	ForwardingRules     []*ForwardingRule
+	AuthorizedUsers     map[string]map[string]struct{}
+	VNCAuthorizedUsers  map[string]map[string]struct{}
+	VNCSessionPubKeys   []VNCSessionPubKey
+	EnableSSH           bool
+	// ForceRoutingPeerDNSResolution forces the peer to run/use routing-peer DNS
+	// resolution regardless of the account-global setting, for reverse-proxy
+	// domain targets.
+	ForceRoutingPeerDNSResolution bool
+}
+
+func (nm *NetworkMap) Merge(other *NetworkMap) {
+	nm.Peers = mergeUniquePeersByID(nm.Peers, other.Peers)
+	nm.Routes = mergeUnique(nm.Routes, other.Routes)
+	nm.OfflinePeers = mergeUniquePeersByID(nm.OfflinePeers, other.OfflinePeers)
+	nm.FirewallRules = mergeUnique(nm.FirewallRules, other.FirewallRules)
+	nm.RoutesFirewallRules = mergeUnique(nm.RoutesFirewallRules, other.RoutesFirewallRules)
+	nm.ForwardingRules = mergeUnique(nm.ForwardingRules, other.ForwardingRules)
+	nm.ForceRoutingPeerDNSResolution = nm.ForceRoutingPeerDNSResolution || other.ForceRoutingPeerDNSResolution
+}
+
+type comparableObject[T any] interface {
+	Equal(other T) bool
+}
+
+func mergeUnique[T comparableObject[T]](arr1, arr2 []T) []T {
+	var result []T
+
+	for _, item := range arr1 {
+		if !containsEqual(result, item) {
+			result = append(result, item)
+		}
+	}
+
+	for _, item := range arr2 {
+		if !containsEqual(result, item) {
+			result = append(result, item)
+		}
+	}
+
+	return result
+}
+
+func containsEqual[T comparableObject[T]](slice []T, element T) bool {
+	for _, item := range slice {
+		if item.Equal(element) {
+			return true
+		}
+	}
+	return false
+}
+
+func mergeUniquePeersByID(peers1, peers2 []*ComponentPeer) []*ComponentPeer {
+	result := make(map[string]*ComponentPeer)
+	for _, peer := range peers1 {
+		result[peer.ID] = peer
+	}
+	for _, peer := range peers2 {
+		if _, ok := result[peer.ID]; !ok {
+			result[peer.ID] = peer
+		}
+	}
+
+	return maps.Values(result)
+}
+
+type ForwardingRule struct {
+	RuleProtocol      string
+	DestinationPorts  RulePortRange
+	TranslatedAddress net.IP
+	TranslatedPorts   RulePortRange
+}
+
+func (f *ForwardingRule) ToProto() *proto.ForwardingRule {
+	var protocol proto.RuleProtocol
+	switch f.RuleProtocol {
+	case "icmp":
+		protocol = proto.RuleProtocol_ICMP
+	case "tcp":
+		protocol = proto.RuleProtocol_TCP
+	case "udp":
+		protocol = proto.RuleProtocol_UDP
+	case "all":
+		protocol = proto.RuleProtocol_ALL
+	default:
+		protocol = proto.RuleProtocol_UNKNOWN
+	}
+	return &proto.ForwardingRule{
+		Protocol:          protocol,
+		DestinationPort:   f.DestinationPorts.ToProto(),
+		TranslatedAddress: ipToBytes(f.TranslatedAddress),
+		TranslatedPort:    f.TranslatedPorts.ToProto(),
+	}
+}
+
+func (f *ForwardingRule) Equal(other *ForwardingRule) bool {
+	return f.RuleProtocol == other.RuleProtocol &&
+		f.DestinationPorts.Equal(&other.DestinationPorts) &&
+		f.TranslatedAddress.Equal(other.TranslatedAddress) &&
+		f.TranslatedPorts.Equal(&other.TranslatedPorts)
+}
+
+func ipToBytes(ip net.IP) []byte {
+	if ip4 := ip.To4(); ip4 != nil {
+		return ip4
+	}
+	return ip.To16()
+}
+
+type Network struct {
+	Identifier string    `json:"id"`
+	Net        net.IPNet `gorm:"serializer:json"`
+	// NetV6 is the IPv6 ULA subnet for this account's overlay. Empty if not yet allocated.
+	NetV6 net.IPNet `gorm:"serializer:json"`
+	Dns   string
+	// Serial is an ID that increments by 1 when any change to the network happened (e.g. new peer has been added).
+	// Used to synchronize state to the client apps.
+	Serial uint64
+
+	Mu sync.Mutex `json:"-" gorm:"-"`
+}
+
+// NewNetwork creates a new Network initializing it with a Serial=0
+// It takes a random /16 subnet from 100.64.0.0/10 (64 different subnets)
+// and a random /64 subnet from fd00:4e42::/32 for IPv6.
+func NewNetwork() *Network {
+	n := iplib.NewNet4(net.ParseIP("100.64.0.0"), NetSize)
+	sub, _ := n.Subnet(SubnetSize)
+
+	s := rand.NewSource(time.Now().UnixNano())
+	r := rand.New(s)
+	intn := r.Intn(len(sub))
+
+	return &Network{
+		Identifier: xid.New().String(),
+		Net:        sub[intn].IPNet,
+		NetV6:      AllocateIPv6Subnet(r),
+		Dns:        "",
+		Serial:     0,
+	}
+}
+
+// AllocateIPv6Subnet generates a random RFC 4193 ULA /64 prefix.
+// The format follows RFC 4193 section 3.1: fd + 40-bit Global ID + 16-bit Subnet ID.
+// The Global ID and Subnet ID are randomized (simplified from the SHA-1 algorithm
+// in section 3.2.2), giving 2^56 possible /64 subnets across all accounts.
+func AllocateIPv6Subnet(r *rand.Rand) net.IPNet {
+	ip := make(net.IP, 16)
+	ip[0] = 0xfd
+	// Bytes 1-5: 40-bit random Global ID
+	ip[1] = byte(r.Intn(256))
+	ip[2] = byte(r.Intn(256))
+	ip[3] = byte(r.Intn(256))
+	ip[4] = byte(r.Intn(256))
+	ip[5] = byte(r.Intn(256))
+	// Bytes 6-7: 16-bit random Subnet ID
+	ip[6] = byte(r.Intn(256))
+	ip[7] = byte(r.Intn(256))
+
+	return net.IPNet{
+		IP:   ip,
+		Mask: net.CIDRMask(IPv6SubnetSize, 128),
+	}
+}
+
+// IncSerial increments Serial by 1 reflecting that the network state has been changed
+func (n *Network) IncSerial() {
+	n.Mu.Lock()
+	defer n.Mu.Unlock()
+	n.Serial++
+}
+
+// CurrentSerial returns the Network.Serial of the network (latest state id)
+func (n *Network) CurrentSerial() uint64 {
+	n.Mu.Lock()
+	defer n.Mu.Unlock()
+	return n.Serial
+}
+
+func (n *Network) Copy() *Network {
+	n.Mu.Lock()
+	defer n.Mu.Unlock()
+	return &Network{
+		Identifier: n.Identifier,
+		Net:        n.Net,
+		NetV6:      n.NetV6,
+		Dns:        n.Dns,
+		Serial:     n.Serial,
+	}
+}
+
+// AllocatePeerIP picks an available IP from a netip.Prefix.
+// This method considers already taken IPs and reuses IPs if there are gaps in takenIps.
+// E.g. if prefix=100.30.0.0/16 and takenIps=[100.30.0.1, 100.30.0.4] then the result would be 100.30.0.2 or 100.30.0.3.
+func AllocatePeerIP(prefix netip.Prefix, takenIps []netip.Addr) (netip.Addr, error) {
+	b := prefix.Masked().Addr().As4()
+	baseIP := binary.BigEndian.Uint32(b[:])
+	hostBits := 32 - prefix.Bits()
+	totalIPs := uint32(1 << hostBits)
+
+	taken := make(map[uint32]struct{}, len(takenIps)+1)
+	taken[baseIP] = struct{}{}            // reserve network IP
+	taken[baseIP+totalIPs-1] = struct{}{} // reserve broadcast IP
+
+	for _, ip := range takenIps {
+		ab := ip.As4()
+		taken[binary.BigEndian.Uint32(ab[:])] = struct{}{}
+	}
+
+	rng := rand.New(rand.NewSource(time.Now().UnixNano()))
+	maxAttempts := (int(totalIPs) - len(taken)) / 100
+
+	for i := 0; i < maxAttempts; i++ {
+		offset := uint32(rng.Intn(int(totalIPs-2))) + 1
+		candidate := baseIP + offset
+		if _, exists := taken[candidate]; !exists {
+			return uint32ToIP(candidate), nil
+		}
+	}
+
+	for offset := uint32(1); offset < totalIPs-1; offset++ {
+		candidate := baseIP + offset
+		if _, exists := taken[candidate]; !exists {
+			return uint32ToIP(candidate), nil
+		}
+	}
+
+	return netip.Addr{}, status.Errorf(status.PreconditionFailed, "network %s is out of IPs", prefix.String())
+}
+
+// AllocateRandomPeerIP picks a random available IP from a netip.Prefix.
+func AllocateRandomPeerIP(prefix netip.Prefix) (netip.Addr, error) {
+	b := prefix.Masked().Addr().As4()
+	baseIP := binary.BigEndian.Uint32(b[:])
+	hostBits := 32 - prefix.Bits()
+	totalIPs := uint32(1 << hostBits)
+
+	rng := rand.New(rand.NewSource(time.Now().UnixNano()))
+	offset := uint32(rng.Intn(int(totalIPs-2))) + 1
+
+	candidate := baseIP + offset
+	return uint32ToIP(candidate), nil
+}
+
+// AllocateRandomPeerIPv6 picks a random host address within the given IPv6 prefix.
+// Only the host bits (after the prefix length) are randomized.
+func AllocateRandomPeerIPv6(prefix netip.Prefix) (netip.Addr, error) {
+	ones := prefix.Bits()
+	if ones == 0 || ones > 126 || !prefix.Addr().Is6() {
+		return netip.Addr{}, fmt.Errorf("invalid IPv6 subnet: %s", prefix.String())
+	}
+
+	ip := prefix.Addr().As16()
+
+	rng := rand.New(rand.NewSource(time.Now().UnixNano()))
+
+	// Determine which byte the host bits start in
+	firstHostByte := ones / 8
+	// If the prefix doesn't end on a byte boundary, handle the partial byte
+	partialBits := ones % 8
+
+	if partialBits > 0 {
+		// Keep the network bits in the partial byte, randomize the rest
+		hostMask := byte(0xff >> partialBits)
+		ip[firstHostByte] = (ip[firstHostByte] & ^hostMask) | (byte(rng.Intn(256)) & hostMask)
+		firstHostByte++
+	}
+
+	// Randomize remaining full host bytes
+	for i := firstHostByte; i < 16; i++ {
+		ip[i] = byte(rng.Intn(256))
+	}
+
+	// Avoid all-zeros and all-ones host parts by checking only host bits.
+	if isHostAllZeroOrOnes(ip[:], ones) {
+		ip = prefix.Masked().Addr().As16()
+		ip[15] |= 0x01
+	}
+
+	return netip.AddrFrom16(ip).Unmap(), nil
+}
+
+// isHostAllZeroOrOnes checks whether all host bits (after prefixLen) are zero or all ones.
+func isHostAllZeroOrOnes(ip []byte, prefixLen int) bool {
+	hostStart := prefixLen / 8
+	partialBits := prefixLen % 8
+
+	hostSlice := slices.Clone(ip[hostStart:])
+	if partialBits > 0 {
+		hostSlice[0] &= 0xff >> partialBits
+	}
+
+	allZero := !slices.ContainsFunc(hostSlice, func(v byte) bool { return v != 0 })
+	if allZero {
+		return true
+	}
+
+	// Build the all-ones mask for host bits
+	onesMask := make([]byte, len(hostSlice))
+	for i := range onesMask {
+		onesMask[i] = 0xff
+	}
+	if partialBits > 0 {
+		onesMask[0] = 0xff >> partialBits
+	}
+
+	return slices.Equal(hostSlice, onesMask)
+}
+
+func uint32ToIP(n uint32) netip.Addr {
+	var b [4]byte
+	binary.BigEndian.PutUint32(b[:], n)
+	return netip.AddrFrom4(b)
+}
+
+// generateIPs generates a list of all possible IPs of the given network excluding IPs specified in the exclusion list
+func generateIPs(ipNet *net.IPNet, exclusions map[string]struct{}) ([]net.IP, int) {
+
+	var ips []net.IP
+	for ip := ipNet.IP.Mask(ipNet.Mask); ipNet.Contains(ip); incIP(ip) {
+		if _, ok := exclusions[ip.String()]; !ok && ip[3] != 0 {
+			ips = append(ips, copyIP(ip))
+		}
+	}
+
+	// remove network address, broadcast and Fake DNS resolver address
+	lenIPs := len(ips)
+	switch {
+	case lenIPs < 2:
+		return ips, lenIPs
+	case lenIPs < 3:
+		return ips[1 : len(ips)-1], lenIPs - 2
+	default:
+		return ips[1 : len(ips)-2], lenIPs - 3
+	}
+}
+
+func copyIP(ip net.IP) net.IP {
+	dup := make(net.IP, len(ip))
+	copy(dup, ip)
+	return dup
+}
+
+func incIP(ip net.IP) {
+	for j := len(ip) - 1; j >= 0; j-- {
+		ip[j]++
+		if ip[j] > 0 {
+			break
+		}
+	}
+}

shared/management/types/network_merge_test.go

@@ -0,0 +1,41 @@
+package types
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+type testObject struct {
+	value int
+}
+
+func (t testObject) Equal(other testObject) bool {
+	return t.value == other.value
+}
+
+func Test_MergeUniqueArraysWithoutDuplicates(t *testing.T) {
+	arr1 := []testObject{{value: 1}, {value: 2}}
+	arr2 := []testObject{{value: 2}, {value: 3}}
+	result := mergeUnique(arr1, arr2)
+	assert.Len(t, result, 3)
+	assert.Contains(t, result, testObject{value: 1})
+	assert.Contains(t, result, testObject{value: 2})
+	assert.Contains(t, result, testObject{value: 3})
+}
+
+func Test_MergeUniqueHandlesEmptyArrays(t *testing.T) {
+	arr1 := []testObject{}
+	arr2 := []testObject{}
+	result := mergeUnique(arr1, arr2)
+	assert.Empty(t, result)
+}
+
+func Test_MergeUniqueHandlesOneEmptyArray(t *testing.T) {
+	arr1 := []testObject{{value: 1}, {value: 2}}
+	arr2 := []testObject{}
+	result := mergeUnique(arr1, arr2)
+	assert.Len(t, result, 2)
+	assert.Contains(t, result, testObject{value: 1})
+	assert.Contains(t, result, testObject{value: 2})
+}

shared/management/types/network_test.go

@@ -0,0 +1,264 @@
+package types
+
+import (
+	"encoding/binary"
+	"net"
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewNetwork(t *testing.T) {
+	network := NewNetwork()
+
+	// generated net should be a subnet of a larger 100.64.0.0/10 net
+	ipNet := net.IPNet{IP: net.ParseIP("100.64.0.0"), Mask: net.IPMask{255, 192, 0, 0}}
+	assert.Equal(t, ipNet.Contains(network.Net.IP), true)
+}
+
+func TestAllocatePeerIP(t *testing.T) {
+	prefix := netip.MustParsePrefix("100.64.0.0/24")
+	var ips []netip.Addr
+	for i := 0; i < 252; i++ {
+		ip, err := AllocatePeerIP(prefix, ips)
+		if err != nil {
+			t.Fatal(err)
+		}
+		ips = append(ips, ip)
+	}
+
+	assert.Len(t, ips, 252)
+
+	uniq := make(map[string]struct{})
+	for _, ip := range ips {
+		if _, ok := uniq[ip.String()]; !ok {
+			uniq[ip.String()] = struct{}{}
+		} else {
+			t.Errorf("found duplicate IP %s", ip.String())
+		}
+	}
+}
+
+func TestAllocatePeerIPSmallSubnet(t *testing.T) {
+	// Test /27 network (10.0.0.0/27) - should only have 30 usable IPs (10.0.0.1 to 10.0.0.30)
+	prefix := netip.MustParsePrefix("10.0.0.0/27")
+	var ips []netip.Addr
+
+	// Allocate all available IPs in the /27 network
+	for i := 0; i < 30; i++ {
+		ip, err := AllocatePeerIP(prefix, ips)
+		if err != nil {
+			t.Fatal(err)
+		}
+
+		// Verify IP is within the correct range
+		if !prefix.Contains(ip) {
+			t.Errorf("allocated IP %s is not within network %s", ip.String(), prefix.String())
+		}
+
+		ips = append(ips, ip)
+	}
+
+	assert.Len(t, ips, 30)
+
+	// Verify all IPs are unique
+	uniq := make(map[string]struct{})
+	for _, ip := range ips {
+		if _, ok := uniq[ip.String()]; !ok {
+			uniq[ip.String()] = struct{}{}
+		} else {
+			t.Errorf("found duplicate IP %s", ip.String())
+		}
+	}
+
+	// Try to allocate one more IP - should fail as network is full
+	_, err := AllocatePeerIP(prefix, ips)
+	if err == nil {
+		t.Error("expected error when network is full, but got none")
+	}
+}
+
+func TestAllocatePeerIPVariousCIDRs(t *testing.T) {
+	testCases := []struct {
+		name           string
+		cidr           string
+		expectedUsable int
+	}{
+		{"/30 network", "192.168.1.0/30", 2},   // 4 total - 2 reserved = 2 usable
+		{"/29 network", "192.168.1.0/29", 6},   // 8 total - 2 reserved = 6 usable
+		{"/28 network", "192.168.1.0/28", 14},  // 16 total - 2 reserved = 14 usable
+		{"/27 network", "192.168.1.0/27", 30},  // 32 total - 2 reserved = 30 usable
+		{"/26 network", "192.168.1.0/26", 62},  // 64 total - 2 reserved = 62 usable
+		{"/25 network", "192.168.1.0/25", 126}, // 128 total - 2 reserved = 126 usable
+		{"/16 network", "10.0.0.0/16", 65534},  // 65536 total - 2 reserved = 65534 usable
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			prefix, err := netip.ParsePrefix(tc.cidr)
+			require.NoError(t, err)
+			prefix = prefix.Masked()
+
+			var ips []netip.Addr
+
+			// For larger networks, test only a subset to avoid long test runs
+			testCount := tc.expectedUsable
+			if testCount > 1000 {
+				testCount = 1000
+			}
+
+			// Allocate IPs and verify they're within the correct range
+			for i := 0; i < testCount; i++ {
+				ip, err := AllocatePeerIP(prefix, ips)
+				require.NoError(t, err, "failed to allocate IP %d", i)
+
+				// Verify IP is within the correct range
+				assert.True(t, prefix.Contains(ip), "allocated IP %s is not within network %s", ip.String(), prefix.String())
+
+				// Verify IP is not network or broadcast address
+				networkAddr := prefix.Masked().Addr()
+				hostBits := 32 - prefix.Bits()
+				b := networkAddr.As4()
+				baseIP := binary.BigEndian.Uint32(b[:])
+				broadcastIP := uint32ToIP(baseIP + (1 << hostBits) - 1)
+
+				assert.NotEqual(t, networkAddr, ip, "allocated network address %s", ip.String())
+				assert.NotEqual(t, broadcastIP, ip, "allocated broadcast address %s", ip.String())
+
+				ips = append(ips, ip)
+			}
+
+			assert.Len(t, ips, testCount)
+
+			// Verify all IPs are unique
+			uniq := make(map[string]struct{})
+			for _, ip := range ips {
+				ipStr := ip.String()
+				assert.NotContains(t, uniq, ipStr, "found duplicate IP %s", ipStr)
+				uniq[ipStr] = struct{}{}
+			}
+		})
+	}
+}
+
+func TestGenerateIPs(t *testing.T) {
+	ipNet := net.IPNet{IP: net.ParseIP("100.64.0.0"), Mask: net.IPMask{255, 255, 255, 0}}
+	ips, ipsLen := generateIPs(&ipNet, map[string]struct{}{"100.64.0.0": {}})
+	if ipsLen != 252 {
+		t.Errorf("expected 252 ips, got %d", len(ips))
+		return
+	}
+	if ips[len(ips)-1].String() != "100.64.0.253" {
+		t.Errorf("expected last ip to be: 100.64.0.253, got %s", ips[len(ips)-1].String())
+	}
+}
+
+func TestNewNetworkHasIPv6(t *testing.T) {
+	network := NewNetwork()
+
+	assert.NotNil(t, network.NetV6.IP, "v6 subnet should be allocated")
+	assert.True(t, network.NetV6.IP.To4() == nil, "v6 subnet should be IPv6")
+	assert.Equal(t, byte(0xfd), network.NetV6.IP[0], "v6 subnet should be ULA (fd prefix)")
+
+	ones, bits := network.NetV6.Mask.Size()
+	assert.Equal(t, 64, ones, "v6 subnet should be /64")
+	assert.Equal(t, 128, bits)
+}
+
+func TestAllocateIPv6SubnetUniqueness(t *testing.T) {
+	seen := make(map[string]struct{})
+	for i := 0; i < 100; i++ {
+		network := NewNetwork()
+		key := network.NetV6.IP.String()
+		_, duplicate := seen[key]
+		assert.False(t, duplicate, "duplicate v6 subnet: %s", key)
+		seen[key] = struct{}{}
+	}
+}
+
+func TestAllocateRandomPeerIPv6(t *testing.T) {
+	prefix := netip.MustParsePrefix("fd12:3456:7890:abcd::/64")
+
+	ip, err := AllocateRandomPeerIPv6(prefix)
+	require.NoError(t, err)
+
+	assert.True(t, ip.Is6(), "should be IPv6")
+	assert.True(t, prefix.Contains(ip), "should be within subnet")
+	// First 8 bytes (network prefix) should match
+	b := ip.As16()
+	prefixBytes := prefix.Addr().As16()
+	assert.Equal(t, prefixBytes[:8], b[:8], "prefix should match")
+	// Interface ID should not be all zeros
+	allZero := true
+	for _, v := range b[8:] {
+		if v != 0 {
+			allZero = false
+			break
+		}
+	}
+	assert.False(t, allZero, "interface ID should not be all zeros")
+}
+
+func TestAllocateRandomPeerIPv6_VariousPrefixes(t *testing.T) {
+	tests := []struct {
+		name   string
+		cidr   string
+		prefix int
+	}{
+		{"standard /64", "fd00:1234:5678:abcd::/64", 64},
+		{"small /112", "fd00:1234:5678:abcd::/112", 112},
+		{"large /48", "fd00:1234::/48", 48},
+		{"non-boundary /60", "fd00:1234:5670::/60", 60},
+		{"non-boundary /52", "fd00:1230::/52", 52},
+		{"minimum /120", "fd00:1234:5678:abcd::100/120", 120},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			prefix, err := netip.ParsePrefix(tt.cidr)
+			require.NoError(t, err)
+			prefix = prefix.Masked()
+
+			assert.Equal(t, tt.prefix, prefix.Bits())
+
+			for i := 0; i < 50; i++ {
+				ip, err := AllocateRandomPeerIPv6(prefix)
+				require.NoError(t, err)
+				assert.True(t, prefix.Contains(ip), "IP %s should be within %s", ip, prefix)
+			}
+		})
+	}
+}
+
+func TestAllocateRandomPeerIPv6_PreservesNetworkBits(t *testing.T) {
+	// For a /112, bytes 0-13 should be preserved, only bytes 14-15 should vary
+	prefix := netip.MustParsePrefix("fd00:1234:5678:abcd:ef01:2345:6789:0/112")
+
+	prefixBytes := prefix.Addr().As16()
+	for i := 0; i < 20; i++ {
+		ip, err := AllocateRandomPeerIPv6(prefix)
+		require.NoError(t, err)
+		// First 14 bytes (112 bits = 14 bytes) must match the network
+		b := ip.As16()
+		assert.Equal(t, prefixBytes[:14], b[:14], "network bytes should be preserved for /112")
+	}
+}
+
+func TestAllocateRandomPeerIPv6_NonByteBoundary(t *testing.T) {
+	// For a /60, the first 7.5 bytes are network, so byte 7 is partial
+	prefix := netip.MustParsePrefix("fd00:1234:5678:abc0::/60")
+
+	prefixBytes := prefix.Addr().As16()
+	for i := 0; i < 50; i++ {
+		ip, err := AllocateRandomPeerIPv6(prefix)
+		require.NoError(t, err)
+		b := ip.As16()
+		assert.True(t, prefix.Contains(ip), "IP %s should be within %s", ip, prefix)
+		// First 7 bytes must match exactly
+		assert.Equal(t, prefixBytes[:7], b[:7], "full network bytes should match for /60")
+		// Byte 7: top 4 bits (0xc = 1100) must be preserved
+		assert.Equal(t, prefixBytes[7]&0xf0, b[7]&0xf0, "partial byte network bits should be preserved for /60")
+	}
+}

shared/management/types/networkmap_components_compact.go

@@ -0,0 +1,227 @@
+package types
+
+import (
+	nbdns "github.com/netbirdio/netbird/dns"
+	"github.com/netbirdio/netbird/route"
+)
+
+type GroupCompact struct {
+	Name        string
+	PeerIndexes []int
+}
+
+type NetworkMapComponentsCompact struct {
+	PeerID string
+
+	Network          *Network
+	AccountSettings  *AccountSettingsInfo
+	DNSSettings      *DNSSettings
+	CustomZoneDomain string
+
+	AllPeers          []*ComponentPeer
+	PeerIndexes       []int
+	RouterPeerIndexes []int
+
+	Groups              map[string]*GroupCompact
+	AllPolicies         []*Policy
+	PolicyIndexes       []int
+	ResourcePoliciesMap map[string][]int
+	Routes              []*route.Route
+	NameServerGroups    []*nbdns.NameServerGroup
+	AllDNSRecords       []nbdns.SimpleRecord
+	AccountZones        []nbdns.CustomZone
+
+	RoutersMap       map[string]map[string]*ComponentRouter
+	NetworkResources []*ComponentResource
+
+	GroupIDToUserIDs   map[string][]string
+	AllowedUserIDs     map[string]struct{}
+	PostureFailedPeers map[string]map[string]struct{}
+}
+
+func (c *NetworkMapComponents) ToCompact() *NetworkMapComponentsCompact {
+	peerToIndex := make(map[string]int)
+	var allPeers []*ComponentPeer
+
+	for id, peer := range c.Peers {
+		if _, exists := peerToIndex[id]; !exists {
+			peerToIndex[id] = len(allPeers)
+			allPeers = append(allPeers, peer)
+		}
+	}
+
+	for id, peer := range c.RouterPeers {
+		if _, exists := peerToIndex[id]; !exists {
+			peerToIndex[id] = len(allPeers)
+			allPeers = append(allPeers, peer)
+		}
+	}
+
+	peerIndexes := make([]int, 0, len(c.Peers))
+	for id := range c.Peers {
+		peerIndexes = append(peerIndexes, peerToIndex[id])
+	}
+
+	routerPeerIndexes := make([]int, 0, len(c.RouterPeers))
+	for id := range c.RouterPeers {
+		routerPeerIndexes = append(routerPeerIndexes, peerToIndex[id])
+	}
+
+	groups := make(map[string]*GroupCompact, len(c.Groups))
+	for id, group := range c.Groups {
+		peerIdxs := make([]int, 0, len(group.Peers))
+		for _, peerID := range group.Peers {
+			if idx, ok := peerToIndex[peerID]; ok {
+				peerIdxs = append(peerIdxs, idx)
+			}
+		}
+		groups[id] = &GroupCompact{
+			Name:        group.Name,
+			PeerIndexes: peerIdxs,
+		}
+	}
+
+	policyToIndex := make(map[*Policy]int)
+	var allPolicies []*Policy
+
+	for _, policy := range c.Policies {
+		if _, exists := policyToIndex[policy]; !exists {
+			policyToIndex[policy] = len(allPolicies)
+			allPolicies = append(allPolicies, policy)
+		}
+	}
+
+	for _, policies := range c.ResourcePoliciesMap {
+		for _, policy := range policies {
+			if _, exists := policyToIndex[policy]; !exists {
+				policyToIndex[policy] = len(allPolicies)
+				allPolicies = append(allPolicies, policy)
+			}
+		}
+	}
+
+	policyIndexes := make([]int, len(c.Policies))
+	for i, policy := range c.Policies {
+		policyIndexes[i] = policyToIndex[policy]
+	}
+
+	var resourcePoliciesMap map[string][]int
+	if len(c.ResourcePoliciesMap) > 0 {
+		resourcePoliciesMap = make(map[string][]int, len(c.ResourcePoliciesMap))
+		for resID, policies := range c.ResourcePoliciesMap {
+			indexes := make([]int, len(policies))
+			for i, policy := range policies {
+				indexes[i] = policyToIndex[policy]
+			}
+			resourcePoliciesMap[resID] = indexes
+		}
+	}
+
+	return &NetworkMapComponentsCompact{
+		PeerID:           c.PeerID,
+		Network:          c.Network,
+		AccountSettings:  c.AccountSettings,
+		DNSSettings:      c.DNSSettings,
+		CustomZoneDomain: c.CustomZoneDomain,
+
+		AllPeers:          allPeers,
+		PeerIndexes:       peerIndexes,
+		RouterPeerIndexes: routerPeerIndexes,
+
+		Groups:              groups,
+		AllPolicies:         allPolicies,
+		PolicyIndexes:       policyIndexes,
+		ResourcePoliciesMap: resourcePoliciesMap,
+		Routes:              c.Routes,
+		NameServerGroups:    c.NameServerGroups,
+		AllDNSRecords:       c.AllDNSRecords,
+		AccountZones:        c.AccountZones,
+
+		RoutersMap:       c.RoutersMap,
+		NetworkResources: c.NetworkResources,
+
+		GroupIDToUserIDs:   c.GroupIDToUserIDs,
+		AllowedUserIDs:     c.AllowedUserIDs,
+		PostureFailedPeers: c.PostureFailedPeers,
+	}
+}
+
+func (c *NetworkMapComponentsCompact) ToFull() *NetworkMapComponents {
+	peers := make(map[string]*ComponentPeer, len(c.PeerIndexes))
+	for _, idx := range c.PeerIndexes {
+		if idx >= 0 && idx < len(c.AllPeers) {
+			peer := c.AllPeers[idx]
+			peers[peer.ID] = peer
+		}
+	}
+
+	routerPeers := make(map[string]*ComponentPeer, len(c.RouterPeerIndexes))
+	for _, idx := range c.RouterPeerIndexes {
+		if idx >= 0 && idx < len(c.AllPeers) {
+			peer := c.AllPeers[idx]
+			routerPeers[peer.ID] = peer
+		}
+	}
+
+	groups := make(map[string]*ComponentGroup, len(c.Groups))
+	for id, gc := range c.Groups {
+		peerIDs := make([]string, 0, len(gc.PeerIndexes))
+		for _, idx := range gc.PeerIndexes {
+			if idx >= 0 && idx < len(c.AllPeers) {
+				peerIDs = append(peerIDs, c.AllPeers[idx].ID)
+			}
+		}
+		groups[id] = &ComponentGroup{
+			ID:    id,
+			Name:  gc.Name,
+			Peers: peerIDs,
+		}
+	}
+
+	policies := make([]*Policy, len(c.PolicyIndexes))
+	for i, idx := range c.PolicyIndexes {
+		if idx >= 0 && idx < len(c.AllPolicies) {
+			policies[i] = c.AllPolicies[idx]
+		}
+	}
+
+	var resourcePoliciesMap map[string][]*Policy
+	if len(c.ResourcePoliciesMap) > 0 {
+		resourcePoliciesMap = make(map[string][]*Policy, len(c.ResourcePoliciesMap))
+		for resID, indexes := range c.ResourcePoliciesMap {
+			pols := make([]*Policy, 0, len(indexes))
+			for _, idx := range indexes {
+				if idx >= 0 && idx < len(c.AllPolicies) {
+					pols = append(pols, c.AllPolicies[idx])
+				}
+			}
+			resourcePoliciesMap[resID] = pols
+		}
+	}
+
+	return &NetworkMapComponents{
+		PeerID:           c.PeerID,
+		Network:          c.Network,
+		AccountSettings:  c.AccountSettings,
+		DNSSettings:      c.DNSSettings,
+		CustomZoneDomain: c.CustomZoneDomain,
+
+		Peers:       peers,
+		RouterPeers: routerPeers,
+
+		Groups:           groups,
+		Policies:         policies,
+		Routes:           c.Routes,
+		NameServerGroups: c.NameServerGroups,
+		AllDNSRecords:    c.AllDNSRecords,
+		AccountZones:     c.AccountZones,
+
+		ResourcePoliciesMap: resourcePoliciesMap,
+		RoutersMap:          c.RoutersMap,
+		NetworkResources:    c.NetworkResources,
+
+		GroupIDToUserIDs:   c.GroupIDToUserIDs,
+		AllowedUserIDs:     c.AllowedUserIDs,
+		PostureFailedPeers: c.PostureFailedPeers,
+	}
+}

shared/management/types/policy.go

@@ -0,0 +1,272 @@
+package types
+
+import (
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+const (
+	// PolicyTrafficActionAccept indicates that the traffic is accepted
+	PolicyTrafficActionAccept = PolicyTrafficActionType("accept")
+	// PolicyTrafficActionDrop indicates that the traffic is dropped
+	PolicyTrafficActionDrop = PolicyTrafficActionType("drop")
+)
+
+const (
+	// PolicyRuleProtocolALL type of traffic
+	PolicyRuleProtocolALL = PolicyRuleProtocolType("all")
+	// PolicyRuleProtocolTCP type of traffic
+	PolicyRuleProtocolTCP = PolicyRuleProtocolType("tcp")
+	// PolicyRuleProtocolUDP type of traffic
+	PolicyRuleProtocolUDP = PolicyRuleProtocolType("udp")
+	// PolicyRuleProtocolICMP type of traffic
+	PolicyRuleProtocolICMP = PolicyRuleProtocolType("icmp")
+	// PolicyRuleProtocolNetbirdSSH type of traffic
+	PolicyRuleProtocolNetbirdSSH = PolicyRuleProtocolType("netbird-ssh")
+	// PolicyRuleProtocolNetbirdVNC type of traffic
+	PolicyRuleProtocolNetbirdVNC = PolicyRuleProtocolType("netbird-vnc")
+)
+
+const (
+	// PolicyRuleFlowDirect allows traffic from source to destination
+	PolicyRuleFlowDirect = PolicyRuleDirection("direct")
+	// PolicyRuleFlowBidirect allows traffic to both directions
+	PolicyRuleFlowBidirect = PolicyRuleDirection("bidirect")
+)
+
+const (
+	// DefaultRuleName is a name for the Default rule that is created for every account
+	DefaultRuleName = "Default"
+	// DefaultRuleDescription is a description for the Default rule that is created for every account
+	DefaultRuleDescription = "This is a default rule that allows connections between all the resources"
+	// DefaultPolicyName is a name for the Default policy that is created for every account
+	DefaultPolicyName = "Default"
+	// DefaultPolicyDescription is a description for the Default policy that is created for every account
+	DefaultPolicyDescription = "This is a default policy that allows connections between all the resources"
+)
+
+// PolicyUpdateOperation operation object with type and values to be applied
+type PolicyUpdateOperation struct {
+	Type   PolicyUpdateOperationType
+	Values []string
+}
+
+// Policy of the Rego query
+type Policy struct {
+	// ID of the policy'
+	ID string `gorm:"primaryKey"`
+
+	PublicID string `json:"-"`
+
+	// AccountID is a reference to Account that this object belongs
+	AccountID string `json:"-" gorm:"index"`
+
+	// Name of the Policy
+	Name string
+
+	// Description of the policy visible in the UI
+	Description string
+
+	// Enabled status of the policy
+	Enabled bool
+
+	// Rules of the policy
+	Rules []*PolicyRule `gorm:"foreignKey:PolicyID;references:id;constraint:OnDelete:CASCADE;"`
+
+	// SourcePostureChecks are ID references to Posture checks for policy source groups
+	SourcePostureChecks []string `gorm:"serializer:json"`
+}
+
+// Copy returns a copy of the policy.
+func (p *Policy) Copy() *Policy {
+	c := &Policy{
+		ID:                  p.ID,
+		AccountID:           p.AccountID,
+		PublicID:            p.PublicID,
+		Name:                p.Name,
+		Description:         p.Description,
+		Enabled:             p.Enabled,
+		Rules:               make([]*PolicyRule, len(p.Rules)),
+		SourcePostureChecks: make([]string, len(p.SourcePostureChecks)),
+	}
+	for i, r := range p.Rules {
+		c.Rules[i] = r.Copy()
+	}
+	copy(c.SourcePostureChecks, p.SourcePostureChecks)
+	return c
+}
+
+func (p *Policy) Equal(other *Policy) bool {
+	if p == nil || other == nil {
+		return p == other
+	}
+
+	if p.ID != other.ID ||
+		p.AccountID != other.AccountID ||
+		p.Name != other.Name ||
+		p.Description != other.Description ||
+		p.Enabled != other.Enabled {
+		return false
+	}
+
+	if !stringSlicesEqualUnordered(p.SourcePostureChecks, other.SourcePostureChecks) {
+		return false
+	}
+
+	if len(p.Rules) != len(other.Rules) {
+		return false
+	}
+
+	otherRules := make(map[string]*PolicyRule, len(other.Rules))
+	for _, r := range other.Rules {
+		otherRules[r.ID] = r
+	}
+	for _, r := range p.Rules {
+		otherRule, ok := otherRules[r.ID]
+		if !ok {
+			return false
+		}
+		if !r.Equal(otherRule) {
+			return false
+		}
+	}
+
+	return true
+}
+
+// EventMeta returns activity event meta related to this policy
+func (p *Policy) EventMeta() map[string]any {
+	return map[string]any{"name": p.Name}
+}
+
+// UpgradeAndFix different version of policies to latest version
+func (p *Policy) UpgradeAndFix() {
+	for _, r := range p.Rules {
+		// start migrate from version v0.20.3
+		if r.Protocol == "" {
+			r.Protocol = PolicyRuleProtocolALL
+		}
+		if r.Protocol == PolicyRuleProtocolALL && !r.Bidirectional {
+			r.Bidirectional = true
+		}
+		// -- v0.20.4
+	}
+}
+
+// RuleGroups returns a list of all groups referenced in the policy's rules,
+// including sources and destinations.
+func (p *Policy) RuleGroups() []string {
+	groups := make([]string, 0)
+	for _, rule := range p.Rules {
+		groups = append(groups, rule.Sources...)
+		groups = append(groups, rule.Destinations...)
+	}
+
+	return groups
+}
+
+// SourceGroups returns a slice of all unique source groups referenced in the policy's rules.
+func (p *Policy) SourceGroups() []string {
+	if len(p.Rules) == 1 {
+		return p.Rules[0].Sources
+	}
+	groups := make(map[string]struct{}, len(p.Rules))
+	for _, rule := range p.Rules {
+		for _, source := range rule.Sources {
+			groups[source] = struct{}{}
+		}
+	}
+
+	groupIDs := make([]string, 0, len(groups))
+	for groupID := range groups {
+		groupIDs = append(groupIDs, groupID)
+	}
+
+	return groupIDs
+}
+
+func ParseRuleString(rule string) (PolicyRuleProtocolType, RulePortRange, error) {
+	rule = strings.TrimSpace(strings.ToLower(rule))
+	if rule == "all" {
+		return PolicyRuleProtocolALL, RulePortRange{}, nil
+	}
+	if rule == "icmp" {
+		return PolicyRuleProtocolICMP, RulePortRange{}, nil
+	}
+
+	split := strings.Split(rule, "/")
+	if len(split) != 2 {
+		return "", RulePortRange{}, errors.New("invalid rule format: expected protocol/port or protocol/port-range")
+	}
+
+	protoStr := strings.TrimSpace(split[0])
+	portStr := strings.TrimSpace(split[1])
+
+	var protocol PolicyRuleProtocolType
+	switch protoStr {
+	case "tcp":
+		protocol = PolicyRuleProtocolTCP
+	case "udp":
+		protocol = PolicyRuleProtocolUDP
+	case "icmp":
+		return "", RulePortRange{}, errors.New("icmp does not accept ports; use 'icmp' without '/…'")
+	case "netbird-ssh":
+		return PolicyRuleProtocolNetbirdSSH, RulePortRange{Start: nativeSSHPortNumber, End: nativeSSHPortNumber}, nil
+	case "netbird-vnc":
+		return PolicyRuleProtocolNetbirdVNC, RulePortRange{Start: vncInternalPort, End: vncInternalPort}, nil
+	default:
+		return "", RulePortRange{}, fmt.Errorf("invalid protocol: %q", protoStr)
+	}
+
+	portRange, err := parsePortRange(portStr)
+	if err != nil {
+		return "", RulePortRange{}, err
+	}
+
+	return protocol, portRange, nil
+}
+
+func parsePortRange(portStr string) (RulePortRange, error) {
+	if strings.Contains(portStr, "-") {
+		rangeParts := strings.Split(portStr, "-")
+		if len(rangeParts) != 2 {
+			return RulePortRange{}, fmt.Errorf("invalid port range %q", portStr)
+		}
+		start, err := parsePort(strings.TrimSpace(rangeParts[0]))
+		if err != nil {
+			return RulePortRange{}, err
+		}
+		end, err := parsePort(strings.TrimSpace(rangeParts[1]))
+		if err != nil {
+			return RulePortRange{}, err
+		}
+		if start > end {
+			return RulePortRange{}, fmt.Errorf("invalid port range: start %d > end %d", start, end)
+		}
+		return RulePortRange{Start: uint16(start), End: uint16(end)}, nil
+	}
+
+	p, err := parsePort(portStr)
+	if err != nil {
+		return RulePortRange{}, err
+	}
+
+	return RulePortRange{Start: uint16(p), End: uint16(p)}, nil
+}
+
+func parsePort(portStr string) (int, error) {
+
+	if portStr == "" {
+		return 0, errors.New("empty port")
+	}
+	p, err := strconv.Atoi(portStr)
+	if err != nil {
+		return 0, fmt.Errorf("invalid port %q: %w", portStr, err)
+	}
+	if p < 1 || p > 65535 {
+		return 0, fmt.Errorf("port out of range (1–65535): %d", p)
+	}
+	return p, nil
+}

shared/management/types/policy_authorized_users.go

@@ -0,0 +1,214 @@
+package types
+
+import (
+	"context"
+	"strconv"
+
+	log "github.com/sirupsen/logrus"
+
+	auth "github.com/netbirdio/netbird/shared/sessionauth"
+)
+
+// vncInternalPort is the internal port the VNC server listens on (behind DNAT from 5900).
+const vncInternalPort = 25900
+
+// PeerConnResolveState carries the in-progress maps mutated by per-rule
+// resolution while walking an account's policies.
+type PeerConnResolveState struct {
+	AuthorizedUsers    map[string]map[string]struct{}
+	VNCAuthorizedUsers map[string]map[string]struct{}
+	VNCSessionPubKeys  []VNCSessionPubKey
+	SSHEnabled         bool
+}
+
+// NewPeerConnResolveState returns a state with its maps allocated.
+func NewPeerConnResolveState() *PeerConnResolveState {
+	return &PeerConnResolveState{
+		AuthorizedUsers:    make(map[string]map[string]struct{}),
+		VNCAuthorizedUsers: make(map[string]map[string]struct{}),
+	}
+}
+
+// VNCSessionPubKey carries an ephemeral X25519 static public key the
+// dashboard registered via temporary-access. The daemon uses it as the
+// allowed-client side of a Noise_IK handshake; a successful handshake
+// authenticates the connection as UserID.
+type VNCSessionPubKey struct {
+	// PubKey is the base64-encoded 32-byte X25519 public key.
+	PubKey string
+	// UserID is the unhashed user identity the pubkey authenticates as.
+	UserID string
+	// DisplayName is a human-readable label for UserID, used by the host
+	// peer's approval prompt. Empty when not provided.
+	DisplayName string
+}
+
+// RuleAuthCallbacks lets Account and NetworkMapComponents share the per-rule
+// direction-and-auth logic while keeping their own context/state plumbing for
+// authorized-user collection and allowed-user lookups.
+type RuleAuthCallbacks struct {
+	CollectSSHUsers   func(*PolicyRule, map[string]map[string]struct{})
+	CollectVNCUsers   func(*PolicyRule, map[string]map[string]struct{})
+	GetAllowedUserIDs func() map[string]struct{}
+}
+
+// ApplyResolvedRuleToState emits firewall rules in the rule's directions and
+// records authorized users into state according to the rule's protocol. The
+// callbacks supply the auth-collection behaviour specific to the calling
+// resolver (Account vs NetworkMapComponents), which also decide the peer
+// representation the resource generator works with.
+func ApplyResolvedRuleToState[P any](
+	rule *PolicyRule,
+	sourcePeers []P,
+	destPeers []P,
+	peerInSources bool,
+	peerInDestinations bool,
+	targetPeerSSHEnabled bool,
+	generateResources func(*PolicyRule, []P, int),
+	cb RuleAuthCallbacks,
+	state *PeerConnResolveState,
+) {
+	emitRuleDirections(rule, sourcePeers, destPeers, peerInSources, peerInDestinations, generateResources)
+
+	receivingPeer := peerInDestinations || (rule.Bidirectional && peerInSources)
+	switch {
+	case rule.Protocol == PolicyRuleProtocolNetbirdSSH:
+		if !receivingPeer {
+			return
+		}
+		state.SSHEnabled = true
+		cb.CollectSSHUsers(rule, state.AuthorizedUsers)
+	case rule.Protocol == PolicyRuleProtocolNetbirdVNC:
+		cb.handleVNCRule(rule, peerInSources, peerInDestinations, state)
+	case PolicyRuleImpliesLegacySSH(rule) && targetPeerSSHEnabled:
+		if !receivingPeer {
+			return
+		}
+		state.SSHEnabled = true
+		MergeWildcardUsers(state.AuthorizedUsers, cb.GetAllowedUserIDs())
+	}
+}
+
+// handleVNCRule collects VNC authorized users and session pubkeys for a VNC
+// policy rule. Bidirectional rules grant access in both directions, so a
+// peer that appears in the rule's sources also needs the SessionPubKey
+// pushed (otherwise the Noise_IK handshake against that peer would fail
+// because its authorizer wouldn't know the client's static key).
+func (cb RuleAuthCallbacks) handleVNCRule(rule *PolicyRule, peerInSources, peerInDestinations bool, state *PeerConnResolveState) {
+	receivingPeer := peerInDestinations || (rule.Bidirectional && peerInSources)
+	if !receivingPeer {
+		return
+	}
+	cb.CollectVNCUsers(rule, state.VNCAuthorizedUsers)
+	if rule.SessionPubKey != "" && rule.AuthorizedUser != "" {
+		state.VNCSessionPubKeys = append(state.VNCSessionPubKeys, VNCSessionPubKey{
+			PubKey:      rule.SessionPubKey,
+			UserID:      rule.AuthorizedUser,
+			DisplayName: rule.SessionDisplayName,
+		})
+	}
+}
+
+// MergeWildcardUsers adds every user in users to the wildcard local-user entry
+// of dst, allocating the entry on demand.
+func MergeWildcardUsers(dst map[string]map[string]struct{}, users map[string]struct{}) {
+	if dst[auth.Wildcard] == nil {
+		dst[auth.Wildcard] = make(map[string]struct{})
+	}
+	for userID := range users {
+		dst[auth.Wildcard][userID] = struct{}{}
+	}
+}
+
+// emitRuleDirections dispatches generateResources for each direction the rule
+// applies in for the target peer.
+func emitRuleDirections[P any](
+	rule *PolicyRule,
+	sourcePeers []P,
+	destPeers []P,
+	peerInSources bool,
+	peerInDestinations bool,
+	generateResources func(*PolicyRule, []P, int),
+) {
+	if rule.Bidirectional {
+		if peerInSources {
+			generateResources(rule, destPeers, FirewallRuleDirectionIN)
+		}
+		if peerInDestinations {
+			generateResources(rule, sourcePeers, FirewallRuleDirectionOUT)
+		}
+	}
+	if peerInSources {
+		generateResources(rule, destPeers, FirewallRuleDirectionOUT)
+	}
+	if peerInDestinations {
+		generateResources(rule, sourcePeers, FirewallRuleDirectionIN)
+	}
+}
+
+// MergeAuthorizedGroupUsers expands AuthorizedGroups (group ID to local user
+// list) into target, mapping each local user to the set of user IDs in the
+// referenced group. Used by both Account and NetworkMapComponents auth
+// resolution paths.
+func MergeAuthorizedGroupUsers(
+	ctx context.Context,
+	authorizedGroups map[string][]string,
+	groupIDToUserIDs map[string][]string,
+	target map[string]map[string]struct{},
+) {
+	for groupID, localUsers := range authorizedGroups {
+		userIDs, ok := groupIDToUserIDs[groupID]
+		if !ok {
+			log.WithContext(ctx).Tracef("no user IDs found for group ID %s", groupID)
+			continue
+		}
+		if len(localUsers) == 0 {
+			localUsers = []string{auth.Wildcard}
+		}
+		assignUsersToLocal(target, localUsers, userIDs)
+	}
+}
+
+// assignUsersToLocal adds each userID to target[localUser] for every entry in
+// localUsers, allocating the inner set on demand.
+func assignUsersToLocal(target map[string]map[string]struct{}, localUsers, userIDs []string) {
+	for _, localUser := range localUsers {
+		if target[localUser] == nil {
+			target[localUser] = make(map[string]struct{})
+		}
+		for _, userID := range userIDs {
+			target[localUser][userID] = struct{}{}
+		}
+	}
+}
+
+// EnsureWildcardUser ensures the wildcard local-user entry exists in target
+// and adds the given authorized user to it.
+func EnsureWildcardUser(target map[string]map[string]struct{}, authorizedUser string) {
+	if target[auth.Wildcard] == nil {
+		target[auth.Wildcard] = make(map[string]struct{})
+	}
+	target[auth.Wildcard][authorizedUser] = struct{}{}
+}
+
+// NormalizePolicyRuleProtocol maps NetBird virtual protocols (netbird-ssh,
+// netbird-vnc) to TCP for the on-the-wire firewall view. For NetbirdVNC the
+// rule is also scoped to the embedded VNC port so a VNC-only rule doesn't
+// degrade into an unscoped TCP allow when the user left Ports empty.
+// Returns the effective rule (possibly a shallow copy with Ports overridden)
+// and the resulting protocol.
+func NormalizePolicyRuleProtocol(rule *PolicyRule) (*PolicyRule, PolicyRuleProtocolType) {
+	switch rule.Protocol {
+	case PolicyRuleProtocolNetbirdSSH:
+		return rule, PolicyRuleProtocolTCP
+	case PolicyRuleProtocolNetbirdVNC:
+		if len(rule.Ports) == 0 && len(rule.PortRanges) == 0 {
+			scoped := *rule
+			scoped.Ports = []string{strconv.Itoa(vncInternalPort)}
+			return &scoped, PolicyRuleProtocolTCP
+		}
+		return rule, PolicyRuleProtocolTCP
+	default:
+		return rule, rule.Protocol
+	}
+}

shared/management/types/policy_authorized_users_security_test.go

@@ -0,0 +1,140 @@
+package types
+
+import (
+	"testing"
+)
+
+// TestHandleVNCRule_BidirectionalDistributesPubkeyToSourcePeer covers the
+// latent bug where a bidirectional VNC rule used to drop the
+// SessionPubKey for the peer that appears only in sources, even though
+// the rule explicitly grants access in both directions. Without the
+// pubkey, the source peer's Noise_IK authorizer would not recognise the
+// client's static key and Noise handshakes against it would fail. The
+// fix in handleVNCRule must distribute the pubkey to either side of a
+// bidirectional rule.
+func TestHandleVNCRule_BidirectionalDistributesPubkeyToSourcePeer(t *testing.T) {
+	rule := &PolicyRule{
+		Protocol:           PolicyRuleProtocolNetbirdVNC,
+		Bidirectional:      true,
+		AuthorizedUser:     "user1",
+		SessionPubKey:      "pubkey-base64",
+		SessionDisplayName: "Alice",
+	}
+	cb := RuleAuthCallbacks{
+		CollectVNCUsers: func(_ *PolicyRule, _ map[string]map[string]struct{}) {},
+	}
+	state := NewPeerConnResolveState()
+
+	cb.handleVNCRule(rule, true /*peerInSources*/, false /*peerInDestinations*/, state)
+
+	if len(state.VNCSessionPubKeys) != 1 {
+		t.Fatalf("expected 1 session pubkey distributed to source peer of bidirectional rule, got %d", len(state.VNCSessionPubKeys))
+	}
+	if state.VNCSessionPubKeys[0].PubKey != "pubkey-base64" {
+		t.Fatalf("unexpected pubkey: %q", state.VNCSessionPubKeys[0].PubKey)
+	}
+}
+
+// TestHandleVNCRule_UnidirectionalSourceGetsNoPubkey makes sure the fix
+// above didn't widen pubkey distribution past the bidirectional case:
+// a strictly source-to-destination rule still must not push the
+// SessionPubKey to peers that appear only in sources.
+func TestHandleVNCRule_UnidirectionalSourceGetsNoPubkey(t *testing.T) {
+	rule := &PolicyRule{
+		Protocol:       PolicyRuleProtocolNetbirdVNC,
+		Bidirectional:  false,
+		AuthorizedUser: "user1",
+		SessionPubKey:  "pubkey-base64",
+	}
+	cb := RuleAuthCallbacks{
+		CollectVNCUsers: func(_ *PolicyRule, _ map[string]map[string]struct{}) {},
+	}
+	state := NewPeerConnResolveState()
+
+	cb.handleVNCRule(rule, true /*peerInSources*/, false /*peerInDestinations*/, state)
+
+	if len(state.VNCSessionPubKeys) != 0 {
+		t.Fatalf("expected NO pubkey for source peer of unidirectional rule, got %d", len(state.VNCSessionPubKeys))
+	}
+}
+
+// TestHandleVNCRule_DestinationAlwaysGetsPubkey is the baseline case:
+// destination peers must always receive the SessionPubKey since they're
+// the ones that need to authenticate the incoming Noise handshake.
+func TestHandleVNCRule_DestinationAlwaysGetsPubkey(t *testing.T) {
+	rule := &PolicyRule{
+		Protocol:       PolicyRuleProtocolNetbirdVNC,
+		Bidirectional:  false,
+		AuthorizedUser: "user1",
+		SessionPubKey:  "pubkey-base64",
+	}
+	cb := RuleAuthCallbacks{
+		CollectVNCUsers: func(_ *PolicyRule, _ map[string]map[string]struct{}) {},
+	}
+	state := NewPeerConnResolveState()
+
+	cb.handleVNCRule(rule, false /*peerInSources*/, true /*peerInDestinations*/, state)
+
+	if len(state.VNCSessionPubKeys) != 1 {
+		t.Fatalf("expected 1 session pubkey for destination peer, got %d", len(state.VNCSessionPubKeys))
+	}
+}
+
+// TestApplyResolvedRule_BidirectionalSSHEnablesSourcePeer locks the
+// bidirectional widening for netbird-ssh rules: a peer that appears only
+// in the rule's sources of a bidirectional SSH rule must get SSH enabled
+// and its authorized users collected, because the rule grants access in
+// both directions. A unidirectional rule must not do this for a
+// source-only peer.
+func TestApplyResolvedRule_BidirectionalSSHEnablesSourcePeer(t *testing.T) {
+	collected := false
+	cb := RuleAuthCallbacks{
+		CollectSSHUsers: func(_ *PolicyRule, target map[string]map[string]struct{}) {
+			collected = true
+			target["local"] = map[string]struct{}{"user1": {}}
+		},
+	}
+	rule := &PolicyRule{
+		Protocol:      PolicyRuleProtocolNetbirdSSH,
+		Bidirectional: true,
+	}
+	state := NewPeerConnResolveState()
+
+	ApplyResolvedRuleToState(rule, nil, nil, true /*peerInSources*/, false /*peerInDestinations*/, false, func(*PolicyRule, []*ComponentPeer, int) {}, cb, state)
+
+	if !state.SSHEnabled {
+		t.Fatal("expected SSH enabled on source-side peer of bidirectional SSH rule")
+	}
+	if !collected {
+		t.Fatal("expected authorized users collected on source-side peer of bidirectional SSH rule")
+	}
+	if _, ok := state.AuthorizedUsers["local"]; !ok {
+		t.Fatal("expected authorized users map populated for source-side peer")
+	}
+}
+
+// TestApplyResolvedRule_UnidirectionalSSHSkipsSourcePeer is the negative
+// counterpart: a unidirectional SSH rule must not enable SSH for a peer
+// that appears only in sources.
+func TestApplyResolvedRule_UnidirectionalSSHSkipsSourcePeer(t *testing.T) {
+	collected := false
+	cb := RuleAuthCallbacks{
+		CollectSSHUsers: func(_ *PolicyRule, _ map[string]map[string]struct{}) {
+			collected = true
+		},
+	}
+	rule := &PolicyRule{
+		Protocol:      PolicyRuleProtocolNetbirdSSH,
+		Bidirectional: false,
+	}
+	state := NewPeerConnResolveState()
+
+	ApplyResolvedRuleToState(rule, nil, nil, true /*peerInSources*/, false /*peerInDestinations*/, false, func(*PolicyRule, []*ComponentPeer, int) {}, cb, state)
+
+	if state.SSHEnabled {
+		t.Fatal("expected SSH NOT enabled on source-only peer of unidirectional SSH rule")
+	}
+	if collected {
+		t.Fatal("expected NO authorized users collected on source-only peer of unidirectional SSH rule")
+	}
+}

shared/management/types/policyrule.go

@@ -0,0 +1,242 @@
+package types
+
+import (
+	"slices"
+
+	"github.com/netbirdio/netbird/shared/management/proto"
+)
+
+// PolicyUpdateOperationType operation type
+type PolicyUpdateOperationType int
+
+// PolicyTrafficActionType action type for the firewall
+type PolicyTrafficActionType string
+
+// PolicyRuleProtocolType type of traffic
+type PolicyRuleProtocolType string
+
+// PolicyRuleDirection direction of traffic
+type PolicyRuleDirection string
+
+// RulePortRange represents a range of ports for a firewall rule.
+type RulePortRange struct {
+	Start uint16
+	End   uint16
+}
+
+func (r *RulePortRange) ToProto() *proto.PortInfo {
+	return &proto.PortInfo{
+		PortSelection: &proto.PortInfo_Range_{
+			Range: &proto.PortInfo_Range{
+				Start: uint32(r.Start),
+				End:   uint32(r.End),
+			},
+		},
+	}
+}
+
+func (r *RulePortRange) Equal(other *RulePortRange) bool {
+	return r.Start == other.Start && r.End == other.End
+}
+
+// PolicyRule is the metadata of the policy
+type PolicyRule struct {
+	// ID of the policy rule
+	ID string `gorm:"primaryKey"`
+
+	// PolicyID is a reference to Policy that this object belongs
+	PolicyID string `json:"-" gorm:"index"`
+
+	// Name of the rule visible in the UI
+	Name string
+
+	// Description of the rule visible in the UI
+	Description string
+
+	// Enabled status of rule in the system
+	Enabled bool
+
+	// Action policy accept or drops packets
+	Action PolicyTrafficActionType
+
+	// Destinations policy destination groups
+	Destinations []string `gorm:"serializer:json"`
+
+	// DestinationResource policy destination resource that the rule is applied to
+	DestinationResource Resource `gorm:"serializer:json"`
+
+	// Sources policy source groups
+	Sources []string `gorm:"serializer:json"`
+
+	// SourceResource policy source resource that the rule is applied to
+	SourceResource Resource `gorm:"serializer:json"`
+
+	// Bidirectional define if the rule is applicable in both directions, sources, and destinations
+	Bidirectional bool
+
+	// Protocol type of the traffic
+	Protocol PolicyRuleProtocolType
+
+	// Ports or it ranges list
+	Ports []string `gorm:"serializer:json"`
+
+	// PortRanges a list of port ranges.
+	PortRanges []RulePortRange `gorm:"serializer:json"`
+
+	// AuthorizedGroups is a map of groupIDs and their respective access to local users via ssh
+	AuthorizedGroups map[string][]string `gorm:"serializer:json"`
+
+	// AuthorizedUser is a list of userIDs that are authorized to access local resources via ssh
+	AuthorizedUser string
+
+	// SessionPubKey is the base64 X25519 public key used with Noise_IK to
+	// bind a VNC session to the AuthorizedUser. Set together with
+	// AuthorizedUser when the rule was created via temporary-access for a
+	// VNC scope; empty otherwise.
+	SessionPubKey string
+
+	// SessionDisplayName is a human-readable label for the user the
+	// SessionPubKey was issued to (typically display name, falling back
+	// to email or user id). The daemon surfaces it on the host's
+	// per-connection approval prompt so the user being asked can
+	// recognise who is requesting access.
+	SessionDisplayName string
+}
+
+// Copy returns a copy of a policy rule
+func (pm *PolicyRule) Copy() *PolicyRule {
+	rule := &PolicyRule{
+		ID:                  pm.ID,
+		PolicyID:            pm.PolicyID,
+		Name:                pm.Name,
+		Description:         pm.Description,
+		Enabled:             pm.Enabled,
+		Action:              pm.Action,
+		Destinations:        make([]string, len(pm.Destinations)),
+		DestinationResource: pm.DestinationResource,
+		Sources:             make([]string, len(pm.Sources)),
+		SourceResource:      pm.SourceResource,
+		Bidirectional:       pm.Bidirectional,
+		Protocol:            pm.Protocol,
+		Ports:               make([]string, len(pm.Ports)),
+		PortRanges:          make([]RulePortRange, len(pm.PortRanges)),
+		AuthorizedGroups:    make(map[string][]string, len(pm.AuthorizedGroups)),
+		AuthorizedUser:      pm.AuthorizedUser,
+		SessionPubKey:       pm.SessionPubKey,
+		SessionDisplayName:  pm.SessionDisplayName,
+	}
+	copy(rule.Destinations, pm.Destinations)
+	copy(rule.Sources, pm.Sources)
+	copy(rule.Ports, pm.Ports)
+	copy(rule.PortRanges, pm.PortRanges)
+	for k, v := range pm.AuthorizedGroups {
+		rule.AuthorizedGroups[k] = make([]string, len(v))
+		copy(rule.AuthorizedGroups[k], v)
+	}
+	return rule
+}
+
+func (pm *PolicyRule) Equal(other *PolicyRule) bool {
+	if pm == nil || other == nil {
+		return pm == other
+	}
+
+	if pm.ID != other.ID ||
+		pm.PolicyID != other.PolicyID ||
+		pm.Name != other.Name ||
+		pm.Description != other.Description ||
+		pm.Enabled != other.Enabled ||
+		pm.Action != other.Action ||
+		pm.Bidirectional != other.Bidirectional ||
+		pm.Protocol != other.Protocol ||
+		pm.SourceResource != other.SourceResource ||
+		pm.DestinationResource != other.DestinationResource ||
+		pm.AuthorizedUser != other.AuthorizedUser ||
+		pm.SessionPubKey != other.SessionPubKey ||
+		pm.SessionDisplayName != other.SessionDisplayName {
+		return false
+	}
+
+	if !stringSlicesEqualUnordered(pm.Sources, other.Sources) {
+		return false
+	}
+	if !stringSlicesEqualUnordered(pm.Destinations, other.Destinations) {
+		return false
+	}
+	if !stringSlicesEqualUnordered(pm.Ports, other.Ports) {
+		return false
+	}
+	if !portRangeSlicesEqualUnordered(pm.PortRanges, other.PortRanges) {
+		return false
+	}
+	if !authorizedGroupsEqual(pm.AuthorizedGroups, other.AuthorizedGroups) {
+		return false
+	}
+
+	return true
+}
+
+func stringSlicesEqualUnordered(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	if len(a) == 0 {
+		return true
+	}
+	sorted1 := make([]string, len(a))
+	sorted2 := make([]string, len(b))
+	copy(sorted1, a)
+	copy(sorted2, b)
+	slices.Sort(sorted1)
+	slices.Sort(sorted2)
+	return slices.Equal(sorted1, sorted2)
+}
+
+func portRangeSlicesEqualUnordered(a, b []RulePortRange) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	if len(a) == 0 {
+		return true
+	}
+	cmp := func(x, y RulePortRange) int {
+		if x.Start != y.Start {
+			if x.Start < y.Start {
+				return -1
+			}
+			return 1
+		}
+		if x.End != y.End {
+			if x.End < y.End {
+				return -1
+			}
+			return 1
+		}
+		return 0
+	}
+	sorted1 := make([]RulePortRange, len(a))
+	sorted2 := make([]RulePortRange, len(b))
+	copy(sorted1, a)
+	copy(sorted2, b)
+	slices.SortFunc(sorted1, cmp)
+	slices.SortFunc(sorted2, cmp)
+	return slices.EqualFunc(sorted1, sorted2, func(x, y RulePortRange) bool {
+		return x.Start == y.Start && x.End == y.End
+	})
+}
+
+func authorizedGroupsEqual(a, b map[string][]string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for k, va := range a {
+		vb, ok := b[k]
+		if !ok {
+			return false
+		}
+		if !stringSlicesEqualUnordered(va, vb) {
+			return false
+		}
+	}
+	return true
+}

shared/management/types/resource.go

@@ -0,0 +1,39 @@
+package types
+
+import (
+	"github.com/netbirdio/netbird/shared/management/http/api"
+)
+
+type ResourceType string
+
+const (
+	ResourceTypePeer   ResourceType = "peer"
+	ResourceTypeDomain ResourceType = "domain"
+	ResourceTypeHost   ResourceType = "host"
+	ResourceTypeSubnet ResourceType = "subnet"
+)
+
+type Resource struct {
+	ID   string
+	Type ResourceType
+}
+
+func (r *Resource) ToAPIResponse() *api.Resource {
+	if r.ID == "" && r.Type == "" {
+		return nil
+	}
+
+	return &api.Resource{
+		Id:   r.ID,
+		Type: api.ResourceType(r.Type),
+	}
+}
+
+func (r *Resource) FromAPIRequest(req *api.Resource) {
+	if req == nil {
+		return
+	}
+
+	r.ID = req.Id
+	r.Type = ResourceType(req.Type)
+}

shared/management/types/route_firewall_rule.go

@@ -0,0 +1,64 @@
+package types
+
+import (
+	"github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/domain"
+)
+
+// RouteFirewallRule a firewall rule applicable for a routed network.
+type RouteFirewallRule struct {
+	// PolicyID is the ID of the policy this rule is derived from
+	PolicyID string
+
+	// RouteID is the ID of the route this rule belongs to.
+	RouteID route.ID
+
+	// SourceRanges IP ranges of the routing peers.
+	SourceRanges []string
+
+	// Action of the traffic when the rule is applicable
+	Action string
+
+	// Destination a network prefix for the routed traffic
+	Destination string
+
+	// Protocol of the traffic
+	Protocol string
+
+	// Port of the traffic
+	Port uint16
+
+	// PortRange represents the range of ports for a firewall rule
+	PortRange RulePortRange
+
+	// Domains list of network domains for the routed traffic
+	Domains domain.List
+
+	// isDynamic indicates whether the rule is for DNS routing
+	IsDynamic bool
+}
+
+func (r *RouteFirewallRule) Equal(other *RouteFirewallRule) bool {
+	if r.Action != other.Action {
+		return false
+	}
+	if r.Destination != other.Destination {
+		return false
+	}
+	if r.Protocol != other.Protocol {
+		return false
+	}
+	if r.Port != other.Port {
+		return false
+	}
+	if !r.PortRange.Equal(&other.PortRange) {
+		return false
+	}
+	if !r.Domains.Equal(other.Domains) {
+		return false
+	}
+	if r.IsDynamic != other.IsDynamic {
+		return false
+	}
+	return true
+}

shared/relay/auth/allow/allow_all.go

@@ -8,7 +8,3 @@ type Auth struct {
 func (a *Auth) Validate(any) error {
 	return nil
 }
-
-func (a *Auth) ValidateHelloMsgType(any) error {
-	return nil
-}

shared/relay/auth/hmac/token.go

@@ -1,10 +1,8 @@
 package hmac
 
 import (
-	"bytes"
 	"crypto/hmac"
 	"encoding/base64"
-	"encoding/gob"
 	"fmt"
 	"hash"
 	"strconv"
@@ -18,14 +16,6 @@ type Token struct {
 	Signature string
 }
 
-func unmarshalToken(payload []byte) (Token, error) {
-	var creds Token
-	buffer := bytes.NewBuffer(payload)
-	decoder := gob.NewDecoder(buffer)
-	err := decoder.Decode(&creds)
-	return creds, err
-}
-
 // TimedHMAC generates a token with TTL and uses a pre-shared secret known to the relay server
 type TimedHMAC struct {
 	secret     string

shared/relay/auth/hmac/validator.go

@@ -1,33 +0,0 @@
-package hmac
-
-import (
-	"crypto/sha256"
-	"fmt"
-	"time"
-
-	log "github.com/sirupsen/logrus"
-)
-
-type TimedHMACValidator struct {
-	*TimedHMAC
-}
-
-func NewTimedHMACValidator(secret string, duration time.Duration) *TimedHMACValidator {
-	ta := NewTimedHMAC(secret, duration)
-	return &TimedHMACValidator{
-		ta,
-	}
-}
-
-func (a *TimedHMACValidator) Validate(credentials any) error {
-	b, ok := credentials.([]byte)
-	if !ok {
-		return fmt.Errorf("invalid credentials type")
-	}
-	c, err := unmarshalToken(b)
-	if err != nil {
-		log.Debugf("failed to unmarshal token: %s", err)
-		return err
-	}
-	return a.TimedHMAC.Validate(sha256.New, c)
-}

shared/relay/auth/validator.go

@@ -1,28 +1,19 @@
 package auth
 
 import (
-	"time"
-
-	auth "github.com/netbirdio/netbird/shared/relay/auth/hmac"
 	authv2 "github.com/netbirdio/netbird/shared/relay/auth/hmac/v2"
 )
 
 type TimedHMACValidator struct {
 	authenticatorV2 *authv2.Validator
-	authenticator   *auth.TimedHMACValidator
 }
 
-func NewTimedHMACValidator(secret []byte, duration time.Duration) *TimedHMACValidator {
+func NewTimedHMACValidator(secret []byte) *TimedHMACValidator {
 	return &TimedHMACValidator{
 		authenticatorV2: authv2.NewValidator(secret),
-		authenticator:   auth.NewTimedHMACValidator(string(secret), duration),
 	}
 }
 
 func (a *TimedHMACValidator) Validate(credentials any) error {
 	return a.authenticatorV2.Validate(credentials)
 }
-
-func (a *TimedHMACValidator) ValidateHelloMsgType(credentials any) error {
-	return a.authenticator.Validate(credentials)
-}

shared/relay/client/early_msg_buffer.go

@@ -10,7 +10,7 @@ import (
 
 const (
 	earlyMsgTTL      = 5 * time.Second
-	earlyMsgCapacity = 1000
+	earlyMsgCapacity = 10000
 )
 
 // earlyMsgBuffer buffers transport messages that arrive before the corresponding

shared/relay/messages/address/address.go

@@ -1,21 +0,0 @@
-// Deprecated: This package is deprecated and will be removed in a future release.
-package address
-
-import (
-	"bytes"
-	"encoding/gob"
-	"fmt"
-)
-
-type Address struct {
-	URL string
-}
-
-func (addr *Address) Marshal() ([]byte, error) {
-	var buf bytes.Buffer
-	enc := gob.NewEncoder(&buf)
-	if err := enc.Encode(addr); err != nil {
-		return nil, fmt.Errorf("encode Address: %w", err)
-	}
-	return buf.Bytes(), nil
-}

shared/relay/messages/auth/auth.go

@@ -1,43 +0,0 @@
-// Deprecated: This package is deprecated and will be removed in a future release.
-package auth
-
-import (
-	"bytes"
-	"encoding/gob"
-	"fmt"
-)
-
-type Algorithm int
-
-const (
-	AlgoUnknown Algorithm = iota
-	AlgoHMACSHA256
-	AlgoHMACSHA512
-)
-
-func (a Algorithm) String() string {
-	switch a {
-	case AlgoHMACSHA256:
-		return "HMAC-SHA256"
-	case AlgoHMACSHA512:
-		return "HMAC-SHA512"
-	default:
-		return "Unknown"
-	}
-}
-
-type Msg struct {
-	AuthAlgorithm  Algorithm
-	AdditionalData []byte
-}
-
-func UnmarshalMsg(data []byte) (*Msg, error) {
-	var msg *Msg
-
-	buf := bytes.NewBuffer(data)
-	dec := gob.NewDecoder(buf)
-	if err := dec.Decode(&msg); err != nil {
-		return nil, fmt.Errorf("decode Msg: %w", err)
-	}
-	return msg, nil
-}

shared/relay/messages/message.go

@@ -14,9 +14,10 @@ const (
 	CurrentProtocolVersion = 1
 
 	MsgTypeUnknown MsgType = 0
-	// Deprecated: Use MsgTypeAuth instead.
-	MsgTypeHello = 1
-	// Deprecated: Use MsgTypeAuthResponse instead.
+	// MsgTypeHello and MsgTypeHelloResponse are the removed legacy handshake
+	// message types. They are retained only to reserve wire values 1 and 2 so
+	// the values are never reused; the server rejects both.
+	MsgTypeHello         = 1
 	MsgTypeHelloResponse = 2
 	MsgTypeTransport     = 3
 	MsgTypeClose         = 4
@@ -42,10 +43,6 @@ const (
 	offsetAuthPeerID    = sizeOfProtoHeader + sizeOfMagicByte
 	headerTotalSizeAuth = sizeOfProtoHeader + headerSizeAuth
 
-	// hello message
-	headerSizeHello     = sizeOfMagicByte + peerIDSize
-	headerSizeHelloResp = 0
-
 	// transport
 	headerSizeTransport      = peerIDSize
 	offsetTransportID        = sizeOfProtoHeader
@@ -113,7 +110,6 @@ func DetermineClientMessageType(msg []byte) (MsgType, error) {
 	msgType := MsgType(msg[1])
 	switch msgType {
 	case
-		MsgTypeHello,
 		MsgTypeAuth,
 		MsgTypeTransport,
 		MsgTypeClose,
@@ -135,7 +131,6 @@ func DetermineServerMessageType(msg []byte) (MsgType, error) {
 	msgType := MsgType(msg[1])
 	switch msgType {
 	case
-		MsgTypeHelloResponse,
 		MsgTypeAuthResponse,
 		MsgTypeTransport,
 		MsgTypeClose,
@@ -148,67 +143,6 @@ func DetermineServerMessageType(msg []byte) (MsgType, error) {
 	}
 }
 
-// Deprecated: Use MarshalAuthMsg instead.
-// MarshalHelloMsg initial hello message
-// The Hello message is the first message sent by a client after establishing a connection with the Relay server. This
-// message is used to authenticate the client with the server. The authentication is done using an HMAC method.
-// The protocol does not limit to use HMAC, it can be any other method. If the authentication failed the server will
-// close the network connection without any response.
-func MarshalHelloMsg(peerID PeerID, additions []byte) ([]byte, error) {
-	msg := make([]byte, sizeOfProtoHeader+sizeOfMagicByte, sizeOfProtoHeader+headerSizeHello+len(additions))
-
-	msg[0] = byte(CurrentProtocolVersion)
-	msg[1] = byte(MsgTypeHello)
-
-	copy(msg[sizeOfProtoHeader:sizeOfProtoHeader+sizeOfMagicByte], magicHeader)
-
-	msg = append(msg, peerID[:]...)
-	msg = append(msg, additions...)
-
-	return msg, nil
-}
-
-// Deprecated: Use UnmarshalAuthMsg instead.
-// UnmarshalHelloMsg extracts peerID and the additional data from the hello message. The Additional data is used to
-// authenticate the client with the server.
-func UnmarshalHelloMsg(msg []byte) (*PeerID, []byte, error) {
-	if len(msg) < sizeOfProtoHeader+headerSizeHello {
-		return nil, nil, ErrInvalidMessageLength
-	}
-	if !bytes.Equal(msg[sizeOfProtoHeader:sizeOfProtoHeader+sizeOfMagicByte], magicHeader) {
-		return nil, nil, errors.New("invalid magic header")
-	}
-
-	peerID := PeerID(msg[sizeOfProtoHeader+sizeOfMagicByte : sizeOfProtoHeader+headerSizeHello])
-
-	return &peerID, msg[headerSizeHello:], nil
-}
-
-// Deprecated: Use MarshalAuthResponse instead.
-// MarshalHelloResponse creates a response message to the hello message.
-// In case of success connection the server response with a Hello Response message. This message contains the server's
-// instance URL. This URL will be used by choose the common Relay server in case if the peers are in different Relay
-// servers.
-func MarshalHelloResponse(additionalData []byte) ([]byte, error) {
-	msg := make([]byte, sizeOfProtoHeader, sizeOfProtoHeader+headerSizeHelloResp+len(additionalData))
-
-	msg[0] = byte(CurrentProtocolVersion)
-	msg[1] = byte(MsgTypeHelloResponse)
-
-	msg = append(msg, additionalData...)
-
-	return msg, nil
-}
-
-// Deprecated: Use UnmarshalAuthResponse instead.
-// UnmarshalHelloResponse extracts the additional data from the hello response message.
-func UnmarshalHelloResponse(msg []byte) ([]byte, error) {
-	if len(msg) < sizeOfProtoHeader+headerSizeHelloResp {
-		return nil, ErrInvalidMessageLength
-	}
-	return msg, nil
-}
-
 // MarshalAuthMsg initial authentication message
 // The Auth message is the first message sent by a client after establishing a connection with the Relay server. This
 // message is used to authenticate the client with the server. The authentication is done using an HMAC method.

shared/relay/messages/message_test.go

@@ -4,28 +4,11 @@ import (
 	"testing"
 )
 
-func TestMarshalHelloMsg(t *testing.T) {
-	peerID := HashID("abdFAaBcawquEiCMzAabYosuUaGLtSNhKxz+")
-	msg, err := MarshalHelloMsg(peerID, nil)
-	if err != nil {
-		t.Fatalf("error: %v", err)
-	}
-
-	msgType, err := DetermineClientMessageType(msg)
-	if err != nil {
-		t.Fatalf("error: %v", err)
-	}
-
-	if msgType != MsgTypeHello {
-		t.Errorf("expected %d, got %d", MsgTypeHello, msgType)
-	}
-
-	receivedPeerID, _, err := UnmarshalHelloMsg(msg)
-	if err != nil {
-		t.Fatalf("error: %v", err)
-	}
-	if receivedPeerID.String() != peerID.String() {
-		t.Errorf("expected %s, got %s", peerID, receivedPeerID)
+func TestDetermineClientMessageTypeRejectsHello(t *testing.T) {
+	// The reserved legacy Hello message (type 1) must be rejected by the server.
+	msg := []byte{byte(CurrentProtocolVersion), byte(MsgTypeHello)}
+	if _, err := DetermineClientMessageType(msg); err == nil {
+		t.Fatalf("expected hello message type to be rejected")
 	}
 }
 

shared/testing_helpers/populate_fields.go

@@ -0,0 +1,101 @@
+package testing_helpers
+
+import (
+	"fmt"
+	"net/netip"
+	"reflect"
+)
+
+type PopulateFields struct {
+	CustomFieldSetters map[reflect.Type]func(this *PopulateFields, field reflect.Value) (int, error)
+	TagsToSkip         map[string]string
+}
+
+func NewPopulateFields() *PopulateFields {
+	return &PopulateFields{CustomFieldSetters: defaultCustomFieldSetters(), TagsToSkip: make(map[string]string)}
+}
+
+func (p *PopulateFields) WithCustomFieldSetter(t reflect.Type, f func(this *PopulateFields, field reflect.Value) (int, error)) *PopulateFields {
+	p.CustomFieldSetters[t] = f
+	return p
+}
+
+func (p *PopulateFields) WithSkippedTag(tag, value string) *PopulateFields {
+	p.TagsToSkip[tag] = value
+	return p
+}
+
+func (p *PopulateFields) PopulateAll(v reflect.Value) (int, error) {
+	typ := v.Type()
+	totalExportedFields := 0
+	for i := 0; i < typ.NumField(); i++ {
+		f := typ.Field(i)
+		if f.PkgPath != "" { // unexported
+			continue
+		}
+
+		if p.skippedTagPresent(f.Tag) {
+			continue
+		}
+
+		numOfExportedFields, err := p.setNonZero(v.Field(i))
+		totalExportedFields += numOfExportedFields
+		if err != nil {
+			return totalExportedFields, err
+		}
+	}
+	return totalExportedFields, nil
+}
+
+// setNonZero assigns a deterministic non-zero value to a field based on its kind,
+// recursing into nested structs and populating one element of slice fields.
+func (p *PopulateFields) setNonZero(field reflect.Value) (int, error) {
+	if f, ok := p.CustomFieldSetters[field.Type()]; ok {
+		return f(p, field)
+	}
+
+	switch field.Kind() {
+	case reflect.String:
+		field.SetString("non-zero")
+	case reflect.Bool:
+		field.SetBool(true)
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		field.SetInt(7)
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		field.SetUint(7)
+	case reflect.Float32, reflect.Float64:
+		field.SetFloat(7)
+	case reflect.Struct:
+		n, err := p.PopulateAll(field)
+		return n + 1, err
+	case reflect.Slice:
+		s := reflect.MakeSlice(field.Type(), 1, 1)
+		_, err := p.setNonZero(s.Index(0))
+		if err != nil {
+			return 0, err
+		}
+		field.Set(s)
+	default:
+		return 0, fmt.Errorf("unhandled field kind %s; extend setNonZero", field.Kind())
+	}
+
+	return 1, nil
+}
+
+func defaultCustomFieldSetters() map[reflect.Type]func(this *PopulateFields, field reflect.Value) (int, error) {
+	return map[reflect.Type]func(this *PopulateFields, field reflect.Value) (int, error){
+		reflect.TypeOf(netip.Prefix{}): func(_ *PopulateFields, field reflect.Value) (int, error) {
+			field.Set(reflect.ValueOf(netip.MustParsePrefix("10.0.0.0/24")))
+			return 1, nil
+		},
+	}
+}
+
+func (p *PopulateFields) skippedTagPresent(t reflect.StructTag) bool {
+	for tag, value := range p.TagsToSkip {
+		if v := t.Get(tag); v == value {
+			return true
+		}
+	}
+	return false
+}