Add PCP support

client/cmd/debug.go

@@ -199,11 +199,9 @@ func runForDuration(cmd *cobra.Command, args []string) error {
 		cmd.Println("Log level set to trace.")
 	}
 
-	needsRestoreUp := false
 	if _, err := client.Down(cmd.Context(), &proto.DownRequest{}); err != nil {
 		cmd.PrintErrf("Failed to bring service down: %v\n", status.Convert(err).Message())
 	} else {
-		needsRestoreUp = !stateWasDown
 		cmd.Println("netbird down")
 	}
 
@@ -219,7 +217,6 @@ func runForDuration(cmd *cobra.Command, args []string) error {
 	if _, err := client.Up(cmd.Context(), &proto.UpRequest{}); err != nil {
 		cmd.PrintErrf("Failed to bring service up: %v\n", status.Convert(err).Message())
 	} else {
-		needsRestoreUp = false
 		cmd.Println("netbird up")
 	}
 
@@ -267,14 +264,6 @@ func runForDuration(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("failed to bundle debug: %v", status.Convert(err).Message())
 	}
 
-	if needsRestoreUp {
-		if _, err := client.Up(cmd.Context(), &proto.UpRequest{}); err != nil {
-			cmd.PrintErrf("Failed to restore service up state: %v\n", status.Convert(err).Message())
-		} else {
-			cmd.Println("netbird up (restored)")
-		}
-	}
-
 	if stateWasDown {
 		if _, err := client.Down(cmd.Context(), &proto.DownRequest{}); err != nil {
 			cmd.PrintErrf("Failed to restore service down state: %v\n", status.Convert(err).Message())

client/internal/debug/debug.go

@@ -25,7 +25,6 @@ import (
 	"google.golang.org/protobuf/encoding/protojson"
 
 	"github.com/netbirdio/netbird/client/anonymize"
-	"github.com/netbirdio/netbird/client/configs"
 	"github.com/netbirdio/netbird/client/internal/peer"
 	"github.com/netbirdio/netbird/client/internal/profilemanager"
 	"github.com/netbirdio/netbird/client/internal/updater/installer"
@@ -53,7 +52,6 @@ resolved_domains.txt: Anonymized resolved domain IP addresses from the status re
 config.txt: Anonymized configuration information of the NetBird client.
 network_map.json: Anonymized sync response containing peer configurations, routes, DNS settings, and firewall rules.
 state.json: Anonymized client state dump containing netbird states for the active profile.
-service_params.json: Sanitized service install parameters (service.json). Sensitive environment variable values are masked. Only present when service.json exists.
 metrics.txt: Buffered client metrics in InfluxDB line protocol format. Only present when metrics collection is enabled. Peer identifiers are anonymized.
 mutex.prof: Mutex profiling information.
 goroutine.prof: Goroutine profiling information.
@@ -361,10 +359,6 @@ func (g *BundleGenerator) createArchive() error {
 		log.Errorf("failed to add corrupted state files to debug bundle: %v", err)
 	}
 
-	if err := g.addServiceParams(); err != nil {
-		log.Errorf("failed to add service params to debug bundle: %v", err)
-	}
-
 	if err := g.addMetrics(); err != nil {
 		log.Errorf("failed to add metrics to debug bundle: %v", err)
 	}
@@ -494,90 +488,6 @@ func (g *BundleGenerator) addConfig() error {
 	return nil
 }
 
-const (
-	serviceParamsFile    = "service.json"
-	serviceParamsBundle  = "service_params.json"
-	maskedValue          = "***"
-	envVarPrefix         = "NB_"
-	jsonKeyManagementURL = "management_url"
-	jsonKeyServiceEnv    = "service_env_vars"
-)
-
-var sensitiveEnvSubstrings = []string{"key", "token", "secret", "password", "credential"}
-
-// addServiceParams reads the service.json file and adds a sanitized version to the bundle.
-// Non-NB_ env vars and vars with sensitive names are masked. Other NB_ values are anonymized.
-func (g *BundleGenerator) addServiceParams() error {
-	path := filepath.Join(configs.StateDir, serviceParamsFile)
-
-	data, err := os.ReadFile(path)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return nil
-		}
-		return fmt.Errorf("read service params: %w", err)
-	}
-
-	var params map[string]any
-	if err := json.Unmarshal(data, &params); err != nil {
-		return fmt.Errorf("parse service params: %w", err)
-	}
-
-	if g.anonymize {
-		if mgmtURL, ok := params[jsonKeyManagementURL].(string); ok && mgmtURL != "" {
-			params[jsonKeyManagementURL] = g.anonymizer.AnonymizeURI(mgmtURL)
-		}
-	}
-
-	g.sanitizeServiceEnvVars(params)
-
-	sanitizedData, err := json.MarshalIndent(params, "", "  ")
-	if err != nil {
-		return fmt.Errorf("marshal sanitized service params: %w", err)
-	}
-
-	if err := g.addFileToZip(bytes.NewReader(sanitizedData), serviceParamsBundle); err != nil {
-		return fmt.Errorf("add service params to zip: %w", err)
-	}
-
-	return nil
-}
-
-// sanitizeServiceEnvVars masks or anonymizes env var values in service params.
-// Non-NB_ vars and vars with sensitive names (key, token, etc.) are fully masked.
-// Other NB_ var values are passed through the anonymizer when anonymization is enabled.
-func (g *BundleGenerator) sanitizeServiceEnvVars(params map[string]any) {
-	envVars, ok := params[jsonKeyServiceEnv].(map[string]any)
-	if !ok {
-		return
-	}
-
-	sanitized := make(map[string]any, len(envVars))
-	for k, v := range envVars {
-		val, _ := v.(string)
-		switch {
-		case !strings.HasPrefix(k, envVarPrefix) || isSensitiveEnvVar(k):
-			sanitized[k] = maskedValue
-		case g.anonymize:
-			sanitized[k] = g.anonymizer.AnonymizeString(val)
-		default:
-			sanitized[k] = val
-		}
-	}
-	params[jsonKeyServiceEnv] = sanitized
-}
-
-// isSensitiveEnvVar returns true for env var names that may contain secrets.
-func isSensitiveEnvVar(key string) bool {
-	lower := strings.ToLower(key)
-	for _, s := range sensitiveEnvSubstrings {
-		if strings.Contains(lower, s) {
-			return true
-		}
-	}
-	return false
-}
-
 func (g *BundleGenerator) addCommonConfigFields(configContent *strings.Builder) {
 	configContent.WriteString("NetBird Client Configuration:\n\n")
 

client/internal/debug/debug_test.go

@@ -1,12 +1,8 @@
 package debug
 
 import (
-	"archive/zip"
-	"bytes"
 	"encoding/json"
 	"net"
-	"os"
-	"path/filepath"
 	"strings"
 	"testing"
 
@@ -14,7 +10,6 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/netbirdio/netbird/client/anonymize"
-	"github.com/netbirdio/netbird/client/configs"
 	mgmProto "github.com/netbirdio/netbird/shared/management/proto"
 )
 
@@ -425,226 +420,6 @@ func TestAnonymizeNetworkMap(t *testing.T) {
 	}
 }
 
-func TestIsSensitiveEnvVar(t *testing.T) {
-	tests := []struct {
-		key       string
-		sensitive bool
-	}{
-		{"NB_SETUP_KEY", true},
-		{"NB_API_TOKEN", true},
-		{"NB_CLIENT_SECRET", true},
-		{"NB_PASSWORD", true},
-		{"NB_CREDENTIAL", true},
-		{"NB_LOG_LEVEL", false},
-		{"NB_MANAGEMENT_URL", false},
-		{"NB_HOSTNAME", false},
-		{"HOME", false},
-		{"PATH", false},
-	}
-	for _, tt := range tests {
-		t.Run(tt.key, func(t *testing.T) {
-			assert.Equal(t, tt.sensitive, isSensitiveEnvVar(tt.key))
-		})
-	}
-}
-
-func TestSanitizeServiceEnvVars(t *testing.T) {
-	tests := []struct {
-		name      string
-		anonymize bool
-		input     map[string]any
-		check     func(t *testing.T, params map[string]any)
-	}{
-		{
-			name:      "no env vars key",
-			anonymize: false,
-			input:     map[string]any{"management_url": "https://mgmt.example.com"},
-			check: func(t *testing.T, params map[string]any) {
-				t.Helper()
-				assert.Equal(t, "https://mgmt.example.com", params["management_url"], "non-env fields should be untouched")
-				_, ok := params[jsonKeyServiceEnv]
-				assert.False(t, ok, "service_env_vars should not be added")
-			},
-		},
-		{
-			name:      "non-NB vars are masked",
-			anonymize: false,
-			input: map[string]any{
-				jsonKeyServiceEnv: map[string]any{
-					"HOME":       "/root",
-					"PATH":       "/usr/bin",
-					"NB_LOG_LEVEL": "debug",
-				},
-			},
-			check: func(t *testing.T, params map[string]any) {
-				t.Helper()
-				env := params[jsonKeyServiceEnv].(map[string]any)
-				assert.Equal(t, maskedValue, env["HOME"], "non-NB_ var should be masked")
-				assert.Equal(t, maskedValue, env["PATH"], "non-NB_ var should be masked")
-				assert.Equal(t, "debug", env["NB_LOG_LEVEL"], "safe NB_ var should pass through")
-			},
-		},
-		{
-			name:      "sensitive NB vars are masked",
-			anonymize: false,
-			input: map[string]any{
-				jsonKeyServiceEnv: map[string]any{
-					"NB_SETUP_KEY":  "abc123",
-					"NB_API_TOKEN":  "tok_xyz",
-					"NB_LOG_LEVEL":  "info",
-				},
-			},
-			check: func(t *testing.T, params map[string]any) {
-				t.Helper()
-				env := params[jsonKeyServiceEnv].(map[string]any)
-				assert.Equal(t, maskedValue, env["NB_SETUP_KEY"], "sensitive NB_ var should be masked")
-				assert.Equal(t, maskedValue, env["NB_API_TOKEN"], "sensitive NB_ var should be masked")
-				assert.Equal(t, "info", env["NB_LOG_LEVEL"], "safe NB_ var should pass through")
-			},
-		},
-		{
-			name:      "safe NB vars anonymized when anonymize is true",
-			anonymize: true,
-			input: map[string]any{
-				jsonKeyServiceEnv: map[string]any{
-					"NB_MANAGEMENT_URL": "https://mgmt.example.com:443",
-					"NB_LOG_LEVEL":      "debug",
-					"NB_SETUP_KEY":      "secret",
-					"SOME_OTHER":        "val",
-				},
-			},
-			check: func(t *testing.T, params map[string]any) {
-				t.Helper()
-				env := params[jsonKeyServiceEnv].(map[string]any)
-				// Safe NB_ values should be anonymized (not the original, not masked)
-				mgmtVal := env["NB_MANAGEMENT_URL"].(string)
-				assert.NotEqual(t, "https://mgmt.example.com:443", mgmtVal, "should be anonymized")
-				assert.NotEqual(t, maskedValue, mgmtVal, "should not be masked")
-
-				logVal := env["NB_LOG_LEVEL"].(string)
-				assert.NotEqual(t, maskedValue, logVal, "safe NB_ var should not be masked")
-
-				// Sensitive and non-NB_ still masked
-				assert.Equal(t, maskedValue, env["NB_SETUP_KEY"])
-				assert.Equal(t, maskedValue, env["SOME_OTHER"])
-			},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			anonymizer := anonymize.NewAnonymizer(anonymize.DefaultAddresses())
-			g := &BundleGenerator{
-				anonymize:  tt.anonymize,
-				anonymizer: anonymizer,
-			}
-			g.sanitizeServiceEnvVars(tt.input)
-			tt.check(t, tt.input)
-		})
-	}
-}
-
-func TestAddServiceParams(t *testing.T) {
-	t.Run("missing service.json returns nil", func(t *testing.T) {
-		g := &BundleGenerator{
-			anonymizer: anonymize.NewAnonymizer(anonymize.DefaultAddresses()),
-		}
-
-		origStateDir := configs.StateDir
-		configs.StateDir = t.TempDir()
-		t.Cleanup(func() { configs.StateDir = origStateDir })
-
-		err := g.addServiceParams()
-		assert.NoError(t, err)
-	})
-
-	t.Run("management_url anonymized when anonymize is true", func(t *testing.T) {
-		dir := t.TempDir()
-		origStateDir := configs.StateDir
-		configs.StateDir = dir
-		t.Cleanup(func() { configs.StateDir = origStateDir })
-
-		input := map[string]any{
-			jsonKeyManagementURL: "https://api.example.com:443",
-			jsonKeyServiceEnv: map[string]any{
-				"NB_LOG_LEVEL": "trace",
-			},
-		}
-		data, err := json.Marshal(input)
-		require.NoError(t, err)
-		require.NoError(t, os.WriteFile(filepath.Join(dir, serviceParamsFile), data, 0600))
-
-		var buf bytes.Buffer
-		zw := zip.NewWriter(&buf)
-
-		g := &BundleGenerator{
-			anonymize:  true,
-			anonymizer: anonymize.NewAnonymizer(anonymize.DefaultAddresses()),
-			archive:    zw,
-		}
-
-		require.NoError(t, g.addServiceParams())
-		require.NoError(t, zw.Close())
-
-		zr, err := zip.NewReader(bytes.NewReader(buf.Bytes()), int64(buf.Len()))
-		require.NoError(t, err)
-		require.Len(t, zr.File, 1)
-		assert.Equal(t, serviceParamsBundle, zr.File[0].Name)
-
-		rc, err := zr.File[0].Open()
-		require.NoError(t, err)
-		defer rc.Close()
-
-		var result map[string]any
-		require.NoError(t, json.NewDecoder(rc).Decode(&result))
-
-		mgmt := result[jsonKeyManagementURL].(string)
-		assert.NotEqual(t, "https://api.example.com:443", mgmt, "management_url should be anonymized")
-		assert.NotEmpty(t, mgmt)
-
-		env := result[jsonKeyServiceEnv].(map[string]any)
-		assert.NotEqual(t, maskedValue, env["NB_LOG_LEVEL"], "safe NB_ var should not be masked")
-	})
-
-	t.Run("management_url preserved when anonymize is false", func(t *testing.T) {
-		dir := t.TempDir()
-		origStateDir := configs.StateDir
-		configs.StateDir = dir
-		t.Cleanup(func() { configs.StateDir = origStateDir })
-
-		input := map[string]any{
-			jsonKeyManagementURL: "https://api.example.com:443",
-		}
-		data, err := json.Marshal(input)
-		require.NoError(t, err)
-		require.NoError(t, os.WriteFile(filepath.Join(dir, serviceParamsFile), data, 0600))
-
-		var buf bytes.Buffer
-		zw := zip.NewWriter(&buf)
-
-		g := &BundleGenerator{
-			anonymize:  false,
-			anonymizer: anonymize.NewAnonymizer(anonymize.DefaultAddresses()),
-			archive:    zw,
-		}
-
-		require.NoError(t, g.addServiceParams())
-		require.NoError(t, zw.Close())
-
-		zr, err := zip.NewReader(bytes.NewReader(buf.Bytes()), int64(buf.Len()))
-		require.NoError(t, err)
-
-		rc, err := zr.File[0].Open()
-		require.NoError(t, err)
-		defer rc.Close()
-
-		var result map[string]any
-		require.NoError(t, json.NewDecoder(rc).Decode(&result))
-
-		assert.Equal(t, "https://api.example.com:443", result[jsonKeyManagementURL], "management_url should be preserved")
-	})
-}
-
 // Helper function to check if IP is in CGNAT range
 func isInCGNATRange(ip net.IP) bool {
 	cgnat := net.IPNet{

client/internal/portforward/env.go

@@ -8,18 +8,27 @@ import (
 )
 
 const (
-	envDisableNATMapper = "NB_DISABLE_NAT_MAPPER"
+	envDisableNATMapper      = "NB_DISABLE_NAT_MAPPER"
+	envDisablePCPHealthCheck = "NB_DISABLE_PCP_HEALTH_CHECK"
 )
 
 func isDisabledByEnv() bool {
-	val := os.Getenv(envDisableNATMapper)
+	return parseBoolEnv(envDisableNATMapper)
+}
+
+func isHealthCheckDisabled() bool {
+	return parseBoolEnv(envDisablePCPHealthCheck)
+}
+
+func parseBoolEnv(key string) bool {
+	val := os.Getenv(key)
 	if val == "" {
 		return false
 	}
 
 	disabled, err := strconv.ParseBool(val)
 	if err != nil {
-		log.Warnf("failed to parse %s: %v", envDisableNATMapper, err)
+		log.Warnf("failed to parse %s: %v", key, err)
 		return false
 	}
 	return disabled

client/internal/portforward/manager.go

@@ -6,39 +6,31 @@ import (
 	"context"
 	"fmt"
 	"net"
-	"regexp"
 	"sync"
 	"time"
 
 	"github.com/libp2p/go-nat"
 	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/internal/portforward/pcp"
 )
 
 const (
-	defaultMappingTTL  = 2 * time.Hour
-	discoveryTimeout   = 10 * time.Second
-	mappingDescription = "NetBird"
+	defaultMappingTTL   = 2 * time.Hour
+	renewalInterval     = defaultMappingTTL / 2
+	healthCheckInterval = 1 * time.Minute
+	discoveryTimeout    = 10 * time.Second
+	mappingDescription  = "NetBird"
 )
 
-// upnpErrPermanentLeaseOnly matches UPnP error 725 in SOAP fault XML,
-// allowing for whitespace/newlines between tags from different router firmware.
-var upnpErrPermanentLeaseOnly = regexp.MustCompile(`<errorCode>\s*725\s*</errorCode>`)
-
-// Mapping represents an active NAT port mapping.
 type Mapping struct {
 	Protocol     string
 	InternalPort uint16
 	ExternalPort uint16
 	ExternalIP   net.IP
 	NATType      string
-	// TTL is the lease duration. Zero means a permanent lease that never expires.
-	TTL time.Duration
 }
 
-// TODO: persist mapping state for crash recovery cleanup of permanent leases.
-// Currently not done because State.Cleanup requires NAT gateway re-discovery,
-// which blocks startup for ~10s when no gateway is present (affects all clients).
-
 type Manager struct {
 	cancel context.CancelFunc
 
@@ -54,7 +46,6 @@ type Manager struct {
 	mu sync.Mutex
 }
 
-// NewManager creates a new port forwarding manager.
 func NewManager() *Manager {
 	return &Manager{
 		stopCtx: make(chan context.Context, 1),
@@ -89,7 +80,8 @@ func (m *Manager) Start(ctx context.Context, wgPort uint16) {
 
 	gateway, mapping, err := m.setup(ctx)
 	if err != nil {
-		log.Infof("port forwarding setup: %v", err)
+		log.Errorf("failed to setup NAT port mapping: %v", err)
+
 		return
 	}
 
@@ -97,7 +89,7 @@ func (m *Manager) Start(ctx context.Context, wgPort uint16) {
 	m.mapping = mapping
 	m.mappingLock.Unlock()
 
-	m.renewLoop(ctx, gateway, mapping.TTL)
+	m.renewLoop(ctx, gateway)
 
 	select {
 	case cleanupCtx := <-m.stopCtx:
@@ -154,16 +146,18 @@ func (m *Manager) setup(ctx context.Context) (nat.NAT, *Mapping, error) {
 	discoverCtx, discoverCancel := context.WithTimeout(ctx, discoveryTimeout)
 	defer discoverCancel()
 
-	gateway, err := nat.DiscoverGateway(discoverCtx)
+	gateway, err := discoverGateway(discoverCtx)
 	if err != nil {
-		return nil, nil, fmt.Errorf("discover gateway: %w", err)
+		log.Infof("NAT gateway discovery failed: %v (port forwarding disabled)", err)
+		return nil, nil, err
 	}
 
 	log.Infof("discovered NAT gateway: %s", gateway.Type())
 
 	mapping, err := m.createMapping(ctx, gateway)
 	if err != nil {
-		return nil, nil, fmt.Errorf("create port mapping: %w", err)
+		log.Warnf("failed to create port mapping: %v", err)
+		return nil, nil, err
 	}
 	return gateway, mapping, nil
 }
@@ -172,24 +166,14 @@ func (m *Manager) createMapping(ctx context.Context, gateway nat.NAT) (*Mapping,
 	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
 	defer cancel()
 
-	ttl := defaultMappingTTL
-	externalPort, err := gateway.AddPortMapping(ctx, "udp", int(m.wgPort), mappingDescription, ttl)
+	externalPort, err := gateway.AddPortMapping(ctx, "udp", int(m.wgPort), mappingDescription, defaultMappingTTL)
 	if err != nil {
-		if !isPermanentLeaseRequired(err) {
-			return nil, err
-		}
-		log.Infof("gateway only supports permanent leases, retrying with indefinite duration")
-		ttl = 0
-		externalPort, err = gateway.AddPortMapping(ctx, "udp", int(m.wgPort), mappingDescription, ttl)
-		if err != nil {
-			return nil, err
-		}
+		return nil, err
 	}
 
 	externalIP, err := gateway.GetExternalAddress()
 	if err != nil {
 		log.Debugf("failed to get external address: %v", err)
-		// todo return with err?
 	}
 
 	mapping := &Mapping{
@@ -198,7 +182,6 @@ func (m *Manager) createMapping(ctx context.Context, gateway nat.NAT) (*Mapping,
 		ExternalPort: uint16(externalPort),
 		ExternalIP:   externalIP,
 		NATType:      gateway.Type(),
-		TTL:          ttl,
 	}
 
 	log.Infof("created port mapping: %d -> %d via %s (external IP: %s)",
@@ -206,34 +189,73 @@ func (m *Manager) createMapping(ctx context.Context, gateway nat.NAT) (*Mapping,
 	return mapping, nil
 }
 
-func (m *Manager) renewLoop(ctx context.Context, gateway nat.NAT, ttl time.Duration) {
-	if ttl == 0 {
-		// Permanent mappings don't expire, just wait for cancellation.
-		<-ctx.Done()
-		return
-	}
-
-	ticker := time.NewTicker(ttl / 2)
-	defer ticker.Stop()
+func (m *Manager) renewLoop(ctx context.Context, gateway nat.NAT) {
+	renewTicker := time.NewTicker(renewalInterval)
+	healthTicker := time.NewTicker(healthCheckInterval)
+	defer renewTicker.Stop()
+	defer healthTicker.Stop()
 
 	for {
 		select {
 		case <-ctx.Done():
 			return
-		case <-ticker.C:
+		case <-renewTicker.C:
 			if err := m.renewMapping(ctx, gateway); err != nil {
 				log.Warnf("failed to renew port mapping: %v", err)
 				continue
 			}
+		case <-healthTicker.C:
+			if m.checkHealthAndRecreate(ctx, gateway) {
+				renewTicker.Reset(renewalInterval)
+			}
 		}
 	}
 }
 
+func (m *Manager) checkHealthAndRecreate(ctx context.Context, gateway nat.NAT) bool {
+	if isHealthCheckDisabled() {
+		return false
+	}
+
+	m.mappingLock.Lock()
+	hasMapping := m.mapping != nil
+	m.mappingLock.Unlock()
+
+	if !hasMapping {
+		return false
+	}
+
+	pcpNAT, ok := gateway.(*pcp.NAT)
+	if !ok {
+		return false
+	}
+
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+
+	epoch, serverRestarted, err := pcpNAT.CheckServerHealth(ctx)
+	if err != nil {
+		log.Debugf("PCP health check failed: %v", err)
+		return false
+	}
+
+	if serverRestarted {
+		log.Warnf("PCP server restart detected (epoch=%d), recreating port mapping", epoch)
+		if err := m.renewMapping(ctx, gateway); err != nil {
+			log.Errorf("failed to recreate port mapping after server restart: %v", err)
+			return false
+		}
+		return true
+	}
+
+	return false
+}
+
 func (m *Manager) renewMapping(ctx context.Context, gateway nat.NAT) error {
 	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
 	defer cancel()
 
-	externalPort, err := gateway.AddPortMapping(ctx, m.mapping.Protocol, int(m.mapping.InternalPort), mappingDescription, m.mapping.TTL)
+	externalPort, err := gateway.AddPortMapping(ctx, m.mapping.Protocol, int(m.mapping.InternalPort), mappingDescription, defaultMappingTTL)
 	if err != nil {
 		return fmt.Errorf("add port mapping: %w", err)
 	}
@@ -274,7 +296,3 @@ func (m *Manager) startTearDown(ctx context.Context) {
 	}
 }
 
-// isPermanentLeaseRequired checks if a UPnP error indicates the gateway only supports permanent leases (error 725).
-func isPermanentLeaseRequired(err error) bool {
-	return err != nil && upnpErrPermanentLeaseOnly.MatchString(err.Error())
-}

client/internal/portforward/manager_js.go

@@ -3,18 +3,15 @@ package portforward
 import (
 	"context"
 	"net"
-	"time"
 )
 
-// Mapping represents an active NAT port mapping.
+// Mapping represents port mapping information.
 type Mapping struct {
 	Protocol     string
 	InternalPort uint16
 	ExternalPort uint16
 	ExternalIP   net.IP
 	NATType      string
-	// TTL is the lease duration. Zero means a permanent lease that never expires.
-	TTL time.Duration
 }
 
 // Manager is a stub for js/wasm builds where NAT-PMP/UPnP is not supported.

client/internal/portforward/manager_test.go

@@ -4,25 +4,23 @@ package portforward
 
 import (
 	"context"
-	"fmt"
 	"net"
 	"testing"
 	"time"
 
+	"github.com/libp2p/go-nat"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 type mockNAT struct {
-	natType             string
-	deviceAddr          net.IP
-	externalAddr        net.IP
-	internalAddr        net.IP
-	mappings            map[int]int
-	addMappingErr       error
-	deleteMappingErr    error
-	onlyPermanentLeases bool
-	lastTimeout         time.Duration
+	natType          string
+	deviceAddr       net.IP
+	externalAddr     net.IP
+	internalAddr     net.IP
+	mappings         map[int]int
+	addMappingErr    error
+	deleteMappingErr error
 }
 
 func newMockNAT() *mockNAT {
@@ -55,12 +53,8 @@ func (m *mockNAT) AddPortMapping(ctx context.Context, protocol string, internalP
 	if m.addMappingErr != nil {
 		return 0, m.addMappingErr
 	}
-	if m.onlyPermanentLeases && timeout != 0 {
-		return 0, fmt.Errorf("SOAP fault. Code:  | Explanation:  | Detail: <UPnPError xmlns=\"urn:schemas-upnp-org:control-1-0\"><errorCode>725</errorCode><errorDescription>OnlyPermanentLeasesSupported</errorDescription></UPnPError>")
-	}
 	externalPort := internalPort
 	m.mappings[internalPort] = externalPort
-	m.lastTimeout = timeout
 	return externalPort, nil
 }
 
@@ -86,7 +80,6 @@ func TestManager_CreateMapping(t *testing.T) {
 	assert.Equal(t, uint16(51820), mapping.ExternalPort)
 	assert.Equal(t, "Mock-NAT", mapping.NATType)
 	assert.Equal(t, net.ParseIP("203.0.113.50").To4(), mapping.ExternalIP.To4())
-	assert.Equal(t, defaultMappingTTL, mapping.TTL)
 }
 
 func TestManager_GetMapping_ReturnsNilWhenNotReady(t *testing.T) {
@@ -138,64 +131,29 @@ func TestManager_Cleanup_NilMapping(t *testing.T) {
 	m.cleanup(context.Background(), gateway)
 }
 
+func TestState_Cleanup(t *testing.T) {
+	origDiscover := discoverGateway
+	defer func() { discoverGateway = origDiscover }()
 
-func TestManager_CreateMapping_PermanentLeaseFallback(t *testing.T) {
-	m := NewManager()
-	m.wgPort = 51820
-
-	gateway := newMockNAT()
-	gateway.onlyPermanentLeases = true
-
-	mapping, err := m.createMapping(context.Background(), gateway)
-	require.NoError(t, err)
-	require.NotNil(t, mapping)
-
-	assert.Equal(t, uint16(51820), mapping.InternalPort)
-	assert.Equal(t, time.Duration(0), mapping.TTL, "should return zero TTL for permanent lease")
-	assert.Equal(t, time.Duration(0), gateway.lastTimeout, "should have retried with zero duration")
-}
-
-func TestIsPermanentLeaseRequired(t *testing.T) {
-	tests := []struct {
-		name     string
-		err      error
-		expected bool
-	}{
-		{
-			name:     "nil error",
-			err:      nil,
-			expected: false,
-		},
-		{
-			name:     "UPnP error 725",
-			err:      fmt.Errorf("SOAP fault. Code:  | Detail: <UPnPError><errorCode>725</errorCode><errorDescription>OnlyPermanentLeasesSupported</errorDescription></UPnPError>"),
-			expected: true,
-		},
-		{
-			name:     "wrapped error with 725",
-			err:      fmt.Errorf("add port mapping: %w", fmt.Errorf("Detail: <errorCode>725</errorCode>")),
-			expected: true,
-		},
-		{
-			name:     "error 725 with newlines in XML",
-			err:      fmt.Errorf("<errorCode>\n  725\n</errorCode>"),
-			expected: true,
-		},
-		{
-			name:     "bare 725 without XML tag",
-			err:      fmt.Errorf("error code 725"),
-			expected: false,
-		},
-		{
-			name:     "unrelated error",
-			err:      fmt.Errorf("connection refused"),
-			expected: false,
-		},
+	mockGateway := newMockNAT()
+	mockGateway.mappings[51820] = 51820
+	discoverGateway = func(ctx context.Context) (nat.NAT, error) {
+		return mockGateway, nil
 	}
 
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			assert.Equal(t, tt.expected, isPermanentLeaseRequired(tt.err))
-		})
+	state := &State{
+		Protocol:     "udp",
+		InternalPort: 51820,
 	}
+
+	err := state.Cleanup()
+	assert.NoError(t, err)
+
+	_, exists := mockGateway.mappings[51820]
+	assert.False(t, exists, "mapping should be deleted after cleanup")
+}
+
+func TestState_Name(t *testing.T) {
+	state := &State{}
+	assert.Equal(t, "port_forward_state", state.Name())
 }

client/internal/portforward/pcp/client.go

@@ -0,0 +1,408 @@
+package pcp
+
+import (
+	"context"
+	"crypto/rand"
+	"errors"
+	"fmt"
+	"net"
+	"net/netip"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+)
+
+const (
+	defaultTimeout     = 3 * time.Second
+	responseBufferSize = 128
+
+	// RFC 6887 Section 8.1.1 retry timing
+	initialRetryDelay = 3 * time.Second
+	maxRetryDelay     = 1024 * time.Second
+	maxRetries        = 4 // 3s + 6s + 12s + 24s = 45s total worst case
+)
+
+// Client is a PCP protocol client.
+// All methods are safe for concurrent use.
+type Client struct {
+	gateway netip.Addr
+	timeout time.Duration
+
+	mu sync.Mutex
+	// localIP caches the resolved local IP address.
+	localIP netip.Addr
+	// lastEpoch is the last observed server epoch value.
+	lastEpoch uint32
+	// epochTime tracks when lastEpoch was received for state loss detection.
+	epochTime time.Time
+	// externalIP caches the external IP from the last successful MAP response.
+	externalIP netip.Addr
+	// epochStateLost is set when epoch indicates server restart.
+	epochStateLost bool
+}
+
+// NewClient creates a new PCP client for the gateway at the given IP.
+func NewClient(gateway net.IP) *Client {
+	addr, ok := netip.AddrFromSlice(gateway)
+	if !ok {
+		log.Debugf("invalid gateway IP: %v", gateway)
+	}
+	return &Client{
+		gateway: addr.Unmap(),
+		timeout: defaultTimeout,
+	}
+}
+
+// NewClientWithTimeout creates a new PCP client with a custom timeout.
+func NewClientWithTimeout(gateway net.IP, timeout time.Duration) *Client {
+	addr, ok := netip.AddrFromSlice(gateway)
+	if !ok {
+		log.Debugf("invalid gateway IP: %v", gateway)
+	}
+	return &Client{
+		gateway: addr.Unmap(),
+		timeout: timeout,
+	}
+}
+
+// SetLocalIP sets the local IP address to use in PCP requests.
+func (c *Client) SetLocalIP(ip net.IP) {
+	addr, ok := netip.AddrFromSlice(ip)
+	if !ok {
+		log.Debugf("invalid local IP: %v", ip)
+	}
+	c.mu.Lock()
+	c.localIP = addr.Unmap()
+	c.mu.Unlock()
+}
+
+// Gateway returns the gateway IP address.
+func (c *Client) Gateway() net.IP {
+	return c.gateway.AsSlice()
+}
+
+// Announce sends a PCP ANNOUNCE request to discover PCP support.
+// Returns the server's epoch time on success.
+func (c *Client) Announce(ctx context.Context) (epoch uint32, err error) {
+	localIP, err := c.getLocalIP()
+	if err != nil {
+		return 0, fmt.Errorf("get local IP: %w", err)
+	}
+
+	req := buildAnnounceRequest(localIP)
+	resp, err := c.sendRequest(ctx, req)
+	if err != nil {
+		return 0, fmt.Errorf("send announce: %w", err)
+	}
+
+	parsed, err := parseResponse(resp)
+	if err != nil {
+		return 0, fmt.Errorf("parse announce response: %w", err)
+	}
+
+	if parsed.ResultCode != ResultSuccess {
+		return 0, fmt.Errorf("PCP ANNOUNCE failed: %s", ResultCodeString(parsed.ResultCode))
+	}
+
+	c.mu.Lock()
+	if c.updateEpochLocked(parsed.Epoch) {
+		log.Warnf("PCP server epoch indicates state loss - mappings may need refresh")
+	}
+	c.mu.Unlock()
+	return parsed.Epoch, nil
+}
+
+// AddPortMapping requests a port mapping from the PCP server.
+func (c *Client) AddPortMapping(ctx context.Context, protocol string, internalPort int, lifetime time.Duration) (*MapResponse, error) {
+	return c.addPortMappingWithHint(ctx, protocol, internalPort, internalPort, netip.Addr{}, lifetime)
+}
+
+// AddPortMappingWithHint requests a port mapping with suggested external port and IP.
+// Use lifetime <= 0 to delete a mapping.
+func (c *Client) AddPortMappingWithHint(ctx context.Context, protocol string, internalPort, suggestedExtPort int, suggestedExtIP net.IP, lifetime time.Duration) (*MapResponse, error) {
+	var extIP netip.Addr
+	if suggestedExtIP != nil {
+		var ok bool
+		extIP, ok = netip.AddrFromSlice(suggestedExtIP)
+		if !ok {
+			log.Debugf("invalid suggested external IP: %v", suggestedExtIP)
+		}
+		extIP = extIP.Unmap()
+	}
+	return c.addPortMappingWithHint(ctx, protocol, internalPort, suggestedExtPort, extIP, lifetime)
+}
+
+func (c *Client) addPortMappingWithHint(ctx context.Context, protocol string, internalPort, suggestedExtPort int, suggestedExtIP netip.Addr, lifetime time.Duration) (*MapResponse, error) {
+	localIP, err := c.getLocalIP()
+	if err != nil {
+		return nil, fmt.Errorf("get local IP: %w", err)
+	}
+
+	proto, err := protocolNumber(protocol)
+	if err != nil {
+		return nil, fmt.Errorf("parse protocol: %w", err)
+	}
+
+	var nonce [12]byte
+	if _, err := rand.Read(nonce[:]); err != nil {
+		return nil, fmt.Errorf("generate nonce: %w", err)
+	}
+
+	// Convert lifetime to seconds. Lifetime 0 means delete, so only apply
+	// default for positive durations that round to 0 seconds.
+	var lifetimeSec uint32
+	if lifetime > 0 {
+		lifetimeSec = uint32(lifetime.Seconds())
+		if lifetimeSec == 0 {
+			lifetimeSec = DefaultLifetime
+		}
+	}
+
+	req := buildMapRequest(localIP, nonce, proto, uint16(internalPort), uint16(suggestedExtPort), suggestedExtIP, lifetimeSec)
+
+	resp, err := c.sendRequest(ctx, req)
+	if err != nil {
+		return nil, fmt.Errorf("send map request: %w", err)
+	}
+
+	mapResp, err := parseMapResponse(resp)
+	if err != nil {
+		return nil, fmt.Errorf("parse map response: %w", err)
+	}
+
+	if mapResp.Nonce != nonce {
+		return nil, fmt.Errorf("nonce mismatch in response")
+	}
+
+	if mapResp.Protocol != proto {
+		return nil, fmt.Errorf("protocol mismatch: requested %d, got %d", proto, mapResp.Protocol)
+	}
+	if mapResp.InternalPort != uint16(internalPort) {
+		return nil, fmt.Errorf("internal port mismatch: requested %d, got %d", internalPort, mapResp.InternalPort)
+	}
+
+	if mapResp.ResultCode != ResultSuccess {
+		return nil, &Error{
+			Code:    mapResp.ResultCode,
+			Message: ResultCodeString(mapResp.ResultCode),
+		}
+	}
+
+	c.mu.Lock()
+	if c.updateEpochLocked(mapResp.Epoch) {
+		log.Warnf("PCP server epoch indicates state loss - mappings may need refresh")
+	}
+	c.cacheExternalIPLocked(mapResp.ExternalIP)
+	c.mu.Unlock()
+	return mapResp, nil
+}
+
+// DeletePortMapping removes a port mapping by requesting zero lifetime.
+func (c *Client) DeletePortMapping(ctx context.Context, protocol string, internalPort int) error {
+	if _, err := c.addPortMappingWithHint(ctx, protocol, internalPort, 0, netip.Addr{}, 0); err != nil {
+		var pcpErr *Error
+		if errors.As(err, &pcpErr) && pcpErr.Code == ResultNotAuthorized {
+			return nil
+		}
+		return fmt.Errorf("delete mapping: %w", err)
+	}
+	return nil
+}
+
+// GetExternalAddress returns the external IP address.
+// First checks for a cached value from previous MAP responses.
+// If not cached, creates a short-lived mapping to discover the external IP.
+func (c *Client) GetExternalAddress(ctx context.Context) (net.IP, error) {
+	c.mu.Lock()
+	if c.externalIP.IsValid() {
+		ip := c.externalIP.AsSlice()
+		c.mu.Unlock()
+		return ip, nil
+	}
+	c.mu.Unlock()
+
+	// Use an ephemeral port in the dynamic range (49152-65535).
+	// Port 0 is not valid with UDP/TCP protocols per RFC 6887.
+	ephemeralPort := 49152 + int(uint16(time.Now().UnixNano()))%(65535-49152)
+
+	// Use minimal lifetime (1 second) for discovery.
+	resp, err := c.AddPortMapping(ctx, "udp", ephemeralPort, time.Second)
+	if err != nil {
+		return nil, fmt.Errorf("create temporary mapping: %w", err)
+	}
+
+	if err := c.DeletePortMapping(ctx, "udp", ephemeralPort); err != nil {
+		log.Debugf("cleanup temporary PCP mapping: %v", err)
+	}
+
+	return resp.ExternalIP.AsSlice(), nil
+}
+
+// LastEpoch returns the last observed server epoch value.
+// A decrease in epoch indicates the server may have restarted and mappings may be lost.
+func (c *Client) LastEpoch() uint32 {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.lastEpoch
+}
+
+// EpochStateLost returns true if epoch state loss was detected and clears the flag.
+func (c *Client) EpochStateLost() bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	lost := c.epochStateLost
+	c.epochStateLost = false
+	return lost
+}
+
+// updateEpoch updates the epoch tracking and detects potential state loss.
+// Returns true if state loss was detected (server likely restarted).
+// Caller must hold c.mu.
+func (c *Client) updateEpochLocked(newEpoch uint32) bool {
+	now := time.Now()
+	stateLost := false
+
+	// RFC 6887 Section 8.5: Detect invalid epoch indicating server state loss.
+	// client_delta = time since last response
+	// server_delta = epoch change since last response
+	// Invalid if: client_delta+2 < server_delta - server_delta/16
+	//         OR: server_delta+2 < client_delta - client_delta/16
+	// The +2 handles quantization, /16 (6.25%) handles clock drift.
+	if !c.epochTime.IsZero() && c.lastEpoch > 0 {
+		clientDelta := uint32(now.Sub(c.epochTime).Seconds())
+		serverDelta := newEpoch - c.lastEpoch
+
+		// Check for epoch going backwards or jumping unexpectedly.
+		// Subtraction is safe: serverDelta/16 is always <= serverDelta.
+		if clientDelta+2 < serverDelta-(serverDelta/16) ||
+			serverDelta+2 < clientDelta-(clientDelta/16) {
+			stateLost = true
+			c.epochStateLost = true
+		}
+	}
+
+	c.lastEpoch = newEpoch
+	c.epochTime = now
+	return stateLost
+}
+
+// cacheExternalIP stores the external IP from a successful MAP response.
+// Caller must hold c.mu.
+func (c *Client) cacheExternalIPLocked(ip netip.Addr) {
+	if ip.IsValid() && !ip.IsUnspecified() {
+		c.externalIP = ip
+	}
+}
+
+// sendRequest sends a PCP request with retries per RFC 6887 Section 8.1.1.
+func (c *Client) sendRequest(ctx context.Context, req []byte) ([]byte, error) {
+	addr := &net.UDPAddr{IP: c.gateway.AsSlice(), Port: Port}
+
+	var lastErr error
+	delay := initialRetryDelay
+
+	for range maxRetries {
+		resp, err := c.sendOnce(ctx, addr, req)
+		if err == nil {
+			return resp, nil
+		}
+		lastErr = err
+
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+
+		// RFC 6887 Section 8.1.1: RT = (1 + RAND) * MIN(2 * RTprev, MRT)
+		// RAND is random between -0.1 and +0.1
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(retryDelayWithJitter(delay)):
+		}
+		delay = min(delay*2, maxRetryDelay)
+	}
+
+	return nil, fmt.Errorf("PCP request failed after %d retries: %w", maxRetries, lastErr)
+}
+
+// retryDelayWithJitter applies RFC 6887 jitter: multiply by (1 + RAND) where RAND is [-0.1, +0.1].
+func retryDelayWithJitter(d time.Duration) time.Duration {
+	var b [1]byte
+	_, _ = rand.Read(b[:])
+	// Convert byte to range [-0.1, +0.1]: (b/255 * 0.2) - 0.1
+	jitter := (float64(b[0])/255.0)*0.2 - 0.1
+	return time.Duration(float64(d) * (1 + jitter))
+}
+
+func (c *Client) sendOnce(ctx context.Context, addr *net.UDPAddr, req []byte) ([]byte, error) {
+	// Use ListenUDP instead of DialUDP to validate response source address per RFC 6887 §8.3.
+	conn, err := net.ListenUDP("udp", nil)
+	if err != nil {
+		return nil, fmt.Errorf("listen: %w", err)
+	}
+	defer func() {
+		if err := conn.Close(); err != nil {
+			log.Debugf("close UDP connection: %v", err)
+		}
+	}()
+
+	timeout := c.timeout
+	if deadline, ok := ctx.Deadline(); ok {
+		if remaining := time.Until(deadline); remaining < timeout {
+			timeout = remaining
+		}
+	}
+
+	if err := conn.SetDeadline(time.Now().Add(timeout)); err != nil {
+		return nil, fmt.Errorf("set deadline: %w", err)
+	}
+
+	if _, err := conn.WriteToUDP(req, addr); err != nil {
+		return nil, fmt.Errorf("write: %w", err)
+	}
+
+	resp := make([]byte, responseBufferSize)
+	n, from, err := conn.ReadFromUDP(resp)
+	if err != nil {
+		return nil, fmt.Errorf("read: %w", err)
+	}
+
+	// RFC 6887 §8.3: Validate response came from expected PCP server.
+	if !from.IP.Equal(addr.IP) {
+		return nil, fmt.Errorf("response from unexpected source %s (expected %s)", from.IP, addr.IP)
+	}
+
+	return resp[:n], nil
+}
+
+func (c *Client) getLocalIP() (netip.Addr, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if !c.localIP.IsValid() {
+		return netip.Addr{}, fmt.Errorf("local IP not set for gateway %s", c.gateway)
+	}
+	return c.localIP, nil
+}
+
+func protocolNumber(protocol string) (uint8, error) {
+	switch protocol {
+	case "udp", "UDP":
+		return ProtoUDP, nil
+	case "tcp", "TCP":
+		return ProtoTCP, nil
+	default:
+		return 0, fmt.Errorf("unsupported protocol: %s", protocol)
+	}
+}
+
+// Error represents a PCP error response.
+type Error struct {
+	Code    uint8
+	Message string
+}
+
+func (e *Error) Error() string {
+	return fmt.Sprintf("PCP error: %s (%d)", e.Message, e.Code)
+}

client/internal/portforward/pcp/client_test.go

@@ -0,0 +1,187 @@
+package pcp
+
+import (
+	"context"
+	"net"
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestAddrConversion(t *testing.T) {
+	tests := []struct {
+		name string
+		addr netip.Addr
+	}{
+		{"IPv4", netip.MustParseAddr("192.168.1.100")},
+		{"IPv4 loopback", netip.MustParseAddr("127.0.0.1")},
+		{"IPv6", netip.MustParseAddr("2001:db8::1")},
+		{"IPv6 loopback", netip.MustParseAddr("::1")},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			b16 := addrTo16(tt.addr)
+
+			recovered := addrFrom16(b16)
+			assert.Equal(t, tt.addr, recovered, "address should round-trip")
+		})
+	}
+}
+
+func TestBuildAnnounceRequest(t *testing.T) {
+	clientIP := netip.MustParseAddr("192.168.1.100")
+	req := buildAnnounceRequest(clientIP)
+
+	require.Len(t, req, headerSize)
+	assert.Equal(t, byte(Version), req[0], "version")
+	assert.Equal(t, byte(OpAnnounce), req[1], "opcode")
+
+	// Check client IP is properly encoded as IPv4-mapped IPv6
+	assert.Equal(t, byte(0xff), req[18], "IPv4-mapped prefix byte 10")
+	assert.Equal(t, byte(0xff), req[19], "IPv4-mapped prefix byte 11")
+	assert.Equal(t, byte(192), req[20], "IP octet 1")
+	assert.Equal(t, byte(168), req[21], "IP octet 2")
+	assert.Equal(t, byte(1), req[22], "IP octet 3")
+	assert.Equal(t, byte(100), req[23], "IP octet 4")
+}
+
+func TestBuildMapRequest(t *testing.T) {
+	clientIP := netip.MustParseAddr("192.168.1.100")
+	nonce := [12]byte{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}
+	req := buildMapRequest(clientIP, nonce, ProtoUDP, 51820, 51820, netip.Addr{}, 3600)
+
+	require.Len(t, req, mapRequestSize)
+	assert.Equal(t, byte(Version), req[0], "version")
+	assert.Equal(t, byte(OpMap), req[1], "opcode")
+
+	// Lifetime at bytes 4-7
+	assert.Equal(t, uint32(3600), (uint32(req[4])<<24)|(uint32(req[5])<<16)|(uint32(req[6])<<8)|uint32(req[7]), "lifetime")
+
+	// Nonce at bytes 24-35
+	assert.Equal(t, nonce[:], req[24:36], "nonce")
+
+	// Protocol at byte 36
+	assert.Equal(t, byte(ProtoUDP), req[36], "protocol")
+
+	// Internal port at bytes 40-41
+	assert.Equal(t, uint16(51820), (uint16(req[40])<<8)|uint16(req[41]), "internal port")
+
+	// External port at bytes 42-43
+	assert.Equal(t, uint16(51820), (uint16(req[42])<<8)|uint16(req[43]), "external port")
+}
+
+func TestParseResponse(t *testing.T) {
+	// Construct a valid ANNOUNCE response
+	resp := make([]byte, headerSize)
+	resp[0] = Version
+	resp[1] = OpAnnounce | OpReply
+	// Result code = 0 (success)
+	// Lifetime = 0
+	// Epoch = 12345
+	resp[8] = 0
+	resp[9] = 0
+	resp[10] = 0x30
+	resp[11] = 0x39
+
+	parsed, err := parseResponse(resp)
+	require.NoError(t, err)
+	assert.Equal(t, uint8(Version), parsed.Version)
+	assert.Equal(t, uint8(OpAnnounce|OpReply), parsed.Opcode)
+	assert.Equal(t, uint8(ResultSuccess), parsed.ResultCode)
+	assert.Equal(t, uint32(12345), parsed.Epoch)
+}
+
+func TestParseResponseErrors(t *testing.T) {
+	t.Run("too short", func(t *testing.T) {
+		_, err := parseResponse([]byte{1, 2, 3})
+		assert.Error(t, err)
+	})
+
+	t.Run("wrong version", func(t *testing.T) {
+		resp := make([]byte, headerSize)
+		resp[0] = 1 // Wrong version
+		resp[1] = OpReply
+		_, err := parseResponse(resp)
+		assert.Error(t, err)
+	})
+
+	t.Run("missing reply bit", func(t *testing.T) {
+		resp := make([]byte, headerSize)
+		resp[0] = Version
+		resp[1] = OpAnnounce // Missing OpReply bit
+		_, err := parseResponse(resp)
+		assert.Error(t, err)
+	})
+}
+
+func TestResultCodeString(t *testing.T) {
+	assert.Equal(t, "SUCCESS", ResultCodeString(ResultSuccess))
+	assert.Equal(t, "NOT_AUTHORIZED", ResultCodeString(ResultNotAuthorized))
+	assert.Equal(t, "ADDRESS_MISMATCH", ResultCodeString(ResultAddressMismatch))
+	assert.Contains(t, ResultCodeString(255), "UNKNOWN")
+}
+
+func TestProtocolNumber(t *testing.T) {
+	proto, err := protocolNumber("udp")
+	require.NoError(t, err)
+	assert.Equal(t, uint8(ProtoUDP), proto)
+
+	proto, err = protocolNumber("tcp")
+	require.NoError(t, err)
+	assert.Equal(t, uint8(ProtoTCP), proto)
+
+	proto, err = protocolNumber("UDP")
+	require.NoError(t, err)
+	assert.Equal(t, uint8(ProtoUDP), proto)
+
+	_, err = protocolNumber("icmp")
+	assert.Error(t, err)
+}
+
+func TestClientCreation(t *testing.T) {
+	gateway := netip.MustParseAddr("192.168.1.1").AsSlice()
+
+	client := NewClient(gateway)
+	assert.Equal(t, net.IP(gateway), client.Gateway())
+	assert.Equal(t, defaultTimeout, client.timeout)
+
+	clientWithTimeout := NewClientWithTimeout(gateway, 5*time.Second)
+	assert.Equal(t, 5*time.Second, clientWithTimeout.timeout)
+}
+
+func TestNATType(t *testing.T) {
+	n := NewNAT(netip.MustParseAddr("192.168.1.1").AsSlice(), netip.MustParseAddr("192.168.1.100").AsSlice())
+	assert.Equal(t, "PCP", n.Type())
+}
+
+// Integration test - skipped unless PCP_TEST_GATEWAY env is set
+func TestClientIntegration(t *testing.T) {
+	t.Skip("Integration test - run manually with PCP_TEST_GATEWAY=<gateway-ip>")
+
+	gateway := netip.MustParseAddr("10.0.1.1").AsSlice()   // Change to your test gateway
+	localIP := netip.MustParseAddr("10.0.1.100").AsSlice() // Change to your local IP
+
+	client := NewClient(gateway)
+	client.SetLocalIP(localIP)
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	// Test ANNOUNCE
+	epoch, err := client.Announce(ctx)
+	require.NoError(t, err)
+	t.Logf("Server epoch: %d", epoch)
+
+	// Test MAP
+	resp, err := client.AddPortMapping(ctx, "udp", 51820, 1*time.Hour)
+	require.NoError(t, err)
+	t.Logf("Mapping: internal=%d external=%d externalIP=%s",
+		resp.InternalPort, resp.ExternalPort, resp.ExternalIP)
+
+	// Cleanup
+	err = client.DeletePortMapping(ctx, "udp", 51820)
+	require.NoError(t, err)
+}

client/internal/portforward/pcp/nat.go

@@ -0,0 +1,209 @@
+package pcp
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/netip"
+	"sync"
+	"time"
+
+	log "github.com/sirupsen/logrus"
+
+	"github.com/libp2p/go-nat"
+	"github.com/libp2p/go-netroute"
+)
+
+var _ nat.NAT = (*NAT)(nil)
+
+// NAT implements the go-nat NAT interface using PCP.
+// Supports dual-stack (IPv4 and IPv6) when available.
+// All methods are safe for concurrent use.
+//
+// TODO: IPv6 pinholes use the local IPv6 address. If the address changes
+// (e.g., due to SLAAC rotation or network change), the pinhole becomes stale
+// and needs to be recreated with the new address.
+type NAT struct {
+	client *Client
+
+	mu sync.RWMutex
+	// client6 is the IPv6 PCP client, nil if IPv6 is unavailable.
+	client6 *Client
+	// localIP6 caches the local IPv6 address used for PCP requests.
+	localIP6 netip.Addr
+}
+
+// NewNAT creates a new NAT instance backed by PCP.
+func NewNAT(gateway, localIP net.IP) *NAT {
+	client := NewClient(gateway)
+	client.SetLocalIP(localIP)
+	return &NAT{
+		client: client,
+	}
+}
+
+// Type returns "PCP" as the NAT type.
+func (n *NAT) Type() string {
+	return "PCP"
+}
+
+// GetDeviceAddress returns the gateway IP address.
+func (n *NAT) GetDeviceAddress() (net.IP, error) {
+	return n.client.Gateway(), nil
+}
+
+// GetExternalAddress returns the external IP address.
+func (n *NAT) GetExternalAddress() (net.IP, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	return n.client.GetExternalAddress(ctx)
+}
+
+// GetInternalAddress returns the local IP address used to communicate with the gateway.
+func (n *NAT) GetInternalAddress() (net.IP, error) {
+	addr, err := n.client.getLocalIP()
+	if err != nil {
+		return nil, err
+	}
+	return addr.AsSlice(), nil
+}
+
+// AddPortMapping creates a port mapping on both IPv4 and IPv6 (if available).
+func (n *NAT) AddPortMapping(ctx context.Context, protocol string, internalPort int, _ string, timeout time.Duration) (int, error) {
+	resp, err := n.client.AddPortMapping(ctx, protocol, internalPort, timeout)
+	if err != nil {
+		return 0, fmt.Errorf("add mapping: %w", err)
+	}
+
+	n.mu.RLock()
+	client6 := n.client6
+	localIP6 := n.localIP6
+	n.mu.RUnlock()
+
+	if client6 == nil {
+		return int(resp.ExternalPort), nil
+	}
+
+	if _, err := client6.AddPortMapping(ctx, protocol, internalPort, timeout); err != nil {
+		log.Warnf("IPv6 PCP mapping failed (continuing with IPv4): %v", err)
+		return int(resp.ExternalPort), nil
+	}
+
+	log.Infof("created IPv6 PCP pinhole: %s:%d", localIP6, internalPort)
+	return int(resp.ExternalPort), nil
+}
+
+// DeletePortMapping removes a port mapping from both IPv4 and IPv6.
+func (n *NAT) DeletePortMapping(ctx context.Context, protocol string, internalPort int) error {
+	err := n.client.DeletePortMapping(ctx, protocol, internalPort)
+
+	n.mu.RLock()
+	client6 := n.client6
+	n.mu.RUnlock()
+
+	if client6 != nil {
+		if err6 := client6.DeletePortMapping(ctx, protocol, internalPort); err6 != nil {
+			log.Warnf("IPv6 PCP delete mapping failed: %v", err6)
+		}
+	}
+
+	if err != nil {
+		return fmt.Errorf("delete mapping: %w", err)
+	}
+	return nil
+}
+
+// CheckServerHealth sends an ANNOUNCE to verify the server is still responsive.
+// Returns the current epoch and whether the server may have restarted (epoch state loss detected).
+func (n *NAT) CheckServerHealth(ctx context.Context) (epoch uint32, serverRestarted bool, err error) {
+	epoch, err = n.client.Announce(ctx)
+	if err != nil {
+		return 0, false, fmt.Errorf("announce: %w", err)
+	}
+	return epoch, n.client.EpochStateLost(), nil
+}
+
+// DiscoverPCP attempts to discover a PCP-capable gateway.
+// Returns a NAT interface if PCP is supported, or an error otherwise.
+// Discovers both IPv4 and IPv6 gateways when available.
+func DiscoverPCP(ctx context.Context) (nat.NAT, error) {
+	gateway, localIP, err := getDefaultGateway()
+	if err != nil {
+		return nil, fmt.Errorf("get default gateway: %w", err)
+	}
+
+	client := NewClient(gateway)
+	client.SetLocalIP(localIP)
+	if _, err := client.Announce(ctx); err != nil {
+		return nil, fmt.Errorf("PCP announce: %w", err)
+	}
+
+	result := &NAT{client: client}
+	discoverIPv6(ctx, result)
+
+	return result, nil
+}
+
+func discoverIPv6(ctx context.Context, result *NAT) {
+	gateway6, localIP6, err := getDefaultGateway6()
+	if err != nil {
+		log.Debugf("IPv6 gateway discovery failed: %v", err)
+		return
+	}
+
+	client6 := NewClient(gateway6)
+	client6.SetLocalIP(localIP6)
+	if _, err := client6.Announce(ctx); err != nil {
+		log.Debugf("PCP IPv6 announce failed: %v", err)
+		return
+	}
+
+	addr, ok := netip.AddrFromSlice(localIP6)
+	if !ok {
+		log.Debugf("invalid IPv6 local IP: %v", localIP6)
+		return
+	}
+	result.mu.Lock()
+	result.client6 = client6
+	result.localIP6 = addr
+	result.mu.Unlock()
+	log.Debugf("PCP IPv6 gateway discovered: %s (local: %s)", gateway6, localIP6)
+}
+
+// getDefaultGateway returns the default IPv4 gateway and local IP using the system routing table.
+func getDefaultGateway() (gateway net.IP, localIP net.IP, err error) {
+	router, err := netroute.New()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	_, gateway, localIP, err = router.Route(net.IPv4zero)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if gateway == nil {
+		return nil, nil, nat.ErrNoNATFound
+	}
+
+	return gateway, localIP, nil
+}
+
+// getDefaultGateway6 returns the default IPv6 gateway IP address using the system routing table.
+func getDefaultGateway6() (gateway net.IP, localIP net.IP, err error) {
+	router, err := netroute.New()
+	if err != nil {
+		return nil, nil, err
+	}
+
+	_, gateway, localIP, err = router.Route(net.IPv6zero)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if gateway == nil {
+		return nil, nil, nat.ErrNoNATFound
+	}
+
+	return gateway, localIP, nil
+}

client/internal/portforward/pcp/protocol.go

@@ -0,0 +1,225 @@
+// Package pcp implements the Port Control Protocol (RFC 6887).
+//
+// # Implemented Features
+//
+//   - ANNOUNCE opcode: Discovers PCP server support
+//   - MAP opcode: Creates/deletes port mappings (IPv4 NAT) and firewall pinholes (IPv6)
+//   - Dual-stack: Simultaneous IPv4 and IPv6 support via separate clients
+//   - Nonce validation: Prevents response spoofing
+//   - Epoch tracking: Detects server restarts per Section 8.5
+//   - RFC-compliant retry timing: 3s initial, exponential backoff to 1024s max (Section 8.1.1)
+//
+// # Not Implemented
+//
+//   - PEER opcode: For outbound peer connections (not needed for inbound NAT traversal)
+//   - THIRD_PARTY option: For managing mappings on behalf of other devices
+//   - PREFER_FAILURE option: Requires exact external port or fail (IPv4 NAT only, not needed for IPv6 pinholing)
+//   - FILTER option: To restrict remote peer addresses
+//
+// These optional features are omitted because the primary use case is simple
+// port forwarding for WireGuard, which only requires MAP with default behavior.
+package pcp
+
+import (
+	"encoding/binary"
+	"fmt"
+	"net/netip"
+)
+
+const (
+	// Version is the PCP protocol version (RFC 6887).
+	Version = 2
+
+	// Port is the standard PCP server port.
+	Port = 5351
+
+	// DefaultLifetime is the default requested mapping lifetime in seconds.
+	DefaultLifetime = 7200 // 2 hours
+
+	// Header sizes
+	headerSize     = 24
+	mapPayloadSize = 36
+	mapRequestSize = headerSize + mapPayloadSize // 60 bytes
+)
+
+// Opcodes
+const (
+	OpAnnounce = 0
+	OpMap      = 1
+	OpPeer     = 2
+	OpReply    = 0x80 // OR'd with opcode in responses
+)
+
+// Protocol numbers for MAP requests
+const (
+	ProtoUDP = 17
+	ProtoTCP = 6
+)
+
+// Result codes (RFC 6887 Section 7.4)
+const (
+	ResultSuccess              = 0
+	ResultUnsuppVersion        = 1
+	ResultNotAuthorized        = 2
+	ResultMalformedRequest     = 3
+	ResultUnsuppOpcode         = 4
+	ResultUnsuppOption         = 5
+	ResultMalformedOption      = 6
+	ResultNetworkFailure       = 7
+	ResultNoResources          = 8
+	ResultUnsuppProtocol       = 9
+	ResultUserExQuota          = 10
+	ResultCannotProvideExt     = 11
+	ResultAddressMismatch      = 12
+	ResultExcessiveRemotePeers = 13
+)
+
+// ResultCodeString returns a human-readable string for a result code.
+func ResultCodeString(code uint8) string {
+	switch code {
+	case ResultSuccess:
+		return "SUCCESS"
+	case ResultUnsuppVersion:
+		return "UNSUPP_VERSION"
+	case ResultNotAuthorized:
+		return "NOT_AUTHORIZED"
+	case ResultMalformedRequest:
+		return "MALFORMED_REQUEST"
+	case ResultUnsuppOpcode:
+		return "UNSUPP_OPCODE"
+	case ResultUnsuppOption:
+		return "UNSUPP_OPTION"
+	case ResultMalformedOption:
+		return "MALFORMED_OPTION"
+	case ResultNetworkFailure:
+		return "NETWORK_FAILURE"
+	case ResultNoResources:
+		return "NO_RESOURCES"
+	case ResultUnsuppProtocol:
+		return "UNSUPP_PROTOCOL"
+	case ResultUserExQuota:
+		return "USER_EX_QUOTA"
+	case ResultCannotProvideExt:
+		return "CANNOT_PROVIDE_EXTERNAL"
+	case ResultAddressMismatch:
+		return "ADDRESS_MISMATCH"
+	case ResultExcessiveRemotePeers:
+		return "EXCESSIVE_REMOTE_PEERS"
+	default:
+		return fmt.Sprintf("UNKNOWN(%d)", code)
+	}
+}
+
+// Response represents a parsed PCP response header.
+type Response struct {
+	Version    uint8
+	Opcode     uint8
+	ResultCode uint8
+	Lifetime   uint32
+	Epoch      uint32
+}
+
+// MapResponse contains the full response to a MAP request.
+type MapResponse struct {
+	Response
+	Nonce        [12]byte
+	Protocol     uint8
+	InternalPort uint16
+	ExternalPort uint16
+	ExternalIP   netip.Addr
+}
+
+// addrTo16 converts an address to its 16-byte IPv4-mapped IPv6 representation.
+func addrTo16(addr netip.Addr) [16]byte {
+	if addr.Is4() {
+		return netip.AddrFrom4(addr.As4()).As16()
+	}
+	return addr.As16()
+}
+
+// addrFrom16 extracts an address from a 16-byte representation, unmapping IPv4.
+func addrFrom16(b [16]byte) netip.Addr {
+	return netip.AddrFrom16(b).Unmap()
+}
+
+// buildAnnounceRequest creates a PCP ANNOUNCE request packet.
+func buildAnnounceRequest(clientIP netip.Addr) []byte {
+	req := make([]byte, headerSize)
+	req[0] = Version
+	req[1] = OpAnnounce
+	mapped := addrTo16(clientIP)
+	copy(req[8:24], mapped[:])
+	return req
+}
+
+// buildMapRequest creates a PCP MAP request packet.
+func buildMapRequest(clientIP netip.Addr, nonce [12]byte, protocol uint8, internalPort, suggestedExtPort uint16, suggestedExtIP netip.Addr, lifetime uint32) []byte {
+	req := make([]byte, mapRequestSize)
+
+	// Header
+	req[0] = Version
+	req[1] = OpMap
+	binary.BigEndian.PutUint32(req[4:8], lifetime)
+	mapped := addrTo16(clientIP)
+	copy(req[8:24], mapped[:])
+
+	// MAP payload
+	copy(req[24:36], nonce[:])
+	req[36] = protocol
+	binary.BigEndian.PutUint16(req[40:42], internalPort)
+	binary.BigEndian.PutUint16(req[42:44], suggestedExtPort)
+	if suggestedExtIP.IsValid() {
+		extMapped := addrTo16(suggestedExtIP)
+		copy(req[44:60], extMapped[:])
+	}
+
+	return req
+}
+
+// parseResponse parses the common PCP response header.
+func parseResponse(data []byte) (*Response, error) {
+	if len(data) < headerSize {
+		return nil, fmt.Errorf("response too short: %d bytes", len(data))
+	}
+
+	resp := &Response{
+		Version:    data[0],
+		Opcode:     data[1],
+		ResultCode: data[3], // Byte 2 is reserved, byte 3 is result code (RFC 6887 §7.2)
+		Lifetime:   binary.BigEndian.Uint32(data[4:8]),
+		Epoch:      binary.BigEndian.Uint32(data[8:12]),
+	}
+
+	if resp.Version != Version {
+		return nil, fmt.Errorf("unsupported PCP version: %d", resp.Version)
+	}
+
+	if resp.Opcode&OpReply == 0 {
+		return nil, fmt.Errorf("response missing reply bit: opcode=0x%02x", resp.Opcode)
+	}
+
+	return resp, nil
+}
+
+// parseMapResponse parses a complete MAP response.
+func parseMapResponse(data []byte) (*MapResponse, error) {
+	if len(data) < mapRequestSize {
+		return nil, fmt.Errorf("MAP response too short: %d bytes", len(data))
+	}
+
+	resp, err := parseResponse(data)
+	if err != nil {
+		return nil, fmt.Errorf("parse header: %w", err)
+	}
+
+	mapResp := &MapResponse{
+		Response:     *resp,
+		Protocol:     data[36],
+		InternalPort: binary.BigEndian.Uint16(data[40:42]),
+		ExternalPort: binary.BigEndian.Uint16(data[42:44]),
+		ExternalIP:   addrFrom16([16]byte(data[44:60])),
+	}
+	copy(mapResp.Nonce[:], data[24:36])
+
+	return mapResp, nil
+}

client/internal/portforward/state.go

@@ -0,0 +1,63 @@
+//go:build !js
+
+package portforward
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/libp2p/go-nat"
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/client/internal/portforward/pcp"
+)
+
+// discoverGateway is the function used for NAT gateway discovery.
+// It can be replaced in tests to avoid real network operations.
+// Tries PCP first, then falls back to NAT-PMP/UPnP.
+var discoverGateway = defaultDiscoverGateway
+
+func defaultDiscoverGateway(ctx context.Context) (nat.NAT, error) {
+	pcpGateway, err := pcp.DiscoverPCP(ctx)
+	if err == nil {
+		return pcpGateway, nil
+	}
+	log.Debugf("PCP discovery failed: %v, trying NAT-PMP/UPnP", err)
+
+	return nat.DiscoverGateway(ctx)
+}
+
+// State is persisted only for crash recovery cleanup
+type State struct {
+	InternalPort uint16 `json:"internal_port,omitempty"`
+	Protocol     string `json:"protocol,omitempty"`
+}
+
+func (s *State) Name() string {
+	return "port_forward_state"
+}
+
+// Cleanup implements statemanager.CleanableState for crash recovery
+func (s *State) Cleanup() error {
+	if s.InternalPort == 0 {
+		return nil
+	}
+
+	log.Infof("cleaning up stale port mapping for port %d", s.InternalPort)
+
+	ctx, cancel := context.WithTimeout(context.Background(), discoveryTimeout)
+	defer cancel()
+
+	gateway, err := discoverGateway(ctx)
+	if err != nil {
+		// Discovery failure is not an error - gateway may not exist
+		log.Debugf("cleanup: no gateway found: %v", err)
+		return nil
+	}
+
+	if err := gateway.DeletePortMapping(ctx, s.Protocol, int(s.InternalPort)); err != nil {
+		return fmt.Errorf("delete port mapping: %w", err)
+	}
+
+	return nil
+}

client/internal/routemanager/systemops/systemops_unix.go

@@ -105,20 +105,7 @@ func (r *SysOps) FlushMarkedRoutes() error {
 }
 
 func (r *SysOps) addToRouteTable(prefix netip.Prefix, nexthop Nexthop) error {
-	if err := r.routeSocket(unix.RTM_ADD, prefix, nexthop); err != nil {
-		if !errors.Is(err, unix.EEXIST) {
-			return err
-		}
-
-		// Route already exists from a previous session that wasn't cleaned up properly
-		// (e.g. macOS sleep/wake). Remove the stale route and retry.
-		log.Infof("Route for %s already exists, replacing with new route", prefix)
-		if err := r.routeSocket(unix.RTM_DELETE, prefix, nexthop); err != nil {
-			log.Warnf("Failed to remove stale route for %s: %v", prefix, err)
-		}
-		return r.routeSocket(unix.RTM_ADD, prefix, nexthop)
-	}
-	return nil
+	return r.routeSocket(unix.RTM_ADD, prefix, nexthop)
 }
 
 func (r *SysOps) removeFromRouteTable(prefix netip.Prefix, nexthop Nexthop) error {
@@ -241,7 +228,7 @@ func (r *SysOps) parseRouteResponse(buf []byte) error {
 
 	rtMsg := (*unix.RtMsghdr)(unsafe.Pointer(&buf[0]))
 	if rtMsg.Errno != 0 {
-		return fmt.Errorf("route socket: %w", syscall.Errno(rtMsg.Errno))
+		return fmt.Errorf("parse: %d", rtMsg.Errno)
 	}
 
 	return nil

client/server/state_generic.go

@@ -10,6 +10,10 @@ import (
 )
 
 // registerStates registers all states that need crash recovery cleanup.
+// Note: portforward.State is intentionally NOT registered here to avoid blocking startup
+// for up to 10 seconds during NAT gateway discovery when no gateway is present.
+// The gateway reference cannot be persisted across restarts, so cleanup requires re-discovery.
+// Port forward cleanup is handled by the Manager during normal operation instead.
 func registerStates(mgr *statemanager.Manager) {
 	mgr.RegisterState(&dns.ShutdownState{})
 	mgr.RegisterState(&systemops.ShutdownState{})

client/server/state_linux.go

@@ -12,6 +12,10 @@ import (
 )
 
 // registerStates registers all states that need crash recovery cleanup.
+// Note: portforward.State is intentionally NOT registered here to avoid blocking startup
+// for up to 10 seconds during NAT gateway discovery when no gateway is present.
+// The gateway reference cannot be persisted across restarts, so cleanup requires re-discovery.
+// Port forward cleanup is handled by the Manager during normal operation instead.
 func registerStates(mgr *statemanager.Manager) {
 	mgr.RegisterState(&dns.ShutdownState{})
 	mgr.RegisterState(&systemops.ShutdownState{})

client/system/info_freebsd.go

@@ -43,24 +43,18 @@ func GetInfo(ctx context.Context) *Info {
 
 	systemHostname, _ := os.Hostname()
 
-	addrs, err := networkAddresses()
-	if err != nil {
-		log.Warnf("failed to discover network addresses: %s", err)
-	}
-
 	return &Info{
-		GoOS:             runtime.GOOS,
-		Kernel:           osInfo[0],
-		Platform:         runtime.GOARCH,
-		OS:               osName,
-		OSVersion:        osVersion,
-		Hostname:         extractDeviceName(ctx, systemHostname),
-		CPUs:             runtime.NumCPU(),
-		NetbirdVersion:   version.NetbirdVersion(),
-		UIVersion:        extractUserAgent(ctx),
-		KernelVersion:    osInfo[1],
-		NetworkAddresses: addrs,
-		Environment:      env,
+		GoOS:           runtime.GOOS,
+		Kernel:         osInfo[0],
+		Platform:       runtime.GOARCH,
+		OS:             osName,
+		OSVersion:      osVersion,
+		Hostname:       extractDeviceName(ctx, systemHostname),
+		CPUs:           runtime.NumCPU(),
+		NetbirdVersion: version.NetbirdVersion(),
+		UIVersion:      extractUserAgent(ctx),
+		KernelVersion:  osInfo[1],
+		Environment:    env,
 	}
 }
 

client/ui/debug.go

@@ -24,10 +24,9 @@ import (
 
 // Initial state for the debug collection
 type debugInitialState struct {
-	wasDown        bool
-	needsRestoreUp bool
-	logLevel       proto.LogLevel
-	isLevelTrace   bool
+	wasDown      bool
+	logLevel     proto.LogLevel
+	isLevelTrace bool
 }
 
 // Debug collection parameters
@@ -372,51 +371,46 @@ func (s *serviceClient) configureServiceForDebug(
 	conn proto.DaemonServiceClient,
 	state *debugInitialState,
 	enablePersistence bool,
-) {
+) error {
 	if state.wasDown {
 		if _, err := conn.Up(s.ctx, &proto.UpRequest{}); err != nil {
-			log.Warnf("failed to bring service up: %v", err)
-		} else {
-			log.Info("Service brought up for debug")
-			time.Sleep(time.Second * 10)
+			return fmt.Errorf("bring service up: %v", err)
 		}
+		log.Info("Service brought up for debug")
+		time.Sleep(time.Second * 10)
 	}
 
 	if !state.isLevelTrace {
 		if _, err := conn.SetLogLevel(s.ctx, &proto.SetLogLevelRequest{Level: proto.LogLevel_TRACE}); err != nil {
-			log.Warnf("failed to set log level to TRACE: %v", err)
-		} else {
-			log.Info("Log level set to TRACE for debug")
+			return fmt.Errorf("set log level to TRACE: %v", err)
 		}
+		log.Info("Log level set to TRACE for debug")
 	}
 
 	if _, err := conn.Down(s.ctx, &proto.DownRequest{}); err != nil {
-		log.Warnf("failed to bring service down: %v", err)
-	} else {
-		state.needsRestoreUp = !state.wasDown
-		time.Sleep(time.Second)
+		return fmt.Errorf("bring service down: %v", err)
 	}
+	time.Sleep(time.Second)
 
 	if enablePersistence {
 		if _, err := conn.SetSyncResponsePersistence(s.ctx, &proto.SetSyncResponsePersistenceRequest{
 			Enabled: true,
 		}); err != nil {
-			log.Warnf("failed to enable sync response persistence: %v", err)
-		} else {
-			log.Info("Sync response persistence enabled for debug")
+			return fmt.Errorf("enable sync response persistence: %v", err)
 		}
+		log.Info("Sync response persistence enabled for debug")
 	}
 
 	if _, err := conn.Up(s.ctx, &proto.UpRequest{}); err != nil {
-		log.Warnf("failed to bring service back up: %v", err)
-	} else {
-		state.needsRestoreUp = false
-		time.Sleep(time.Second * 3)
+		return fmt.Errorf("bring service back up: %v", err)
 	}
+	time.Sleep(time.Second * 3)
 
 	if _, err := conn.StartCPUProfile(s.ctx, &proto.StartCPUProfileRequest{}); err != nil {
 		log.Warnf("failed to start CPU profiling: %v", err)
 	}
+
+	return nil
 }
 
 func (s *serviceClient) collectDebugData(
@@ -430,7 +424,9 @@ func (s *serviceClient) collectDebugData(
 	var wg sync.WaitGroup
 	startProgressTracker(ctx, &wg, params.duration, progress)
 
-	s.configureServiceForDebug(conn, state, params.enablePersistence)
+	if err := s.configureServiceForDebug(conn, state, params.enablePersistence); err != nil {
+		return err
+	}
 
 	wg.Wait()
 	progress.progressBar.Hide()
@@ -486,17 +482,9 @@ func (s *serviceClient) createDebugBundleFromCollection(
 
 // Restore service to original state
 func (s *serviceClient) restoreServiceState(conn proto.DaemonServiceClient, state *debugInitialState) {
-	if state.needsRestoreUp {
-		if _, err := conn.Up(s.ctx, &proto.UpRequest{}); err != nil {
-			log.Warnf("failed to restore up state: %v", err)
-		} else {
-			log.Info("Service state restored to up")
-		}
-	}
-
 	if state.wasDown {
 		if _, err := conn.Down(s.ctx, &proto.DownRequest{}); err != nil {
-			log.Warnf("failed to restore down state: %v", err)
+			log.Errorf("Failed to restore down state: %v", err)
 		} else {
 			log.Info("Service state restored to down")
 		}
@@ -504,7 +492,7 @@ func (s *serviceClient) restoreServiceState(conn proto.DaemonServiceClient, stat
 
 	if !state.isLevelTrace {
 		if _, err := conn.SetLogLevel(s.ctx, &proto.SetLogLevelRequest{Level: state.logLevel}); err != nil {
-			log.Warnf("failed to restore log level: %v", err)
+			log.Errorf("Failed to restore log level: %v", err)
 		} else {
 			log.Info("Log level restored to original setting")
 		}

management/server/store/sql_store.go

@@ -2099,7 +2099,6 @@ func (s *SqlStore) getServices(ctx context.Context, accountID string) ([]*rpserv
 		var createdAt, certIssuedAt sql.NullTime
 		var status, proxyCluster, sessionPrivateKey, sessionPublicKey sql.NullString
 		var mode, source, sourcePeer sql.NullString
-		var terminated sql.NullBool
 		err := row.Scan(
 			&s.ID,
 			&s.AccountID,
@@ -2120,7 +2119,7 @@ func (s *SqlStore) getServices(ctx context.Context, accountID string) ([]*rpserv
 			&s.PortAutoAssigned,
 			&source,
 			&sourcePeer,
-			&terminated,
+			&s.Terminated,
 		)
 		if err != nil {
 			return nil, err
@@ -2161,9 +2160,7 @@ func (s *SqlStore) getServices(ctx context.Context, accountID string) ([]*rpserv
 		if sourcePeer.Valid {
 			s.SourcePeer = sourcePeer.String
 		}
-		if terminated.Valid {
-			s.Terminated = terminated.Bool
-		}
+
 		s.Targets = []*rpservice.Target{}
 		return &s, nil
 	})

management/server/types/networkmap_benchmark_test.go

@@ -1,217 +0,0 @@
-package types_test
-
-import (
-	"context"
-	"fmt"
-	"os"
-	"testing"
-
-	nbdns "github.com/netbirdio/netbird/dns"
-	"github.com/netbirdio/netbird/management/server/types"
-)
-
-type benchmarkScale struct {
-	name   string
-	peers  int
-	groups int
-}
-
-var defaultScales = []benchmarkScale{
-	{"100peers_5groups", 100, 5},
-	{"500peers_20groups", 500, 20},
-	{"1000peers_50groups", 1000, 50},
-	{"5000peers_100groups", 5000, 100},
-	{"10000peers_200groups", 10000, 200},
-	{"20000peers_200groups", 20000, 200},
-	{"30000peers_300groups", 30000, 300},
-}
-
-func skipCIBenchmark(b *testing.B) {
-	if os.Getenv("CI") == "true" {
-		b.Skip("Skipping benchmark in CI")
-	}
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// Single Peer Network Map Generation
-// ──────────────────────────────────────────────────────────────────────────────
-
-// BenchmarkNetworkMapGeneration_Components benchmarks the components-based approach for a single peer.
-func BenchmarkNetworkMapGeneration_Components(b *testing.B) {
-	skipCIBenchmark(b)
-	for _, scale := range defaultScales {
-		b.Run(scale.name, func(b *testing.B) {
-			account, validatedPeers := scalableTestAccount(scale.peers, scale.groups)
-			ctx := context.Background()
-			resourcePolicies := account.GetResourcePoliciesMap()
-			routers := account.GetResourceRoutersMap()
-			groupIDToUserIDs := account.GetActiveGroupUsers()
-
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				_ = account.GetPeerNetworkMapFromComponents(ctx, "peer-0", nbdns.CustomZone{}, nil, validatedPeers, resourcePolicies, routers, nil, groupIDToUserIDs)
-			}
-		})
-	}
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// All Peers (UpdateAccountPeers hot path)
-// ──────────────────────────────────────────────────────────────────────────────
-
-// BenchmarkNetworkMapGeneration_AllPeers benchmarks generating network maps for ALL peers.
-func BenchmarkNetworkMapGeneration_AllPeers(b *testing.B) {
-	skipCIBenchmark(b)
-	scales := []benchmarkScale{
-		{"100peers_5groups", 100, 5},
-		{"500peers_20groups", 500, 20},
-		{"1000peers_50groups", 1000, 50},
-		{"5000peers_100groups", 5000, 100},
-	}
-
-	for _, scale := range scales {
-		account, validatedPeers := scalableTestAccount(scale.peers, scale.groups)
-		ctx := context.Background()
-
-		peerIDs := make([]string, 0, len(account.Peers))
-		for peerID := range account.Peers {
-			peerIDs = append(peerIDs, peerID)
-		}
-
-		b.Run("components/"+scale.name, func(b *testing.B) {
-			resourcePolicies := account.GetResourcePoliciesMap()
-			routers := account.GetResourceRoutersMap()
-			groupIDToUserIDs := account.GetActiveGroupUsers()
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				for _, peerID := range peerIDs {
-					_ = account.GetPeerNetworkMapFromComponents(ctx, peerID, nbdns.CustomZone{}, nil, validatedPeers, resourcePolicies, routers, nil, groupIDToUserIDs)
-				}
-			}
-		})
-	}
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// Sub-operations
-// ──────────────────────────────────────────────────────────────────────────────
-
-// BenchmarkNetworkMapGeneration_ComponentsCreation benchmarks components extraction.
-func BenchmarkNetworkMapGeneration_ComponentsCreation(b *testing.B) {
-	skipCIBenchmark(b)
-	for _, scale := range defaultScales {
-		b.Run(scale.name, func(b *testing.B) {
-			account, validatedPeers := scalableTestAccount(scale.peers, scale.groups)
-			ctx := context.Background()
-			resourcePolicies := account.GetResourcePoliciesMap()
-			routers := account.GetResourceRoutersMap()
-			groupIDToUserIDs := account.GetActiveGroupUsers()
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				_ = account.GetPeerNetworkMapComponents(ctx, "peer-0", nbdns.CustomZone{}, nil, validatedPeers, resourcePolicies, routers, groupIDToUserIDs)
-			}
-		})
-	}
-}
-
-// BenchmarkNetworkMapGeneration_ComponentsCalculation benchmarks calculation from pre-built components.
-func BenchmarkNetworkMapGeneration_ComponentsCalculation(b *testing.B) {
-	skipCIBenchmark(b)
-	for _, scale := range defaultScales {
-		b.Run(scale.name, func(b *testing.B) {
-			account, validatedPeers := scalableTestAccount(scale.peers, scale.groups)
-			ctx := context.Background()
-			resourcePolicies := account.GetResourcePoliciesMap()
-			routers := account.GetResourceRoutersMap()
-			groupIDToUserIDs := account.GetActiveGroupUsers()
-			components := account.GetPeerNetworkMapComponents(ctx, "peer-0", nbdns.CustomZone{}, nil, validatedPeers, resourcePolicies, routers, groupIDToUserIDs)
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				_ = types.CalculateNetworkMapFromComponents(ctx, components)
-			}
-		})
-	}
-}
-
-// BenchmarkNetworkMapGeneration_PrecomputeMaps benchmarks precomputed map costs.
-func BenchmarkNetworkMapGeneration_PrecomputeMaps(b *testing.B) {
-	skipCIBenchmark(b)
-	for _, scale := range defaultScales {
-		b.Run("ResourcePoliciesMap/"+scale.name, func(b *testing.B) {
-			account, _ := scalableTestAccount(scale.peers, scale.groups)
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				_ = account.GetResourcePoliciesMap()
-			}
-		})
-		b.Run("ResourceRoutersMap/"+scale.name, func(b *testing.B) {
-			account, _ := scalableTestAccount(scale.peers, scale.groups)
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				_ = account.GetResourceRoutersMap()
-			}
-		})
-		b.Run("ActiveGroupUsers/"+scale.name, func(b *testing.B) {
-			account, _ := scalableTestAccount(scale.peers, scale.groups)
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				_ = account.GetActiveGroupUsers()
-			}
-		})
-	}
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// Scaling Analysis
-// ──────────────────────────────────────────────────────────────────────────────
-
-// BenchmarkNetworkMapGeneration_GroupScaling tests group count impact on performance.
-func BenchmarkNetworkMapGeneration_GroupScaling(b *testing.B) {
-	skipCIBenchmark(b)
-	groupCounts := []int{1, 5, 20, 50, 100, 200, 500}
-	for _, numGroups := range groupCounts {
-		b.Run(fmt.Sprintf("components_%dgroups", numGroups), func(b *testing.B) {
-			account, validatedPeers := scalableTestAccount(1000, numGroups)
-			ctx := context.Background()
-			resourcePolicies := account.GetResourcePoliciesMap()
-			routers := account.GetResourceRoutersMap()
-			groupIDToUserIDs := account.GetActiveGroupUsers()
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				_ = account.GetPeerNetworkMapFromComponents(ctx, "peer-0", nbdns.CustomZone{}, nil, validatedPeers, resourcePolicies, routers, nil, groupIDToUserIDs)
-			}
-		})
-	}
-}
-
-// BenchmarkNetworkMapGeneration_PeerScaling tests peer count impact on performance.
-func BenchmarkNetworkMapGeneration_PeerScaling(b *testing.B) {
-	skipCIBenchmark(b)
-	peerCounts := []int{50, 100, 500, 1000, 2000, 5000, 10000, 20000, 30000}
-	for _, numPeers := range peerCounts {
-		numGroups := numPeers / 20
-		if numGroups < 1 {
-			numGroups = 1
-		}
-		b.Run(fmt.Sprintf("components_%dpeers", numPeers), func(b *testing.B) {
-			account, validatedPeers := scalableTestAccount(numPeers, numGroups)
-			ctx := context.Background()
-			resourcePolicies := account.GetResourcePoliciesMap()
-			routers := account.GetResourceRoutersMap()
-			groupIDToUserIDs := account.GetActiveGroupUsers()
-			b.ReportAllocs()
-			b.ResetTimer()
-			for range b.N {
-				_ = account.GetPeerNetworkMapFromComponents(ctx, "peer-0", nbdns.CustomZone{}, nil, validatedPeers, resourcePolicies, routers, nil, groupIDToUserIDs)
-			}
-		})
-	}
-}