[management] validate the proxy cluster an agent network bootstraps onto

The agent network gateway service is synthesised as private: agents reach
it over the WireGuard tunnel and are authorised by ValidateTunnelPeer
against the enabled policies' source groups, and its only target is the
cluster itself with DirectUpstream. Only a proxy running embedded in a
netbird client can serve that, which management already reports per
cluster as the `private` capability.

CreateSettings accepted any hostname as proxy_address, so a labeled
bootstrap could pin the account to a cluster that cannot serve its
gateway — another account's BYOP cluster, or one whose proxies are all
centralised. The endpoint assigned at bootstrap is immutable, so the
account is then stuck with a dead gateway until someone deletes and
re-bootstraps the settings row.

Validate the cluster before allocating an endpoint beneath it: a cluster
whose live proxies have reported their capabilities must be one the
account may route through and must be private-capable. A cluster nothing
is connected to is left alone, so claiming an address ahead of the
proxy's first connection keeps working — the same address-first order the
dedicated (self-addressed) path documents, and the one the e2e suite and
self-hosted setups follow.

The e2e coverage drives the real thing: one combined server and two
proxies in the same cluster — a centralised one that makes the cluster
live but unusable, then an embedded one that makes it usable — so both
the refusal and the acceptance are exercised against the same account and
cluster address, with the domains endpoint (the list the dashboard picks
from) as the barrier between starting a proxy and asserting on it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

management/internals/modules/agentnetwork/handlers/handlers_test.go

