Add tests

# Conflicts:
#	shared/relay/client/manager.go

client/android/client.go

@@ -247,6 +247,9 @@ func (c *Client) DebugBundle(platformFiles PlatformFiles, anonymize bool) (strin
 		deps.SyncResponse = resp
 
 		if e := cc.Engine(); e != nil {
+			deps.RefreshStatus = func() {
+				e.RunHealthProbes(context.Background(), true)
+			}
 			if cm := e.GetClientMetrics(); cm != nil {
 				deps.ClientMetrics = cm
 			}

client/iface/configurer/common.go

@@ -3,7 +3,6 @@ package configurer
 import (
 	"net"
 	"net/netip"
-	"time"
 
 	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
 )
@@ -20,43 +19,6 @@ func buildPresharedKeyConfig(peerKey wgtypes.Key, psk wgtypes.Key, updateOnly bo
 	}
 }
 
-// buildIdlePeerEndpointConfig creates a config that removes and re-creates a peer in a
-// single transaction with the given allowed IPs, endpoint and disabled keepalive.
-func buildIdlePeerEndpointConfig(peerKey wgtypes.Key, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) wgtypes.Config {
-	keepAlive := time.Duration(0)
-	return wgtypes.Config{
-		Peers: []wgtypes.PeerConfig{
-			{
-				PublicKey: peerKey,
-				Remove:    true,
-			},
-			{
-				PublicKey:                   peerKey,
-				AllowedIPs:                  prefixesToIPNets(allowedIPs),
-				Endpoint:                    endpoint,
-				PersistentKeepaliveInterval: &keepAlive,
-			},
-		},
-	}
-}
-
-// mergePrefixes returns the union of the two prefix lists, keeping the original order and
-// dropping duplicates.
-func mergePrefixes(current, base []netip.Prefix) []netip.Prefix {
-	merged := make([]netip.Prefix, 0, len(current)+len(base))
-	seen := make(map[netip.Prefix]struct{}, len(current)+len(base))
-	for _, group := range [][]netip.Prefix{current, base} {
-		for _, prefix := range group {
-			if _, ok := seen[prefix]; ok {
-				continue
-			}
-			seen[prefix] = struct{}{}
-			merged = append(merged, prefix)
-		}
-	}
-	return merged
-}
-
 func prefixesToIPNets(prefixes []netip.Prefix) []net.IPNet {
 	ipNets := make([]net.IPNet, len(prefixes))
 	for i, prefix := range prefixes {

client/iface/configurer/kernel_unix.go

@@ -3,7 +3,6 @@
 package configurer
 
 import (
-	"errors"
 	"fmt"
 	"net"
 	"net/netip"
@@ -146,39 +145,6 @@ func (c *KernelConfigurer) RemovePeer(peerKey string) error {
 	return nil
 }
 
-// IdlePeerEndpoint re-creates the peer pointing at the lazy wake endpoint, dropping
-// handshake state while preserving the peer's currently installed allowed IPs.
-func (c *KernelConfigurer) IdlePeerEndpoint(peerKey string, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) error {
-	peerKeyParsed, err := wgtypes.ParseKey(peerKey)
-	if err != nil {
-		return err
-	}
-
-	var current []netip.Prefix
-	existing, err := c.getPeer(c.deviceName, peerKey)
-	switch {
-	case errors.Is(err, ErrPeerNotFound):
-	case err != nil:
-		return fmt.Errorf("get peer: %w", err)
-	default:
-		for _, ipNet := range existing.AllowedIPs {
-			addr, ok := netip.AddrFromSlice(ipNet.IP)
-			if !ok {
-				log.Warnf("failed to convert allowed IP %s of peer %s", ipNet.String(), peerKey)
-				continue
-			}
-			ones, _ := ipNet.Mask.Size()
-			current = append(current, netip.PrefixFrom(addr.Unmap(), ones))
-		}
-	}
-
-	config := buildIdlePeerEndpointConfig(peerKeyParsed, mergePrefixes(current, allowedIPs), endpoint)
-	if err := c.configure(config); err != nil {
-		return fmt.Errorf(`received error "%w" while setting idle endpoint for peer %s on interface %s`, err, peerKey, c.deviceName)
-	}
-	return nil
-}
-
 func (c *KernelConfigurer) AddAllowedIP(peerKey string, allowedIP netip.Prefix) error {
 	ipNet := net.IPNet{
 		IP:   allowedIP.Addr().AsSlice(),

client/iface/configurer/usp.go

@@ -210,64 +210,6 @@ func (c *WGUSPConfigurer) RemovePeer(peerKey string) error {
 	return ipcErr
 }
 
-// IdlePeerEndpoint re-creates the peer pointing at the lazy wake endpoint, dropping
-// handshake state while preserving the peer's currently installed allowed IPs.
-func (c *WGUSPConfigurer) IdlePeerEndpoint(peerKey string, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) error {
-	peerKeyParsed, err := wgtypes.ParseKey(peerKey)
-	if err != nil {
-		return err
-	}
-
-	current, err := c.currentAllowedIPs(hex.EncodeToString(peerKeyParsed[:]))
-	if err != nil {
-		return fmt.Errorf("get current allowed IPs: %w", err)
-	}
-
-	config := buildIdlePeerEndpointConfig(peerKeyParsed, mergePrefixes(current, allowedIPs), endpoint)
-	if err := c.device.IpcSet(toWgUserspaceString(config)); err != nil {
-		return fmt.Errorf("set idle peer endpoint: %w", err)
-	}
-
-	if endpoint != nil {
-		addr, err := netip.ParseAddr(endpoint.IP.String())
-		if err != nil {
-			return fmt.Errorf("parse endpoint address: %w", err)
-		}
-		c.activityRecorder.UpsertAddress(peerKey, netip.AddrPortFrom(addr.Unmap(), uint16(endpoint.Port)))
-	}
-	return nil
-}
-
-// currentAllowedIPs returns the allowed IPs currently installed for the peer identified by
-// its hex-encoded public key. It returns an empty list when the peer does not exist.
-func (c *WGUSPConfigurer) currentAllowedIPs(hexKey string) ([]netip.Prefix, error) {
-	ipc, err := c.device.IpcGet()
-	if err != nil {
-		return nil, err
-	}
-
-	var prefixes []netip.Prefix
-	foundPeer := false
-	for _, line := range strings.Split(ipc, "\n") {
-		line = strings.TrimSpace(line)
-		if strings.HasPrefix(line, "public_key=") {
-			foundPeer = line == "public_key="+hexKey
-			continue
-		}
-		if !foundPeer || !strings.HasPrefix(line, "allowed_ip=") {
-			continue
-		}
-
-		prefix, err := netip.ParsePrefix(strings.TrimPrefix(line, "allowed_ip="))
-		if err != nil {
-			log.Warnf("failed to parse allowed IP %q: %v", line, err)
-			continue
-		}
-		prefixes = append(prefixes, prefix)
-	}
-	return prefixes, nil
-}
-
 func (c *WGUSPConfigurer) AddAllowedIP(peerKey string, allowedIP netip.Prefix) error {
 	ipNet := net.IPNet{
 		IP:   allowedIP.Addr().AsSlice(),

client/iface/configurer/usp_idle_test.go

@@ -1,158 +0,0 @@
-package configurer
-
-import (
-	"encoding/hex"
-	"net"
-	"net/netip"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-	wgconn "golang.zx2c4.com/wireguard/conn"
-	"golang.zx2c4.com/wireguard/device"
-	"golang.zx2c4.com/wireguard/tun/netstack"
-	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
-
-	"github.com/netbirdio/netbird/client/iface/bind"
-)
-
-// newTestConfigurer creates a configurer backed by an in-memory wireguard-go device.
-func newTestConfigurer(t *testing.T) *WGUSPConfigurer {
-	t.Helper()
-
-	tunDev, _, err := netstack.CreateNetTUN([]netip.Addr{netip.MustParseAddr("100.64.0.1")}, []netip.Addr{}, 1280)
-	require.NoError(t, err)
-
-	wgDev := device.NewDevice(tunDev, wgconn.NewDefaultBind(), device.NewLogger(device.LogLevelSilent, "[test] "))
-	t.Cleanup(wgDev.Close)
-
-	c := NewUSPConfigurerNoUAPI(wgDev, "utun-test", bind.NewActivityRecorder())
-
-	key, err := wgtypes.GeneratePrivateKey()
-	require.NoError(t, err)
-	require.NoError(t, c.ConfigureInterface(key.String(), 0))
-
-	return c
-}
-
-// peerAllowedIPs returns the allowed IPs currently installed for the given peer.
-func peerAllowedIPs(t *testing.T, c *WGUSPConfigurer, pubKey string) []string {
-	t.Helper()
-
-	var ips []string
-	for _, line := range peerIpcLines(t, c, pubKey) {
-		if strings.HasPrefix(line, "allowed_ip=") {
-			ips = append(ips, strings.TrimPrefix(line, "allowed_ip="))
-		}
-	}
-	return ips
-}
-
-// peerEndpoint returns the endpoint currently installed for the given peer.
-func peerEndpoint(t *testing.T, c *WGUSPConfigurer, pubKey string) string {
-	t.Helper()
-
-	for _, line := range peerIpcLines(t, c, pubKey) {
-		if strings.HasPrefix(line, "endpoint=") {
-			return strings.TrimPrefix(line, "endpoint=")
-		}
-	}
-	return ""
-}
-
-// peerIpcLines returns the uapi config lines belonging to the given peer.
-func peerIpcLines(t *testing.T, c *WGUSPConfigurer, pubKey string) []string {
-	t.Helper()
-
-	key, err := wgtypes.ParseKey(pubKey)
-	require.NoError(t, err)
-	hexKey := hex.EncodeToString(key[:])
-
-	ipc, err := c.device.IpcGet()
-	require.NoError(t, err)
-
-	var lines []string
-	inPeer := false
-	for _, line := range strings.Split(ipc, "\n") {
-		line = strings.TrimSpace(line)
-		if strings.HasPrefix(line, "public_key=") {
-			inPeer = line == "public_key="+hexKey
-			continue
-		}
-		if inPeer && line != "" {
-			lines = append(lines, line)
-		}
-	}
-	return lines
-}
-
-// TestUSPConfigurer_IdlePeerEndpointPreservesAllowedIPs verifies the invariant the lazy idle
-// transition relies on: IdlePeerEndpoint re-creates the peer (dropping handshake state via the
-// remove+add transaction) while keeping every installed allowed IP, including routed
-// prefixes added later by the route manager, and points the endpoint at the wake listener.
-func TestUSPConfigurer_IdlePeerEndpointPreservesAllowedIPs(t *testing.T) {
-	c := newTestConfigurer(t)
-
-	peerKey, err := wgtypes.GeneratePrivateKey()
-	require.NoError(t, err)
-	pubKey := peerKey.PublicKey().String()
-
-	overlay := netip.MustParsePrefix("100.64.0.5/32")
-	routed := netip.MustParsePrefix("10.99.0.0/24")
-
-	realEndpoint := &net.UDPAddr{IP: net.ParseIP("127.0.0.1"), Port: 51821}
-	require.NoError(t, c.UpdatePeer(pubKey, []netip.Prefix{overlay}, 25*time.Second, realEndpoint, nil))
-	require.NoError(t, c.AddAllowedIP(pubKey, routed))
-
-	ips := peerAllowedIPs(t, c, pubKey)
-	require.Contains(t, ips, overlay.String(), "overlay prefix must be installed before the idle endpoint swap")
-	require.Contains(t, ips, routed.String(), "routed prefix must be installed before the idle endpoint swap")
-
-	wakeEndpoint := &net.UDPAddr{IP: net.ParseIP("127.2.0.5"), Port: 17473}
-	require.NoError(t, c.IdlePeerEndpoint(pubKey, []netip.Prefix{overlay}, wakeEndpoint))
-
-	ips = peerAllowedIPs(t, c, pubKey)
-	assert.Contains(t, ips, routed.String(), "routed prefix must survive the idle endpoint swap")
-	assert.Contains(t, ips, overlay.String(), "overlay prefix must survive the idle endpoint swap")
-	assert.Equal(t, "127.2.0.5:17473", peerEndpoint(t, c, pubKey), "endpoint must point at the wake listener after the idle endpoint swap")
-}
-
-// TestUSPConfigurer_IdlePeerEndpointCreatesMissingPeer verifies the cold-start arm path: when the
-// peer does not exist yet (never connected), IdlePeerEndpoint creates it with the given base
-// allowed IPs and the wake endpoint.
-func TestUSPConfigurer_IdlePeerEndpointCreatesMissingPeer(t *testing.T) {
-	c := newTestConfigurer(t)
-
-	peerKey, err := wgtypes.GeneratePrivateKey()
-	require.NoError(t, err)
-	pubKey := peerKey.PublicKey().String()
-
-	overlay := netip.MustParsePrefix("100.64.0.5/32")
-	wakeEndpoint := &net.UDPAddr{IP: net.ParseIP("127.2.0.5"), Port: 17473}
-
-	require.NoError(t, c.IdlePeerEndpoint(pubKey, []netip.Prefix{overlay}, wakeEndpoint))
-
-	assert.Equal(t, []string{overlay.String()}, peerAllowedIPs(t, c, pubKey), "missing peer must be created with the base allowed IPs")
-	assert.Equal(t, "127.2.0.5:17473", peerEndpoint(t, c, pubKey), "missing peer must be created with the wake endpoint")
-}
-
-// TestUSPConfigurer_AddAllowedIPOnMissingPeerIsSilentNoOp documents the wireguard-go
-// behavior the removed-peer idle flow raced against: AddAllowedIP uses update_only,
-// which is a silent no-op when the peer does not exist. The idle transition must
-// therefore keep the WireGuard peer (Conn.Idle + IdlePeerEndpoint) instead of leaving a
-// window where the peer is absent.
-func TestUSPConfigurer_AddAllowedIPOnMissingPeerIsSilentNoOp(t *testing.T) {
-	c := newTestConfigurer(t)
-
-	peerKey, err := wgtypes.GeneratePrivateKey()
-	require.NoError(t, err)
-	pubKey := peerKey.PublicKey().String()
-
-	routed := netip.MustParsePrefix("10.99.0.0/24")
-
-	require.NoError(t, c.AddAllowedIP(pubKey, routed), "update-only on a missing peer must not return an error")
-
-	assert.Empty(t, peerIpcLines(t, c, pubKey), "update-only call must not create the peer")
-}

client/iface/device/interface.go

@@ -15,7 +15,6 @@ type WGConfigurer interface {
 	ConfigureInterface(privateKey string, port int) error
 	UpdatePeer(peerKey string, allowedIps []netip.Prefix, keepAlive time.Duration, endpoint *net.UDPAddr, preSharedKey *wgtypes.Key) error
 	RemovePeer(peerKey string) error
-	IdlePeerEndpoint(peerKey string, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) error
 	AddAllowedIP(peerKey string, allowedIP netip.Prefix) error
 	RemoveAllowedIP(peerKey string, allowedIP netip.Prefix) error
 	SetPresharedKey(peerKey string, psk wgtypes.Key, updateOnly bool) error

client/iface/iface.go

@@ -184,19 +184,6 @@ func (w *WGIface) RemovePeer(peerKey string) error {
 	return w.configurer.RemovePeer(peerKey)
 }
 
-// IdlePeerEndpoint re-creates the peer pointing at the lazy wake endpoint, dropping
-// handshake state while preserving the peer's currently installed allowed IPs.
-func (w *WGIface) IdlePeerEndpoint(peerKey string, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) error {
-	w.mu.Lock()
-	defer w.mu.Unlock()
-	if w.configurer == nil {
-		return ErrIfaceNotFound
-	}
-
-	log.Debugf("Resetting peer on interface %s: %s, endpoint %s", w.tun.DeviceName(), peerKey, endpoint)
-	return w.configurer.IdlePeerEndpoint(peerKey, allowedIPs, endpoint)
-}
-
 // AddAllowedIP adds a prefix to the allowed IPs list of peer
 func (w *WGIface) AddAllowedIP(peerKey string, allowedIP netip.Prefix) error {
 	w.mu.Lock()

client/internal/conn_mgr.go

@@ -228,7 +228,7 @@ func (e *ConnMgr) RemovePeerConn(peerKey string) {
 	if !ok {
 		return
 	}
-	defer conn.Close()
+	defer conn.Close(false)
 
 	if !e.isStartedWithLazyMgr() {
 		return

client/internal/engine.go

@@ -1778,7 +1778,7 @@ func (e *Engine) addNewPeer(peerConfig *mgmProto.RemotePeerConfig) error {
 	}
 
 	if exists := e.connMgr.AddPeerConn(e.ctx, peerKey, conn); exists {
-		conn.Close()
+		conn.Close(false)
 		return fmt.Errorf("peer already exists: %s", peerKey)
 	}
 

client/internal/engine_test.go

@@ -53,7 +53,6 @@ type MockWGIface struct {
 	UpdateAddrFunc             func(newAddr wgaddr.Address) error
 	UpdatePeerFunc             func(peerKey string, allowedIps []netip.Prefix, keepAlive time.Duration, endpoint *net.UDPAddr, preSharedKey *wgtypes.Key) error
 	RemovePeerFunc             func(peerKey string) error
-	IdlePeerEndpointFunc       func(peerKey string, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) error
 	AddAllowedIPFunc           func(peerKey string, allowedIP netip.Prefix) error
 	RemoveAllowedIPFunc        func(peerKey string, allowedIP netip.Prefix) error
 	CloseFunc                  func() error
@@ -125,13 +124,6 @@ func (m *MockWGIface) RemovePeer(peerKey string) error {
 	return m.RemovePeerFunc(peerKey)
 }
 
-func (m *MockWGIface) IdlePeerEndpoint(peerKey string, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) error {
-	if m.IdlePeerEndpointFunc == nil {
-		return nil
-	}
-	return m.IdlePeerEndpointFunc(peerKey, allowedIPs, endpoint)
-}
-
 func (m *MockWGIface) AddAllowedIP(peerKey string, allowedIP netip.Prefix) error {
 	return m.AddAllowedIPFunc(peerKey, allowedIP)
 }

client/internal/iface_common.go

@@ -32,7 +32,6 @@ type wgIfaceBase interface {
 	UpdatePeer(peerKey string, allowedIps []netip.Prefix, keepAlive time.Duration, endpoint *net.UDPAddr, preSharedKey *wgtypes.Key) error
 	RemoveEndpointAddress(key string) error
 	RemovePeer(peerKey string) error
-	IdlePeerEndpoint(peerKey string, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) error
 	AddAllowedIP(peerKey string, allowedIP netip.Prefix) error
 	RemoveAllowedIP(peerKey string, allowedIP netip.Prefix) error
 	Close() error

client/internal/lazyconn/activity/listener_bind.go

@@ -106,7 +106,7 @@ func (d *BindListener) setupLazyConn() error {
 		IP:   d.fakeIP.AsSlice(),
 		Port: lazyBindPort,
 	}
-	return d.wgIface.IdlePeerEndpoint(d.peerCfg.PublicKey, d.peerCfg.AllowedIPs, endpoint)
+	return d.wgIface.UpdatePeer(d.peerCfg.PublicKey, d.peerCfg.AllowedIPs, 0, endpoint, nil)
 }
 
 // ReadPackets blocks until activity is detected on the LazyConn or the listener is closed.

client/internal/lazyconn/activity/listener_bind_test.go

@@ -9,6 +9,7 @@ import (
 	log "github.com/sirupsen/logrus"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
 
 	"github.com/netbirdio/netbird/client/iface/device"
 	"github.com/netbirdio/netbird/client/iface/wgaddr"
@@ -44,7 +45,7 @@ type MockWGIfaceBind struct {
 	endpointMgr *mockEndpointManager
 }
 
-func (m *MockWGIfaceBind) IdlePeerEndpoint(string, []netip.Prefix, *net.UDPAddr) error {
+func (m *MockWGIfaceBind) UpdatePeer(string, []netip.Prefix, time.Duration, *net.UDPAddr, *wgtypes.Key) error {
 	return nil
 }
 

client/internal/lazyconn/activity/listener_udp.go

@@ -101,7 +101,7 @@ func (d *UDPListener) Close() {
 
 func (d *UDPListener) createEndpoint() error {
 	d.peerCfg.Log.Debugf("creating lazy endpoint: %s", d.endpoint.String())
-	return d.wgIface.IdlePeerEndpoint(d.peerCfg.PublicKey, d.peerCfg.AllowedIPs, d.endpoint)
+	return d.wgIface.UpdatePeer(d.peerCfg.PublicKey, d.peerCfg.AllowedIPs, 0, d.endpoint, nil)
 }
 
 func (d *UDPListener) newConn() (*net.UDPConn, error) {

client/internal/lazyconn/activity/manager.go

@@ -5,8 +5,10 @@ import (
 	"net"
 	"net/netip"
 	"sync"
+	"time"
 
 	log "github.com/sirupsen/logrus"
+	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
 
 	"github.com/netbirdio/netbird/client/iface/wgaddr"
 	"github.com/netbirdio/netbird/client/internal/lazyconn"
@@ -28,7 +30,7 @@ type Event struct {
 }
 
 type WgInterface interface {
-	IdlePeerEndpoint(peerKey string, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) error
+	UpdatePeer(peerKey string, allowedIps []netip.Prefix, keepAlive time.Duration, endpoint *net.UDPAddr, preSharedKey *wgtypes.Key) error
 	IsUserspaceBind() bool
 	Address() wgaddr.Address
 	MTU() uint16

client/internal/lazyconn/activity/manager_test.go

@@ -8,6 +8,7 @@ import (
 	"time"
 
 	log "github.com/sirupsen/logrus"
+	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
 
 	"github.com/netbirdio/netbird/client/iface/wgaddr"
 	"github.com/netbirdio/netbird/client/internal/lazyconn"
@@ -25,7 +26,7 @@ func (m *MocPeer) ConnID() peerid.ConnID {
 type MocWGIface struct {
 }
 
-func (m MocWGIface) IdlePeerEndpoint(string, []netip.Prefix, *net.UDPAddr) error {
+func (m MocWGIface) UpdatePeer(string, []netip.Prefix, time.Duration, *net.UDPAddr, *wgtypes.Key) error {
 	return nil
 }
 

client/internal/lazyconn/manager/manager.go

@@ -280,7 +280,7 @@ func (m *Manager) DeactivatePeer(peerID peerid.ConnID) {
 		return
 	}
 
-	m.peerStore.PeerConnIdle(mp.peerCfg.PublicKey, false)
+	m.peerStore.PeerConnClose(mp.peerCfg.PublicKey)
 
 	mp.peerCfg.Log.Infof("start activity monitor")
 
@@ -569,7 +569,7 @@ func (m *Manager) onPeerInactivityTimedOut(peerIDs map[string]struct{}) {
 		mp.peerCfg.Log.Infof("connection timed out")
 
 		// this is blocking operation, potentially can be optimized
-		m.peerStore.PeerConnIdle(mp.peerCfg.PublicKey, true)
+		m.peerStore.PeerConnIdle(mp.peerCfg.PublicKey)
 
 		mp.expectedWatcher = watcherActivity
 

client/internal/lazyconn/wgiface.go

@@ -3,6 +3,9 @@ package lazyconn
 import (
 	"net"
 	"net/netip"
+	"time"
+
+	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
 
 	"github.com/netbirdio/netbird/client/iface/wgaddr"
 	"github.com/netbirdio/netbird/monotime"
@@ -10,7 +13,7 @@ import (
 
 type WGIface interface {
 	RemovePeer(peerKey string) error
-	IdlePeerEndpoint(peerKey string, allowedIPs []netip.Prefix, endpoint *net.UDPAddr) error
+	UpdatePeer(peerKey string, allowedIps []netip.Prefix, keepAlive time.Duration, endpoint *net.UDPAddr, preSharedKey *wgtypes.Key) error
 	IsUserspaceBind() bool
 	Address() wgaddr.Address
 	LastActivities() map[string]monotime.Time

client/internal/peer/conn.go

@@ -285,20 +285,8 @@ func (conn *Conn) open(engineCtx context.Context, firstPacket []byte) error {
 	return nil
 }
 
-// Close closes this peer Conn issuing a close event to the Conn closeCh and removes the WireGuard peer
-func (conn *Conn) Close() {
-	conn.close(false, true)
-}
-
-// Idle tears down the connection for the lazy idle state: transports and proxies are
-// closed but the WireGuard peer is kept, so its AllowedIPs (including routed prefixes
-// installed by the route manager) survive until the activity listener re-points the
-// endpoint at the wake listener.
-func (conn *Conn) Idle(signalToRemote bool) {
-	conn.close(signalToRemote, false)
-}
-
-func (conn *Conn) close(signalToRemote bool, removeWgPeer bool) {
+// Close closes this peer Conn issuing a close event to the Conn closeCh
+func (conn *Conn) Close(signalToRemote bool) {
 	conn.mu.Lock()
 	defer conn.wgWatcherWg.Wait()
 	defer conn.mu.Unlock()
@@ -341,12 +329,8 @@ func (conn *Conn) close(signalToRemote bool, removeWgPeer bool) {
 		conn.wgProxyICE = nil
 	}
 
-	if removeWgPeer {
-		if err := conn.endpointUpdater.RemoveWgPeer(); err != nil {
-			conn.Log.Errorf("failed to remove wg endpoint: %v", err)
-		}
-	} else {
-		conn.endpointUpdater.CancelPendingUpdates()
+	if err := conn.endpointUpdater.RemoveWgPeer(); err != nil {
+		conn.Log.Errorf("failed to remove wg endpoint: %v", err)
 	}
 
 	if conn.evalStatus() == StatusConnected && conn.onDisconnected != nil {

client/internal/peer/endpoint.go

@@ -65,16 +65,6 @@ func (e *EndpointUpdater) RemoveWgPeer() error {
 	return e.wgConfig.WgInterface.RemovePeer(e.wgConfig.RemoteKey)
 }
 
-// CancelPendingUpdates stops a scheduled delayed endpoint update without touching the
-// WireGuard peer. Used on the idle transition where the peer is kept so a pending
-// responder-side update cannot overwrite the wake endpoint later.
-func (e *EndpointUpdater) CancelPendingUpdates() {
-	e.mu.Lock()
-	defer e.mu.Unlock()
-
-	e.waitForCloseTheDelayedUpdate()
-}
-
 func (e *EndpointUpdater) RemoveEndpointAddress() error {
 	e.mu.Lock()
 	defer e.mu.Unlock()

client/internal/peer/endpoint_test.go

@@ -1,101 +0,0 @@
-package peer
-
-import (
-	"net"
-	"net/netip"
-	"sync"
-	"testing"
-	"time"
-
-	log "github.com/sirupsen/logrus"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
-
-	"github.com/netbirdio/netbird/client/iface/configurer"
-	"github.com/netbirdio/netbird/client/iface/wgaddr"
-	"github.com/netbirdio/netbird/client/iface/wgproxy"
-)
-
-type endpointTestWGIface struct {
-	mu          sync.Mutex
-	updateCalls int
-	removeCalls int
-}
-
-func (m *endpointTestWGIface) UpdatePeer(string, []netip.Prefix, time.Duration, *net.UDPAddr, *wgtypes.Key) error {
-	m.mu.Lock()
-	defer m.mu.Unlock()
-	m.updateCalls++
-	return nil
-}
-
-func (m *endpointTestWGIface) RemovePeer(string) error {
-	m.mu.Lock()
-	defer m.mu.Unlock()
-	m.removeCalls++
-	return nil
-}
-
-func (m *endpointTestWGIface) GetStats() (map[string]configurer.WGStats, error) {
-	return map[string]configurer.WGStats{}, nil
-}
-
-func (m *endpointTestWGIface) GetProxy() wgproxy.Proxy { return nil }
-
-func (m *endpointTestWGIface) Address() wgaddr.Address { return wgaddr.Address{} }
-
-func (m *endpointTestWGIface) RemoveEndpointAddress(string) error { return nil }
-
-func (m *endpointTestWGIface) counts() (updates, removes int) {
-	m.mu.Lock()
-	defer m.mu.Unlock()
-	return m.updateCalls, m.removeCalls
-}
-
-func newTestEndpointUpdater(iface *endpointTestWGIface, initiator bool) *EndpointUpdater {
-	cfg := WgConfig{
-		RemoteKey:   "remoteKey",
-		WgInterface: iface,
-		AllowedIps:  []netip.Prefix{netip.MustParsePrefix("100.64.0.5/32")},
-	}
-	return NewEndpointUpdater(log.WithField("peer", "test"), cfg, initiator)
-}
-
-// TestEndpointUpdater_CancelPendingUpdates ensures a scheduled responder-side delayed
-// update is stopped without removing the WireGuard peer, so an idle transition cannot
-// be overwritten later by a stale endpoint update.
-func TestEndpointUpdater_CancelPendingUpdates(t *testing.T) {
-	iface := &endpointTestWGIface{}
-	e := newTestEndpointUpdater(iface, false)
-
-	addr := &net.UDPAddr{IP: net.ParseIP("127.0.0.1"), Port: 51820}
-	require.NoError(t, e.ConfigureWGEndpoint(addr, nil))
-
-	updates, _ := iface.counts()
-	require.Equal(t, 1, updates, "responder must apply the immediate nil-endpoint update")
-
-	// CancelPendingUpdates waits for the delayed-update goroutine to exit, so the
-	// call counts below are final: the 5s fallback update can never fire anymore.
-	e.CancelPendingUpdates()
-
-	updates, removes := iface.counts()
-	assert.Equal(t, 1, updates, "delayed endpoint update must not fire after cancellation")
-	assert.Equal(t, 0, removes, "cancellation must not remove the WireGuard peer")
-}
-
-// TestEndpointUpdater_CancelPendingUpdatesNoPending ensures cancellation is a safe no-op
-// when no delayed update is scheduled (initiator path).
-func TestEndpointUpdater_CancelPendingUpdatesNoPending(t *testing.T) {
-	iface := &endpointTestWGIface{}
-	e := newTestEndpointUpdater(iface, true)
-
-	addr := &net.UDPAddr{IP: net.ParseIP("127.0.0.1"), Port: 51820}
-	require.NoError(t, e.ConfigureWGEndpoint(addr, nil))
-
-	e.CancelPendingUpdates()
-
-	updates, removes := iface.counts()
-	assert.Equal(t, 1, updates, "initiator applies exactly one direct update")
-	assert.Equal(t, 0, removes, "cancellation must not remove the WireGuard peer")
-}

client/internal/peer/worker_relay.go

@@ -54,19 +54,15 @@ func (w *WorkerRelay) OnNewOffer(remoteOfferAnswer *OfferAnswer) {
 	w.relaySupportedOnRemotePeer.Store(true)
 
 	// the relayManager will return with error in case if the connection has lost with relay server
-	currentRelayAddress, _, err := w.relayManager.RelayInstanceAddress()
+	_, _, err := w.relayManager.RelayInstanceAddress()
 	if err != nil {
 		w.log.Errorf("failed to handle new offer: %s", err)
 		return
 	}
 
-	srv := w.preferredRelayServer(currentRelayAddress, remoteOfferAnswer.RelaySrvAddress)
-	var serverIP netip.Addr
-	if srv == remoteOfferAnswer.RelaySrvAddress {
-		serverIP = remoteOfferAnswer.RelaySrvIP
-	}
-
-	relayedConn, err := w.relayManager.OpenConn(w.peerCtx, srv, w.config.Key, serverIP)
+	preferForeign := !w.isController
+	remoteRelayServer := relayClient.RelayServer{Addr: remoteOfferAnswer.RelaySrvAddress, IP: remoteOfferAnswer.RelaySrvIP}
+	relayedConn, err := w.relayManager.OpenConn(w.peerCtx, remoteRelayServer, w.config.Key, preferForeign)
 	if err != nil {
 		if errors.Is(err, relayClient.ErrConnAlreadyExists) {
 			w.log.Debugf("handled offer by reusing existing relay connection")
@@ -80,14 +76,13 @@ func (w *WorkerRelay) OnNewOffer(remoteOfferAnswer *OfferAnswer) {
 	w.relayedConn = relayedConn
 	w.relayLock.Unlock()
 
-	err = w.relayManager.AddCloseListener(srv, w.onRelayClientDisconnected)
-	if err != nil {
-		log.Errorf("failed to add close listener: %s", err)
+	if err := w.relayManager.AddCloseListener(relayedConn.RemoteAddr().String(), w.onRelayClientDisconnected); err != nil {
+		w.log.Errorf("failed to add close listener: %s", err)
 		_ = relayedConn.Close()
 		return
 	}
 
-	w.log.Debugf("peer conn opened via Relay: %s", srv)
+	w.log.Debugf("peer conn opened via Relay: %s", relayedConn.RemoteAddr())
 	go w.conn.onRelayConnectionIsReady(RelayConnInfo{
 		relayedConn:     relayedConn,
 		rosenpassPubKey: remoteOfferAnswer.RosenpassPubKey,
@@ -126,13 +121,6 @@ func (w *WorkerRelay) isRelaySupported(answer *OfferAnswer) bool {
 	return answer.RelaySrvAddress != ""
 }
 
-func (w *WorkerRelay) preferredRelayServer(myRelayAddress, remoteRelayAddress string) string {
-	if w.isController {
-		return myRelayAddress
-	}
-	return remoteRelayAddress
-}
-
 func (w *WorkerRelay) onRelayClientDisconnected() {
 	go w.conn.onRelayDisconnected()
 }

client/internal/peerstore/store.go

@@ -108,10 +108,7 @@ func (s *Store) PeerConnOpenWithFirstPacket(ctx context.Context, pubKey string,
 	}
 }
 
-// PeerConnIdle transitions the peer connection to the lazy idle state, keeping the
-// WireGuard peer and its AllowedIPs in place. signalToRemote indicates whether the
-// remote peer should be notified (false when the remote initiated the idle via GOAWAY).
-func (s *Store) PeerConnIdle(pubKey string, signalToRemote bool) {
+func (s *Store) PeerConnIdle(pubKey string) {
 	s.peerConnsMu.RLock()
 	defer s.peerConnsMu.RUnlock()
 
@@ -119,7 +116,18 @@ func (s *Store) PeerConnIdle(pubKey string, signalToRemote bool) {
 	if !ok {
 		return
 	}
-	p.Idle(signalToRemote)
+	p.Close(true)
+}
+
+func (s *Store) PeerConnClose(pubKey string) {
+	s.peerConnsMu.RLock()
+	defer s.peerConnsMu.RUnlock()
+
+	p, ok := s.peerConns[pubKey]
+	if !ok {
+		return
+	}
+	p.Close(false)
 }
 
 func (s *Store) PeersPubKey() []string {

client/ios/NetBirdSDK/client.go

@@ -233,6 +233,9 @@ func (c *Client) DebugBundle(anonymize bool) (string, error) {
 		deps.SyncResponse = resp
 
 		if e := cc.Engine(); e != nil {
+			deps.RefreshStatus = func() {
+				e.RunHealthProbes(context.Background(), true)
+			}
 			if cm := e.GetClientMetrics(); cm != nil {
 				deps.ClientMetrics = cm
 			}

client/ui/i18n/locales/_index.json

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

combined/cmd/root.go

@@ -226,7 +226,7 @@ func (s *serverInstances) createRelayServer(cfg *CombinedConfig, tlsSupport bool
 	}
 
 	hashedSecret := sha256.Sum256([]byte(cfg.Relay.AuthSecret))
-	authenticator := auth.NewTimedHMACValidator(hashedSecret[:], 24*time.Hour)
+	authenticator := auth.NewTimedHMACValidator(hashedSecret[:])
 
 	relayCfg := relayServer.Config{
 		Meter:          s.metricsServer.Meter,

go.mod

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

go.sum

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

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

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

management/internals/modules/agentnetwork/synthesizer.go

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

management/internals/modules/agentnetwork/synthesizer_test.go

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

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

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

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

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

proxy/cmd/proxy/cmd/root.go

@@ -18,6 +18,7 @@ import (
 	"github.com/netbirdio/netbird/client/embed"
 	"github.com/netbirdio/netbird/proxy"
 	nbacme "github.com/netbirdio/netbird/proxy/internal/acme"
+	"github.com/netbirdio/netbird/trustedproxy"
 	"github.com/netbirdio/netbird/util"
 )
 
@@ -209,7 +210,7 @@ func runServer(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("invalid domain value %q: %w", proxyDomain, err)
 	}
 
-	parsedTrustedProxies, err := proxy.ParseTrustedProxies(trustedProxies)
+	parsedTrustedProxies, err := trustedproxy.Parse(trustedProxies)
 	if err != nil {
 		return fmt.Errorf("invalid --trusted-proxies: %w", err)
 	}

proxy/internal/accesslog/logger.go

@@ -16,6 +16,7 @@ import (
 	"github.com/netbirdio/netbird/proxy/auth"
 	"github.com/netbirdio/netbird/proxy/internal/types"
 	"github.com/netbirdio/netbird/shared/management/proto"
+	"github.com/netbirdio/netbird/trustedproxy"
 )
 
 const (
@@ -66,7 +67,7 @@ type denyBucket struct {
 type Logger struct {
 	client         gRPCClient
 	logger         *log.Logger
-	trustedProxies []netip.Prefix
+	trustedProxies *trustedproxy.List
 
 	usageMux    sync.Mutex
 	domainUsage map[string]*domainUsage
@@ -82,7 +83,7 @@ type Logger struct {
 // NewLogger creates a new access log Logger. The trustedProxies parameter
 // configures which upstream proxy IP ranges are trusted for extracting
 // the real client IP from X-Forwarded-For headers.
-func NewLogger(client gRPCClient, logger *log.Logger, trustedProxies []netip.Prefix) *Logger {
+func NewLogger(client gRPCClient, logger *log.Logger, trustedProxies *trustedproxy.List) *Logger {
 	if logger == nil {
 		logger = log.StandardLogger()
 	}

proxy/internal/accesslog/requestip.go

@@ -4,13 +4,13 @@ import (
 	"net/http"
 	"net/netip"
 
-	"github.com/netbirdio/netbird/proxy/internal/proxy"
+	"github.com/netbirdio/netbird/trustedproxy"
 )
 
 // extractSourceIP resolves the real client IP from the request using trusted
 // proxy configuration. When trustedProxies is non-empty and the direct
 // connection is from a trusted source, it walks X-Forwarded-For right-to-left
 // skipping trusted IPs. Otherwise it returns RemoteAddr directly.
-func extractSourceIP(r *http.Request, trustedProxies []netip.Prefix) netip.Addr {
-	return proxy.ResolveClientIP(r.RemoteAddr, r.Header.Get("X-Forwarded-For"), trustedProxies)
+func extractSourceIP(r *http.Request, trustedProxies *trustedproxy.List) netip.Addr {
+	return trustedProxies.ResolveClientIP(r.RemoteAddr, r.Header.Get("X-Forwarded-For"))
 }

proxy/internal/llm/bedrock_model.go

@@ -0,0 +1,38 @@
+package llm
+
+import (
+	"regexp"
+	"strings"
+)
+
+// bedrockRegionPrefixes are the cross-region inference-profile prefixes that
+// front a Bedrock model id (e.g. "eu.anthropic.claude-...").
+var bedrockRegionPrefixes = []string{"us.", "eu.", "apac.", "global."}
+
+// bedrockVersionSuffix matches the trailing "-vN[:N]" or "-YYYYMMDD-vN[:N]"
+// version/throughput suffix of a Bedrock model id.
+var bedrockVersionSuffix = regexp.MustCompile(`-(\d{8}-)?v\d+(:\d+)?$`)
+
+// NormalizeBedrockModel strips an ARN wrapper, a cross-region inference-profile
+// prefix, and the version/throughput suffix from a Bedrock model id so it
+// matches the catalog/pricing key, e.g.
+// "eu.anthropic.claude-sonnet-4-5-20250929-v1:0" -> "anthropic.claude-sonnet-4-5"
+// and the inference-profile ARN's last segment likewise. It is the single
+// source of truth shared by the request parser (which normalizes the request
+// model from the URL path) and the router (which normalizes the operator's
+// registered Bedrock model ids so both sides compare equal).
+func NormalizeBedrockModel(modelID string) string {
+	m := modelID
+	if strings.HasPrefix(m, "arn:") {
+		if i := strings.LastIndex(m, "/"); i >= 0 {
+			m = m[i+1:]
+		}
+	}
+	for _, p := range bedrockRegionPrefixes {
+		if strings.HasPrefix(m, p) {
+			m = m[len(p):]
+			break
+		}
+	}
+	return bedrockVersionSuffix.ReplaceAllString(m, "")
+}

proxy/internal/llm/bedrock_model_test.go

@@ -0,0 +1,23 @@
+package llm
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestNormalizeBedrockModel(t *testing.T) {
+	cases := map[string]string{
+		"eu.anthropic.claude-sonnet-4-5-20250929-v1:0": "anthropic.claude-sonnet-4-5",
+		"us.anthropic.claude-haiku-4-5":                "anthropic.claude-haiku-4-5",
+		"us.anthropic.claude-opus-4-8-20250101-v1:0":   "anthropic.claude-opus-4-8",
+		"anthropic.claude-sonnet-4-5-20250929-v1:0":    "anthropic.claude-sonnet-4-5",
+		"meta.llama3-3-70b-instruct-v1:0":              "meta.llama3-3-70b-instruct",
+		"amazon.nova-pro-v1:0":                         "amazon.nova-pro",
+		// Inference-profile ARN — model id lives in the last path segment.
+		"arn:aws:bedrock:eu-central-1:123456789012:inference-profile/eu.anthropic.claude-sonnet-4-5-20250929-v1:0": "anthropic.claude-sonnet-4-5",
+	}
+	for in, want := range cases {
+		require.Equal(t, want, NormalizeBedrockModel(in), "normalize %q", in)
+	}
+}

proxy/internal/middleware/builtin/llm_identity_inject/factory.go

@@ -64,6 +64,11 @@ type JSONMetadataRule struct {
 	UserKey        string `json:"user_key,omitempty"`
 	GroupsKey      string `json:"groups_key,omitempty"`
 	MaxValueLength int    `json:"max_value_length,omitempty"`
+	// Sanitize replaces characters outside the destination provider's accepted
+	// set with '_' before emitting each value. AWS Bedrock's
+	// X-Amzn-Bedrock-Request-Metadata restricts values to [A-Za-z0-9 +-=._:/@];
+	// group display names with other characters would otherwise 400.
+	Sanitize bool `json:"sanitize,omitempty"`
 }
 
 // Config is the on-wire configuration accepted by the factory. An

proxy/internal/middleware/builtin/llm_identity_inject/middleware.go

@@ -292,15 +292,21 @@ func applyJSONMetadata(rule *JSONMetadataRule, in *middleware.Input) *middleware
 	mutations := &middleware.Mutations{}
 	mutations.HeadersRemove = append(mutations.HeadersRemove, rule.Header)
 
+	emit := func(v string) string {
+		if rule.Sanitize {
+			v = sanitizeMetadataValue(v)
+		}
+		return truncate(v, rule.MaxValueLength)
+	}
 	payload := map[string]string{}
 	if rule.UserKey != "" {
 		if identity := identityFor(in); identity != "" {
-			payload[rule.UserKey] = truncate(identity, rule.MaxValueLength)
+			payload[rule.UserKey] = emit(identity)
 		}
 	}
 	if rule.GroupsKey != "" {
 		if csv := authorisingTagsCSV(in); csv != "" {
-			payload[rule.GroupsKey] = truncate(csv, rule.MaxValueLength)
+			payload[rule.GroupsKey] = emit(csv)
 		}
 	}
 	if len(payload) == 0 {
@@ -359,6 +365,36 @@ func truncate(s string, maxBytes int) string {
 	return s[:maxBytes]
 }
 
+// sanitizeMetadataValue replaces any character outside AWS Bedrock's accepted
+// request-metadata class — letters, digits, space, and + - = . _ : / @ — with
+// '_'. This keeps values (notably the groups CSV, whose commas are rejected, and
+// group display names with arbitrary characters) from making Bedrock reject the
+// request with 400. The result stays opaque to the gateway.
+func sanitizeMetadataValue(s string) string {
+	var b strings.Builder
+	b.Grow(len(s))
+	for _, r := range s {
+		if metadataCharAllowed(r) {
+			b.WriteRune(r)
+		} else {
+			b.WriteByte('_')
+		}
+	}
+	return b.String()
+}
+
+func metadataCharAllowed(r rune) bool {
+	switch {
+	case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9':
+		return true
+	}
+	switch r {
+	case ' ', '+', '-', '=', '.', '_', ':', '/', '@':
+		return true
+	}
+	return false
+}
+
 // tagsIDsFromAuthorising reads llm_router's authorising-groups metadata
 // (a CSV of group ids) and returns the parsed slice. Returns nil when
 // the key is absent or empty so the caller can fall back to the full

proxy/internal/middleware/builtin/llm_identity_inject/middleware_test.go

@@ -304,6 +304,46 @@ func TestInject_JSONMetadata_TruncatesValues(t *testing.T) {
 		"per-value byte length must be capped at MaxValueLength")
 }
 
+// TestInject_JSONMetadata_Sanitize pins the AWS-Bedrock sanitization path: when
+// Sanitize is set, characters outside Bedrock's accepted metadata class
+// (notably the groups CSV comma and arbitrary characters in group display
+// names) are replaced with '_' so Bedrock doesn't reject the request. Allowed
+// characters (letters, digits, spaces, and @ . _ : / + - =) pass through.
+func TestInject_JSONMetadata_Sanitize(t *testing.T) {
+	rule := ProviderInjection{
+		ProviderID: portkeyProvider,
+		JSONMetadata: &JSONMetadataRule{
+			Header:         "X-Amzn-Bedrock-Request-Metadata",
+			UserKey:        "user",
+			GroupsKey:      "group",
+			MaxValueLength: 256,
+			Sanitize:       true,
+		},
+	}
+	mw := New(Config{Providers: []ProviderInjection{rule}})
+	in := newInput(portkeyProvider, "alice", []string{"g1", "g2"})
+	in.UserEmail = "alice@example.com"
+	// Group display names carry characters Bedrock rejects (comma, '#'); the CSV
+	// join adds another comma between the two groups.
+	in.UserGroupNames = []string{"Eng,Team", "Ops#1"}
+
+	out, err := mw.Invoke(context.Background(), in)
+	require.NoError(t, err)
+	require.NotNil(t, out.Mutations)
+	require.Len(t, out.Mutations.HeadersAdd, 1)
+	added := out.Mutations.HeadersAdd[0]
+	assert.Equal(t, "X-Amzn-Bedrock-Request-Metadata", added.Key,
+		"the Bedrock cost-allocation header carries the metadata JSON")
+
+	var payload map[string]string
+	require.NoError(t, json.Unmarshal([]byte(added.Value), &payload))
+	assert.Equal(t, "alice@example.com", payload["user"],
+		"'@' and '.' are in Bedrock's accepted set and must be preserved")
+	assert.NotContains(t, payload["group"], ",", "commas must be sanitized — Bedrock rejects them")
+	assert.NotContains(t, payload["group"], "#", "disallowed characters must be sanitized")
+	assert.Contains(t, payload["group"], "Eng", "allowed characters must be preserved")
+}
+
 // TestInject_JSONMetadata_EmptyIdentity_StripsButDoesNotAdd verifies the
 // anti-spoof Remove still fires when there's nothing to stamp.
 func TestInject_JSONMetadata_EmptyIdentity_StripsButDoesNotAdd(t *testing.T) {

proxy/internal/middleware/builtin/llm_router/bedrock_route_test.go

@@ -0,0 +1,30 @@
+package llm_router
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestRouteClaimsModel_BedrockNormalizesCandidate guards the fix for the native
+// Bedrock routing gap: the request model reaches the router already normalized
+// (the parser strips the region/inference-profile prefix and version suffix),
+// so a provider registered with the raw inference-profile id must still match.
+func TestRouteClaimsModel_BedrockNormalizesCandidate(t *testing.T) {
+	route := ProviderRoute{Bedrock: true, Models: []string{"us.anthropic.claude-haiku-4-5"}}
+	assert.True(t, routeClaimsModel(route, "anthropic.claude-haiku-4-5"),
+		"raw region-prefixed Bedrock model must match the normalized request model")
+	assert.False(t, routeClaimsModel(route, "anthropic.claude-opus-4-8"),
+		"a model outside the provider's list must not match")
+
+	// A provider registered with the already-normalized id also matches.
+	normalized := ProviderRoute{Bedrock: true, Models: []string{"anthropic.claude-haiku-4-5"}}
+	assert.True(t, routeClaimsModel(normalized, "anthropic.claude-haiku-4-5"),
+		"normalized Bedrock model must match")
+
+	// Non-Bedrock routes keep exact matching (no prefix stripping).
+	openai := ProviderRoute{Models: []string{"gpt-4o"}}
+	assert.True(t, routeClaimsModel(openai, "gpt-4o"), "exact model must match")
+	assert.False(t, routeClaimsModel(openai, "us.gpt-4o"),
+		"non-Bedrock routes must not strip a us. prefix")
+}

proxy/internal/middleware/builtin/llm_router/middleware.go

@@ -23,6 +23,7 @@ import (
 	"golang.org/x/oauth2"
 	"golang.org/x/oauth2/google"
 
+	"github.com/netbirdio/netbird/proxy/internal/llm"
 	"github.com/netbirdio/netbird/proxy/internal/middleware"
 )
 
@@ -555,6 +556,14 @@ func routeClaimsModel(route ProviderRoute, model string) bool {
 		if candidate == model {
 			return true
 		}
+		// Bedrock request models reach the router already normalized (the parser
+		// strips the region / inference-profile prefix and version suffix), but
+		// the operator may register the raw inference-profile id (e.g.
+		// "us.anthropic.claude-haiku-4-5"). Normalize the candidate so both sides
+		// compare equal; otherwise a native Bedrock request denies as not-routable.
+		if route.Bedrock && llm.NormalizeBedrockModel(candidate) == model {
+			return true
+		}
 	}
 	return false
 }

proxy/internal/proxy/reverseproxy.go

@@ -22,6 +22,7 @@ import (
 	"github.com/netbirdio/netbird/proxy/internal/roundtrip"
 	"github.com/netbirdio/netbird/proxy/internal/types"
 	"github.com/netbirdio/netbird/proxy/web"
+	"github.com/netbirdio/netbird/trustedproxy"
 )
 
 type ReverseProxy struct {
@@ -29,10 +30,10 @@ type ReverseProxy struct {
 	// forwardedProto overrides the X-Forwarded-Proto header value.
 	// Valid values: "auto" (detect from TLS), "http", "https".
 	forwardedProto string
-	// trustedProxies is a list of IP prefixes for trusted upstream proxies.
-	// When the direct connection comes from a trusted proxy, forwarding
-	// headers are preserved and appended to instead of being stripped.
-	trustedProxies []netip.Prefix
+	// trustedProxies is the set of trusted upstream proxies. When the direct
+	// connection comes from a trusted proxy, forwarding headers are preserved
+	// and appended to instead of being stripped.
+	trustedProxies *trustedproxy.List
 	mappingsMux    sync.RWMutex
 	mappings       map[string]Mapping
 	logger         *log.Logger
@@ -63,7 +64,7 @@ func WithMiddlewareManager(m *middleware.Manager) Option {
 // between requested URLs and targets.
 // The internal mappings can be modified using the AddMapping
 // and RemoveMapping functions.
-func NewReverseProxy(transport http.RoundTripper, forwardedProto string, trustedProxies []netip.Prefix, logger *log.Logger, opts ...Option) *ReverseProxy {
+func NewReverseProxy(transport http.RoundTripper, forwardedProto string, trustedProxies *trustedproxy.List, logger *log.Logger, opts ...Option) *ReverseProxy {
 	if logger == nil {
 		logger = log.StandardLogger()
 	}
@@ -527,7 +528,7 @@ func (p *ReverseProxy) isSelfTargetLoop(r *http.Request, target *url.URL) bool {
 	if !types.IsOverlayOrigin(r.Context()) {
 		return false
 	}
-	srcIP := extractHostIP(r.RemoteAddr)
+	srcIP := trustedproxy.ExtractHostIP(r.RemoteAddr)
 	if !srcIP.IsValid() {
 		return false
 	}
@@ -578,9 +579,9 @@ func (p *ReverseProxy) rewriteFunc(target *url.URL, matchedPath string, passHost
 
 		stampNetBirdIdentity(r)
 
-		clientIP := extractHostIP(r.In.RemoteAddr)
+		clientIP := trustedproxy.ExtractHostIP(r.In.RemoteAddr)
 
-		if isTrustedAddr(clientIP, p.trustedProxies) {
+		if p.trustedProxies.Contains(clientIP) {
 			p.setTrustedForwardingHeaders(r, clientIP)
 		} else {
 			p.setUntrustedForwardingHeaders(r, clientIP)
@@ -664,7 +665,7 @@ func (p *ReverseProxy) setTrustedForwardingHeaders(r *httputil.ProxyRequest, cli
 	if realIP := r.In.Header.Get("X-Real-IP"); realIP != "" {
 		r.Out.Header.Set("X-Real-IP", realIP)
 	} else {
-		resolved := ResolveClientIP(r.In.RemoteAddr, r.In.Header.Get("X-Forwarded-For"), p.trustedProxies)
+		resolved := p.trustedProxies.ResolveClientIP(r.In.RemoteAddr, r.In.Header.Get("X-Forwarded-For"))
 		r.Out.Header.Set("X-Real-IP", resolved.String())
 	}
 

proxy/internal/proxy/reverseproxy_test.go

@@ -23,6 +23,7 @@ import (
 	"github.com/netbirdio/netbird/proxy/internal/roundtrip"
 	"github.com/netbirdio/netbird/proxy/internal/types"
 	"github.com/netbirdio/netbird/proxy/web"
+	"github.com/netbirdio/netbird/trustedproxy"
 )
 
 func TestRewriteFunc_HostRewriting(t *testing.T) {
@@ -302,7 +303,7 @@ func TestExtractHostIP(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			assert.Equal(t, tt.expected, extractHostIP(tt.remoteAddr))
+			assert.Equal(t, tt.expected, trustedproxy.ExtractHostIP(tt.remoteAddr))
 		})
 	}
 }
@@ -330,7 +331,7 @@ func TestExtractForwardedPort(t *testing.T) {
 
 func TestRewriteFunc_TrustedProxy(t *testing.T) {
 	target, _ := url.Parse("http://backend.internal:8080")
-	trusted := []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")}
+	trusted := trustedproxy.FromPrefixes([]netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")})
 
 	t.Run("appends to X-Forwarded-For", func(t *testing.T) {
 		p := &ReverseProxy{forwardedProto: "auto", trustedProxies: trusted}

proxy/internal/proxy/trustedproxy.go

@@ -1,81 +0,0 @@
-package proxy
-
-import (
-	"net/netip"
-	"strings"
-)
-
-// IsTrustedProxy checks if the given IP string falls within any of the trusted prefixes.
-func IsTrustedProxy(ipStr string, trusted []netip.Prefix) bool {
-	addr, err := netip.ParseAddr(ipStr)
-	if err != nil || len(trusted) == 0 {
-		return false
-	}
-	return isTrustedAddr(addr.Unmap(), trusted)
-}
-
-// ResolveClientIP extracts the real client IP from X-Forwarded-For using the trusted proxy list.
-// It walks the XFF chain right-to-left, skipping IPs that match trusted prefixes.
-// The first untrusted IP is the real client.
-//
-// If the trusted list is empty or remoteAddr is not trusted, it returns the
-// remoteAddr IP directly (ignoring any forwarding headers).
-func ResolveClientIP(remoteAddr, xff string, trusted []netip.Prefix) netip.Addr {
-	remoteIP := extractHostIP(remoteAddr)
-
-	if len(trusted) == 0 || !isTrustedAddr(remoteIP, trusted) {
-		return remoteIP
-	}
-
-	if xff == "" {
-		return remoteIP
-	}
-
-	parts := strings.Split(xff, ",")
-	for i := len(parts) - 1; i >= 0; i-- {
-		ip := strings.TrimSpace(parts[i])
-		if ip == "" {
-			continue
-		}
-		addr, err := netip.ParseAddr(ip)
-		if err != nil {
-			continue
-		}
-		addr = addr.Unmap()
-		if !isTrustedAddr(addr, trusted) {
-			return addr
-		}
-	}
-
-	// All IPs in XFF are trusted; return the leftmost as best guess.
-	if first := strings.TrimSpace(parts[0]); first != "" {
-		if addr, err := netip.ParseAddr(first); err == nil {
-			return addr.Unmap()
-		}
-	}
-	return remoteIP
-}
-
-// extractHostIP parses the IP from a host:port string and returns it unmapped.
-func extractHostIP(hostPort string) netip.Addr {
-	if ap, err := netip.ParseAddrPort(hostPort); err == nil {
-		return ap.Addr().Unmap()
-	}
-	if addr, err := netip.ParseAddr(hostPort); err == nil {
-		return addr.Unmap()
-	}
-	return netip.Addr{}
-}
-
-// isTrustedAddr checks if the given address falls within any of the trusted prefixes.
-func isTrustedAddr(addr netip.Addr, trusted []netip.Prefix) bool {
-	if !addr.IsValid() {
-		return false
-	}
-	for _, prefix := range trusted {
-		if prefix.Contains(addr) {
-			return true
-		}
-	}
-	return false
-}

proxy/internal/proxy/trustedproxy_test.go

@@ -1,129 +0,0 @@
-package proxy
-
-import (
-	"net/netip"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestIsTrustedProxy(t *testing.T) {
-	trusted := []netip.Prefix{
-		netip.MustParsePrefix("10.0.0.0/8"),
-		netip.MustParsePrefix("192.168.1.0/24"),
-		netip.MustParsePrefix("fd00::/8"),
-	}
-
-	tests := []struct {
-		name    string
-		ip      string
-		trusted []netip.Prefix
-		want    bool
-	}{
-		{"empty trusted list", "10.0.0.1", nil, false},
-		{"IP within /8 prefix", "10.1.2.3", trusted, true},
-		{"IP within /24 prefix", "192.168.1.100", trusted, true},
-		{"IP outside all prefixes", "203.0.113.50", trusted, false},
-		{"boundary IP just outside prefix", "192.168.2.1", trusted, false},
-		{"unparsable IP", "not-an-ip", trusted, false},
-		{"IPv6 in trusted range", "fd00::1", trusted, true},
-		{"IPv6 outside range", "2001:db8::1", trusted, false},
-		{"empty string", "", trusted, false},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			assert.Equal(t, tt.want, IsTrustedProxy(tt.ip, tt.trusted))
-		})
-	}
-}
-
-func TestResolveClientIP(t *testing.T) {
-	trusted := []netip.Prefix{
-		netip.MustParsePrefix("10.0.0.0/8"),
-		netip.MustParsePrefix("172.16.0.0/12"),
-	}
-
-	tests := []struct {
-		name       string
-		remoteAddr string
-		xff        string
-		trusted    []netip.Prefix
-		want       netip.Addr
-	}{
-		{
-			name:       "empty trusted list returns RemoteAddr",
-			remoteAddr: "203.0.113.50:9999",
-			xff:        "1.2.3.4",
-			trusted:    nil,
-			want:       netip.MustParseAddr("203.0.113.50"),
-		},
-		{
-			name:       "untrusted RemoteAddr ignores XFF",
-			remoteAddr: "203.0.113.50:9999",
-			xff:        "1.2.3.4, 10.0.0.1",
-			trusted:    trusted,
-			want:       netip.MustParseAddr("203.0.113.50"),
-		},
-		{
-			name:       "trusted RemoteAddr with single client in XFF",
-			remoteAddr: "10.0.0.1:5000",
-			xff:        "203.0.113.50",
-			trusted:    trusted,
-			want:       netip.MustParseAddr("203.0.113.50"),
-		},
-		{
-			name:       "trusted RemoteAddr walks past trusted entries in XFF",
-			remoteAddr: "10.0.0.1:5000",
-			xff:        "203.0.113.50, 10.0.0.2, 172.16.0.5",
-			trusted:    trusted,
-			want:       netip.MustParseAddr("203.0.113.50"),
-		},
-		{
-			name:       "trusted RemoteAddr with empty XFF falls back to RemoteAddr",
-			remoteAddr: "10.0.0.1:5000",
-			xff:        "",
-			trusted:    trusted,
-			want:       netip.MustParseAddr("10.0.0.1"),
-		},
-		{
-			name:       "all XFF IPs trusted returns leftmost",
-			remoteAddr: "10.0.0.1:5000",
-			xff:        "10.0.0.2, 172.16.0.1, 10.0.0.3",
-			trusted:    trusted,
-			want:       netip.MustParseAddr("10.0.0.2"),
-		},
-		{
-			name:       "XFF with whitespace",
-			remoteAddr: "10.0.0.1:5000",
-			xff:        " 203.0.113.50 , 10.0.0.2 ",
-			trusted:    trusted,
-			want:       netip.MustParseAddr("203.0.113.50"),
-		},
-		{
-			name:       "XFF with empty segments",
-			remoteAddr: "10.0.0.1:5000",
-			xff:        "203.0.113.50,,10.0.0.2",
-			trusted:    trusted,
-			want:       netip.MustParseAddr("203.0.113.50"),
-		},
-		{
-			name:       "multi-hop with mixed trust",
-			remoteAddr: "10.0.0.1:5000",
-			xff:        "8.8.8.8, 203.0.113.50, 172.16.0.1",
-			trusted:    trusted,
-			want:       netip.MustParseAddr("203.0.113.50"),
-		},
-		{
-			name:       "RemoteAddr without port",
-			remoteAddr: "10.0.0.1",
-			xff:        "203.0.113.50",
-			trusted:    trusted,
-			want:       netip.MustParseAddr("203.0.113.50"),
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			assert.Equal(t, tt.want, ResolveClientIP(tt.remoteAddr, tt.xff, tt.trusted))
-		})
-	}
-}

proxy/lifecycle.go

@@ -2,13 +2,13 @@ package proxy
 
 import (
 	"context"
-	"net/netip"
 	"time"
 
 	log "github.com/sirupsen/logrus"
 
 	"github.com/netbirdio/netbird/client/embed"
 	"github.com/netbirdio/netbird/proxy/internal/acme"
+	"github.com/netbirdio/netbird/trustedproxy"
 )
 
 // Config bundles every knob the proxy reads at construction time. It mirrors
@@ -83,9 +83,9 @@ type Config struct {
 	// ForwardedProto overrides the X-Forwarded-Proto value sent to
 	// backends. Valid values: "auto", "http", "https".
 	ForwardedProto string
-	// TrustedProxies is a list of IP prefixes for trusted upstream
-	// proxies that may set forwarding headers.
-	TrustedProxies []netip.Prefix
+	// TrustedProxies is the set of trusted upstream proxies that may set
+	// forwarding headers.
+	TrustedProxies *trustedproxy.List
 	// WireguardPort is the UDP port for the embedded NetBird tunnel.
 	// Zero asks the OS for a random port.
 	WireguardPort uint16

proxy/proxyprotocol_test.go

@@ -10,12 +10,14 @@ import (
 	log "github.com/sirupsen/logrus"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/trustedproxy"
 )
 
 func TestWrapProxyProtocol_OverridesRemoteAddr(t *testing.T) {
 	srv := &Server{
 		Logger:         log.StandardLogger(),
-		TrustedProxies: []netip.Prefix{netip.MustParsePrefix("127.0.0.1/32")},
+		TrustedProxies: trustedproxy.FromPrefixes([]netip.Prefix{netip.MustParsePrefix("127.0.0.1/32")}),
 		ProxyProtocol:  true,
 	}
 
@@ -66,7 +68,7 @@ func TestWrapProxyProtocol_OverridesRemoteAddr(t *testing.T) {
 func TestProxyProtocolPolicy_TrustedRequires(t *testing.T) {
 	srv := &Server{
 		Logger:         log.StandardLogger(),
-		TrustedProxies: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
+		TrustedProxies: trustedproxy.FromPrefixes([]netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")}),
 	}
 
 	opts := proxyproto.ConnPolicyOptions{
@@ -80,7 +82,7 @@ func TestProxyProtocolPolicy_TrustedRequires(t *testing.T) {
 func TestProxyProtocolPolicy_UntrustedIgnores(t *testing.T) {
 	srv := &Server{
 		Logger:         log.StandardLogger(),
-		TrustedProxies: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
+		TrustedProxies: trustedproxy.FromPrefixes([]netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")}),
 	}
 
 	opts := proxyproto.ConnPolicyOptions{
@@ -94,7 +96,7 @@ func TestProxyProtocolPolicy_UntrustedIgnores(t *testing.T) {
 func TestProxyProtocolPolicy_InvalidIPRejects(t *testing.T) {
 	srv := &Server{
 		Logger:         log.StandardLogger(),
-		TrustedProxies: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
+		TrustedProxies: trustedproxy.FromPrefixes([]netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")}),
 	}
 
 	opts := proxyproto.ConnPolicyOptions{

proxy/server.go

@@ -67,6 +67,7 @@ import (
 	"github.com/netbirdio/netbird/proxy/web"
 	"github.com/netbirdio/netbird/shared/management/domain"
 	"github.com/netbirdio/netbird/shared/management/proto"
+	"github.com/netbirdio/netbird/trustedproxy"
 	"github.com/netbirdio/netbird/util/embeddedroots"
 )
 
@@ -79,19 +80,19 @@ type portRouter struct {
 
 type Server struct {
 	ctx               context.Context
-	mgmtClient    proto.ProxyServiceClient
-	proxy         *proxy.ReverseProxy
-	netbird       *roundtrip.NetBird
-	acme          *acme.Manager
+	mgmtClient        proto.ProxyServiceClient
+	proxy             *proxy.ReverseProxy
+	netbird           *roundtrip.NetBird
+	acme              *acme.Manager
 	staticCertWatcher *certwatch.Watcher
-	auth          *auth.Middleware
-	http          *http.Server
-	https         *http.Server
-	debug         *http.Server
-	healthServer  *health.Server
-	healthChecker *health.Checker
-	meter         *proxymetrics.Metrics
-	accessLog     *accesslog.Logger
+	auth              *auth.Middleware
+	http              *http.Server
+	https             *http.Server
+	debug             *http.Server
+	healthServer      *health.Server
+	healthChecker     *health.Checker
+	meter             *proxymetrics.Metrics
+	accessLog         *accesslog.Logger
 	// middlewareManager drives per-target middleware dispatch. Always
 	// constructed during boot; an empty registry produces empty chains and
 	// the reverse-proxy stays on the no-capture fast path.
@@ -99,16 +100,16 @@ type Server struct {
 	// middlewareRegistry is the source of registered middleware factories.
 	// Concrete middlewares register themselves through init().
 	middlewareRegistry *middleware.Registry
-	mainRouter    *nbtcp.Router
-	mainPort      uint16
-	udpMu         sync.Mutex
-	udpRelays     map[types.ServiceID]*udprelay.Relay
-	udpRelayWg    sync.WaitGroup
-	portMu        sync.RWMutex
-	portRouters   map[uint16]*portRouter
-	svcPorts      map[types.ServiceID][]uint16
-	lastMappings  map[types.ServiceID]*proto.ProxyMapping
-	portRouterWg  sync.WaitGroup
+	mainRouter         *nbtcp.Router
+	mainPort           uint16
+	udpMu              sync.Mutex
+	udpRelays          map[types.ServiceID]*udprelay.Relay
+	udpRelayWg         sync.WaitGroup
+	portMu             sync.RWMutex
+	portRouters        map[uint16]*portRouter
+	svcPorts           map[types.ServiceID][]uint16
+	lastMappings       map[types.ServiceID]*proto.ProxyMapping
+	portRouterWg       sync.WaitGroup
 
 	// hijackTracker tracks hijacked connections (e.g. WebSocket upgrades)
 	// so they can be closed during graceful shutdown, since http.Server.Shutdown
@@ -192,10 +193,10 @@ type Server struct {
 	// ForwardedProto overrides the X-Forwarded-Proto value sent to backends.
 	// Valid values: "auto" (detect from TLS), "http", "https".
 	ForwardedProto string
-	// TrustedProxies is a list of IP prefixes for trusted upstream proxies.
-	// When set, forwarding headers from these sources are preserved and
-	// appended to instead of being stripped.
-	TrustedProxies []netip.Prefix
+	// TrustedProxies is the set of trusted upstream proxies. When set,
+	// forwarding headers from these sources are preserved and appended to
+	// instead of being stripped.
+	TrustedProxies *trustedproxy.List
 	// WireguardPort is the port for the NetBird tunnel interface. Use 0
 	// for a random OS-assigned port. A fixed port only works with
 	// single-account deployments; multiple accounts will fail to bind
@@ -718,7 +719,7 @@ func (s *Server) wrapProxyProtocol(ln net.Listener) net.Listener {
 		Listener:          ln,
 		ReadHeaderTimeout: proxyProtoHeaderTimeout,
 	}
-	if len(s.TrustedProxies) > 0 {
+	if !s.TrustedProxies.Empty() {
 		ppListener.ConnPolicy = s.proxyProtocolPolicy
 	} else {
 		s.Logger.Warn("PROXY protocol enabled without trusted proxies; any source may send PROXY headers")
@@ -742,10 +743,8 @@ func (s *Server) proxyProtocolPolicy(opts proxyproto.ConnPolicyOptions) (proxypr
 	addr = addr.Unmap()
 
 	// called per accept
-	for _, prefix := range s.TrustedProxies {
-		if prefix.Contains(addr) {
-			return proxyproto.REQUIRE, nil
-		}
+	if s.TrustedProxies.Contains(addr) {
+		return proxyproto.REQUIRE, nil
 	}
 	return proxyproto.IGNORE, nil
 }

proxy/trustedproxy.go

@@ -1,43 +0,0 @@
-package proxy
-
-import (
-	"fmt"
-	"net/netip"
-	"strings"
-)
-
-// ParseTrustedProxies parses a comma-separated list of CIDR prefixes or bare IPs
-// into a slice of netip.Prefix values suitable for trusted proxy configuration.
-// Bare IPs are converted to single-host prefixes (/32 or /128).
-func ParseTrustedProxies(raw string) ([]netip.Prefix, error) {
-	if raw == "" {
-		return nil, nil
-	}
-
-	parts := strings.Split(raw, ",")
-	prefixes := make([]netip.Prefix, 0, len(parts))
-	for _, part := range parts {
-		part = strings.TrimSpace(part)
-		if part == "" {
-			continue
-		}
-
-		prefix, err := netip.ParsePrefix(part)
-		if err == nil {
-			prefixes = append(prefixes, prefix)
-			continue
-		}
-
-		addr, addrErr := netip.ParseAddr(part)
-		if addrErr != nil {
-			return nil, fmt.Errorf("parse trusted proxy %q: not a valid CIDR or IP: %w", part, addrErr)
-		}
-
-		bits := 32
-		if addr.Is6() {
-			bits = 128
-		}
-		prefixes = append(prefixes, netip.PrefixFrom(addr, bits))
-	}
-	return prefixes, nil
-}

proxy/trustedproxy_test.go

@@ -1,90 +0,0 @@
-package proxy
-
-import (
-	"net/netip"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestParseTrustedProxies(t *testing.T) {
-	tests := []struct {
-		name    string
-		raw     string
-		want    []netip.Prefix
-		wantErr bool
-	}{
-		{
-			name: "empty string returns nil",
-			raw:  "",
-			want: nil,
-		},
-		{
-			name: "single CIDR",
-			raw:  "10.0.0.0/8",
-			want: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
-		},
-		{
-			name: "single bare IPv4",
-			raw:  "1.2.3.4",
-			want: []netip.Prefix{netip.MustParsePrefix("1.2.3.4/32")},
-		},
-		{
-			name: "single bare IPv6",
-			raw:  "::1",
-			want: []netip.Prefix{netip.MustParsePrefix("::1/128")},
-		},
-		{
-			name: "comma-separated CIDRs",
-			raw:  "10.0.0.0/8, 192.168.1.0/24",
-			want: []netip.Prefix{
-				netip.MustParsePrefix("10.0.0.0/8"),
-				netip.MustParsePrefix("192.168.1.0/24"),
-			},
-		},
-		{
-			name: "mixed CIDRs and bare IPs",
-			raw:  "10.0.0.0/8, 1.2.3.4, fd00::/8",
-			want: []netip.Prefix{
-				netip.MustParsePrefix("10.0.0.0/8"),
-				netip.MustParsePrefix("1.2.3.4/32"),
-				netip.MustParsePrefix("fd00::/8"),
-			},
-		},
-		{
-			name: "whitespace around entries",
-			raw:  "  10.0.0.0/8 , 192.168.0.0/16  ",
-			want: []netip.Prefix{
-				netip.MustParsePrefix("10.0.0.0/8"),
-				netip.MustParsePrefix("192.168.0.0/16"),
-			},
-		},
-		{
-			name: "trailing comma produces no extra entry",
-			raw:  "10.0.0.0/8,",
-			want: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
-		},
-		{
-			name:    "invalid entry",
-			raw:     "not-an-ip",
-			wantErr: true,
-		},
-		{
-			name:    "partially invalid",
-			raw:     "10.0.0.0/8, garbage",
-			wantErr: true,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got, err := ParseTrustedProxies(tt.raw)
-			if tt.wantErr {
-				require.Error(t, err)
-				return
-			}
-			require.NoError(t, err)
-			assert.Equal(t, tt.want, got)
-		})
-	}
-}

relay/cmd/root.go

@@ -24,6 +24,7 @@ import (
 	"github.com/netbirdio/netbird/shared/metrics"
 	"github.com/netbirdio/netbird/shared/relay/auth"
 	"github.com/netbirdio/netbird/stun"
+	"github.com/netbirdio/netbird/trustedproxy"
 	"github.com/netbirdio/netbird/util"
 )
 
@@ -45,6 +46,9 @@ type Config struct {
 	LogLevel                 string
 	LogFile                  string
 	HealthcheckListenAddress string
+	// TrustedProxies is a comma-separated list of upstream proxy CIDRs/IPs whose
+	// X-Real-Ip/X-Real-Port headers are trusted. Empty means never trust these headers.
+	TrustedProxies string
 	// STUN server configuration
 	EnableSTUN   bool
 	STUNPorts    []int
@@ -116,6 +120,7 @@ func init() {
 	rootCmd.PersistentFlags().StringVar(&cobraConfig.LogLevel, "log-level", "info", "log level")
 	rootCmd.PersistentFlags().StringVar(&cobraConfig.LogFile, "log-file", "console", "log file")
 	rootCmd.PersistentFlags().StringVarP(&cobraConfig.HealthcheckListenAddress, "health-listen-address", "H", ":9000", "listen address of healthcheck server")
+	rootCmd.PersistentFlags().StringVar(&cobraConfig.TrustedProxies, "trusted-proxies", "", "comma-separated list of upstream proxy CIDRs or IPs whose X-Real-Ip/X-Real-Port headers are trusted; leave empty to always use the direct connection address")
 	rootCmd.PersistentFlags().BoolVar(&cobraConfig.EnableSTUN, "enable-stun", false, "enable embedded STUN server")
 	rootCmd.PersistentFlags().IntSliceVar(&cobraConfig.STUNPorts, "stun-ports", []int{3478}, "ports for the embedded STUN server (can be specified multiple times or comma-separated)")
 	rootCmd.PersistentFlags().StringVar(&cobraConfig.STUNLogLevel, "stun-log-level", "info", "log level for STUN server (panic, fatal, error, warn, info, debug, trace)")
@@ -155,8 +160,15 @@ func execute(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("setup metrics: %v", err)
 	}
 
+	trustedProxies, err := trustedproxy.Parse(cobraConfig.TrustedProxies)
+	if err != nil {
+		log.Debugf("failed to parse trusted proxies: %s", err)
+		return fmt.Errorf("failed to parse trusted proxies: %s", err)
+	}
+
 	srvListenerCfg := server.ListenerConfig{
-		Address: cobraConfig.ListenAddress,
+		Address:        cobraConfig.ListenAddress,
+		TrustedProxies: trustedProxies,
 	}
 
 	tlsConfig, tlsSupport, err := handleTLSConfig(cobraConfig)
@@ -173,7 +185,7 @@ func execute(cmd *cobra.Command, args []string) error {
 	}
 
 	hashedSecret := sha256.Sum256([]byte(cobraConfig.AuthSecret))
-	authenticator := auth.NewTimedHMACValidator(hashedSecret[:], 24*time.Hour)
+	authenticator := auth.NewTimedHMACValidator(hashedSecret[:])
 
 	cfg := server.Config{
 		Meter:          metricsServer.Meter,

relay/server/handshake.go

@@ -5,14 +5,8 @@ import (
 	"fmt"
 	"time"
 
-	log "github.com/sirupsen/logrus"
-
 	"github.com/netbirdio/netbird/relay/server/listener"
 	"github.com/netbirdio/netbird/shared/relay/messages"
-	//nolint:staticcheck
-	"github.com/netbirdio/netbird/shared/relay/messages/address"
-	//nolint:staticcheck
-	authmsg "github.com/netbirdio/netbird/shared/relay/messages/auth"
 )
 
 const (
@@ -23,55 +17,30 @@ const (
 
 type Validator interface {
 	Validate(any) error
-	// Deprecated: Use Validate instead.
-	ValidateHelloMsgType(any) error
 }
 
-// preparedMsg contains the marshalled success response messages
+// preparedMsg contains the marshalled success response message
 type preparedMsg struct {
-	responseHelloMsg []byte
-	responseAuthMsg  []byte
+	responseAuthMsg []byte
 }
 
 func newPreparedMsg(instanceURL string) (*preparedMsg, error) {
-	rhm, err := marshalResponseHelloMsg(instanceURL)
-	if err != nil {
-		return nil, err
-	}
-
 	ram, err := messages.MarshalAuthResponse(instanceURL)
 	if err != nil {
 		return nil, fmt.Errorf("failed to marshal auth response msg: %w", err)
 	}
 
 	return &preparedMsg{
-		responseHelloMsg: rhm,
-		responseAuthMsg:  ram,
+		responseAuthMsg: ram,
 	}, nil
 }
 
-func marshalResponseHelloMsg(instanceURL string) ([]byte, error) {
-	addr := &address.Address{URL: instanceURL}
-	addrData, err := addr.Marshal()
-	if err != nil {
-		return nil, fmt.Errorf("failed to marshal response address: %w", err)
-	}
-
-	//nolint:staticcheck
-	responseMsg, err := messages.MarshalHelloResponse(addrData)
-	if err != nil {
-		return nil, fmt.Errorf("failed to marshal hello response: %w", err)
-	}
-	return responseMsg, nil
-}
-
 type handshake struct {
 	conn        listener.Conn
 	validator   Validator
 	preparedMsg *preparedMsg
 
-	handshakeMethodAuth bool
-	peerID              *messages.PeerID
+	peerID *messages.PeerID
 }
 
 func (h *handshake) handshakeReceive(ctx context.Context) (*messages.PeerID, error) {
@@ -93,17 +62,11 @@ func (h *handshake) handshakeReceive(ctx context.Context) (*messages.PeerID, err
 		return nil, fmt.Errorf("determine message type from %s: %w", h.conn.RemoteAddr(), err)
 	}
 
-	var peerID *messages.PeerID
-	switch msgType {
-	//nolint:staticcheck
-	case messages.MsgTypeHello:
-		peerID, err = h.handleHelloMsg(buf)
-	case messages.MsgTypeAuth:
-		h.handshakeMethodAuth = true
-		peerID, err = h.handleAuthMsg(buf)
-	default:
+	if msgType != messages.MsgTypeAuth {
 		return nil, fmt.Errorf("invalid message type %d from %s", msgType, h.conn.RemoteAddr())
 	}
+
+	peerID, err := h.handleAuthMsg(buf)
 	if err != nil {
 		return peerID, err
 	}
@@ -112,46 +75,17 @@ func (h *handshake) handshakeReceive(ctx context.Context) (*messages.PeerID, err
 }
 
 func (h *handshake) handshakeResponse(ctx context.Context) error {
-	var responseMsg []byte
-	if h.handshakeMethodAuth {
-		responseMsg = h.preparedMsg.responseAuthMsg
-	} else {
-		responseMsg = h.preparedMsg.responseHelloMsg
-	}
-
-	if _, err := h.conn.Write(ctx, responseMsg); err != nil {
+	if _, err := h.conn.Write(ctx, h.preparedMsg.responseAuthMsg); err != nil {
 		return fmt.Errorf("handshake response write to %s (%s): %w", h.peerID, h.conn.RemoteAddr(), err)
 	}
 
 	return nil
 }
 
-func (h *handshake) handleHelloMsg(buf []byte) (*messages.PeerID, error) {
-	//nolint:staticcheck
-	peerID, authData, err := messages.UnmarshalHelloMsg(buf)
-	if err != nil {
-		return nil, fmt.Errorf("unmarshal hello message: %w", err)
-	}
-
-	log.Warnf("peer %s (%s) is using deprecated initial message type", peerID, h.conn.RemoteAddr())
-
-	authMsg, err := authmsg.UnmarshalMsg(authData)
-	if err != nil {
-		return nil, fmt.Errorf("unmarshal auth message: %w", err)
-	}
-
-	//nolint:staticcheck
-	if err := h.validator.ValidateHelloMsgType(authMsg.AdditionalData); err != nil {
-		return nil, fmt.Errorf("validate %s (%s): %w", peerID, h.conn.RemoteAddr(), err)
-	}
-
-	return peerID, nil
-}
-
 func (h *handshake) handleAuthMsg(buf []byte) (*messages.PeerID, error) {
 	rawPeerID, authPayload, err := messages.UnmarshalAuthMsg(buf)
 	if err != nil {
-		return nil, fmt.Errorf("unmarshal hello message: %w", err)
+		return nil, fmt.Errorf("unmarshal auth message: %w", err)
 	}
 
 	if err := h.validator.Validate(authPayload); err != nil {

relay/server/listener/ws/listener.go

@@ -15,6 +15,7 @@ import (
 	"github.com/netbirdio/netbird/relay/protocol"
 	relaylistener "github.com/netbirdio/netbird/relay/server/listener"
 	"github.com/netbirdio/netbird/shared/relay"
+	"github.com/netbirdio/netbird/trustedproxy"
 )
 
 const (
@@ -27,6 +28,9 @@ type Listener struct {
 	Address string
 	// TLSConfig is the TLS configuration for the server.
 	TLSConfig *tls.Config
+	// TrustedProxies is the set of upstream proxies whose X-Real-Ip/X-Real-Port
+	// headers are trusted. Headers from any other immediate peer are ignored.
+	TrustedProxies *trustedproxy.List
 
 	server   *http.Server
 	acceptFn func(conn relaylistener.Conn)
@@ -75,7 +79,7 @@ func (l *Listener) Shutdown(ctx context.Context) error {
 }
 
 func (l *Listener) onAccept(w http.ResponseWriter, r *http.Request) {
-	connRemoteAddr := remoteAddr(r)
+	connRemoteAddr := remoteAddr(r, l.TrustedProxies)
 
 	acceptOptions := &websocket.AcceptOptions{
 		OriginPatterns: []string{"*"},
@@ -102,9 +106,17 @@ func (l *Listener) onAccept(w http.ResponseWriter, r *http.Request) {
 	l.acceptFn(conn)
 }
 
-func remoteAddr(r *http.Request) string {
-	if r.Header.Get("X-Real-Ip") == "" || r.Header.Get("X-Real-Port") == "" {
+func remoteAddr(r *http.Request, trustedProxies *trustedproxy.List) string {
+	realIP := r.Header.Get("X-Real-Ip")
+	realPort := r.Header.Get("X-Real-Port")
+	if realIP == "" || realPort == "" {
 		return r.RemoteAddr
 	}
-	return net.JoinHostPort(r.Header.Get("X-Real-Ip"), r.Header.Get("X-Real-Port"))
+
+	if !trustedProxies.IsTrusted(r.RemoteAddr) {
+		log.Debugf("ignoring X-Real-Ip header from untrusted peer %s", r.RemoteAddr)
+		return r.RemoteAddr
+	}
+
+	return net.JoinHostPort(realIP, realPort)
 }

relay/server/server.go

@@ -15,14 +15,17 @@ import (
 	"github.com/netbirdio/netbird/relay/server/listener/quic"
 	"github.com/netbirdio/netbird/relay/server/listener/ws"
 	quictls "github.com/netbirdio/netbird/shared/relay/tls"
+	"github.com/netbirdio/netbird/trustedproxy"
 )
 
 // ListenerConfig is the configuration for the listener.
 // Address: the address to bind the listener to. It could be an address behind a reverse proxy.
 // TLSConfig: the TLS configuration for the listener.
+// TrustedProxies: upstream proxy prefixes whose forwarding headers (X-Real-Ip/X-Real-Port) are trusted.
 type ListenerConfig struct {
-	Address   string
-	TLSConfig *tls.Config
+	Address        string
+	TLSConfig      *tls.Config
+	TrustedProxies *trustedproxy.List
 }
 
 // Server is the main entry point for the relay server.
@@ -62,8 +65,9 @@ func NewServer(config Config) (*Server, error) {
 // Listen starts the relay server.
 func (r *Server) Listen(cfg ListenerConfig) error {
 	wSListener := &ws.Listener{
-		Address:   cfg.Address,
-		TLSConfig: cfg.TLSConfig,
+		Address:        cfg.Address,
+		TLSConfig:      cfg.TLSConfig,
+		TrustedProxies: cfg.TrustedProxies,
 	}
 
 	r.listenerMux.Lock()

shared/management/http/api/openapi.yml

@@ -5164,6 +5164,10 @@ components:
           type: boolean
           description: Whether upstream TLS certificate verification is skipped when the proxy dials this provider's URL. Intended for self-hosted / internal gateways behind a private or self-signed certificate.
           example: false
+        metadata_disabled:
+          type: boolean
+          description: Whether identity metadata injection is disabled for this provider. When enabled (the default), the proxy stamps the caller's user and authorizing group onto upstream requests as provider-specific metadata (e.g. AWS Bedrock's X-Amzn-Bedrock-Request-Metadata header). Set true to suppress it.
+          example: false
         created_at:
           type: string
           format: date-time
@@ -5184,6 +5188,7 @@ components:
         - models
         - enabled
         - skip_tls_verification
+        - metadata_disabled
         - created_at
         - updated_at
     AgentNetworkProviderRequest:
@@ -5240,6 +5245,10 @@ components:
           type: boolean
           description: Skip upstream TLS certificate verification when the proxy dials this provider's URL. For self-hosted / internal gateways behind a private or self-signed certificate. Defaults to false. When omitted on update, the stored value is left unchanged.
           example: false
+        metadata_disabled:
+          type: boolean
+          description: Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected). When omitted on update, the stored value is left unchanged.
+          example: false
       required:
         - provider_id
         - name

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

@@ -2227,6 +2227,9 @@ type AgentNetworkProvider struct {
 	// IdentityHeaderUserId Wire header name the proxy stamps with the caller's display identity (user email or peer name) when the catalog entry's HeaderPair is `customizable`. Empty disables stamping for this dimension. Ignored when the catalog entry has a fixed HeaderPair (e.g. LiteLLM, Portkey). Used today by Bifrost: typical values are `x-bf-lh-netbird_user_id` (always-on log metadata) or `x-bf-dim-netbird_user_id` (Prometheus / OTEL — requires the label to be pre-declared in the gateway's `client.prometheus_labels` config).
 	IdentityHeaderUserId *string `json:"identity_header_user_id,omitempty"`
 
+	// MetadataDisabled Whether identity metadata injection is disabled for this provider. When enabled (the default), the proxy stamps the caller's user and authorizing group onto upstream requests as provider-specific metadata (e.g. AWS Bedrock's X-Amzn-Bedrock-Request-Metadata header). Set true to suppress it.
+	MetadataDisabled bool `json:"metadata_disabled"`
+
 	// Models Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
 	Models []AgentNetworkProviderModel `json:"models"`
 
@@ -2278,6 +2281,9 @@ type AgentNetworkProviderRequest struct {
 	// IdentityHeaderUserId Wire header name for the caller's display identity. See AgentNetworkProvider.identity_header_user_id. When omitted on a request, the stored value is left unchanged; pass an empty string explicitly to clear it (which disables stamping for this dimension).
 	IdentityHeaderUserId *string `json:"identity_header_user_id,omitempty"`
 
+	// MetadataDisabled Disable identity metadata injection (the caller's user + authorizing group) for this provider. Defaults to false (metadata is injected). When omitted on update, the stored value is left unchanged.
+	MetadataDisabled *bool `json:"metadata_disabled,omitempty"`
+
 	// Models Models exposed through this endpoint, with the operator's per-1k input/output prices. Empty means all catalog models are allowed at catalog prices.
 	Models *[]AgentNetworkProviderModel `json:"models,omitempty"`
 

shared/relay/auth/allow/allow_all.go

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

shared/relay/auth/hmac/token.go

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

shared/relay/auth/hmac/validator.go

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

shared/relay/auth/validator.go

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

shared/relay/client/fallback_opener.go

@@ -0,0 +1,176 @@
+package client
+
+import (
+	"context"
+	"errors"
+	"net"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	raceTotalTimeout  = 40 * time.Second
+	raceFallbackDelay = 10 * time.Second
+)
+
+type raceAttempt struct {
+	conn net.Conn
+	err  error
+}
+
+type raceOutcome struct {
+	conn net.Conn
+	err  error
+	done bool
+}
+
+type connRace struct {
+	opener            *FallbackOpener
+	peerKey           string
+	remoteRelayServer RelayServer
+	preferForeign     bool
+
+	raceCtx         context.Context
+	otherCtx        context.Context
+	cancelPreferred context.CancelFunc
+	cancelOther     context.CancelFunc
+	results         chan raceAttempt
+	fallbackTimer   *time.Timer
+
+	otherStarted bool
+	settled      int
+	lastErr      error
+}
+
+type FallbackOpener struct {
+	home         *Client
+	foreignStore *ForeignRelaysStore
+
+	fallbackDelay time.Duration
+	totalTimeout  time.Duration
+	// openFn performs a single attempt. It is overridable in tests; when nil the
+	// real home/foreign dispatch in open is used.
+	openFn func(ctx context.Context, peerKey string, remoteRelayServer RelayServer, foreign bool) raceAttempt
+}
+
+func NewFallbackOpener(home *Client, foreignStore *ForeignRelaysStore) *FallbackOpener {
+	return &FallbackOpener{
+		home:          home,
+		foreignStore:  foreignStore,
+		fallbackDelay: raceFallbackDelay,
+		totalTimeout:  raceTotalTimeout,
+	}
+}
+
+func (r *FallbackOpener) Run(ctx context.Context, peerKey string, remoteRelayServer RelayServer, preferForeign bool) (net.Conn, error) {
+	raceCtx, cancel := context.WithTimeout(ctx, r.totalTimeout)
+	defer cancel()
+
+	preferredCtx, cancelPreferred := context.WithCancel(raceCtx)
+	otherCtx, cancelOther := context.WithCancel(raceCtx)
+
+	race := &connRace{
+		opener:            r,
+		peerKey:           peerKey,
+		remoteRelayServer: remoteRelayServer,
+		preferForeign:     preferForeign,
+		raceCtx:           raceCtx,
+		otherCtx:          otherCtx,
+		cancelPreferred:   cancelPreferred,
+		cancelOther:       cancelOther,
+		results:           make(chan raceAttempt, 2),
+		fallbackTimer:     time.NewTimer(r.fallbackDelay),
+	}
+	defer race.fallbackTimer.Stop()
+
+	go func() {
+		race.results <- r.open(preferredCtx, peerKey, remoteRelayServer, preferForeign)
+	}()
+
+	for {
+		select {
+		case <-race.fallbackTimer.C:
+			race.startOther()
+		case res := <-race.results:
+			if o := race.handleResult(res); o.done {
+				return o.conn, o.err
+			}
+		case <-raceCtx.Done():
+			return race.onTimeout()
+		}
+	}
+}
+
+func (c *connRace) startOther() {
+	if c.otherStarted {
+		return
+	}
+	c.otherStarted = true
+	c.fallbackTimer.Stop()
+	go func() {
+		c.results <- c.opener.open(c.otherCtx, c.peerKey, c.remoteRelayServer, !c.preferForeign)
+	}()
+}
+
+func (c *connRace) handleResult(res raceAttempt) raceOutcome {
+	if (res.err == nil && res.conn != nil) || errors.Is(res.err, ErrConnAlreadyExists) {
+		c.settled++
+		c.stop()
+		return raceOutcome{conn: res.conn, err: res.err, done: true}
+	}
+
+	c.lastErr = res.err
+	c.settled++
+	if !c.otherStarted {
+		c.startOther()
+		return raceOutcome{}
+	}
+	if c.settled == 2 {
+		c.cancelPreferred()
+		c.cancelOther()
+		return raceOutcome{err: c.lastErr, done: true}
+	}
+	return raceOutcome{}
+}
+
+func (c *connRace) onTimeout() (net.Conn, error) {
+	c.stop()
+	if c.lastErr != nil {
+		return nil, c.lastErr
+	}
+	return nil, c.raceCtx.Err()
+}
+
+func (c *connRace) stop() {
+	c.cancelPreferred()
+	c.cancelOther()
+	go c.opener.drainLoser(c.results, c.settled, c.otherStarted)
+}
+
+func (r *FallbackOpener) open(ctx context.Context, peerKey string, remoteRelayServer RelayServer, foreign bool) raceAttempt {
+	if r.openFn != nil {
+		return r.openFn(ctx, peerKey, remoteRelayServer, foreign)
+	}
+	if foreign {
+		conn, err := r.foreignStore.OpenConn(ctx, peerKey, remoteRelayServer)
+		return raceAttempt{conn: conn, err: err}
+	}
+	conn, err := r.home.OpenConn(ctx, peerKey)
+	return raceAttempt{conn: conn, err: err}
+}
+
+func (r *FallbackOpener) drainLoser(results chan raceAttempt, settled int, otherStarted bool) {
+	started := 1
+	if otherStarted {
+		started = 2
+	}
+	for i := settled; i < started; i++ {
+		res := <-results
+		if res.conn != nil {
+			if err := res.conn.Close(); err != nil {
+				log.Debugf("failed to close losing relay connection: %v", err)
+			}
+		}
+	}
+}

shared/relay/client/fallback_opener_test.go

@@ -0,0 +1,450 @@
+package client
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// The FallbackOpener race is driven by a single goroutine (Run's select loop)
+// with worker goroutines that communicate only through the buffered results
+// channel and the two cancel contexts. These tests exercise that state machine
+// in isolation via an injected openFn, so no relay server or network is needed.
+// Timing is scaled down through the fallbackDelay/totalTimeout fields.
+
+// raceFakeConn tracks whether Close was called. Only Close is exercised by the
+// race logic (drainLoser closes losers; Run returns the winner untouched).
+type raceFakeConn struct {
+	net.Conn
+	label  string
+	closed atomic.Bool
+}
+
+func (c *raceFakeConn) Close() error {
+	c.closed.Store(true)
+	return nil
+}
+
+// raceAttemptScript describes how a single scripted attempt behaves.
+type raceAttemptScript struct {
+	delay time.Duration
+	conn  *raceFakeConn // non-nil => the attempt succeeds and returns this conn
+	err   error         // returned when conn is nil
+	// ignoreCtx makes the attempt complete after delay even if its context is
+	// cancelled. It models an OpenConn that produced a real connection right as
+	// the race cancelled it - exactly the case drainLoser must clean up.
+	ignoreCtx bool
+}
+
+// fakeOpener replaces FallbackOpener.open. Scripts are keyed by the foreign
+// flag, so which script is "preferred" depends on the preferForeign argument
+// passed to Run.
+type fakeOpener struct {
+	mu      sync.Mutex
+	scripts map[bool]raceAttemptScript
+	calls   []bool // foreign flag of each open() invocation, in order
+}
+
+func (f *fakeOpener) open(ctx context.Context, _ string, _ RelayServer, foreign bool) raceAttempt {
+	f.mu.Lock()
+	f.calls = append(f.calls, foreign)
+	s, ok := f.scripts[foreign]
+	f.mu.Unlock()
+	if !ok {
+		return raceAttempt{err: fmt.Errorf("no script for foreign=%v", foreign)}
+	}
+
+	if s.delay > 0 {
+		timer := time.NewTimer(s.delay)
+		defer timer.Stop()
+		if s.ignoreCtx {
+			<-timer.C
+		} else {
+			select {
+			case <-timer.C:
+			case <-ctx.Done():
+				return raceAttempt{err: ctx.Err()}
+			}
+		}
+	}
+
+	if s.conn != nil {
+		return raceAttempt{conn: s.conn}
+	}
+	return raceAttempt{err: s.err}
+}
+
+func (f *fakeOpener) callCount() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return len(f.calls)
+}
+
+func (f *fakeOpener) firstCallForeign(t *testing.T) bool {
+	t.Helper()
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	require.NotEmpty(t, f.calls, "expected at least one open attempt")
+	return f.calls[0]
+}
+
+func newTestOpener(f *fakeOpener, fallbackDelay, totalTimeout time.Duration) *FallbackOpener {
+	o := NewFallbackOpener(nil, nil)
+	o.openFn = f.open
+	o.fallbackDelay = fallbackDelay
+	o.totalTimeout = totalTimeout
+	return o
+}
+
+const (
+	// controller prefers the home relay, i.e. preferForeign == false.
+	preferHome    = false
+	preferForeign = true
+)
+
+var errAttempt = errors.New("attempt failed")
+
+// The preferred attempt wins before the fallback timer fires, so the other
+// attempt is never started.
+func TestFallbackOpener_PreferredWinsImmediately(t *testing.T) {
+	homeConn := &raceFakeConn{label: "home"}
+	foreignConn := &raceFakeConn{label: "foreign"}
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		false: {conn: homeConn},                            // preferred (home): instant success
+		true:  {delay: 5 * time.Second, conn: foreignConn}, // would never finish in time
+	}}
+	o := newTestOpener(f, 40*time.Millisecond, 2*time.Second)
+
+	conn, err := o.Run(context.Background(), "peer", RelayServer{Addr: "srv"}, preferHome)
+
+	require.NoError(t, err)
+	require.Same(t, homeConn, conn)
+	assert.Equal(t, 1, f.callCount(), "other attempt must not start when preferred wins first")
+	assert.False(t, f.firstCallForeign(t), "home must be tried first when preferring home")
+	assert.False(t, foreignConn.closed.Load())
+}
+
+// preferForeign flips which relay is tried first.
+func TestFallbackOpener_PreferForeignRoutesForeignFirst(t *testing.T) {
+	foreignConn := &raceFakeConn{label: "foreign"}
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		true:  {conn: foreignConn}, // preferred (foreign): instant success
+		false: {delay: 5 * time.Second, conn: &raceFakeConn{}},
+	}}
+	o := newTestOpener(f, 40*time.Millisecond, 2*time.Second)
+
+	conn, err := o.Run(context.Background(), "peer", RelayServer{Addr: "srv"}, preferForeign)
+
+	require.NoError(t, err)
+	require.Same(t, foreignConn, conn)
+	assert.Equal(t, 1, f.callCount())
+	assert.True(t, f.firstCallForeign(t), "foreign must be tried first when preferring foreign")
+}
+
+// ErrConnAlreadyExists counts as success: Run returns it and does not start the
+// other attempt.
+func TestFallbackOpener_ErrConnAlreadyExistsIsSuccess(t *testing.T) {
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		false: {err: ErrConnAlreadyExists},
+		true:  {delay: 5 * time.Second, conn: &raceFakeConn{}},
+	}}
+	o := newTestOpener(f, 40*time.Millisecond, 2*time.Second)
+
+	conn, err := o.Run(context.Background(), "peer", RelayServer{Addr: "srv"}, preferHome)
+
+	require.ErrorIs(t, err, ErrConnAlreadyExists)
+	assert.Nil(t, conn)
+	assert.Equal(t, 1, f.callCount(), "other attempt must not start on ErrConnAlreadyExists")
+}
+
+// A preferred failure starts the other attempt immediately, without waiting for
+// the fallback timer.
+func TestFallbackOpener_PreferredFailsStartsOtherBeforeTimer(t *testing.T) {
+	foreignConn := &raceFakeConn{label: "foreign"}
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		false: {err: errAttempt}, // preferred fails instantly
+		true:  {delay: 5 * time.Millisecond, conn: foreignConn},
+	}}
+	fallbackDelay := 500 * time.Millisecond
+	o := newTestOpener(f, fallbackDelay, 2*time.Second)
+
+	start := time.Now()
+	conn, err := o.Run(context.Background(), "peer", RelayServer{Addr: "srv"}, preferHome)
+	elapsed := time.Since(start)
+
+	require.NoError(t, err)
+	require.Same(t, foreignConn, conn)
+	assert.Equal(t, 2, f.callCount())
+	assert.Less(t, elapsed, fallbackDelay/2, "fallback must not wait for the timer after a preferred failure")
+}
+
+// When the preferred attempt is slow, the fallback timer starts the other
+// attempt and its success wins.
+func TestFallbackOpener_TimerStartsOtherWhenPreferredSlow(t *testing.T) {
+	foreignConn := &raceFakeConn{label: "foreign"}
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		false: {delay: 5 * time.Second}, // preferred hangs until cancelled
+		true:  {delay: 5 * time.Millisecond, conn: foreignConn},
+	}}
+	fallbackDelay := 40 * time.Millisecond
+	o := newTestOpener(f, fallbackDelay, 2*time.Second)
+
+	start := time.Now()
+	conn, err := o.Run(context.Background(), "peer", RelayServer{Addr: "srv"}, preferHome)
+	elapsed := time.Since(start)
+
+	require.NoError(t, err)
+	require.Same(t, foreignConn, conn)
+	assert.Equal(t, 2, f.callCount())
+	assert.GreaterOrEqual(t, elapsed, fallbackDelay, "other must not start before the fallback timer fires")
+}
+
+// Both attempts fail: Run returns the last error and tries both relays.
+func TestFallbackOpener_BothFail(t *testing.T) {
+	errOther := errors.New("other failed")
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		false: {err: errAttempt},
+		true:  {err: errOther},
+	}}
+	o := newTestOpener(f, 40*time.Millisecond, 2*time.Second)
+
+	conn, err := o.Run(context.Background(), "peer", RelayServer{Addr: "srv"}, preferHome)
+
+	require.Error(t, err)
+	assert.Nil(t, conn)
+	assert.ErrorIs(t, err, errOther, "the most recent error should be surfaced")
+	assert.Equal(t, 2, f.callCount())
+}
+
+// When both attempts succeed, drainLoser must close the losing connection so it
+// is not leaked. Here the preferred attempt wins and the foreign loser - which
+// produced a real conn despite being cancelled - is closed.
+func TestFallbackOpener_DoubleSuccessClosesLoser(t *testing.T) {
+	homeConn := &raceFakeConn{label: "home"}
+	foreignConn := &raceFakeConn{label: "foreign"}
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		false: {delay: 30 * time.Millisecond, conn: homeConn},                     // preferred wins
+		true:  {delay: 80 * time.Millisecond, conn: foreignConn, ignoreCtx: true}, // loser yields a conn after cancel
+	}}
+	o := newTestOpener(f, 15*time.Millisecond, 2*time.Second)
+
+	conn, err := o.Run(context.Background(), "peer", RelayServer{Addr: "srv"}, preferHome)
+
+	require.NoError(t, err)
+	require.Same(t, homeConn, conn)
+	assert.Equal(t, 2, f.callCount())
+	assert.False(t, homeConn.closed.Load(), "the winning connection must not be closed")
+	require.Eventually(t, foreignConn.closed.Load, time.Second, 5*time.Millisecond,
+		"the losing connection must be closed by drainLoser")
+}
+
+// Winner selection is purely by result arrival order, not by preference: when
+// the non-preferred attempt returns first it wins even though home was
+// preferred. This is the mechanism behind the split-relay concern - two peers
+// racing independently have no shared tie-break, so under adversarial timing
+// they can settle on different relays. Documented here as current behavior.
+func TestFallbackOpener_FasterOtherWinsDespitePreference(t *testing.T) {
+	homeConn := &raceFakeConn{label: "home"}
+	foreignConn := &raceFakeConn{label: "foreign"}
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		false: {delay: 60 * time.Millisecond, conn: homeConn, ignoreCtx: true}, // preferred but slower
+		true:  {delay: 5 * time.Millisecond, conn: foreignConn},                // other is faster
+	}}
+	o := newTestOpener(f, 15*time.Millisecond, 2*time.Second)
+
+	conn, err := o.Run(context.Background(), "peer", RelayServer{Addr: "srv"}, preferHome)
+
+	require.NoError(t, err)
+	require.Same(t, foreignConn, conn, "the first successful attempt wins regardless of preference")
+	require.Eventually(t, homeConn.closed.Load, time.Second, 5*time.Millisecond,
+		"the slower preferred attempt becomes the loser and is closed")
+}
+
+// The whole race is bounded by totalTimeout. With no attempt succeeding or
+// failing, Run returns the deadline error.
+func TestFallbackOpener_TotalTimeout(t *testing.T) {
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		false: {delay: 5 * time.Second},
+		true:  {delay: 5 * time.Second},
+	}}
+	o := newTestOpener(f, 20*time.Millisecond, 80*time.Millisecond)
+
+	conn, err := o.Run(context.Background(), "peer", RelayServer{Addr: "srv"}, preferHome)
+
+	require.Error(t, err)
+	assert.Nil(t, conn)
+	assert.ErrorIs(t, err, context.DeadlineExceeded)
+}
+
+// Cancelling the caller's context aborts the race promptly with the cancel
+// error, even before the fallback timer would fire.
+func TestFallbackOpener_ParentContextCanceled(t *testing.T) {
+	f := &fakeOpener{scripts: map[bool]raceAttemptScript{
+		false: {delay: 5 * time.Second},
+		true:  {delay: 5 * time.Second},
+	}}
+	// fallbackDelay large so the timer never fires; only the parent cancel ends the race.
+	o := newTestOpener(f, 5*time.Second, 5*time.Second)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	go func() {
+		time.Sleep(20 * time.Millisecond)
+		cancel()
+	}()
+
+	start := time.Now()
+	conn, err := o.Run(ctx, "peer", RelayServer{Addr: "srv"}, preferHome)
+
+	require.Error(t, err)
+	assert.Nil(t, conn)
+	assert.ErrorIs(t, err, context.Canceled)
+	assert.Less(t, time.Since(start), time.Second, "must return shortly after the parent context is cancelled")
+	assert.Equal(t, 1, f.callCount(), "the other attempt must not start")
+}
+
+// rendezvous models the relay-level requirement that a relayed connection is
+// established only once BOTH peers subscribe to the same relay server. arrive
+// records a peer's presence on a relay and returns a channel that closes when
+// the second peer arrives, so an attempt can only complete after a real
+// rendezvous - the same coupling the production code depends on.
+type rendezvous struct {
+	mu       sync.Mutex
+	arrivals map[string]int
+	gates    map[string]chan struct{}
+}
+
+func newRendezvous() *rendezvous {
+	return &rendezvous{arrivals: map[string]int{}, gates: map[string]chan struct{}{}}
+}
+
+func (r *rendezvous) arrive(relay string) <-chan struct{} {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	g, ok := r.gates[relay]
+	if !ok {
+		g = make(chan struct{})
+		r.gates[relay] = g
+	}
+	r.arrivals[relay]++
+	if r.arrivals[relay] == 2 {
+		close(g)
+	}
+	return g
+}
+
+// splitPeer is one peer's view of the two relays. relayFor maps the foreign
+// flag to a relay name; postDelay is how long after the rendezvous that peer's
+// OpenConn takes to return (its per-relay subscribe latency). Different values
+// per peer model the asymmetric timing that triggers finding #1.
+type splitPeer struct {
+	rv        *rendezvous
+	relayFor  map[bool]string
+	postDelay map[string]time.Duration
+}
+
+func (p *splitPeer) open(ctx context.Context, _ string, _ RelayServer, foreign bool) raceAttempt {
+	relay := p.relayFor[foreign]
+
+	select {
+	case <-p.rv.arrive(relay):
+	case <-ctx.Done():
+		return raceAttempt{err: ctx.Err()}
+	}
+
+	timer := time.NewTimer(p.postDelay[relay])
+	defer timer.Stop()
+	select {
+	case <-timer.C:
+	case <-ctx.Done():
+		return raceAttempt{err: ctx.Err()}
+	}
+	return raceAttempt{conn: &raceFakeConn{label: relay}}
+}
+
+// TestFallbackOpener_SplitRelaySelection reproduces finding #1: the two peers
+// run FallbackOpener.Run independently with no shared tie-break, so the winner
+// is chosen purely by local result-arrival order. Under an adversarial - but
+// self-consistent - timing profile they settle on DIFFERENT relays.
+//
+// Both peers prefer relayA (the controller's home). The split needs each peer's
+// preferred relayA to be slow enough that both start their fallback (so both
+// relays actually rendezvous), and then each peer's fast path to be a different
+// relay:
+//   - peerA: relayA slow (abandoned), relayB fast  -> peerA wins relayB
+//   - peerB: relayA fast (wins),      relayB slow  -> peerB wins relayA
+//
+// Each winner then cancels its attempt on the relay the OTHER peer actually
+// kept, leaving two half-open relayed connections that were both reported as
+// successful. When a deterministic cross-peer tie-break is added to fix this,
+// invert the assertion below to require convergence.
+func TestFallbackOpener_SplitRelaySelection(t *testing.T) {
+	const (
+		relayA = "relayA" // controller's home relay; both peers prefer it
+		relayB = "relayB" // non-controller's home relay
+	)
+	rv := newRendezvous()
+
+	peerA := &splitPeer{
+		rv:       rv,
+		relayFor: map[bool]string{false: relayA, true: relayB}, // home=relayA
+		postDelay: map[string]time.Duration{
+			relayA: 500 * time.Millisecond, // preferred but slow -> abandoned
+			relayB: 10 * time.Millisecond,  // fallback is fast -> peerA wins relayB
+		},
+	}
+	peerB := &splitPeer{
+		rv:       rv,
+		relayFor: map[bool]string{false: relayB, true: relayA}, // home=relayB
+		postDelay: map[string]time.Duration{
+			relayA: 80 * time.Millisecond,  // preferred, wins - but only after starting fallback
+			relayB: 500 * time.Millisecond, // fallback (home) is slow -> abandoned
+		},
+	}
+
+	fallbackDelay := 30 * time.Millisecond
+	newPeerOpener := func(p *splitPeer) *FallbackOpener {
+		o := NewFallbackOpener(nil, nil)
+		o.openFn = p.open
+		o.fallbackDelay = fallbackDelay
+		o.totalTimeout = 5 * time.Second
+		return o
+	}
+	oA := newPeerOpener(peerA)
+	oB := newPeerOpener(peerB)
+
+	type result struct {
+		conn net.Conn
+		err  error
+	}
+	var ra, rb result
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() {
+		defer wg.Done()
+		ra.conn, ra.err = oA.Run(context.Background(), "peerB", RelayServer{Addr: relayB}, preferHome)
+	}()
+	go func() {
+		defer wg.Done()
+		rb.conn, rb.err = oB.Run(context.Background(), "peerA", RelayServer{Addr: relayA}, preferForeign)
+	}()
+	wg.Wait()
+
+	require.NoError(t, ra.err)
+	require.NoError(t, rb.err)
+	aRelay := ra.conn.(*raceFakeConn).label
+	bRelay := rb.conn.(*raceFakeConn).label
+	t.Logf("peerA settled on %s, peerB settled on %s", aRelay, bRelay)
+
+	assert.Equal(t, aRelay, bRelay,
+		"peers selected different relays with no cross-peer tie-break")
+	assert.Equal(t, relayB, aRelay, "peerA abandoned its slow preferred relay and won the fallback")
+	assert.Equal(t, relayA, bRelay, "peerB won its preferred relay after starting the fallback")
+}

shared/relay/client/foreign_relays_store.go

@@ -0,0 +1,155 @@
+package client
+
+import (
+	"context"
+	"net"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+	"golang.org/x/sync/singleflight"
+
+	relayAuth "github.com/netbirdio/netbird/shared/relay/auth/hmac"
+)
+
+type foreignRelay struct {
+	client  *Client
+	created time.Time
+	inUse   int
+}
+
+type ForeignRelaysStore struct {
+	mu      sync.RWMutex
+	clients map[string]*foreignRelay
+
+	group singleflight.Group
+
+	ctx                  context.Context
+	tokenStore           *relayAuth.TokenStore
+	peerID               string
+	mtu                  uint16
+	transportFallback    *transportFallback
+	onDisconnect         func(string)
+	keepUnusedServerTime time.Duration
+}
+
+func NewForeignRelaysStore(ctx context.Context, tokenStore *relayAuth.TokenStore, peerID string, mtu uint16, transportFallback *transportFallback, onDisconnect func(string), keepUnusedServerTime time.Duration) *ForeignRelaysStore {
+	return &ForeignRelaysStore{
+		clients:              make(map[string]*foreignRelay),
+		ctx:                  ctx,
+		tokenStore:           tokenStore,
+		peerID:               peerID,
+		mtu:                  mtu,
+		transportFallback:    transportFallback,
+		onDisconnect:         onDisconnect,
+		keepUnusedServerTime: keepUnusedServerTime,
+	}
+}
+
+func (f *ForeignRelaysStore) OpenConn(ctx context.Context, peerKey string, remoteRelayServer RelayServer) (net.Conn, error) {
+	fr, err := f.acquire(remoteRelayServer)
+	if err != nil {
+		return nil, err
+	}
+	defer f.release(fr)
+
+	return fr.client.OpenConn(ctx, peerKey)
+}
+
+func (f *ForeignRelaysStore) acquire(remoteRelayServer RelayServer) (*foreignRelay, error) {
+	f.mu.Lock()
+	if fr, ok := f.clients[remoteRelayServer.Addr]; ok {
+		fr.inUse++
+		f.mu.Unlock()
+		return fr, nil
+	}
+	f.mu.Unlock()
+
+	v, err, _ := f.group.Do(remoteRelayServer.Addr, func() (any, error) {
+		f.mu.RLock()
+		fr, ok := f.clients[remoteRelayServer.Addr]
+		f.mu.RUnlock()
+		if ok {
+			return fr, nil
+		}
+
+		relayClient := NewClientWithServerIP(remoteRelayServer.Addr, remoteRelayServer.IP, f.tokenStore, f.peerID, f.mtu)
+		relayClient.SetTransportFallback(f.transportFallback)
+		if err := relayClient.Connect(f.ctx); err != nil {
+			return nil, err
+		}
+		relayClient.SetOnDisconnectListener(f.onDisconnect)
+
+		f.mu.Lock()
+		fr = &foreignRelay{client: relayClient, created: time.Now()}
+		f.clients[remoteRelayServer.Addr] = fr
+		f.mu.Unlock()
+		return fr, nil
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	fr := v.(*foreignRelay)
+	f.mu.Lock()
+	if cur, ok := f.clients[remoteRelayServer.Addr]; !ok || cur != fr {
+		f.mu.Unlock()
+		return f.acquire(remoteRelayServer)
+	}
+	fr.inUse++
+	f.mu.Unlock()
+	return fr, nil
+}
+
+func (f *ForeignRelaysStore) release(fr *foreignRelay) {
+	f.mu.Lock()
+	fr.inUse--
+	f.mu.Unlock()
+}
+
+func (f *ForeignRelaysStore) evict(serverAddress string) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if _, ok := f.clients[serverAddress]; ok {
+		delete(f.clients, serverAddress)
+		log.Debugf("evicted disconnected foreign relay client: %s", serverAddress)
+	}
+}
+
+func (f *ForeignRelaysStore) cleanupUnused() {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+
+	for addr, fr := range f.clients {
+		if time.Since(fr.created) <= f.keepUnusedServerTime {
+			continue
+		}
+		if fr.inUse > 0 {
+			continue
+		}
+		if fr.client.HasConns() {
+			continue
+		}
+		fr.client.SetOnDisconnectListener(nil)
+		go func() {
+			_ = fr.client.Close()
+		}()
+		log.Debugf("clean up unused relay server connection: %s", addr)
+		delete(f.clients, addr)
+	}
+}
+
+func (f *ForeignRelaysStore) states() []RelayConnState {
+	f.mu.RLock()
+	clients := make([]*Client, 0, len(f.clients))
+	for _, fr := range f.clients {
+		clients = append(clients, fr.client)
+	}
+	f.mu.RUnlock()
+
+	states := make([]RelayConnState, 0, len(clients))
+	for _, c := range clients {
+		states = append(states, relayConnState(c))
+	}
+	return states
+}

shared/relay/client/manager.go

@@ -22,27 +22,6 @@ var (
 	ErrRelayClientNotConnected = fmt.Errorf("relay client not connected")
 )
 
-// RelayTrack hold the relay clients for the foreign relay servers.
-// With the mutex can ensure we can open new connection in case the relay connection has been established with
-// the relay server.
-type RelayTrack struct {
-	sync.RWMutex
-	relayClient *Client
-	err         error
-	created     time.Time
-	// ready is closed once the dial started by openConnVia finishes (relayClient
-	// or err is set). Callers reusing a track wait on this instead of the track
-	// lock, so the dial never runs under rt.Lock.
-	ready chan struct{}
-}
-
-func NewRelayTrack() *RelayTrack {
-	return &RelayTrack{
-		created: time.Now(),
-		ready:   make(chan struct{}),
-	}
-}
-
 type OnServerCloseListener func()
 
 // ManagerOption configures a Manager at construction time.
@@ -59,6 +38,11 @@ type RelayConnState struct {
 	Err error
 }
 
+type RelayServer struct {
+	Addr string
+	IP   netip.Addr
+}
+
 // WithMaxBackoffInterval caps the exponential backoff between reconnect
 // attempts to the home relay. A non-positive value keeps the default.
 func WithMaxBackoffInterval(d time.Duration) ManagerOption {
@@ -83,8 +67,7 @@ type Manager struct {
 	relayClientMu  sync.RWMutex
 	reconnectGuard *Guard
 
-	relayClients      map[string]*RelayTrack
-	relayClientsMutex sync.RWMutex
+	foreign *ForeignRelaysStore
 
 	onDisconnectedListeners map[string]*list.List
 	onReconnectedListenerFn func()
@@ -120,7 +103,6 @@ func NewManager(ctx context.Context, serverURLs []string, peerID string, mtu uin
 			ConnectionTimeout: defaultConnectionTimeout,
 			TransportFallback: tf,
 		},
-		relayClients:            make(map[string]*RelayTrack),
 		onDisconnectedListeners: make(map[string]*list.List),
 		cleanupInterval:         relayCleanupInterval,
 		keepUnusedServerTime:    keepUnusedServerTime,
@@ -128,6 +110,7 @@ func NewManager(ctx context.Context, serverURLs []string, peerID string, mtu uin
 	for _, opt := range opts {
 		opt(m)
 	}
+	m.foreign = NewForeignRelaysStore(ctx, tokenStore, peerID, mtu, tf, m.onServerDisconnected, m.keepUnusedServerTime)
 	m.serverPicker.ServerURLs.Store(serverURLs)
 	m.reconnectGuard = NewGuard(m.serverPicker, m.maxBackoffInterval)
 	return m
@@ -159,40 +142,26 @@ func (m *Manager) Serve() error {
 	return err
 }
 
-// OpenConn opens a connection to the given peer key. If the peer is on the same relay server, the connection will be
-// established via the relay server. If the peer is on a different relay server, the manager will establish a new
-// connection to the relay server. It returns back with a net.Conn what represent the remote peer connection.
-//
-// serverIP, when valid and serverAddress is foreign, is used as a dial target if the FQDN-based dial fails.
-// Ignored for the local home-server path. TLS verification still uses the FQDN via SNI.
-func (m *Manager) OpenConn(ctx context.Context, serverAddress, peerKey string, serverIP netip.Addr) (net.Conn, error) {
+func (m *Manager) OpenConn(ctx context.Context, remoteRelayServer RelayServer, peerKey string, preferForeign bool) (net.Conn, error) {
 	m.relayClientMu.RLock()
-	defer m.relayClientMu.RUnlock()
+	relayClient := m.relayClient
+	m.relayClientMu.RUnlock()
 
-	if m.relayClient == nil {
+	if relayClient == nil {
 		return nil, ErrRelayClientNotConnected
 	}
 
-	foreign, err := m.isForeignServer(serverAddress)
+	foreign, err := m.isForeignServer(relayClient, remoteRelayServer.Addr)
 	if err != nil {
 		return nil, err
 	}
 
-	var (
-		netConn net.Conn
-	)
 	if !foreign {
-		log.Debugf("open peer connection via permanent server: %s", peerKey)
-		netConn, err = m.relayClient.OpenConn(ctx, peerKey)
-	} else {
-		log.Debugf("open peer connection via foreign server: %s", serverAddress)
-		netConn, err = m.openConnVia(ctx, serverAddress, peerKey, serverIP)
-	}
-	if err != nil {
-		return nil, err
+		return relayClient.OpenConn(ctx, peerKey)
 	}
 
-	return netConn, err
+	opener := NewFallbackOpener(relayClient, m.foreign)
+	return opener.Run(ctx, peerKey, remoteRelayServer, preferForeign)
 }
 
 // Ready returns true if the home Relay client is connected to the relay server.
@@ -223,7 +192,7 @@ func (m *Manager) AddCloseListener(serverAddress string, onClosedListener OnServ
 		return ErrRelayClientNotConnected
 	}
 
-	foreign, err := m.isForeignServer(serverAddress)
+	foreign, err := m.isForeignServer(m.relayClient, serverAddress)
 	if err != nil {
 		return err
 	}
@@ -287,26 +256,7 @@ func (m *Manager) RelayStates() []RelayConnState {
 		states = append(states, st)
 	}
 
-	// Snapshot the tracks, then query each outside the map lock: a track can be
-	// held by an in-progress Connect, and blocking on it must not stall other
-	// relay operations.
-	m.relayClientsMutex.RLock()
-	tracks := make([]*RelayTrack, 0, len(m.relayClients))
-	for _, rt := range m.relayClients {
-		tracks = append(tracks, rt)
-	}
-	m.relayClientsMutex.RUnlock()
-
-	// Only connected foreign relays carry state; a failed connect is evicted
-	// immediately (openConnVia), so there is no error state to surface.
-	for _, rt := range tracks {
-		rt.RLock()
-		rc := rt.relayClient
-		rt.RUnlock()
-		if rc != nil {
-			states = append(states, relayConnState(rc))
-		}
-	}
+	states = append(states, m.foreign.states()...)
 
 	return states
 }
@@ -327,76 +277,6 @@ func (m *Manager) UpdateToken(token *relayAuth.Token) error {
 	return m.tokenStore.UpdateToken(token)
 }
 
-func (m *Manager) openConnVia(ctx context.Context, serverAddress, peerKey string, serverIP netip.Addr) (net.Conn, error) {
-	// check if already has a connection to the desired relay server
-	m.relayClientsMutex.RLock()
-	rt, ok := m.relayClients[serverAddress]
-	m.relayClientsMutex.RUnlock()
-	if ok {
-		return m.openConnOnTrack(ctx, rt, peerKey)
-	}
-
-	// if not, establish a new connection but check it again (because changed the lock type) before starting the
-	// connection
-	m.relayClientsMutex.Lock()
-	rt, ok = m.relayClients[serverAddress]
-	if ok {
-		m.relayClientsMutex.Unlock()
-		return m.openConnOnTrack(ctx, rt, peerKey)
-	}
-
-	// Publish the track and release the map lock BEFORE dialing, so the dial does
-	// not run under rt.Lock (which would block RelayStates and the cleanup loop
-	// for the full dial). Concurrent callers find this track and wait on rt.ready.
-	rt = NewRelayTrack()
-	m.relayClients[serverAddress] = rt
-	m.relayClientsMutex.Unlock()
-
-	relayClient := NewClientWithServerIP(serverAddress, serverIP, m.tokenStore, m.peerID, m.mtu)
-	relayClient.SetTransportFallback(m.transportFallback)
-	err := relayClient.Connect(m.ctx)
-	if err != nil {
-		rt.Lock()
-		rt.err = err
-		rt.Unlock()
-		close(rt.ready)
-		m.relayClientsMutex.Lock()
-		delete(m.relayClients, serverAddress)
-		m.relayClientsMutex.Unlock()
-		return nil, err
-	}
-	// if connection closed then delete the relay client from the list
-	relayClient.SetOnDisconnectListener(m.onServerDisconnected)
-	rt.Lock()
-	rt.relayClient = relayClient
-	rt.Unlock()
-	close(rt.ready)
-
-	return relayClient.OpenConn(ctx, peerKey)
-}
-
-// openConnOnTrack opens a peer connection through an existing relay track,
-// waiting for the dial started by another openConnVia call to finish. It waits
-// on rt.ready rather than the track lock, so it neither holds nor contends the
-// track lock across the dial.
-func (m *Manager) openConnOnTrack(ctx context.Context, rt *RelayTrack, peerKey string) (net.Conn, error) {
-	select {
-	case <-rt.ready:
-	case <-ctx.Done():
-		return nil, ctx.Err()
-	}
-
-	rt.RLock()
-	defer rt.RUnlock()
-	if rt.err != nil {
-		return nil, rt.err
-	}
-	if rt.relayClient == nil {
-		return nil, ErrRelayClientNotConnected
-	}
-	return rt.relayClient.OpenConn(ctx, peerKey)
-}
-
 func (m *Manager) onServerConnected() {
 	m.listenerLock.Lock()
 	defer m.listenerLock.Unlock()
@@ -422,21 +302,12 @@ func (m *Manager) onServerDisconnected(serverAddress string) {
 	m.relayClientMu.Unlock()
 
 	if !isHome {
-		m.evictForeignRelay(serverAddress)
+		m.foreign.evict(serverAddress)
 	}
 
 	m.notifyOnDisconnectListeners(serverAddress)
 }
 
-func (m *Manager) evictForeignRelay(serverAddress string) {
-	m.relayClientsMutex.Lock()
-	defer m.relayClientsMutex.Unlock()
-	if _, ok := m.relayClients[serverAddress]; ok {
-		delete(m.relayClients, serverAddress)
-		log.Debugf("evicted disconnected foreign relay client: %s", serverAddress)
-	}
-}
-
 func (m *Manager) listenGuardEvent(ctx context.Context) {
 	for {
 		select {
@@ -459,8 +330,8 @@ func (m *Manager) storeClient(client *Client) {
 	m.relayClient.SetOnDisconnectListener(m.onServerDisconnected)
 }
 
-func (m *Manager) isForeignServer(address string) (bool, error) {
-	rAddr, err := m.relayClient.ServerInstanceURL()
+func (m *Manager) isForeignServer(relayClient *Client, address string) (bool, error) {
+	rAddr, err := relayClient.ServerInstanceURL()
 	if err != nil {
 		return false, fmt.Errorf("relay client not connected")
 	}
@@ -475,50 +346,11 @@ func (m *Manager) startCleanupLoop() {
 		case <-m.ctx.Done():
 			return
 		case <-ticker.C:
-			m.cleanUpUnusedRelays()
+			m.foreign.cleanupUnused()
 		}
 	}
 }
 
-func (m *Manager) cleanUpUnusedRelays() {
-	m.relayClientsMutex.Lock()
-	defer m.relayClientsMutex.Unlock()
-
-	for addr, rt := range m.relayClients {
-		rt.Lock()
-		// if the connection failed to the server the relay client will be nil
-		// but the instance will be kept in the relayClients until the next locking
-		if rt.err != nil {
-			rt.Unlock()
-			continue
-		}
-
-		// dial still in progress (openConnVia publishes the track before Connect
-		// completes and no longer holds rt.Lock during it), nothing to clean up.
-		if rt.relayClient == nil {
-			rt.Unlock()
-			continue
-		}
-
-		if time.Since(rt.created) <= m.keepUnusedServerTime {
-			rt.Unlock()
-			continue
-		}
-
-		if rt.relayClient.HasConns() {
-			rt.Unlock()
-			continue
-		}
-		rt.relayClient.SetOnDisconnectListener(nil)
-		go func() {
-			_ = rt.relayClient.Close()
-		}()
-		log.Debugf("clean up unused relay server connection: %s", addr)
-		delete(m.relayClients, addr)
-		rt.Unlock()
-	}
-}
-
 func (m *Manager) addListener(serverAddress string, onClosedListener OnServerCloseListener) {
 	m.listenerLock.Lock()
 	defer m.listenerLock.Unlock()

shared/relay/client/manager_cleanup_test.go

@@ -2,17 +2,14 @@ package client
 
 import (
 	"context"
-	"net/netip"
 	"testing"
 	"time"
-
-	"github.com/stretchr/testify/require"
 )
 
 // TestCleanUpUnusedRelays_DoesNotBlockOnRealHangingDial drives a real, hanging foreign
-// relay dial and asserts cleanUpUnusedRelays does not stall behind it.
+// relay dial and asserts the foreign store cleanup does not stall behind it.
 func TestCleanUpUnusedRelays_DoesNotBlockOnRealHangingDial(t *testing.T) {
-	serverAddr := stallingRelayListener(t)
+	serverAddr, accepted := stallingRelayListener(t)
 
 	mCtx, mCancel := context.WithCancel(context.Background())
 	t.Cleanup(mCancel)
@@ -22,39 +19,32 @@ func TestCleanUpUnusedRelays_DoesNotBlockOnRealHangingDial(t *testing.T) {
 	dialDone := make(chan struct{})
 	go func() {
 		defer close(dialDone)
-		_, _ = m.openConnVia(mCtx, serverAddr, "peerKey", netip.Addr{})
+		_, _ = m.foreign.OpenConn(mCtx, "peerKey", RelayServer{Addr: serverAddr})
 	}()
 
-	// The track appears in the map once the dial is in flight.
-	require.Eventually(t, func() bool {
-		m.relayClientsMutex.RLock()
-		defer m.relayClientsMutex.RUnlock()
-		_, ok := m.relayClients[serverAddr]
-		return ok
-	}, 5*time.Second, 5*time.Millisecond, "relay dial did not start")
+	select {
+	case <-accepted:
+	case <-time.After(5 * time.Second):
+		t.Fatal("relay dial did not reach the listener")
+	}
 
 	cleanupDone := make(chan struct{})
 	go func() {
 		defer close(cleanupDone)
-		m.cleanUpUnusedRelays()
+		m.foreign.cleanupUnused()
 	}()
 
 	select {
 	case <-cleanupDone:
 	case <-time.After(2 * time.Second):
-		t.Fatal("cleanUpUnusedRelays blocked on an in-progress relay dial while holding the relay map lock")
+		t.Fatal("cleanupUnused blocked on an in-progress relay dial")
 	}
 
-	m.relayClientsMutex.RLock()
-	_, stillTracked := m.relayClients[serverAddr]
-	m.relayClientsMutex.RUnlock()
-	require.True(t, stillTracked, "an in-progress relay dial must not be evicted by cleanup")
-
 	// Release the hanging dial so the goroutine can exit cleanly.
 	mCancel()
 	select {
 	case <-dialDone:
 	case <-time.After(5 * time.Second):
-		t.Fatal("openConnVia did not return after context cancellation")
+		t.Fatal("foreign OpenConn did not return after context cancellation")
 	}
 }

shared/relay/client/manager_relaystates_test.go

@@ -3,7 +3,6 @@ package client
 import (
 	"context"
 	"net"
-	"net/netip"
 	"sync"
 	"testing"
 	"time"
@@ -13,13 +12,16 @@ import (
 
 // stallingRelayListener accepts TCP connections and holds them open without ever
 // responding, so a relay handshake dialed against it blocks until its context is
-// cancelled. It returns the "rel://host:port" URL to dial.
-func stallingRelayListener(t *testing.T) string {
+// cancelled. accepted is signalled once per incoming connection so a caller can
+// wait until a dial has actually reached the listener. It returns the
+// "rel://host:port" URL to dial.
+func stallingRelayListener(t *testing.T) (string, <-chan struct{}) {
 	t.Helper()
 
 	ln, err := net.Listen("tcp", "127.0.0.1:0")
 	require.NoError(t, err)
 
+	accepted := make(chan struct{}, 1)
 	var mu sync.Mutex
 	var conns []net.Conn
 	go func() {
@@ -31,6 +33,10 @@ func stallingRelayListener(t *testing.T) string {
 			mu.Lock()
 			conns = append(conns, c)
 			mu.Unlock()
+			select {
+			case accepted <- struct{}{}:
+			default:
+			}
 		}
 	}()
 	t.Cleanup(func() {
@@ -42,14 +48,14 @@ func stallingRelayListener(t *testing.T) string {
 		mu.Unlock()
 	})
 
-	return "rel://" + ln.Addr().String()
+	return "rel://" + ln.Addr().String(), accepted
 }
 
 // TestRelayStates_DoesNotBlockOnRealHangingDial is a regression test for
 // RelayStates() called by a "status -d command" hanging behind an in-progress
-// relay dial.
+// foreign relay dial.
 func TestRelayStates_DoesNotBlockOnRealHangingDial(t *testing.T) {
-	serverAddr := stallingRelayListener(t)
+	serverAddr, accepted := stallingRelayListener(t)
 
 	mCtx, mCancel := context.WithCancel(context.Background())
 	t.Cleanup(mCancel)
@@ -59,15 +65,14 @@ func TestRelayStates_DoesNotBlockOnRealHangingDial(t *testing.T) {
 	dialDone := make(chan struct{})
 	go func() {
 		defer close(dialDone)
-		_, _ = m.openConnVia(mCtx, serverAddr, "peerKey", netip.Addr{})
+		_, _ = m.foreign.OpenConn(mCtx, "peerKey", RelayServer{Addr: serverAddr})
 	}()
 
-	require.Eventually(t, func() bool {
-		m.relayClientsMutex.RLock()
-		defer m.relayClientsMutex.RUnlock()
-		_, ok := m.relayClients[serverAddr]
-		return ok
-	}, 5*time.Second, 5*time.Millisecond, "relay dial did not start")
+	select {
+	case <-accepted:
+	case <-time.After(5 * time.Second):
+		t.Fatal("relay dial did not reach the listener")
+	}
 
 	done := make(chan []RelayConnState, 1)
 	go func() {
@@ -86,6 +91,6 @@ func TestRelayStates_DoesNotBlockOnRealHangingDial(t *testing.T) {
 	select {
 	case <-dialDone:
 	case <-time.After(5 * time.Second):
-		t.Fatal("openConnVia did not return after context cancellation")
+		t.Fatal("foreign OpenConn did not return after context cancellation")
 	}
 }

shared/relay/client/manager_serverip_test.go

@@ -3,7 +3,6 @@ package client
 import (
 	"context"
 	"io"
-	"net/netip"
 	"testing"
 	"time"
 
@@ -85,7 +84,7 @@ func TestManager_ForeignRelayServerIP(t *testing.T) {
 	t.Run("no server IP, dial fails", func(t *testing.T) {
 		dialCtx, dialCancel := context.WithTimeout(ctx, 5*time.Second)
 		defer dialCancel()
-		_, err := mgrAlice.OpenConn(dialCtx, brokenFQDN, "bob", netip.Addr{})
+		_, err := mgrAlice.OpenConn(dialCtx, RelayServer{Addr: brokenFQDN}, "bob", true)
 		if err == nil {
 			t.Fatalf("expected OpenConn to fail without server IP, got success")
 		}
@@ -95,7 +94,7 @@ func TestManager_ForeignRelayServerIP(t *testing.T) {
 		// Bob waits for Alice's incoming peer connection on his side.
 		bobSideCh := make(chan error, 1)
 		go func() {
-			conn, err := mgrBob.OpenConn(ctx, bobRealAddr, "alice", netip.Addr{})
+			conn, err := mgrBob.OpenConn(ctx, RelayServer{Addr: bobRealAddr}, "alice", false)
 			if err != nil {
 				bobSideCh <- err
 				return
@@ -113,7 +112,7 @@ func TestManager_ForeignRelayServerIP(t *testing.T) {
 			bobSideCh <- nil
 		}()
 
-		aliceConn, err := mgrAlice.OpenConn(ctx, brokenFQDN, "bob", bobAdvertisedIP)
+		aliceConn, err := mgrAlice.OpenConn(ctx, RelayServer{Addr: brokenFQDN, IP: bobAdvertisedIP}, "bob", true)
 		if err != nil {
 			t.Fatalf("alice OpenConn with server IP: %s", err)
 		}

shared/relay/client/manager_test.go

@@ -3,7 +3,6 @@ package client
 import (
 	"context"
 	"fmt"
-	"net/netip"
 	"testing"
 	"time"
 
@@ -106,11 +105,11 @@ func TestForeignConn(t *testing.T) {
 	if err != nil {
 		t.Fatalf("failed to get relay address: %s", err)
 	}
-	connAliceToBob, err := clientAlice.OpenConn(ctx, bobsSrvAddr, "bob", netip.Addr{})
+	connAliceToBob, err := clientAlice.OpenConn(ctx, RelayServer{Addr: bobsSrvAddr}, "bob", true)
 	if err != nil {
 		t.Fatalf("failed to bind channel: %s", err)
 	}
-	connBobToAlice, err := clientBob.OpenConn(ctx, bobsSrvAddr, "alice", netip.Addr{})
+	connBobToAlice, err := clientBob.OpenConn(ctx, RelayServer{Addr: bobsSrvAddr}, "alice", false)
 	if err != nil {
 		t.Fatalf("failed to bind channel: %s", err)
 	}
@@ -210,7 +209,7 @@ func TestForeginConnClose(t *testing.T) {
 	if err != nil {
 		t.Fatalf("failed to serve manager: %s", err)
 	}
-	conn, err := mgr.OpenConn(ctx, toURL(srvCfg2)[0], "bob", netip.Addr{})
+	conn, err := mgr.OpenConn(ctx, RelayServer{Addr: toURL(srvCfg2)[0]}, "bob", true)
 	if err != nil {
 		t.Fatalf("failed to bind channel: %s", err)
 	}
@@ -302,7 +301,7 @@ func TestForeignAutoClose(t *testing.T) {
 	}
 
 	t.Log("open connection to another peer")
-	if _, err = mgr.OpenConn(ctx, foreignServerURL, "anotherpeer", netip.Addr{}); err == nil {
+	if _, err = mgr.OpenConn(ctx, RelayServer{Addr: foreignServerURL}, "anotherpeer", true); err == nil {
 		t.Fatalf("should have failed to open connection to another peer")
 	}
 
@@ -372,7 +371,7 @@ func TestAutoReconnect(t *testing.T) {
 	if err != nil {
 		t.Errorf("failed to get relay address: %s", err)
 	}
-	conn, err := clientAlice.OpenConn(ctx, ra, "bob", netip.Addr{})
+	conn, err := clientAlice.OpenConn(ctx, RelayServer{Addr: ra}, "bob", false)
 	if err != nil {
 		t.Errorf("failed to bind channel: %s", err)
 	}
@@ -392,7 +391,7 @@ func TestAutoReconnect(t *testing.T) {
 	}
 
 	log.Infof("reopent the connection")
-	_, err = clientAlice.OpenConn(ctx, ra, "bob", netip.Addr{})
+	_, err = clientAlice.OpenConn(ctx, RelayServer{Addr: ra}, "bob", false)
 	if err != nil {
 		t.Errorf("failed to open channel: %s", err)
 	}
@@ -454,7 +453,7 @@ func TestNotifierDoubleAdd(t *testing.T) {
 		t.Fatalf("failed to serve manager: %s", err)
 	}
 
-	conn1, err := clientAlice.OpenConn(ctx, clientAlice.ServerURLs()[0], "bob", netip.Addr{})
+	conn1, err := clientAlice.OpenConn(ctx, RelayServer{Addr: clientAlice.ServerURLs()[0]}, "bob", false)
 	if err != nil {
 		t.Fatalf("failed to bind channel: %s", err)
 	}

shared/relay/messages/address/address.go

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

shared/relay/messages/auth/auth.go

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

shared/relay/messages/message.go

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

shared/relay/messages/message_test.go

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

trustedproxy/trustedproxy.go

@@ -0,0 +1,132 @@
+package trustedproxy
+
+import (
+	"fmt"
+	"net/netip"
+	"strings"
+)
+
+// List holds a parsed set of trusted upstream proxy prefixes and answers trust
+// questions against it. The zero value (and a nil *List) is a valid, empty list
+// that never trusts any address, so callers can use it without a nil check.
+type List struct {
+	prefixes []netip.Prefix
+}
+
+// Parse parses a comma-separated list of CIDR prefixes or bare IPs into a List.
+// Bare IPs are converted to single-host prefixes (/32 or /128). An empty input
+// yields an empty List that trusts nothing.
+func Parse(raw string) (*List, error) {
+	if raw == "" {
+		return &List{}, nil
+	}
+
+	parts := strings.Split(raw, ",")
+	prefixes := make([]netip.Prefix, 0, len(parts))
+	for _, part := range parts {
+		part = strings.TrimSpace(part)
+		if part == "" {
+			continue
+		}
+
+		prefix, err := netip.ParsePrefix(part)
+		if err == nil {
+			prefixes = append(prefixes, prefix)
+			continue
+		}
+
+		addr, addrErr := netip.ParseAddr(part)
+		if addrErr != nil {
+			return nil, fmt.Errorf("parse trusted proxy %q: not a valid CIDR or IP: %w", part, addrErr)
+		}
+
+		bits := 32
+		if addr.Is6() {
+			bits = 128
+		}
+		prefixes = append(prefixes, netip.PrefixFrom(addr, bits))
+	}
+	return &List{prefixes: prefixes}, nil
+}
+
+// FromPrefixes wraps an already-parsed set of prefixes in a List.
+func FromPrefixes(prefixes []netip.Prefix) *List {
+	return &List{prefixes: prefixes}
+}
+
+// Empty reports whether the list contains no prefixes.
+func (l *List) Empty() bool {
+	return l == nil || len(l.prefixes) == 0
+}
+
+// IsTrusted reports whether the given host:port or bare IP falls within the list.
+func (l *List) IsTrusted(remoteAddr string) bool {
+	if l.Empty() {
+		return false
+	}
+	return l.Contains(ExtractHostIP(remoteAddr))
+}
+
+// Contains reports whether the given address falls within any trusted prefix.
+func (l *List) Contains(addr netip.Addr) bool {
+	if l.Empty() || !addr.IsValid() {
+		return false
+	}
+	for _, prefix := range l.prefixes {
+		if prefix.Contains(addr) {
+			return true
+		}
+	}
+	return false
+}
+
+// ResolveClientIP extracts the real client IP from X-Forwarded-For using the
+// list. It walks the XFF chain right-to-left, skipping IPs that match trusted
+// prefixes; the first untrusted IP is the real client. If the list is empty or
+// remoteAddr is not trusted, it returns the remoteAddr IP directly, ignoring any
+// forwarding headers.
+func (l *List) ResolveClientIP(remoteAddr, xff string) netip.Addr {
+	remoteIP := ExtractHostIP(remoteAddr)
+
+	if l.Empty() || !l.Contains(remoteIP) {
+		return remoteIP
+	}
+
+	if xff == "" {
+		return remoteIP
+	}
+
+	parts := strings.Split(xff, ",")
+	for i := len(parts) - 1; i >= 0; i-- {
+		ip := strings.TrimSpace(parts[i])
+		if ip == "" {
+			continue
+		}
+		addr, err := netip.ParseAddr(ip)
+		if err != nil {
+			continue
+		}
+		addr = addr.Unmap()
+		if !l.Contains(addr) {
+			return addr
+		}
+	}
+
+	if first := strings.TrimSpace(parts[0]); first != "" {
+		if addr, err := netip.ParseAddr(first); err == nil {
+			return addr.Unmap()
+		}
+	}
+	return remoteIP
+}
+
+// ExtractHostIP parses the IP from a host:port string and returns it unmapped.
+func ExtractHostIP(hostPort string) netip.Addr {
+	if ap, err := netip.ParseAddrPort(hostPort); err == nil {
+		return ap.Addr().Unmap()
+	}
+	if addr, err := netip.ParseAddr(hostPort); err == nil {
+		return addr.Unmap()
+	}
+	return netip.Addr{}
+}

trustedproxy/trustedproxy_test.go

@@ -0,0 +1,216 @@
+package trustedproxy
+
+import (
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParse(t *testing.T) {
+	tests := []struct {
+		name    string
+		raw     string
+		want    []netip.Prefix
+		wantErr bool
+	}{
+		{
+			name: "empty string returns empty list",
+			raw:  "",
+			want: nil,
+		},
+		{
+			name: "single CIDR",
+			raw:  "10.0.0.0/8",
+			want: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
+		},
+		{
+			name: "single bare IPv4",
+			raw:  "1.2.3.4",
+			want: []netip.Prefix{netip.MustParsePrefix("1.2.3.4/32")},
+		},
+		{
+			name: "single bare IPv6",
+			raw:  "::1",
+			want: []netip.Prefix{netip.MustParsePrefix("::1/128")},
+		},
+		{
+			name: "comma-separated CIDRs",
+			raw:  "10.0.0.0/8, 192.168.1.0/24",
+			want: []netip.Prefix{
+				netip.MustParsePrefix("10.0.0.0/8"),
+				netip.MustParsePrefix("192.168.1.0/24"),
+			},
+		},
+		{
+			name: "mixed CIDRs and bare IPs",
+			raw:  "10.0.0.0/8, 1.2.3.4, fd00::/8",
+			want: []netip.Prefix{
+				netip.MustParsePrefix("10.0.0.0/8"),
+				netip.MustParsePrefix("1.2.3.4/32"),
+				netip.MustParsePrefix("fd00::/8"),
+			},
+		},
+		{
+			name: "whitespace around entries",
+			raw:  "  10.0.0.0/8 , 192.168.0.0/16  ",
+			want: []netip.Prefix{
+				netip.MustParsePrefix("10.0.0.0/8"),
+				netip.MustParsePrefix("192.168.0.0/16"),
+			},
+		},
+		{
+			name: "trailing comma produces no extra entry",
+			raw:  "10.0.0.0/8,",
+			want: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/8")},
+		},
+		{
+			name:    "invalid entry",
+			raw:     "not-an-ip",
+			wantErr: true,
+		},
+		{
+			name:    "partially invalid",
+			raw:     "10.0.0.0/8, garbage",
+			wantErr: true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := Parse(tt.raw)
+			if tt.wantErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got.prefixes)
+		})
+	}
+}
+
+func TestListIsTrusted(t *testing.T) {
+	list, err := Parse("10.0.0.0/8, 192.168.1.0/24, fd00::/8")
+	require.NoError(t, err)
+
+	tests := []struct {
+		name string
+		addr string
+		list *List
+		want bool
+	}{
+		{"nil list", "10.0.0.1", nil, false},
+		{"empty list", "10.0.0.1", &List{}, false},
+		{"IP within /8 prefix", "10.1.2.3", list, true},
+		{"IP within /24 prefix", "192.168.1.100", list, true},
+		{"IP outside all prefixes", "203.0.113.50", list, false},
+		{"boundary IP just outside prefix", "192.168.2.1", list, false},
+		{"unparsable IP", "not-an-ip", list, false},
+		{"IPv6 in trusted range", "fd00::1", list, true},
+		{"IPv6 outside range", "2001:db8::1", list, false},
+		{"empty string", "", list, false},
+		{"host:port within prefix", "10.1.2.3:9999", list, true},
+		{"host:port outside prefix", "203.0.113.50:9999", list, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, tt.list.IsTrusted(tt.addr))
+		})
+	}
+}
+
+func TestListResolveClientIP(t *testing.T) {
+	trusted, err := Parse("10.0.0.0/8, 172.16.0.0/12")
+	require.NoError(t, err)
+
+	tests := []struct {
+		name       string
+		remoteAddr string
+		xff        string
+		list       *List
+		want       netip.Addr
+	}{
+		{
+			name:       "empty list returns RemoteAddr",
+			remoteAddr: "203.0.113.50:9999",
+			xff:        "1.2.3.4",
+			list:       &List{},
+			want:       netip.MustParseAddr("203.0.113.50"),
+		},
+		{
+			name:       "nil list returns RemoteAddr",
+			remoteAddr: "203.0.113.50:9999",
+			xff:        "1.2.3.4",
+			list:       nil,
+			want:       netip.MustParseAddr("203.0.113.50"),
+		},
+		{
+			name:       "untrusted RemoteAddr ignores XFF",
+			remoteAddr: "203.0.113.50:9999",
+			xff:        "1.2.3.4, 10.0.0.1",
+			list:       trusted,
+			want:       netip.MustParseAddr("203.0.113.50"),
+		},
+		{
+			name:       "trusted RemoteAddr with single client in XFF",
+			remoteAddr: "10.0.0.1:5000",
+			xff:        "203.0.113.50",
+			list:       trusted,
+			want:       netip.MustParseAddr("203.0.113.50"),
+		},
+		{
+			name:       "trusted RemoteAddr walks past trusted entries in XFF",
+			remoteAddr: "10.0.0.1:5000",
+			xff:        "203.0.113.50, 10.0.0.2, 172.16.0.5",
+			list:       trusted,
+			want:       netip.MustParseAddr("203.0.113.50"),
+		},
+		{
+			name:       "trusted RemoteAddr with empty XFF falls back to RemoteAddr",
+			remoteAddr: "10.0.0.1:5000",
+			xff:        "",
+			list:       trusted,
+			want:       netip.MustParseAddr("10.0.0.1"),
+		},
+		{
+			name:       "all XFF IPs trusted returns leftmost",
+			remoteAddr: "10.0.0.1:5000",
+			xff:        "10.0.0.2, 172.16.0.1, 10.0.0.3",
+			list:       trusted,
+			want:       netip.MustParseAddr("10.0.0.2"),
+		},
+		{
+			name:       "XFF with whitespace",
+			remoteAddr: "10.0.0.1:5000",
+			xff:        " 203.0.113.50 , 10.0.0.2 ",
+			list:       trusted,
+			want:       netip.MustParseAddr("203.0.113.50"),
+		},
+		{
+			name:       "XFF with empty segments",
+			remoteAddr: "10.0.0.1:5000",
+			xff:        "203.0.113.50,,10.0.0.2",
+			list:       trusted,
+			want:       netip.MustParseAddr("203.0.113.50"),
+		},
+		{
+			name:       "multi-hop with mixed trust",
+			remoteAddr: "10.0.0.1:5000",
+			xff:        "8.8.8.8, 203.0.113.50, 172.16.0.1",
+			list:       trusted,
+			want:       netip.MustParseAddr("203.0.113.50"),
+		},
+		{
+			name:       "RemoteAddr without port",
+			remoteAddr: "10.0.0.1",
+			xff:        "203.0.113.50",
+			list:       trusted,
+			want:       netip.MustParseAddr("203.0.113.50"),
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, tt.list.ResolveClientIP(tt.remoteAddr, tt.xff))
+		})
+	}
+}