[management] fix handling of empty network map during decode and encode (#6987)

## Describe your changes

Agent Network gates providers, policies, guardrails, budgets, usage,
access logs, and settings behind the single `agent_network` permission
module, so access is all-or-nothing: a future delegated role cannot be
scoped to a subset of the area (for example usage-only visibility).

This introduces dotted submodules (`agent_network.providers`,
`.policies`, `.guardrails`, `.budgets`, `.usage`, `.logs`, `.settings`)
and resolves grants with a cascade: exact module first, then its parent,
then the role's `AutoAllowNew` default. The agent network manager now
validates each operation against its matching submodule. `usage`
(aggregated counters, overview) is deliberately separate from `logs`
(request-level entries, which can contain captured prompts).

No role definitions change. No built-in role carries an explicit
`agent_network` entry, so every role resolves the submodules exactly as
it resolved the parent module before — pinned by a test that compares
each built-in role's answer on every submodule against its answer on
`agent_network`. Role additions that use these submodules come
separately.

.goreleaser_ui.yaml

@@ -93,7 +93,9 @@ nfpms:
       - src: client/ui/build/appicon.png
         dst: /usr/share/pixmaps/netbird.png
     dependencies:
-      - netbird
+      - netbird (>= 0.75.0)
+      - libgtk-4-1 (>= 4.14)
+      - libwebkitgtk-6.0-4
 
   - maintainer: Netbird <dev@netbird.io>
     description: Netbird client UI.
@@ -114,7 +116,9 @@ nfpms:
       - src: client/ui/build/appicon.png
         dst: /usr/share/pixmaps/netbird.png
     dependencies:
-      - netbird
+      - netbird >= 0.75.0
+      - (gtk4 >= 4.14 or libgtk-4-1 >= 4.14)
+      - (webkitgtk6.0 or libwebkitgtk-6_0-4)
 
     rpm:
       signature:

client/internal/dns/interface_index.go

@@ -0,0 +1,15 @@
+package dns
+
+import (
+	"fmt"
+	"net"
+)
+
+func getInterfaceIndex(interfaceName string) (int, error) {
+	iface, err := net.InterfaceByName(interfaceName)
+	if err != nil {
+		return 0, fmt.Errorf("lookup interface %q: %w", interfaceName, err)
+	}
+
+	return iface.Index, nil
+}

client/internal/dns/interface_index_test.go

@@ -0,0 +1,35 @@
+package dns
+
+import (
+	"net"
+	"testing"
+)
+
+func TestGetInterfaceIndexExisting(t *testing.T) {
+	interfaces, err := net.Interfaces()
+	if err != nil {
+		t.Fatalf("list network interfaces: %v", err)
+	}
+	if len(interfaces) == 0 {
+		t.Fatal("expected at least one network interface")
+	}
+
+	iface := interfaces[0]
+	index, err := getInterfaceIndex(iface.Name)
+	if err != nil {
+		t.Fatalf("look up existing interface %q: %v", iface.Name, err)
+	}
+	if index != iface.Index {
+		t.Fatalf("expected interface index %d, got %d", iface.Index, index)
+	}
+}
+
+func TestGetInterfaceIndexMissing(t *testing.T) {
+	index, err := getInterfaceIndex("netbird-interface-that-does-not-exist")
+	if index != 0 {
+		t.Fatalf("expected missing interface index to be 0, got %d", index)
+	}
+	if err == nil {
+		t.Fatal("expected missing interface lookup to return an error")
+	}
+}

client/internal/dns/upstream_ios.go

@@ -130,8 +130,3 @@ func GetClientPrivate(iface privateClientIface, upstreamIP netip.Addr, dialTimeo
 	}
 	return client, nil
 }
-
-func getInterfaceIndex(interfaceName string) (int, error) {
-	iface, err := net.InterfaceByName(interfaceName)
-	return iface.Index, err
-}

client/ios/NetBirdSDK/client.go