@@ -9,6 +9,7 @@ import (
 	"runtime"
 	"strings"
 	"testing"
+	"time"
 
 	"go.uber.org/mock/gomock"
 	"github.com/gorilla/mux"
@@ -17,6 +18,7 @@ import (
 
 	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork"
 	agentNetworkTypes "github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	rpproxy "github.com/netbirdio/netbird/management/internals/modules/reverseproxy/proxy"
 	"github.com/netbirdio/netbird/management/server/account"
 	nbcontext "github.com/netbirdio/netbird/management/server/context"
 	"github.com/netbirdio/netbird/management/server/permissions"
@@ -29,6 +31,9 @@ import (
 const (
 	testAccountID = "acc-1"
 	testUserID    = "user-bob"
+	// testClusterAddress is the shared proxy cluster the settings tests pin
+	// their gateway to; the fixture seeds a connected embedded proxy for it.
+	testClusterAddress = "eu.proxy.netbird.io"
 )
 
 // agentNetworkHandlerFixture builds a real agentnetwork.Manager with
@@ -75,6 +80,12 @@ func newAgentNetworkHandlerFixture(t *testing.T) *agentNetworkHandlerFixture {
 	manager := agentnetwork.NewManager(st, perms, accounts, nil)
 	h := &handler{manager: manager}
 
+	// The labeled bootstrap validates its proxy_address against the live
+	// clusters, so seed the shared cluster these tests pin to as a real,
+	// private-capable one — the wire-shape assertions then run through the
+	// validated path rather than the "nothing connected yet" carve-out.
+	seedSharedEmbeddedCluster(t, st, testClusterAddress)
+
 	router := mux.NewRouter()
 	router.HandleFunc("/agent-network/providers", h.createProvider).Methods("POST")
 	router.HandleFunc("/agent-network/providers/{providerId}", h.getProvider).Methods("GET")
@@ -268,3 +279,21 @@ func TestConsumptionHandler_PopulatedAccountListsRows(t *testing.T) {
 	assert.Equal(t, groupRow.WindowStartUtc, userRow.WindowStartUtc,
 		"rows recorded in the same window must share the aligned window_start_utc")
 }
+
+// seedSharedEmbeddedCluster registers a connected, NetBird-operated proxy
+// running embedded in a netbird client (the `private` capability) so
+// clusterAddr is a cluster any account may pin its agent-network gateway to.
+func seedSharedEmbeddedCluster(t *testing.T, st store.Store, clusterAddr string) {
+	t.Helper()
+	private := true
+	now := time.Now().UTC()
+	require.NoError(t, st.SaveProxy(context.Background(), &rpproxy.Proxy{
+		ID:             "shared-proxy-" + clusterAddr,
+		SessionID:      "shared-session",
+		ClusterAddress: clusterAddr,
+		LastSeen:       now,
+		ConnectedAt:    &now,
+		Status:         rpproxy.StatusConnected,
+		Capabilities:   rpproxy.Capabilities{Private: &private},
+	}), "seeding the shared proxy cluster must succeed")
+}

management/internals/modules/agentnetwork/manager.go

@@ -860,18 +860,108 @@ func (m *managerImpl) bootstrapSelfAddressed(ctx context.Context, settings *type
 	return nil
 }
 
+// validateGatewayCluster rejects a labeled bootstrap pinned to a cluster that
+// cannot serve the account's gateway.
+//
+// The synthesised gateway service is unconditionally private
+// (buildAccountService): agents reach it over the WireGuard tunnel and are
+// authorised by ValidateTunnelPeer against the policies' source groups, and
+// its single target is the cluster itself with DirectUpstream. Only a proxy
+// running embedded in a netbird client (`netbird proxy`) can serve that — a
+// centralised proxy has no tunnel identity to authenticate against and no
+// WireGuard endpoint to be reached on. Management reports that per cluster as
+// the `private` capability, the same flag the dashboard renders as
+// supports_private when it gates NetBird-only services.
+//
+// Without this check the bootstrap happily pins to any hostname the caller
+// names, including a cluster the account cannot use or one with no embedded
+// proxy — and the endpoint it allocates is immutable, so the account is left
+// with a dead gateway that only a DeleteSettings/re-bootstrap can undo.
+//
+// Only a cluster management can actually judge is rejected: one whose live
+// proxies have reported their capabilities. A cluster nothing is connected to
+// is left alone, because pinning ahead of the proxy's first connection is a
+// legitimate order (the dedicated path claims an address the same way, before
+// any proxy declares it).
+func (m *managerImpl) validateGatewayCluster(ctx context.Context, accountID, clusterAddr string) error {
+	private := m.store.GetClusterSupportsPrivate(ctx, clusterAddr)
+	if private == nil {
+		// No live proxy in the cluster reported its capabilities: either
+		// nothing is connected there yet, or the proxies predate capability
+		// reporting. Nothing to judge — let the pin through.
+		return nil
+	}
+
+	available, err := m.accountClusterAddresses(ctx, accountID)
+	if err != nil {
+		return err
+	}
+	if !slices.Contains(available, clusterAddr) {
+		// Live, but not a cluster this account may route through: another
+		// account's BYOP cluster. Its proxies filter foreign mappings out on
+		// delivery, so the pin would be dead on arrival.
+		return status.Errorf(status.InvalidArgument,
+			"proxy cluster %s is not available to this account", clusterAddr)
+	}
+
+	if !*private {
+		return status.Errorf(status.InvalidArgument,
+			"proxy cluster %s cannot serve the agent network gateway: the gateway is reachable only from connected peers, "+
+				"which needs at least one connected embedded proxy (netbird proxy) in the cluster", clusterAddr)
+	}
+	return nil
+}
+
+// accountClusterAddresses lists the active proxy cluster addresses the account
+// may pin its gateway to: its own (BYOP) clusters plus the shared ones. This
+// mirrors the free-domain allow list the dashboard offers as cluster choices,
+// so the API accepts exactly what the UI can present. Addresses are stored as
+// the proxy declared them; they are normalised here so the comparison against
+// a normalised proxy_address is not defeated by case.
+func (m *managerImpl) accountClusterAddresses(ctx context.Context, accountID string) ([]string, error) {
+	byop, err := m.store.GetActiveProxyClusterAddressesForAccount(ctx, accountID)
+	if err != nil {
+		return nil, fmt.Errorf("list account proxy clusters: %w", err)
+	}
+	shared, err := m.store.GetActiveProxyClusterAddresses(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("list shared proxy clusters: %w", err)
+	}
+
+	addresses := make([]string, 0, len(byop)+len(shared))
+	for _, addr := range slices.Concat(byop, shared) {
+		normalized, err := types.NormalizeHostname(addr)
+		if err != nil {
+			// A cluster address the proxy declared in a shape we cannot
+			// normalise is not one an endpoint can be allocated beneath.
+			log.WithContext(ctx).Debugf("skipping unusable proxy cluster address %q: %s", addr, err)
+			continue
+		}
+		addresses = append(addresses, normalized)
+	}
+	return addresses, nil
+}
+
 // bootstrapLabeled allocates a labeled endpoint one label beneath the given
 // cluster address: Domain = <label>.<proxyAddress>, served by whichever proxy
 // declares the parent. Labels are adjective-noun tuples; a candidate is
 // checked by read and the domain unique index stays the authority, so a
 // concurrent allocation of the same tuple surfaces as a unique violation and
 // another tuple is drawn.
+//
+// Unlike the self-addressed path this pins to a cluster that must already
+// exist, so the cluster is validated before an endpoint is allocated beneath
+// it.
 func (m *managerImpl) bootstrapLabeled(ctx context.Context, settings *types.Settings, proxyAddress string) error {
 	parent, err := types.NormalizeHostname(proxyAddress)
 	if err != nil {
 		return status.Errorf(status.InvalidArgument, "invalid proxy_address: %s", err)
 	}
 
+	if err := m.validateGatewayCluster(ctx, settings.AccountID, parent); err != nil {
+		return err
+	}
+
 	for attempt := 1; attempt <= maxDomainAllocationAttempts; attempt++ {
 		m.labelRngMu.Lock()
 		label := labelgen.PickTuple(m.labelRng)

management/internals/modules/agentnetwork/settings_bootstrap_test.go

@@ -5,12 +5,14 @@ import (
 	"runtime"
 	"strings"
 	"testing"
+	"time"
 
 	"go.uber.org/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/internals/modules/reverseproxy/proxy"
 	"github.com/netbirdio/netbird/management/server/account"
 	"github.com/netbirdio/netbird/management/server/permissions"
 	"github.com/netbirdio/netbird/management/server/permissions/modules"
@@ -64,6 +66,33 @@ func (f *bootstrapFixture) createSettings(ctx context.Context, accountID, userID
 	return f.manager.CreateSettings(ctx, userID, types.DefaultSettings(accountID), proxyAddress, endpoint)
 }
 
+// seedProxy registers a connected proxy in clusterAddr so the labeled
+// bootstrap path has a real cluster to validate against. accountID empty
+// makes it a shared (NetBird-operated) cluster; private mirrors the
+// capability an embedded `netbird proxy` reports, nil an unreported one.
+func (f *bootstrapFixture) seedProxy(t *testing.T, proxyID, accountID, clusterAddr string, private *bool) {
+	t.Helper()
+	p := &proxy.Proxy{
+		ID:             proxyID,
+		ClusterAddress: clusterAddr,
+		Status:         proxy.StatusConnected,
+		LastSeen:       time.Now().UTC(),
+		Capabilities:   proxy.Capabilities{Private: private},
+	}
+	if accountID != "" {
+		p.AccountID = &accountID
+	}
+	require.NoError(t, f.store.SaveProxy(context.Background(), p), "seeding a proxy must succeed")
+}
+
+// seedEmbeddedCluster is the common case: a shared cluster with a connected
+// embedded proxy, which is what the labeled bootstrap requires.
+func (f *bootstrapFixture) seedEmbeddedCluster(t *testing.T, clusterAddr string) {
+	t.Helper()
+	private := true
+	f.seedProxy(t, "proxy-"+clusterAddr, "", clusterAddr, &private)
+}
+
 // TestCreateSettingsRequiresPermission pins the gate: bootstrap assigns the
 // account's immutable endpoint, a settings write requiring the settings
 // Create permission — and a denial leaves no row behind.
@@ -88,6 +117,7 @@ func TestCreateSettingsRequiresPermission(t *testing.T) {
 func TestCreateSettingsLabeled(t *testing.T) {
 	ctx := context.Background()
 	f := newBootstrapFixture(t)
+	f.seedEmbeddedCluster(t, "cluster1.example.com")
 	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
 
 	created, err := f.createSettings(ctx, "account1", "user1", "Cluster1.Example.com", "")
@@ -161,6 +191,7 @@ func TestCreateSettingsIdentityFieldValidation(t *testing.T) {
 func TestCreateSettingsConflictsOnSecondBootstrap(t *testing.T) {
 	ctx := context.Background()
 	f := newBootstrapFixture(t)
+	f.seedEmbeddedCluster(t, "cluster1.example.com")
 	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
 
 	first, err := f.createSettings(ctx, "account1", "user1", "cluster1.example.com", "")
@@ -223,3 +254,91 @@ func TestCreateProviderHasNoSettingsSideEffects(t *testing.T) {
 	_, err = f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
 	assert.Error(t, err, "provider create must not conjure a settings row")
 }
+
+// TestCreateSettingsAllowsUnjudgeableCluster pins the address-first carve-out:
+// a cluster nothing is connected to yet cannot be judged, so the pin is
+// allowed — the same order the dedicated path documents (claim the address,
+// connect the proxy after). A stale cluster whose proxies have aged out of
+// the active window reads the same way.
+func TestCreateSettingsAllowsUnjudgeableCluster(t *testing.T) {
+	ctx := context.Background()
+	private := true
+
+	cases := map[string]func(f *bootstrapFixture, t *testing.T){
+		"no proxy at all": func(*bootstrapFixture, *testing.T) {},
+		"heartbeat aged out": func(f *bootstrapFixture, t *testing.T) {
+			require.NoError(t, f.store.SaveProxy(ctx, &proxy.Proxy{
+				ID:             "proxy-stale",
+				ClusterAddress: "future.example.com",
+				Status:         proxy.StatusConnected,
+				LastSeen:       time.Now().UTC().Add(-time.Hour),
+				Capabilities:   proxy.Capabilities{Private: &private},
+			}), "seeding a stale proxy must succeed")
+		},
+	}
+	for name, seed := range cases {
+		t.Run(name, func(t *testing.T) {
+			f := newBootstrapFixture(t)
+			seed(f, t)
+			f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+
+			created, err := f.createSettings(ctx, "account1", "user1", "future.example.com", "")
+			require.NoError(t, err, "a cluster with nothing live in it must stay pinnable")
+			assert.Equal(t, "future.example.com", created.ProxyAddress)
+		})
+	}
+}
+
+// TestCreateSettingsRequiresPrivateCluster pins the capability gate: the
+// synthesised gateway service is always private, so a live cluster whose
+// proxies are not embedded in a netbird client cannot serve it and must not
+// become the account's immutable endpoint.
+func TestCreateSettingsRequiresPrivateCluster(t *testing.T) {
+	ctx := context.Background()
+	f := newBootstrapFixture(t)
+	notPrivate := false
+	f.seedProxy(t, "proxy1", "", "central.example.com", &notPrivate)
+	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+
+	_, err := f.createSettings(ctx, "account1", "user1", "central.example.com", "")
+	require.Error(t, err, "a cluster without an embedded proxy must be rejected")
+	var sErr *status.Error
+	require.ErrorAs(t, err, &sErr)
+	assert.Equal(t, status.InvalidArgument, sErr.Type(), "rejection must be a validation error")
+	assert.Contains(t, err.Error(), "embedded proxy", "the error must name what the cluster is missing")
+
+	_, err = f.store.GetAgentNetworkSettings(ctx, store.LockingStrengthNone, "account1")
+	assert.Error(t, err, "no row may be left behind by a rejected bootstrap")
+}
+
+// TestCreateSettingsRejectsForeignCluster pins tenant isolation on the pin: an
+// account-owned (BYOP) cluster belongs to the account that runs it, and is not
+// a cluster another account may hang its gateway beneath — even though it is
+// private-capable.
+func TestCreateSettingsRejectsForeignCluster(t *testing.T) {
+	ctx := context.Background()
+	f := newBootstrapFixture(t)
+	private := true
+	f.seedProxy(t, "proxy1", "account2", "byop.account2.example.com", &private)
+	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+
+	_, err := f.createSettings(ctx, "account1", "user1", "byop.account2.example.com", "")
+	require.Error(t, err, "another account's BYOP cluster must be rejected")
+	var sErr *status.Error
+	require.ErrorAs(t, err, &sErr)
+	assert.Equal(t, status.InvalidArgument, sErr.Type(), "rejection must be a validation error")
+}
+
+// TestCreateSettingsAcceptsOwnPrivateCluster pins the BYOP happy path: the
+// account's own cluster with a connected embedded proxy is a valid pin.
+func TestCreateSettingsAcceptsOwnPrivateCluster(t *testing.T) {
+	ctx := context.Background()
+	f := newBootstrapFixture(t)
+	private := true
+	f.seedProxy(t, "proxy1", "account1", "byop.account1.example.com", &private)
+	f.expectPermission("account1", "user1", modules.AgentNetworkSettings, operations.Create, true)
+
+	created, err := f.createSettings(ctx, "account1", "user1", "byop.account1.example.com", "")
+	require.NoError(t, err, "the account's own private cluster must be accepted")
+	assert.Equal(t, "byop.account1.example.com", created.ProxyAddress)
+}