[client, management] offload client config generation to the client (#6711)

Signed-off-by: Dmitri Dolguikh <dmitri.external@netbird.io>
Co-authored-by: crn4 <vladimir@netbird.io>
Co-authored-by: pascal <pascal@netbird.io>

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"
 )
@@ -1026,6 +1027,8 @@ func infoToMetaData(info *system.Info) *proto.PeerSystemMeta {
 		},
 
 		Capabilities: peerCapabilities(*info),
+
+		SyncMessageVersion: syncMessageVersion(*info),
 	}
 }
 
@@ -1039,3 +1042,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/networkmap/decode.go

@@ -0,0 +1,550 @@
+package networkmap
+
+import (
+	"encoding/base64"
+	"fmt"
+	"net"
+	"net/netip"
+	"strconv"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+
+	nbdns "github.com/netbirdio/netbird/dns"
+	resourceTypes "github.com/netbirdio/netbird/management/server/networks/resources/types"
+	routerTypes "github.com/netbirdio/netbird/management/server/networks/routers/types"
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	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]*nbpeer.Peer, len(full.Peers)),
+		Groups:              make(map[string]*types.Group, 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]*routerTypes.NetworkRouter),
+		NetworkResources:    make([]*resourceTypes.NetworkResource, 0, len(full.NetworkResources)),
+		RouterPeers:         make(map[string]*nbpeer.Peer),
+		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.Group{
+			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]*routerTypes.NetworkRouter, 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] = &routerTypes.NetworkRouter{
+				ID:         "",
+				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) *nbpeer.Peer {
+	var caps []int32
+	if pc.SupportsSourcePrefixes {
+		caps = append(caps, nbpeer.PeerCapabilitySourcePrefixes)
+	}
+	if pc.SupportsIpv6 {
+		caps = append(caps, nbpeer.PeerCapabilityIPv6Overlay)
+	}
+	peer := &nbpeer.Peer{
+		ID:                     peerID,
+		Key:                    peerID,
+		SSHKey:                 string(pc.SshPubKey),
+		SSHEnabled:             pc.SshEnabled,
+		DNSLabel:               pc.DnsLabel,
+		LoginExpirationEnabled: pc.LoginExpirationEnabled,
+		Meta: nbpeer.PeerSystemMeta{
+			WtVersion:    pc.AgentVersion,
+			Capabilities: caps,
+			Flags: nbpeer.Flags{
+				ServerSSHAllowed: pc.ServerSshAllowed,
+			},
+		},
+	}
+	if pc.AddedWithSsoLogin {
+		// Set a non-empty UserID so (*Peer).AddedWithSSOLogin() returns true.
+		// The original UserID isn't on the wire; the value is intentionally
+		// visibly synthetic so any future consumer that mistakes UserID for a
+		// real account user xid won't silently match (or worse, write the
+		// sentinel into a downstream record).
+		peer.UserID = "<env-sso>"
+	}
+	if pc.LastLoginUnixNano != 0 {
+		t := time.Unix(0, pc.LastLoginUnixNano)
+		peer.LastLogin = &t
+	}
+	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) *resourceTypes.NetworkResource {
+	out := &resourceTypes.NetworkResource{
+		ID:          nr.Id,
+		PublicID:    nr.Id,
+		NetworkID:   nr.NetworkSeq,
+		Name:        nr.Name,
+		Description: nr.Description,
+		Type:        resourceTypes.NetworkResourceType(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,323 @@
+// 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"
+
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"github.com/netbirdio/netbird/shared/management/types"
+	nbroute "github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/proto"
+	"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 []*nbpeer.Peer, dnsName string, includeIPv6 bool) []*proto.RemotePeerConfig {
+	for _, rPeer := range peers {
+		allowedIPs := []string{rPeer.IP.String() + "/32"}
+		if includeIPv6 && rPeer.IPv6.IsValid() {
+			allowedIPs = append(allowedIPs, rPeer.IPv6.String()+"/128")
+		}
+		dst = append(dst, &proto.RemotePeerConfig{
+			WgPubKey:     rPeer.Key,
+			AllowedIps:   allowedIPs,
+			SshConfig:    &proto.SSHConfig{SshPubKey: []byte(rPeer.SSHKey)},
+			Fqdn:         rPeer.FQDN(dnsName),
+			AgentVersion: rPeer.Meta.WtVersion,
+		})
+	}
+	return dst
+}
+
+// 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,295 @@
+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"
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"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]*nbpeer.Peer{}
+	for i, id := range []string{"peer-T", "peer-S", "peer-ALL", "peer-O"} {
+		peers[id] = &nbpeer.Peer{
+			ID:       id,
+			Key:      randomWgKey(t),
+			IP:       netip.AddrFrom4([4]byte{100, 64, 0, byte(i + 1)}),
+			DNSLabel: id,
+			Meta:     nbpeer.PeerSystemMeta{WtVersion: "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.Group{
+			"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 := &nbpeer.Peer{
+		ID:       "peer-A",
+		Key:      peerAKey,
+		IP:       netip.AddrFrom4([4]byte{100, 64, 0, 1}),
+		DNSLabel: "peerA",
+		Meta:     nbpeer.PeerSystemMeta{WtVersion: "0.40.0"},
+	}
+	peerB := &nbpeer.Peer{
+		ID:       "peer-B",
+		Key:      peerBKey,
+		IP:       netip.AddrFrom4([4]byte{100, 64, 0, 2}),
+		DNSLabel: "peerB",
+		Meta:     nbpeer.PeerSystemMeta{WtVersion: "0.40.0"},
+	}
+
+	group := &types.Group{
+		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]*nbpeer.Peer{
+			"peer-A": peerA,
+			"peer-B": peerB,
+		},
+		Groups: map[string]*types.Group{
+			"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 {
@@ -229,6 +237,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.
@@ -252,6 +262,7 @@ message PeerSystemMeta {
   Flags flags = 17;
 
   repeated PeerCapability capabilities = 18;
+  int32 syncMessageVersion = 19;
 }
 
 message LoginResponse {
@@ -617,6 +628,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 {
@@ -757,3 +775,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/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,131 @@
+package types
+
+import (
+	"strconv"
+
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"github.com/netbirdio/netbird/management/server/posture"
+	"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 *nbpeer.Peer) []*FirewallRule {
+	features := peerSupportedFirewallFeatures(peer.Meta.WtVersion)
+
+	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 *nbpeer.Peer) bool {
+	return supportsNative && peer.SSHEnabled && peer.Meta.Flags.ServerSSHAllowed && rule.Protocol == PolicyRuleProtocolTCP
+}
+
+func peerSupportedFirewallFeatures(peerVer string) supportedFeatures {
+	if version.IsDevelopmentVersion(peerVer) {
+		return supportedFeatures{true, true}
+	}
+
+	var features supportedFeatures
+
+	meetMinVer, err := posture.MeetsMinVersion(firewallRuleMinNativeSSHVer, peerVer)
+	features.nativeSSH = err == nil && meetMinVer
+
+	if features.nativeSSH {
+		features.portRanges = true
+	} else {
+		meetMinVer, err = posture.MeetsMinVersion(firewallRuleMinPortRangesVer, peerVer)
+		features.portRanges = err == nil && meetMinVer
+	}
+
+	return features
+}

shared/management/types/firewall_rule.go

@@ -0,0 +1,182 @@
+package types
+
+import (
+	"context"
+	"fmt"
+	"reflect"
+	"strconv"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	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 []*nbpeer.Peer, 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 []*nbpeer.Peer) (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,197 @@
+package types
+
+import (
+	"context"
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"github.com/netbirdio/netbird/route"
+	"github.com/netbirdio/netbird/shared/management/domain"
+)
+
+func TestSplitPeerSourcesByFamily(t *testing.T) {
+	peers := []*nbpeer.Peer{
+		{
+			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 := []*nbpeer.Peer{
+		{
+			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 := []*nbpeer.Peer{
+		{
+			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 := []*nbpeer.Peer{
+		{
+			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 := []*nbpeer.Peer{
+		{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 := []*nbpeer.Peer{
+		{
+			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/group.go

@@ -0,0 +1,159 @@
+package types
+
+import (
+	"github.com/netbirdio/netbird/management/server/integration_reference"
+	"github.com/netbirdio/netbird/management/server/networks/resources/types"
+)
+
+const (
+	GroupIssuedAPI         = "api"
+	GroupIssuedJWT         = "jwt"
+	GroupIssuedIntegration = "integration"
+)
+
+// Group of the peers for ACL
+type Group struct {
+	// ID of the group
+	ID string `gorm:"primaryKey"`
+
+	// AccountID is a reference to Account that this object belongs
+	AccountID string `json:"-" gorm:"index"`
+
+	PublicID string `json:"-"`
+
+	// Name visible in the UI
+	Name string
+
+	// Issued defines how this group was created (enum of "api", "integration" or "jwt")
+	Issued string
+
+	// Peers list of the group
+	Peers      []string    `gorm:"-"` // Peers and GroupPeers list will be ignored when writing to the DB. Use AddPeerToGroup and RemovePeerFromGroup methods to modify group membership
+	GroupPeers []GroupPeer `gorm:"foreignKey:GroupID;references:id;constraint:OnDelete:CASCADE;"`
+
+	// Resources contains a list of resources in that group
+	Resources []Resource `gorm:"serializer:json"`
+
+	IntegrationReference integration_reference.IntegrationReference `gorm:"embedded;embeddedPrefix:integration_ref_"`
+}
+
+type GroupPeer struct {
+	AccountID string `gorm:"index"`
+	GroupID   string `gorm:"primaryKey"`
+	PeerID    string `gorm:"primaryKey"`
+}
+
+func (g *Group) LoadGroupPeers() {
+	g.Peers = make([]string, len(g.GroupPeers))
+	for i, peer := range g.GroupPeers {
+		g.Peers[i] = peer.PeerID
+	}
+	g.GroupPeers = []GroupPeer{}
+}
+
+func (g *Group) StoreGroupPeers() {
+	g.GroupPeers = make([]GroupPeer, len(g.Peers))
+	for i, peer := range g.Peers {
+		g.GroupPeers[i] = GroupPeer{
+			AccountID: g.AccountID,
+			GroupID:   g.ID,
+			PeerID:    peer,
+		}
+	}
+	g.Peers = []string{}
+}
+
+// EventMeta returns activity event meta related to the group
+func (g *Group) EventMeta() map[string]any {
+	return map[string]any{"name": g.Name}
+}
+
+func (g *Group) EventMetaResource(resource *types.NetworkResource) map[string]any {
+	return map[string]any{"name": g.Name, "id": g.ID, "resource_name": resource.Name, "resource_id": resource.ID, "resource_type": resource.Type}
+}
+
+func (g *Group) Copy() *Group {
+	group := &Group{
+		ID:                   g.ID,
+		AccountID:            g.AccountID,
+		PublicID:             g.PublicID,
+		Name:                 g.Name,
+		Issued:               g.Issued,
+		Peers:                make([]string, len(g.Peers)),
+		GroupPeers:           make([]GroupPeer, len(g.GroupPeers)),
+		Resources:            make([]Resource, len(g.Resources)),
+		IntegrationReference: g.IntegrationReference,
+	}
+	copy(group.Peers, g.Peers)
+	copy(group.GroupPeers, g.GroupPeers)
+	copy(group.Resources, g.Resources)
+	return group
+}
+
+// HasPeers checks if the group has any peers.
+func (g *Group) HasPeers() bool {
+	return len(g.Peers) > 0
+}
+
+// GroupAllName is the reserved name of the default group that contains every peer in an account.
+const GroupAllName = "All"
+
+// IsGroupAll checks if the group is a default "All" group.
+func (g *Group) IsGroupAll() bool {
+	return g.Name == GroupAllName
+}
+
+// AddPeer adds peerID to Peers if not present, returning true if added.
+func (g *Group) AddPeer(peerID string) bool {
+	if peerID == "" {
+		return false
+	}
+
+	for _, itemID := range g.Peers {
+		if itemID == peerID {
+			return false
+		}
+	}
+
+	g.Peers = append(g.Peers, peerID)
+	return true
+}
+
+// RemovePeer removes peerID from Peers if present, returning true if removed.
+func (g *Group) RemovePeer(peerID string) bool {
+	for i, itemID := range g.Peers {
+		if itemID == peerID {
+			g.Peers = append(g.Peers[:i], g.Peers[i+1:]...)
+			return true
+		}
+	}
+	return false
+}
+
+// AddResource adds resource to Resources if not present, returning true if added.
+func (g *Group) AddResource(resource Resource) bool {
+	for _, item := range g.Resources {
+		if item == resource {
+			return false
+		}
+	}
+
+	g.Resources = append(g.Resources, resource)
+	return true
+}
+
+// RemoveResource removes resource from Resources if present, returning true if removed.
+func (g *Group) RemoveResource(resource Resource) bool {
+	for i, item := range g.Resources {
+		if item == resource {
+			g.Resources = append(g.Resources[:i], g.Resources[i+1:]...)
+			return true
+		}
+	}
+	return false
+}
+
+// HasResources checks if the group has any resources.
+func (g *Group) HasResources() bool {
+	return len(g.Resources) > 0
+}

shared/management/types/network.go

@@ -0,0 +1,361 @@
+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"
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"github.com/netbirdio/netbird/management/server/util"
+	"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               []*nbpeer.Peer
+	Network             *Network
+	Routes              []*route.Route
+	DNSConfig           nbdns.Config
+	OfflinePeers        []*nbpeer.Peer
+	FirewallRules       []*FirewallRule
+	RoutesFirewallRules []*RouteFirewallRule
+	ForwardingRules     []*ForwardingRule
+	AuthorizedUsers     map[string]map[string]struct{}
+	EnableSSH           bool
+}
+
+func (nm *NetworkMap) Merge(other *NetworkMap) {
+	nm.Peers = mergeUniquePeersByID(nm.Peers, other.Peers)
+	nm.Routes = util.MergeUnique(nm.Routes, other.Routes)
+	nm.OfflinePeers = mergeUniquePeersByID(nm.OfflinePeers, other.OfflinePeers)
+	nm.FirewallRules = util.MergeUnique(nm.FirewallRules, other.FirewallRules)
+	nm.RoutesFirewallRules = util.MergeUnique(nm.RoutesFirewallRules, other.RoutesFirewallRules)
+	nm.ForwardingRules = util.MergeUnique(nm.ForwardingRules, other.ForwardingRules)
+}
+
+func mergeUniquePeersByID(peers1, peers2 []*nbpeer.Peer) []*nbpeer.Peer {
+	result := make(map[string]*nbpeer.Peer)
+	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_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,230 @@
+package types
+
+import (
+	nbdns "github.com/netbirdio/netbird/dns"
+	resourceTypes "github.com/netbirdio/netbird/management/server/networks/resources/types"
+	routerTypes "github.com/netbirdio/netbird/management/server/networks/routers/types"
+	nbpeer "github.com/netbirdio/netbird/management/server/peer"
+	"github.com/netbirdio/netbird/route"
+)
+
+type GroupCompact struct {
+	Name        string
+	PeerIndexes []int
+}
+
+type NetworkMapComponentsCompact struct {
+	PeerID string
+
+	Network          *Network
+	AccountSettings  *AccountSettingsInfo
+	DNSSettings      *DNSSettings
+	CustomZoneDomain string
+
+	AllPeers          []*nbpeer.Peer
+	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]*routerTypes.NetworkRouter
+	NetworkResources []*resourceTypes.NetworkResource
+
+	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 []*nbpeer.Peer
+
+	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]*nbpeer.Peer, 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]*nbpeer.Peer, 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]*Group, 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] = &Group{
+			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,268 @@
+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")
+)
+
+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
+	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/policyrule.go

@@ -0,0 +1,225 @@
+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
+}
+
+// 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,
+	}
+	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 {
+		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
+}