@@ -158,13 +158,19 @@ func (c *Client) Run(fd int32, interfaceName string, envList *EnvList) error {
 	defer c.ctxCancel()
 	c.ctxCancelLock.Unlock()
 
-	auth := NewAuthWithConfig(ctx, cfg)
-	err = auth.LoginSync()
-	if err != nil {
-		return err
-	}
-
-	log.Infof("Auth successful")
+	// No login pre-flight here. The engine's own loginToManagement (connect.go) performs
+	// the authoritative Login immediately before the first Sync, so a LoginSync() call at
+	// this point only duplicated it — costing two extra Login RPCs (IsLoginRequired +
+	// Login) on every engine start, since IsLoginRequired is itself a full Login RPC.
+	//
+	// Auth failures still reach the caller through the engine path: loginToManagement
+	// returns PermissionDenied, which marks the shared status recorder
+	// (MarkManagementDisconnected) and fires ClientStop → onDisconnected, where
+	// IsLoginRequiredCached() reports login-required. The error is also returned out of Run().
+	//
+	// A pre-flight was also actively harmful when the server is unreachable: its 2-minute
+	// backoff blocked the start and then reported "login required" for what was really a
+	// timeout. The engine instead keeps retrying and recovers when the server returns.
 	// todo do not throw error in case of cancelled context
 	ctx = internal.CtxInitState(ctx)
 	c.onHostDnsFn = func([]string) {}

client/ios/NetBirdSDK/login.go

@@ -222,17 +222,36 @@ func (a *Auth) Login(resultListener ErrListener, urlOpener URLOpener, forceDevic
 // LoginWithDeviceName performs interactive login with device authentication support
 // The deviceName parameter allows specifying a custom device name (required for tvOS)
 func (a *Auth) LoginWithDeviceName(resultListener ErrListener, urlOpener URLOpener, forceDeviceAuth bool, deviceName string) {
+	a.startLogin(resultListener, urlOpener, forceDeviceAuth, deviceName, false)
+}
+
+// LoginInteractive performs the same interactive login as LoginWithDeviceName but skips the
+// IsLoginRequired() pre-flight and goes straight to the browser / device-code flow.
+//
+// IsLoginRequired() is itself a full Login RPC against the management server, so when the
+// caller has ALREADY established that login is required it is a pure duplicate. On iOS the
+// main app decides to show the browser based on its own isLoginRequired() check and then
+// calls straight into this method, so re-asking the server would add another Login RPC to
+// every interactive login.
+//
+// Use LoginWithDeviceName when the auth state is unknown and a silent (browser-less) login
+// must still be possible; use this when the browser is going to be shown regardless.
+func (a *Auth) LoginInteractive(resultListener ErrListener, urlOpener URLOpener, forceDeviceAuth bool, deviceName string) {
+	a.startLogin(resultListener, urlOpener, forceDeviceAuth, deviceName, true)
+}
+
+func (a *Auth) startLogin(resultListener ErrListener, urlOpener URLOpener, forceDeviceAuth bool, deviceName string, skipLoginCheck bool) {
 	if resultListener == nil {
-		log.Errorf("LoginWithDeviceName: resultListener is nil")
+		log.Errorf("startLogin: resultListener is nil")
 		return
 	}
 	if urlOpener == nil {
-		log.Errorf("LoginWithDeviceName: urlOpener is nil")
+		log.Errorf("startLogin: urlOpener is nil")
 		resultListener.OnError(fmt.Errorf("urlOpener is nil"))
 		return
 	}
 	go func() {
-		err := a.login(urlOpener, forceDeviceAuth, deviceName)
+		err := a.login(urlOpener, forceDeviceAuth, deviceName, skipLoginCheck)
 		if err != nil {
 			resultListener.OnError(err)
 		} else {
@@ -241,7 +260,7 @@ func (a *Auth) LoginWithDeviceName(resultListener ErrListener, urlOpener URLOpen
 	}()
 }
 
-func (a *Auth) login(urlOpener URLOpener, forceDeviceAuth bool, deviceName string) error {
+func (a *Auth) login(urlOpener URLOpener, forceDeviceAuth bool, deviceName string, skipLoginCheck bool) error {
 	// Create context with device name if provided
 	ctx := a.ctx
 	if deviceName != "" {
@@ -255,10 +274,13 @@ func (a *Auth) login(urlOpener URLOpener, forceDeviceAuth bool, deviceName strin
 	}
 	defer authClient.Close()
 
-	// check if we need to generate JWT token
-	needsLogin, err := authClient.IsLoginRequired(ctx)
-	if err != nil {
-		return fmt.Errorf("failed to check login requirement: %v", err)
+	// check if we need to generate JWT token (skipped when the caller already knows)
+	needsLogin := true
+	if !skipLoginCheck {
+		needsLogin, err = authClient.IsLoginRequired(ctx)
+		if err != nil {
+			return fmt.Errorf("failed to check login requirement: %v", err)
+		}
 	}
 
 	jwtToken := ""

client/ui/build/linux/nfpm/nfpm.yaml

@@ -26,17 +26,17 @@ contents:
 
 # Default dependencies for the GTK4 + WebKitGTK 6.0 stack (Ubuntu 24.04+ / Debian 13+)
 depends:
-  - libgtk-4-1
+  - libgtk-4-1 (>= 4.14)
   - libwebkitgtk-6.0-4
   - xdg-utils
 
 # Distribution-specific overrides for different package formats
 overrides:
-  # RPM packages for Fedora / RHEL / AlmaLinux / Rocky Linux
+  # RPM packages for Fedora / RHEL / AlmaLinux / Rocky Linux / openSUSE
   rpm:
     depends:
-      - gtk4
-      - webkitgtk6.0
+      - (gtk4 >= 4.14 or libgtk-4-1 >= 4.14)
+      - (webkitgtk6.0 or libwebkitgtk-6_0-4)
       - xdg-utils
 
   # Arch Linux packages

management/internals/modules/agentnetwork/manager.go

@@ -157,14 +157,14 @@ func NewManager(
 }
 
 func (m *managerImpl) GetAllProviders(ctx context.Context, accountID, userID string) ([]*types.Provider, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkProviders, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.GetAccountAgentNetworkProviders(ctx, store.LockingStrengthNone, accountID)
 }
 
 func (m *managerImpl) GetProvider(ctx context.Context, accountID, userID, providerID string) (*types.Provider, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkProviders, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.GetAgentNetworkProviderByID(ctx, store.LockingStrengthNone, accountID, providerID)
@@ -175,9 +175,14 @@ func (m *managerImpl) GetProvider(ctx context.Context, accountID, userID, provid
 // been created yet; otherwise it is ignored (the cluster is pinned on
 // Settings and every provider in the account routes through it).
 func (m *managerImpl) CreateProvider(ctx context.Context, userID string, provider *types.Provider, bootstrapCluster string) (*types.Provider, error) {
-	if err := m.requirePermission(ctx, provider.AccountID, userID, operations.Create); err != nil {
+	if err := m.requirePermission(ctx, provider.AccountID, userID, modules.AgentNetworkProviders, operations.Create); err != nil {
 		return nil, err
 	}
+	if strings.TrimSpace(bootstrapCluster) != "" {
+		if err := m.requireSettingsBootstrapPermission(ctx, provider.AccountID, userID); err != nil {
+			return nil, err
+		}
+	}
 
 	// An empty api_key would silently produce a synthesised service
 	// that 401s on every upstream request. Surface the misconfiguration
@@ -218,7 +223,7 @@ func (m *managerImpl) CreateProvider(ctx context.Context, userID string, provide
 }
 
 func (m *managerImpl) UpdateProvider(ctx context.Context, userID string, provider *types.Provider) (*types.Provider, error) {
-	if err := m.requirePermission(ctx, provider.AccountID, userID, operations.Update); err != nil {
+	if err := m.requirePermission(ctx, provider.AccountID, userID, modules.AgentNetworkProviders, operations.Update); err != nil {
 		return nil, err
 	}
 
@@ -257,7 +262,7 @@ func (m *managerImpl) UpdateProvider(ctx context.Context, userID string, provide
 }
 
 func (m *managerImpl) DeleteProvider(ctx context.Context, accountID, userID, providerID string) error {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Delete); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkProviders, operations.Delete); err != nil {
 		return err
 	}
 
@@ -306,21 +311,21 @@ func pluralize(n int, singular, plural string) string {
 }
 
 func (m *managerImpl) GetAllPolicies(ctx context.Context, accountID, userID string) ([]*types.Policy, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkPolicies, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.GetAccountAgentNetworkPolicies(ctx, store.LockingStrengthNone, accountID)
 }
 
 func (m *managerImpl) GetPolicy(ctx context.Context, accountID, userID, policyID string) (*types.Policy, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkPolicies, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.GetAgentNetworkPolicyByID(ctx, store.LockingStrengthNone, accountID, policyID)
 }
 
 func (m *managerImpl) CreatePolicy(ctx context.Context, userID string, policy *types.Policy) (*types.Policy, error) {
-	if err := m.requirePermission(ctx, policy.AccountID, userID, operations.Create); err != nil {
+	if err := m.requirePermission(ctx, policy.AccountID, userID, modules.AgentNetworkPolicies, operations.Create); err != nil {
 		return nil, err
 	}
 
@@ -346,7 +351,7 @@ func (m *managerImpl) CreatePolicy(ctx context.Context, userID string, policy *t
 }
 
 func (m *managerImpl) UpdatePolicy(ctx context.Context, userID string, policy *types.Policy) (*types.Policy, error) {
-	if err := m.requirePermission(ctx, policy.AccountID, userID, operations.Update); err != nil {
+	if err := m.requirePermission(ctx, policy.AccountID, userID, modules.AgentNetworkPolicies, operations.Update); err != nil {
 		return nil, err
 	}
 
@@ -373,7 +378,7 @@ func (m *managerImpl) UpdatePolicy(ctx context.Context, userID string, policy *t
 }
 
 func (m *managerImpl) DeletePolicy(ctx context.Context, accountID, userID, policyID string) error {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Delete); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkPolicies, operations.Delete); err != nil {
 		return err
 	}
 
@@ -393,21 +398,21 @@ func (m *managerImpl) DeletePolicy(ctx context.Context, accountID, userID, polic
 }
 
 func (m *managerImpl) GetAllGuardrails(ctx context.Context, accountID, userID string) ([]*types.Guardrail, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkGuardrails, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.GetAccountAgentNetworkGuardrails(ctx, store.LockingStrengthNone, accountID)
 }
 
 func (m *managerImpl) GetGuardrail(ctx context.Context, accountID, userID, guardrailID string) (*types.Guardrail, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkGuardrails, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.GetAgentNetworkGuardrailByID(ctx, store.LockingStrengthNone, accountID, guardrailID)
 }
 
 func (m *managerImpl) CreateGuardrail(ctx context.Context, userID string, guardrail *types.Guardrail) (*types.Guardrail, error) {
-	if err := m.requirePermission(ctx, guardrail.AccountID, userID, operations.Create); err != nil {
+	if err := m.requirePermission(ctx, guardrail.AccountID, userID, modules.AgentNetworkGuardrails, operations.Create); err != nil {
 		return nil, err
 	}
 
@@ -429,7 +434,7 @@ func (m *managerImpl) CreateGuardrail(ctx context.Context, userID string, guardr
 }
 
 func (m *managerImpl) UpdateGuardrail(ctx context.Context, userID string, guardrail *types.Guardrail) (*types.Guardrail, error) {
-	if err := m.requirePermission(ctx, guardrail.AccountID, userID, operations.Update); err != nil {
+	if err := m.requirePermission(ctx, guardrail.AccountID, userID, modules.AgentNetworkGuardrails, operations.Update); err != nil {
 		return nil, err
 	}
 
@@ -452,7 +457,7 @@ func (m *managerImpl) UpdateGuardrail(ctx context.Context, userID string, guardr
 }
 
 func (m *managerImpl) DeleteGuardrail(ctx context.Context, accountID, userID, guardrailID string) error {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Delete); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkGuardrails, operations.Delete); err != nil {
 		return err
 	}
 
@@ -473,7 +478,7 @@ func (m *managerImpl) DeleteGuardrail(ctx context.Context, accountID, userID, gu
 
 // GetAllBudgetRules returns every account-level budget rule for the account.
 func (m *managerImpl) GetAllBudgetRules(ctx context.Context, accountID, userID string) ([]*types.AccountBudgetRule, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkBudgets, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.GetAccountAgentNetworkBudgetRules(ctx, store.LockingStrengthNone, accountID)
@@ -481,7 +486,7 @@ func (m *managerImpl) GetAllBudgetRules(ctx context.Context, accountID, userID s
 
 // GetBudgetRule returns a single account-level budget rule.
 func (m *managerImpl) GetBudgetRule(ctx context.Context, accountID, userID, ruleID string) (*types.AccountBudgetRule, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkBudgets, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.GetAgentNetworkBudgetRuleByID(ctx, store.LockingStrengthNone, accountID, ruleID)
@@ -491,7 +496,7 @@ func (m *managerImpl) GetBudgetRule(ctx context.Context, accountID, userID, rule
 // enforced at request time (CheckLLMPolicyLimits), not baked into the synth
 // proxy config, so no reconcile is needed.
 func (m *managerImpl) CreateBudgetRule(ctx context.Context, userID string, rule *types.AccountBudgetRule) (*types.AccountBudgetRule, error) {
-	if err := m.requirePermission(ctx, rule.AccountID, userID, operations.Create); err != nil {
+	if err := m.requirePermission(ctx, rule.AccountID, userID, modules.AgentNetworkBudgets, operations.Create); err != nil {
 		return nil, err
 	}
 
@@ -513,7 +518,7 @@ func (m *managerImpl) CreateBudgetRule(ctx context.Context, userID string, rule
 
 // UpdateBudgetRule updates an existing account-level budget rule.
 func (m *managerImpl) UpdateBudgetRule(ctx context.Context, userID string, rule *types.AccountBudgetRule) (*types.AccountBudgetRule, error) {
-	if err := m.requirePermission(ctx, rule.AccountID, userID, operations.Update); err != nil {
+	if err := m.requirePermission(ctx, rule.AccountID, userID, modules.AgentNetworkBudgets, operations.Update); err != nil {
 		return nil, err
 	}
 
@@ -536,7 +541,7 @@ func (m *managerImpl) UpdateBudgetRule(ctx context.Context, userID string, rule
 
 // DeleteBudgetRule removes an account-level budget rule.
 func (m *managerImpl) DeleteBudgetRule(ctx context.Context, accountID, userID, ruleID string) error {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Delete); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkBudgets, operations.Delete); err != nil {
 		return err
 	}
 
@@ -561,7 +566,7 @@ func (m *managerImpl) DeleteBudgetRule(ctx context.Context, accountID, userID, r
 // gating, access-log emission), a reconcile is triggered so the proxy and peer
 // network maps converge on the new state.
 func (m *managerImpl) UpdateSettings(ctx context.Context, userID string, settings *types.Settings) (*types.Settings, error) {
-	if err := m.requirePermission(ctx, settings.AccountID, userID, operations.Update); err != nil {
+	if err := m.requirePermission(ctx, settings.AccountID, userID, modules.AgentNetworkSettings, operations.Update); err != nil {
 		return nil, err
 	}
 
@@ -615,7 +620,7 @@ func (m *managerImpl) validateProviderRefs(ctx context.Context, accountID string
 // Returns the underlying status.NotFound when no row has been
 // bootstrapped yet (i.e. the account has no providers).
 func (m *managerImpl) GetSettings(ctx context.Context, accountID, userID string) (*types.Settings, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkSettings, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, accountID)
@@ -627,6 +632,22 @@ func (m *managerImpl) GetSettings(ctx context.Context, accountID, userID string)
 // the subdomain is picked from the curated wordlist avoiding
 // collisions on the same cluster. Idempotent: if a row already exists
 // it is returned untouched and the hint is ignored.
+// requireSettingsBootstrapPermission gates the one-time settings bootstrap a
+// first provider create performs. Pinning the account's cluster and subdomain
+// is a settings write, so it needs the settings permission on top of the
+// provider one. No-op once the settings row exists.
+func (m *managerImpl) requireSettingsBootstrapPermission(ctx context.Context, accountID, userID string) error {
+	_, err := m.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, accountID)
+	if err == nil {
+		return nil
+	}
+	var sErr *status.Error
+	if !errors.As(err, &sErr) || sErr.Type() != status.NotFound {
+		return fmt.Errorf("get agent network settings: %w", err)
+	}
+	return m.requirePermission(ctx, accountID, userID, modules.AgentNetworkSettings, operations.Create)
+}
+
 func (m *managerImpl) bootstrapSettingsIfNeeded(ctx context.Context, accountID, providerCluster string) (*types.Settings, error) {
 	if accountID == "" {
 		return nil, fmt.Errorf("bootstrap settings: account id is required")
@@ -685,7 +706,7 @@ func (m *managerImpl) bootstrapSettingsIfNeeded(ctx context.Context, accountID,
 // counter view; permission gate is the same Read role that gates
 // every other agent-network surface.
 func (m *managerImpl) ListConsumption(ctx context.Context, accountID, userID string) ([]*types.Consumption, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkUsage, operations.Read); err != nil {
 		return nil, err
 	}
 	return m.store.ListAgentNetworkConsumption(ctx, store.LockingStrengthNone, accountID)
@@ -694,7 +715,7 @@ func (m *managerImpl) ListConsumption(ctx context.Context, accountID, userID str
 // ListAccessLogs returns a paginated, server-side-filtered page of
 // agent-network access logs plus the total count matching the filter.
 func (m *managerImpl) ListAccessLogs(ctx context.Context, accountID, userID string, filter types.AgentNetworkAccessLogFilter) ([]*types.AgentNetworkAccessLog, int64, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkLogs, operations.Read); err != nil {
 		return nil, 0, err
 	}
 	return m.store.GetAgentNetworkAccessLogs(ctx, store.LockingStrengthNone, accountID, filter)
@@ -704,7 +725,7 @@ func (m *managerImpl) ListAccessLogs(ctx context.Context, accountID, userID stri
 // agent-network access logs grouped by session, plus the total number of
 // sessions matching the filter.
 func (m *managerImpl) ListAccessLogSessions(ctx context.Context, accountID, userID string, filter types.AgentNetworkAccessLogFilter) ([]*types.AgentNetworkAccessLogSession, int64, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkLogs, operations.Read); err != nil {
 		return nil, 0, err
 	}
 	return m.store.GetAgentNetworkAccessLogSessions(ctx, store.LockingStrengthNone, accountID, filter)
@@ -713,7 +734,7 @@ func (m *managerImpl) ListAccessLogSessions(ctx context.Context, accountID, user
 // GetUsageOverview returns the filtered usage rows aggregated into time buckets
 // at the requested granularity, oldest-first.
 func (m *managerImpl) GetUsageOverview(ctx context.Context, accountID, userID string, filter types.AgentNetworkAccessLogFilter, granularity types.UsageGranularity) ([]*types.AgentNetworkUsageBucket, error) {
-	if err := m.requirePermission(ctx, accountID, userID, operations.Read); err != nil {
+	if err := m.requirePermission(ctx, accountID, userID, modules.AgentNetworkUsage, operations.Read); err != nil {
 		return nil, err
 	}
 	rows, err := m.store.GetAgentNetworkUsageRows(ctx, store.LockingStrengthNone, accountID, filter)
@@ -787,8 +808,8 @@ func (m *managerImpl) RecordConsumption(ctx context.Context, accountID string, k
 	return m.store.IncrementAgentNetworkConsumption(ctx, accountID, kind, dimID, windowSeconds, windowStart, tokensIn, tokensOut, costUSD)
 }
 
-func (m *managerImpl) requirePermission(ctx context.Context, accountID, userID string, op operations.Operation) error {
-	ok, _, err := m.permissionsManager.ValidateUserPermissions(ctx, accountID, userID, modules.AgentNetwork, op)
+func (m *managerImpl) requirePermission(ctx context.Context, accountID, userID string, module modules.Module, op operations.Operation) error {
+	ok, _, err := m.permissionsManager.ValidateUserPermissions(ctx, accountID, userID, module, op)
 	if err != nil {
 		return status.NewPermissionValidationError(err)
 	}

management/internals/modules/agentnetwork/provider_bootstrap_test.go

@@ -0,0 +1,134 @@
+package agentnetwork
+
+import (
+	"context"
+	"runtime"
+	"testing"
+
+	"github.com/golang/mock/gomock"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	"github.com/netbirdio/netbird/management/server/account"
+	"github.com/netbirdio/netbird/management/server/permissions"
+	"github.com/netbirdio/netbird/management/server/permissions/modules"
+	"github.com/netbirdio/netbird/management/server/permissions/operations"
+	"github.com/netbirdio/netbird/management/server/store"
+	nbtypes "github.com/netbirdio/netbird/management/server/types"
+	"github.com/netbirdio/netbird/shared/management/status"
+)
+
+// bootstrapFixture wires a real sqlite store to a gomock permissions manager
+// so tests can grant the provider permission while denying (or never
+// expecting) the settings one.
+type bootstrapFixture struct {
+	manager Manager
+	store   store.Store
+	perms   *permissions.MockManager
+}
+
+func newBootstrapFixture(t *testing.T) *bootstrapFixture {
+	t.Helper()
+	if runtime.GOOS == "windows" {
+		t.Skip("sqlite store not properly supported on Windows yet")
+	}
+	t.Setenv("NETBIRD_STORE_ENGINE", string(nbtypes.SqliteStoreEngine))
+
+	st, cleanUp, err := store.NewTestStoreFromSQL(context.Background(), "", t.TempDir())
+	require.NoError(t, err, "test store setup must succeed")
+	t.Cleanup(cleanUp)
+
+	ctrl := gomock.NewController(t)
+	perms := permissions.NewMockManager(ctrl)
+
+	accounts := account.NewMockManager(ctrl)
+	accounts.EXPECT().StoreEvent(gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any()).AnyTimes()
+	accounts.EXPECT().UpdateAccountPeers(gomock.Any(), gomock.Any(), gomock.Any()).AnyTimes()
+	accounts.EXPECT().BufferUpdateAccountPeers(gomock.Any(), gomock.Any(), gomock.Any()).AnyTimes()
+
+	return &bootstrapFixture{
+		manager: NewManager(st, perms, accounts, nil),
+		store:   st,
+		perms:   perms,
+	}
+}
+
+func (f *bootstrapFixture) expectPermission(accountID, userID string, module modules.Module, op operations.Operation, allowed bool) {
+	f.perms.EXPECT().
+		ValidateUserPermissions(gomock.Any(), accountID, userID, module, op).
+		Return(allowed, context.Background(), nil)
+}
+
+func newBootstrapProvider(accountID string) *types.Provider {
+	p := types.NewProvider(accountID)
+	p.Name = "openai"
+	p.UpstreamURL = "https://api.openai.com"
+	p.APIKey = "sk-test"
+	p.Enabled = true
+	return p
+}
+
+// TestCreateProviderBootstrapRequiresSettingsPermission pins the gate on the
+// one-time settings bootstrap: creating the first provider with a
+// bootstrap_cluster pins the account's cluster and subdomain, which is a
+// settings write and must not ride on the providers permission alone.
+func TestCreateProviderBootstrapRequiresSettingsPermission(t *testing.T) {
+	ctx := context.Background()
+
+	t.Run("denied without settings permission", func(t *testing.T) {
+		f := newBootstrapFixture(t)
+		f.expectPermission("account1", "user1", modules.AgentNetworkProviders, operations.Create, true)
+		f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, false)
+
+		_, err := f.manager.CreateProvider(ctx, "user1", newBootstrapProvider("account1"), "cluster1.example.com")
+		require.Error(t, err, "bootstrap without settings permission must fail")
+		var sErr *status.Error
+		require.ErrorAs(t, err, &sErr)
+		assert.Equal(t, status.PermissionDenied, sErr.Type(), "denial should surface as permission denied")
+
+		providers, err := f.store.GetAccountAgentNetworkProviders(ctx, store.LockingStrengthNone, "account1")
+		require.NoError(t, err)
+		assert.Empty(t, providers, "provider must not be persisted when bootstrap is denied")
+		_, err = f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
+		assert.Error(t, err, "settings row must not be created when bootstrap is denied")
+	})
+
+	t.Run("allowed with settings permission", func(t *testing.T) {
+		f := newBootstrapFixture(t)
+		f.expectPermission("account1", "user1", modules.AgentNetworkProviders, operations.Create, true)
+		f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+
+		created, err := f.manager.CreateProvider(ctx, "user1", newBootstrapProvider("account1"), "cluster1.example.com")
+		require.NoError(t, err, "bootstrap with both permissions must succeed")
+		require.NotNil(t, created)
+
+		settings, err := f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
+		require.NoError(t, err, "bootstrap must create the settings row")
+		assert.Equal(t, "cluster1.example.com", settings.Cluster, "settings should pin the bootstrap cluster")
+	})
+
+	t.Run("existing settings need no settings permission", func(t *testing.T) {
+		f := newBootstrapFixture(t)
+		require.NoError(t, f.store.SaveAgentNetworkSettings(ctx, &types.Settings{
+			AccountID: "account1",
+			Cluster:   "cluster1.example.com",
+			Subdomain: "existing",
+		}), "pre-existing settings row setup must succeed")
+
+		// Only the providers permission may be consulted: gomock fails the
+		// test on any unexpected settings-permission call.
+		f.expectPermission("account1", "user1", modules.AgentNetworkProviders, operations.Create, true)
+
+		_, err := f.manager.CreateProvider(ctx, "user1", newBootstrapProvider("account1"), "cluster1.example.com")
+		require.NoError(t, err, "create with existing settings must not require the settings permission")
+	})
+
+	t.Run("no bootstrap cluster needs no settings permission", func(t *testing.T) {
+		f := newBootstrapFixture(t)
+		f.expectPermission("account1", "user1", modules.AgentNetworkProviders, operations.Create, true)
+
+		_, err := f.manager.CreateProvider(ctx, "user1", newBootstrapProvider("account1"), "")
+		require.NoError(t, err, "create without bootstrap must not require the settings permission")
+	})
+}

management/internals/server/boot.go

@@ -24,13 +24,13 @@ import (
 
 	"github.com/netbirdio/netbird/encryption"
 	"github.com/netbirdio/netbird/formatter/hook"
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork"
 	"github.com/netbirdio/netbird/management/internals/modules/reverseproxy/accesslogs"
 	accesslogsmanager "github.com/netbirdio/netbird/management/internals/modules/reverseproxy/accesslogs/manager"
 	rpservice "github.com/netbirdio/netbird/management/internals/modules/reverseproxy/service"
 	nbgrpc "github.com/netbirdio/netbird/management/internals/shared/grpc"
 	"github.com/netbirdio/netbird/management/server/activity"
 	activitystore "github.com/netbirdio/netbird/management/server/activity/store"
-	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork"
 	nbcache "github.com/netbirdio/netbird/management/server/cache"
 	nbContext "github.com/netbirdio/netbird/management/server/context"
 	nbhttp "github.com/netbirdio/netbird/management/server/http"
@@ -184,6 +184,10 @@ func (s *BaseServer) GRPCServer() *grpc.Server {
 			grpc.ChainStreamInterceptor(realip.StreamServerInterceptorOpts(realipOpts...), streamInterceptor, proxyStream),
 		}
 
+		// Append interceptors contributed by registered gRPC extensions. These
+		// run after the built-in chain (ChainUnaryInterceptor is additive).
+		gRPCOpts = appendExtensionInterceptors(gRPCOpts, s.grpcExtensions)
+
 		if s.Config.HttpConfig.LetsEncryptDomain != "" {
 			certManager, err := encryption.CreateCertManager(s.Config.Datadir, s.Config.HttpConfig.LetsEncryptDomain)
 			if err != nil {
@@ -215,6 +219,9 @@ func (s *BaseServer) GRPCServer() *grpc.Server {
 		mgmtProto.RegisterProxyServiceServer(gRPCAPIHandler, s.ReverseProxyGRPCServer())
 		log.Info("ProxyService registered on gRPC server")
 
+		// Register services contributed by external modules via the extension seam.
+		registerExtensions(gRPCAPIHandler, s.grpcExtensions)
+
 		return gRPCAPIHandler
 	})
 }

management/internals/server/grpc_extension.go

@@ -0,0 +1,74 @@
+package server
+
+import (
+	"context"
+
+	"google.golang.org/grpc"
+)
+
+// GRPCExtension bundles an external module's contribution to the management
+// gRPC server: the registration of one or more services onto the shared
+// grpc.Server, any server-wide interceptors those services require, and an
+// optional shutdown hook. It is a generic extension point with no knowledge of
+// any specific service.
+type GRPCExtension struct {
+	// Register is invoked with the shared grpc.Server (as a ServiceRegistrar)
+	// after the built-in services are registered. It may register any number of
+	// services. May be nil.
+	Register func(grpc.ServiceRegistrar)
+	// UnaryInterceptors are appended to the server's unary interceptor chain,
+	// running after the built-in interceptors. May be empty.
+	UnaryInterceptors []grpc.UnaryServerInterceptor
+	// StreamInterceptors are appended to the server's stream interceptor chain,
+	// running after the built-in interceptors. May be empty.
+	StreamInterceptors []grpc.StreamServerInterceptor
+	// Shutdown, if non-nil, is called once during Stop() with the context
+	// governing server shutdown, which carries a deadline. The hook MUST
+	// return promptly and MUST abandon its work once that context is
+	// cancelled or expires: it runs before the rest of Stop()'s cleanup
+	// (store, event store, embedded IdP) and before Stop() itself checks the
+	// context's deadline, so a hook that ignores the context will delay all
+	// of that cleanup and prevent Stop() from returning on time. May be nil.
+	Shutdown func(ctx context.Context)
+}
+
+// RegisterGRPCExtension registers a gRPC extension. Call before the gRPC server
+// is first built (i.e. before Start); registrations after that have no effect.
+func (s *BaseServer) RegisterGRPCExtension(ext GRPCExtension) {
+	s.grpcExtensions = append(s.grpcExtensions, ext)
+}
+
+// appendExtensionInterceptors appends each extension's interceptors to the gRPC
+// server options as additional chained interceptors. grpc.ChainUnaryInterceptor
+// and grpc.ChainStreamInterceptor are additive, so the returned options run the
+// extension interceptors after any interceptors already present in opts.
+func appendExtensionInterceptors(opts []grpc.ServerOption, exts []GRPCExtension) []grpc.ServerOption {
+	for _, ext := range exts {
+		if len(ext.UnaryInterceptors) > 0 {
+			opts = append(opts, grpc.ChainUnaryInterceptor(ext.UnaryInterceptors...))
+		}
+		if len(ext.StreamInterceptors) > 0 {
+			opts = append(opts, grpc.ChainStreamInterceptor(ext.StreamInterceptors...))
+		}
+	}
+	return opts
+}
+
+// registerExtensions registers each extension's services onto reg.
+func registerExtensions(reg grpc.ServiceRegistrar, exts []GRPCExtension) {
+	for _, ext := range exts {
+		if ext.Register != nil {
+			ext.Register(reg)
+		}
+	}
+}
+
+// runExtensionShutdownHooks calls each extension's shutdown hook, if set,
+// passing ctx through so hooks can honor its deadline/cancellation.
+func runExtensionShutdownHooks(ctx context.Context, exts []GRPCExtension) {
+	for _, ext := range exts {
+		if ext.Shutdown != nil {
+			ext.Shutdown(ctx)
+		}
+	}
+}

management/internals/server/grpc_extension_test.go

@@ -0,0 +1,160 @@
+package server
+
+import (
+	"context"
+	"net"
+	"sync/atomic"
+	"testing"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/insecure"
+	"google.golang.org/grpc/health"
+	healthgrpc "google.golang.org/grpc/health/grpc_health_v1"
+	"google.golang.org/grpc/test/bufconn"
+)
+
+// Test that an extension's interceptors and service registration are actually
+// wired onto a real in-process gRPC server via the helpers, and that shutdown
+// hooks run. This validates the load-bearing assumption that
+// grpc.ChainUnaryInterceptor is additive (extension interceptors run in
+// addition to any base chain).
+func TestGRPCExtensionAppliedToServer(t *testing.T) {
+	var unaryCalls atomic.Int32
+	var streamShutdownCalled atomic.Bool
+
+	ext := GRPCExtension{
+		Register: func(reg grpc.ServiceRegistrar) {
+			healthgrpc.RegisterHealthServer(reg, health.NewServer())
+		},
+		UnaryInterceptors: []grpc.UnaryServerInterceptor{
+			func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
+				unaryCalls.Add(1)
+				return handler(ctx, req)
+			},
+		},
+		Shutdown: func(ctx context.Context) { streamShutdownCalled.Store(true) },
+	}
+	exts := []GRPCExtension{ext}
+
+	// Base options mimic GRPCServer(): a pre-existing chain the extension appends to.
+	var baseUnaryCalls atomic.Int32
+	opts := []grpc.ServerOption{
+		grpc.ChainUnaryInterceptor(func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
+			baseUnaryCalls.Add(1)
+			return handler(ctx, req)
+		}),
+	}
+	opts = appendExtensionInterceptors(opts, exts)
+
+	srv := grpc.NewServer(opts...)
+	registerExtensions(srv, exts)
+
+	lis := bufconn.Listen(1024 * 1024)
+	go func() { _ = srv.Serve(lis) }()
+	t.Cleanup(srv.Stop)
+
+	conn, err := grpc.NewClient("passthrough:///bufnet",
+		grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) { return lis.DialContext(ctx) }),
+		grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = conn.Close() })
+
+	_, err = healthgrpc.NewHealthClient(conn).Check(context.Background(), &healthgrpc.HealthCheckRequest{})
+	if err != nil {
+		t.Fatalf("health check via extension-registered service failed: %v", err)
+	}
+	if baseUnaryCalls.Load() != 1 {
+		t.Errorf("base interceptor calls = %d, want 1 (base chain must be preserved)", baseUnaryCalls.Load())
+	}
+	if unaryCalls.Load() != 1 {
+		t.Errorf("extension interceptor calls = %d, want 1", unaryCalls.Load())
+	}
+
+	runExtensionShutdownHooks(context.Background(), exts)
+	if !streamShutdownCalled.Load() {
+		t.Error("extension shutdown hook was not called")
+	}
+}
+
+// TestGRPCExtensionShutdownHookReceivesCallerContext asserts that each hook receives
+// a non-nil context and that it is the very same context the caller passed
+// in, so hooks can rely on values/deadlines placed on it by Stop().
+func TestGRPCExtensionShutdownHookReceivesCallerContext(t *testing.T) {
+	type sentinelKey struct{}
+	want := "shutdown-ctx-sentinel"
+	ctx := context.WithValue(context.Background(), sentinelKey{}, want)
+
+	var called bool
+	ext := GRPCExtension{
+		Shutdown: func(hookCtx context.Context) {
+			called = true
+			if hookCtx == nil {
+				t.Fatal("hook received a nil context")
+			}
+			got, _ := hookCtx.Value(sentinelKey{}).(string)
+			if got != want {
+				t.Errorf("hook context sentinel = %q, want %q (not the caller's context)", got, want)
+			}
+		},
+	}
+
+	runExtensionShutdownHooks(ctx, []GRPCExtension{ext})
+	if !called {
+		t.Fatal("shutdown hook was not called")
+	}
+}
+
+// TestGRPCExtensionShutdownHookObservesCancellation documents, by test, that
+// hooks can honor cancellation/deadlines: a hook given an already-cancelled
+// context must see ctx.Err() != nil and a closed Done() channel.
+func TestGRPCExtensionShutdownHookObservesCancellation(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	var called bool
+	ext := GRPCExtension{
+		Shutdown: func(hookCtx context.Context) {
+			called = true
+			if hookCtx.Err() == nil {
+				t.Error("hook context Err() = nil, want non-nil for a cancelled context")
+			}
+			select {
+			case <-hookCtx.Done():
+			default:
+				t.Error("hook context Done() channel is not closed for a cancelled context")
+			}
+		},
+	}
+
+	runExtensionShutdownHooks(ctx, []GRPCExtension{ext})
+	if !called {
+		t.Fatal("shutdown hook was not called")
+	}
+}
+
+// TestGRPCExtensionShutdownHookNilSkipped asserts that an extension
+// with a nil Shutdown hook is skipped without panicking, and that hooks for
+// other extensions still run.
+func TestGRPCExtensionShutdownHookNilSkipped(t *testing.T) {
+	var called atomic.Bool
+	exts := []GRPCExtension{
+		{Shutdown: nil},
+		{Shutdown: func(context.Context) { called.Store(true) }},
+	}
+
+	runExtensionShutdownHooks(context.Background(), exts)
+	if !called.Load() {
+		t.Error("shutdown hook for non-nil extension was not called")
+	}
+}
+
+func TestRegisterGRPCExtensionAccumulates(t *testing.T) {
+	s := &BaseServer{}
+	s.RegisterGRPCExtension(GRPCExtension{})
+	s.RegisterGRPCExtension(GRPCExtension{})
+	if len(s.grpcExtensions) != 2 {
+		t.Fatalf("grpcExtensions len = %d, want 2", len(s.grpcExtensions))
+	}
+}

management/internals/server/server.go

@@ -68,6 +68,11 @@ type BaseServer struct {
 
 	proxyAuthClose func()
 
+	// grpcExtensions holds additional gRPC services, interceptors, and shutdown
+	// hooks registered by external modules via RegisterGRPCExtension. Populated
+	// during boot (single-threaded), consumed by GRPCServer() and Stop().
+	grpcExtensions []GRPCExtension
+
 	listener    net.Listener
 	certManager *autocert.Manager
 	update      *version.Update
@@ -257,6 +262,7 @@ func (s *BaseServer) Stop() error {
 		s.proxyAuthClose()
 		s.proxyAuthClose = nil
 	}
+	runExtensionShutdownHooks(ctx, s.grpcExtensions)
 	_ = s.Store().Close(ctx)
 	_ = s.EventStore().Close(ctx)
 	if s.update != nil {

management/internals/shared/grpc/components_encoder.go

@@ -61,6 +61,8 @@ func EncodeNetworkMapEnvelope(in ComponentsEnvelopeInput) *proto.NetworkMapEnvel
 		return &proto.NetworkMapEnvelope{
 			Payload: &proto.NetworkMapEnvelope_Full{
 				Full: &proto.NetworkMapComponentsFull{
+					Serial:     networkSerial(c.Network),
+					Network:    toAccountNetwork(c.Network),
 					PeerConfig: in.PeerConfig,
 					// components.Peers always contains the target peer
 					Peers:            []*proto.PeerCompact{toPeerCompact(c.Peers[c.PeerID])},

management/internals/shared/grpc/components_encoder_test.go

@@ -758,6 +758,9 @@ func TestEncodeNetworkMapEnvelope_NilComponentsGracefulDegrade(t *testing.T) {
 	assert.Equal(t, "netbird.cloud", full.DnsDomain)
 	assert.Len(t, full.Peers, 1)
 	assert.Empty(t, full.Policies)
+	require.NotNil(t, full.Network, "client runs Calculate() over the envelope and dereferences Network unconditionally; a nil here would crash the receiver")
+	assert.Equal(t, "net-empty", full.Network.Identifier)
+	assert.Equal(t, uint64(9), full.Serial)
 }
 
 func TestEncodeNetworkMapEnvelope_AccountSettingsAlwaysEmitted(t *testing.T) {
@@ -776,6 +779,12 @@ func TestEncodeNetworkMapEnvelope_AccountSettingsAlwaysEmitted(t *testing.T) {
 func emptyNetworkMapComponents() *types.NetworkMapComponents {
 	return types.EmptyNetworkMapComponents(
 		&types.NetworkMapComponents{
-			PeerID: "peer-id", Peers: map[string]*types.ComponentPeer{"peer-id": {}}},
+			PeerID: "peer-id", Peers: map[string]*types.ComponentPeer{"peer-id": {}},
+			Network: &types.Network{
+				Identifier: "net-empty",
+				Net:        net.IPNet{IP: net.IP{100, 64, 0, 0}, Mask: net.CIDRMask(10, 32)},
+				Serial:     9,
+			},
+		},
 	)
 }

management/server/permissions/manager.go

@@ -82,6 +82,9 @@ func (m *managerImpl) ValidateUserPermissions(
 	return m.ValidateRoleModuleAccess(ctx, accountID, role, module, operation), ctxEnriched, nil
 }
 
+// ValidateRoleModuleAccess resolves an operation against the role's explicit
+// grant for the module, then the grant for its parent module when the module
+// is a dotted submodule, and finally the role's AutoAllowNew default.
 func (m *managerImpl) ValidateRoleModuleAccess(
 	ctx context.Context,
 	accountID string,
@@ -89,7 +92,7 @@ func (m *managerImpl) ValidateRoleModuleAccess(
 	module modules.Module,
 	operation operations.Operation,
 ) bool {
-	if permissions, ok := role.Permissions[module]; ok {
+	if permissions, ok := lookupModulePermissions(role, module); ok {
 		if allowed, exists := permissions[operation]; exists {
 			return allowed
 		}
@@ -100,6 +103,21 @@ func (m *managerImpl) ValidateRoleModuleAccess(
 	return role.AutoAllowNew[operation]
 }
 
+// lookupModulePermissions returns the role's explicit permission set for the
+// module, falling back to the parent module's set for dotted submodules. The
+// second return reports whether any explicit set was found.
+func lookupModulePermissions(role roles.RolePermissions, module modules.Module) (map[operations.Operation]bool, bool) {
+	if permissions, ok := role.Permissions[module]; ok {
+		return permissions, true
+	}
+	if parent, hasParent := module.Parent(); hasParent {
+		if permissions, ok := role.Permissions[parent]; ok {
+			return permissions, true
+		}
+	}
+	return nil, false
+}
+
 func (m *managerImpl) ValidateAccountAccess(ctx context.Context, accountID string, user *types.User, allowOwnerAndAdmin bool) (context.Context, error) {
 	if user.AccountID != accountID {
 		return ctx, status.NewUserNotPartOfAccountError()
@@ -119,7 +137,7 @@ func (m *managerImpl) GetPermissionsByRole(ctx context.Context, role types.UserR
 	permissions := roles.Permissions{}
 
 	for k := range modules.All {
-		if rolePermissions, ok := roleMap.Permissions[k]; ok {
+		if rolePermissions, ok := lookupModulePermissions(roleMap, k); ok {
 			permissions[k] = rolePermissions
 			continue
 		}

management/server/permissions/manager_test.go

@@ -0,0 +1,139 @@
+package permissions
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/management/server/permissions/modules"
+	"github.com/netbirdio/netbird/management/server/permissions/operations"
+	"github.com/netbirdio/netbird/management/server/permissions/roles"
+	"github.com/netbirdio/netbird/management/server/types"
+)
+
+func TestValidateRoleModuleAccessSubmoduleCascade(t *testing.T) {
+	manager := NewManager(nil)
+	ctx := context.Background()
+
+	fullAccess := map[operations.Operation]bool{
+		operations.Read:   true,
+		operations.Create: true,
+		operations.Update: true,
+		operations.Delete: true,
+	}
+	readOnly := map[operations.Operation]bool{
+		operations.Read:   true,
+		operations.Create: false,
+		operations.Update: false,
+		operations.Delete: false,
+	}
+	denyAll := map[operations.Operation]bool{
+		operations.Read:   false,
+		operations.Create: false,
+		operations.Update: false,
+		operations.Delete: false,
+	}
+
+	t.Run("parent grant covers submodules", func(t *testing.T) {
+		role := roles.RolePermissions{
+			AutoAllowNew: denyAll,
+			Permissions:  roles.Permissions{modules.AgentNetwork: fullAccess},
+		}
+		assert.True(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetworkProviders, operations.Create),
+			"parent full grant should allow create on a submodule")
+		assert.True(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetworkLogs, operations.Read),
+			"parent full grant should allow read on a submodule")
+	})
+
+	t.Run("submodule grant does not leak to parent or siblings", func(t *testing.T) {
+		role := roles.RolePermissions{
+			AutoAllowNew: denyAll,
+			Permissions:  roles.Permissions{modules.AgentNetworkUsage: readOnly},
+		}
+		assert.True(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetworkUsage, operations.Read),
+			"explicit submodule read should be allowed")
+		assert.False(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetworkUsage, operations.Create),
+			"read-only submodule grant should not allow create")
+		assert.False(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetwork, operations.Read),
+			"submodule grant should not grant the parent module")
+		assert.False(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetworkProviders, operations.Read),
+			"submodule grant should not grant a sibling submodule")
+	})
+
+	t.Run("explicit submodule entry wins over parent grant", func(t *testing.T) {
+		role := roles.RolePermissions{
+			AutoAllowNew: denyAll,
+			Permissions: roles.Permissions{
+				modules.AgentNetwork:     fullAccess,
+				modules.AgentNetworkLogs: denyAll,
+			},
+		}
+		assert.False(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetworkLogs, operations.Read),
+			"explicit submodule deny should override the parent grant")
+		assert.True(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetworkUsage, operations.Read),
+			"sibling submodules should still resolve through the parent grant")
+	})
+
+	t.Run("auto allow applies when neither submodule nor parent is granted", func(t *testing.T) {
+		role := roles.RolePermissions{
+			AutoAllowNew: readOnly,
+		}
+		assert.True(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetworkProviders, operations.Read),
+			"auto-allow read should apply to submodules")
+		assert.False(t, manager.ValidateRoleModuleAccess(ctx, "account", role, modules.AgentNetworkProviders, operations.Delete),
+			"auto-allow should not grant unlisted operations")
+	})
+}
+
+// TestExistingRolesKeepAgentNetworkBehaviorOnSubmodules pins the behavior the
+// submodule split must not change: every built-in role resolves the new
+// submodules exactly as it resolved the agent_network module before.
+func TestExistingRolesKeepAgentNetworkBehaviorOnSubmodules(t *testing.T) {
+	manager := NewManager(nil)
+	ctx := context.Background()
+
+	submodules := []modules.Module{
+		modules.AgentNetworkProviders,
+		modules.AgentNetworkPolicies,
+		modules.AgentNetworkGuardrails,
+		modules.AgentNetworkBudgets,
+		modules.AgentNetworkUsage,
+		modules.AgentNetworkLogs,
+		modules.AgentNetworkSettings,
+	}
+	allOperations := []operations.Operation{operations.Read, operations.Create, operations.Update, operations.Delete}
+
+	for _, role := range []types.UserRole{types.UserRoleOwner, types.UserRoleAdmin, types.UserRoleAuditor, types.UserRoleNetworkAdmin, types.UserRoleUser} {
+		rolePermissions, ok := roles.RolesMap[role]
+		require.True(t, ok, "role %s must exist in RolesMap", role)
+
+		for _, sub := range submodules {
+			for _, op := range allOperations {
+				expected := manager.ValidateRoleModuleAccess(ctx, "account", rolePermissions, modules.AgentNetwork, op)
+				actual := manager.ValidateRoleModuleAccess(ctx, "account", rolePermissions, sub, op)
+				assert.Equal(t, expected, actual, "role %s: %s on %s should match the agent_network module", role, op, sub)
+			}
+		}
+	}
+}
+
+func TestGetPermissionsByRoleIncludesSubmodules(t *testing.T) {
+	manager := NewManager(nil)
+	ctx := context.Background()
+
+	permissions, err := manager.GetPermissionsByRole(ctx, types.UserRoleAuditor)
+	require.NoError(t, err, "auditor role must resolve")
+
+	usage, ok := permissions[modules.AgentNetworkUsage]
+	require.True(t, ok, "permissions map should contain the usage submodule")
+	assert.True(t, usage[operations.Read], "auditor should read the usage submodule")
+	assert.False(t, usage[operations.Update], "auditor should not update the usage submodule")
+
+	adminPermissions, err := manager.GetPermissionsByRole(ctx, types.UserRoleAdmin)
+	require.NoError(t, err, "admin role must resolve")
+	providers, ok := adminPermissions[modules.AgentNetworkProviders]
+	require.True(t, ok, "permissions map should contain the providers submodule")
+	assert.True(t, providers[operations.Delete], "admin should delete on the providers submodule")
+}

management/server/permissions/modules/module.go

@@ -1,5 +1,7 @@
 package modules
 
+import "strings"
+
 type Module string
 
 const (
@@ -20,6 +22,17 @@ const (
 	IdentityProviders Module = "identity_providers"
 	Services          Module = "services"
 	AgentNetwork      Module = "agent_network"
+
+	// Agent Network submodules. A role may grant one of these directly
+	// or grant the AgentNetwork parent, which covers all of them (see
+	// permissions.Manager cascade resolution).
+	AgentNetworkProviders  Module = "agent_network.providers"
+	AgentNetworkPolicies   Module = "agent_network.policies"
+	AgentNetworkGuardrails Module = "agent_network.guardrails"
+	AgentNetworkBudgets    Module = "agent_network.budgets"
+	AgentNetworkUsage      Module = "agent_network.usage"
+	AgentNetworkLogs       Module = "agent_network.logs"
+	AgentNetworkSettings   Module = "agent_network.settings"
 )
 
 var All = map[Module]struct{}{
@@ -40,4 +53,21 @@ var All = map[Module]struct{}{
 	IdentityProviders: {},
 	Services:          {},
 	AgentNetwork:      {},
+
+	AgentNetworkProviders:  {},
+	AgentNetworkPolicies:   {},
+	AgentNetworkGuardrails: {},
+	AgentNetworkBudgets:    {},
+	AgentNetworkUsage:      {},
+	AgentNetworkLogs:       {},
+	AgentNetworkSettings:   {},
+}
+
+// Parent returns the module owning a dotted submodule name and true, or the
+// module itself and false when it has no parent.
+func (m Module) Parent() (Module, bool) {
+	if i := strings.IndexByte(string(m), '.'); i > 0 {
+		return Module(string(m)[:i]), true
+	}
+	return m, false
 }

management/server/types/proxy_access_token.go

@@ -68,7 +68,7 @@ type ProxyAccessTokenGenerated struct {
 // CreateNewProxyAccessToken generates a new proxy access token.
 // Returns the token with hashed value stored and plain token for one-time display.
 func CreateNewProxyAccessToken(name string, expiresIn time.Duration, accountID *string, createdBy string) (*ProxyAccessTokenGenerated, error) {
-	hashedToken, plainToken, err := generateProxyToken()
+	hashedToken, plainToken, err := GenerateProxyToken()
 	if err != nil {
 		return nil, err
 	}
@@ -94,7 +94,10 @@ func CreateNewProxyAccessToken(name string, expiresIn time.Duration, accountID *
 	}, nil
 }
 
-func generateProxyToken() (HashedProxyToken, PlainProxyToken, error) {
+// GenerateProxyToken generates a new random proxy token, returning its SHA-256
+// hash (for storage) and the one-time plaintext. Exported so external modules
+// can mint tokens in the canonical proxy-token format.
+func GenerateProxyToken() (HashedProxyToken, PlainProxyToken, error) {
 	secret, err := b.Random(ProxyTokenSecretLength)
 	if err != nil {
 		return "", "", err

management/server/types/proxy_access_token_test.go

@@ -1,6 +1,7 @@
 package types
 
 import (
+	"strings"
 	"testing"
 	"time"
 
@@ -123,6 +124,22 @@ func TestCreateNewProxyAccessToken(t *testing.T) {
 	})
 }
 
+func TestGenerateProxyToken(t *testing.T) {
+	hashed, plain, err := GenerateProxyToken()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := plain.Validate(); err != nil {
+		t.Errorf("generated token failed Validate(): %v", err)
+	}
+	if plain.Hash() != hashed {
+		t.Error("returned hashed token does not match Hash(plain)")
+	}
+	if !strings.HasPrefix(string(plain), ProxyTokenPrefix) {
+		t.Errorf("token %q missing prefix %q", plain, ProxyTokenPrefix)
+	}
+}
+
 func TestProxyAccessToken_IsExpired(t *testing.T) {
 	past := time.Now().Add(-1 * time.Hour)
 	future := time.Now().Add(1 * time.Hour)

shared/management/networkmap/decode.go

@@ -228,15 +228,17 @@ func DecodeEnvelope(env *proto.NetworkMapEnvelope) (*types.NetworkMapComponents,
 	return c, nil
 }
 
+// decodeAccountNetwork never returns nil — Calculate() dereferences
+// c.Network unconditionally, and servers that predate the fix omit the field
+// entirely from the empty-components envelope.
 func decodeAccountNetwork(an *proto.AccountNetwork) *types.Network {
+	n := &types.Network{}
 	if an == nil {
-		return nil
-	}
-	n := &types.Network{
-		Identifier: an.Identifier,
-		Dns:        an.Dns,
-		Serial:     an.Serial,
+		return n
 	}
+	n.Identifier = an.Identifier
+	n.Dns = an.Dns
+	n.Serial = an.Serial
 	if an.NetCidr != "" {
 		if _, ipnet, err := net.ParseCIDR(an.NetCidr); err == nil && ipnet != nil {
 			n.Net = *ipnet

shared/management/networkmap/envelope_test.go

@@ -221,6 +221,66 @@ func TestEnvelopeRoundTrip_AllGroupShortCircuitParity(t *testing.T) {
 		"client-side Calculate must connect the same remote peers as the server")
 }
 
+// TestEnvelopeToNetworkMap_EmptyComponents covers the graceful-degrade path
+// the server takes for a peer that is missing from the account or absent from
+// the validated-peers map. The legacy server short-circuited before
+// Calculate() and shipped a NetworkMap carrying only the account Network; the
+// components path runs Calculate() on the client instead, so the envelope must
+// carry Network or the client panics dereferencing a nil *types.Network.
+func TestEnvelopeToNetworkMap_EmptyComponents(t *testing.T) {
+	localPeerKey := randomWgKey(t)
+	c := types.EmptyNetworkMapComponents(&types.NetworkMapComponents{
+		PeerID: "peer-A",
+		Network: &types.Network{
+			Identifier: "net-empty",
+			Net:        net.IPNet{IP: net.IP{100, 64, 0, 0}, Mask: net.CIDRMask(10, 32)},
+			Serial:     7,
+		},
+		Peers: map[string]*types.ComponentPeer{
+			"peer-A": {ID: "peer-A", Key: localPeerKey, IP: netip.AddrFrom4([4]byte{100, 64, 0, 1})},
+		},
+	})
+
+	envelope := mgmtgrpc.EncodeNetworkMapEnvelope(mgmtgrpc.ComponentsEnvelopeInput{
+		Components: c,
+		DNSDomain:  "netbird.cloud",
+	})
+	require.NotNil(t, envelope.GetFull().Network, "empty envelope must carry the account Network")
+
+	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 degrade gracefully on empty components")
+	require.Equal(t, uint64(7), result.NetworkMap.Serial)
+	require.Empty(t, result.NetworkMap.RemotePeers, "unvalidated peer connects to nobody")
+}
+
+// TestEnvelopeToNetworkMap_MissingNetwork simulates a server that omits
+// AccountNetwork from the envelope. Clients must degrade rather than panic, so
+// they survive talking to a management server that predates the encoder fix.
+func TestEnvelopeToNetworkMap_MissingNetwork(t *testing.T) {
+	c, localPeerKey := buildSmokeComponents(t)
+
+	envelope := mgmtgrpc.EncodeNetworkMapEnvelope(mgmtgrpc.ComponentsEnvelopeInput{
+		Components: c,
+		DNSDomain:  "netbird.cloud",
+	})
+	envelope.GetFull().Network = nil
+
+	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, "a missing AccountNetwork must not panic the client")
+	require.NotNil(t, result.Components.Network)
+	require.NotEmpty(t, result.NetworkMap.RemotePeers, "the rest of the snapshot stays usable")
+}
+
 // 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