Authorize daemon IPC callers by their local identity

2026-08-28 10:31:29 +02:00 · 2026-07-29 17:49:58 +02:00
parent 0b7e6a9f46
commit 8972f2a270
58 changed files with 3799 additions and 167 deletions
--- a/client/server/login_gate_test.go
+++ b/client/server/login_gate_test.go
@@ -0,0 +1,127 @@
+package server
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"google.golang.org/grpc/codes"
+	gstatus "google.golang.org/grpc/status"
+
+	"github.com/netbirdio/netbird/client/internal"
+	"github.com/netbirdio/netbird/client/internal/profilemanager"
+	"github.com/netbirdio/netbird/client/proto"
+)
+
+// A refused login must not leave the profile switched. Login can both switch
+// profiles and carry the guarded config fields, so the gate has to run before the
+// switch: otherwise a caller whose change is refused still gets the side effect of
+// activating whichever profile the request named.
+func TestLogin_RefusedChangeLeavesTheProfileAlone(t *testing.T) {
+	s, _, activeProfile, username, _ := setupServerWithProfile(t)
+
+	// Login reads process state off the daemon's root context.
+	s.rootCtx = internal.CtxInitState(context.Background())
+
+	// A second profile that runs the SSH server, which is what makes repointing
+	// its management binding a privileged change.
+	target := "ssh-enabled"
+	_, err := profilemanager.UpdateOrCreateConfig(profilemanager.ConfigInput{
+		ConfigPath:       filepath.Join(profilemanager.DefaultConfigPathDir, target+".json"),
+		ManagementURL:    "https://api.netbird.io:443",
+		ServerSSHAllowed: boolPtr(true),
+	})
+	require.NoError(t, err)
+
+	_, err = s.Login(userCtx(), &proto.LoginRequest{
+		ProfileName:   &target,
+		Username:      &username,
+		ManagementUrl: "https://mgmt.attacker.example:443",
+	})
+	require.Error(t, err, "an unprivileged caller must not move the management URL of an SSH-enabled profile")
+	require.Equal(t, codes.PermissionDenied, gstatus.Code(err), "want a privilege refusal, got %v", err)
+
+	active, err := s.profileManager.GetActiveProfileState()
+	require.NoError(t, err)
+	require.Equal(t, profilemanager.ID(activeProfile), active.ID,
+		"the refused login switched the active profile anyway")
+}
+
+// A caller whose change becomes privileged only after its first check must be
+// refused without having cancelled a login or switched profiles: the first check is
+// unsynchronized, so the SSH server can be enabled by a concurrent privileged
+// request in between, and the authoritative check happens before any side effect.
+func TestLogin_ChangeThatBecomesPrivilegedMidRequestHasNoSideEffects(t *testing.T) {
+	s, _, activeProfile, username, _ := setupServerWithProfile(t)
+	s.rootCtx = internal.CtxInitState(context.Background())
+
+	// The target profile has SSH off, so the first check lets the request through.
+	target := "ssh-later"
+	targetPath := filepath.Join(profilemanager.DefaultConfigPathDir, target+".json")
+	_, err := profilemanager.UpdateOrCreateConfig(profilemanager.ConfigInput{
+		ConfigPath:       targetPath,
+		ManagementURL:    "https://api.netbird.io:443",
+		ServerSSHAllowed: boolPtr(false),
+	})
+	require.NoError(t, err)
+
+	cancelled := false
+	s.actCancel = func() { cancelled = true }
+
+	// Stand in for a privileged SetConfig that enables the SSH server between the
+	// two checks, which is the interleaving the lock has to make safe.
+	afterLoginPreCheck = func() {
+		_, err := profilemanager.UpdateOrCreateConfig(profilemanager.ConfigInput{
+			ConfigPath:       targetPath,
+			ServerSSHAllowed: boolPtr(true),
+		})
+		require.NoError(t, err)
+	}
+	t.Cleanup(func() { afterLoginPreCheck = nil })
+
+	_, err = s.Login(userCtx(), &proto.LoginRequest{
+		ProfileName:   &target,
+		Username:      &username,
+		ManagementUrl: "https://mgmt.attacker.example:443",
+	})
+	require.Error(t, err)
+	require.Equal(t, codes.PermissionDenied, gstatus.Code(err), "want a privilege refusal, got %v", err)
+	require.False(t, cancelled, "the refused login cancelled the login already in progress")
+
+	active, err := s.profileManager.GetActiveProfileState()
+	require.NoError(t, err)
+	require.Equal(t, profilemanager.ID(activeProfile), active.ID, "the refused login switched the active profile anyway")
+
+	stored, err := profilemanager.ReadConfig(targetPath)
+	require.NoError(t, err)
+	require.Equal(t, "https://api.netbird.io:443", stored.ManagementURL.String(), "the refused login moved the management URL")
+}
+
+// Login cancels whatever login is already in progress before starting its own. A
+// refused caller must not get that far, otherwise anyone able to reach the socket
+// can abort someone else's login by sending a request that is denied.
+func TestLogin_RefusedChangeLeavesAnInProgressLoginAlone(t *testing.T) {
+	s, _, _, username, _ := setupServerWithProfile(t)
+	s.rootCtx = internal.CtxInitState(context.Background())
+
+	target := "ssh-enabled"
+	_, err := profilemanager.UpdateOrCreateConfig(profilemanager.ConfigInput{
+		ConfigPath:       filepath.Join(profilemanager.DefaultConfigPathDir, target+".json"),
+		ManagementURL:    "https://api.netbird.io:443",
+		ServerSSHAllowed: boolPtr(true),
+	})
+	require.NoError(t, err)
+
+	cancelled := false
+	s.actCancel = func() { cancelled = true }
+
+	_, err = s.Login(userCtx(), &proto.LoginRequest{
+		ProfileName:   &target,
+		Username:      &username,
+		ManagementUrl: "https://mgmt.attacker.example:443",
+	})
+	require.Error(t, err)
+	require.Equal(t, codes.PermissionDenied, gstatus.Code(err), "want a privilege refusal, got %v", err)
+	require.False(t, cancelled, "the refused login cancelled the login already in progress")
+}
--- a/client/server/server.go
+++ b/client/server/server.go
@@ -82,6 +82,12 @@ type Server struct {
 	// extend flow or vice versa.
 	extendAuthSessionFlow *auth.PendingFlow

+	// guardedConfigMu serializes a privilege check against the write it
+	// authorizes. Without it the two are separate steps over the same file, and a
+	// change that was allowed because the profile had the SSH server disabled
+	// could land after a concurrent privileged request enabled it.
+	guardedConfigMu sync.Mutex
+
 	mutex  sync.Mutex
 	config *profilemanager.Config
 	proto.UnimplementedDaemonServiceServer
@@ -411,6 +417,20 @@ func (s *Server) SetConfig(callerCtx context.Context, msg *proto.SetConfigReques
 		return nil, err
 	}

+	// Privilege gate: refuse the parts of the request that would let a local
+	// user turn the root daemon into a root shell. Held across the write so the
+	// config cannot gain the SSH server between the decision and the update.
+	s.guardedConfigMu.Lock()
+	defer s.guardedConfigMu.Unlock()
+
+	stored, err := s.storedProfileConfig(msg.ProfileName, msg.Username)
+	if err != nil {
+		return nil, err
+	}
+	if err := requirePrivilegeForConfigChange(callerCtx, stored, privilegedChangeFromSetConfig(msg)); err != nil {
+		return nil, err
+	}
+
 	config, err := s.setConfigInputFromRequest(msg)
 	if err != nil {
 		return nil, err
@@ -537,22 +557,23 @@ func (s *Server) Login(callerCtx context.Context, msg *proto.LoginRequest) (*pro
 		}
 	}

-	s.mutex.Lock()
-	if s.actCancel != nil {
-		s.actCancel()
-	}
-	ctx, cancel := context.WithCancel(callerCtx)
-
-	md, ok := metadata.FromIncomingContext(callerCtx)
-	if ok {
-		ctx = metadata.NewOutgoingContext(ctx, md)
+	activeProf, err := s.profileManager.GetActiveProfileState()
+	if err != nil {
+		log.Errorf("failed to get active profile state: %v", err)
+		return nil, fmt.Errorf("failed to get active profile state: %w", err)
 	}

-	s.actCancel = cancel
-	s.mutex.Unlock()
-
-	if err := RestoreResidualState(s.rootCtx, s.profileManager.GetStatePath()); err != nil {
-		log.Warnf(errRestoreResidualState, err)
+	// Privilege gate: same restrictions as SetConfig, since LoginRequest can carry
+	// the same fields. It runs before anything here changes daemon state, so a
+	// refused login neither switches the profile nor cancels a login already in
+	// progress, and it reads the profile the request targets, which is the one the
+	// switch below would activate.
+	stored, err := s.storedLoginConfig(activeProf, msg)
+	if err != nil {
+		return nil, err
+	}
+	if err := requirePrivilegeForConfigChange(callerCtx, stored, privilegedChangeFromLogin(msg)); err != nil {
+		return nil, err
 	}

 	state := internal.CtxGetState(s.rootCtx)
@@ -563,23 +584,16 @@ func (s *Server) Login(callerCtx context.Context, msg *proto.LoginRequest) (*pro
 		}
 	}()

-	activeProf, err := s.profileManager.GetActiveProfileState()
+	ctx, activeProf, err := s.authorizeAndPrepareLogin(callerCtx, msg, activeProf)
 	if err != nil {
-		log.Errorf("failed to get active profile state: %v", err)
-		return nil, fmt.Errorf("failed to get active profile state: %w", err)
-	}
-
-	if msg.ProfileName != nil {
-		if _, err := s.switchProfileIfNeeded(*msg.ProfileName, msg.Username, activeProf); err != nil {
-			log.Errorf("failed to switch profile: %v", err)
-			return nil, err
+		// The RPC boundary is where this gets recorded: nothing logs handler
+		// errors for us, and a caller that retries would otherwise leave no
+		// trace in the daemon log. A refusal is skipped because the gate has
+		// already logged the decision, with the caller's identity.
+		if gstatus.Code(err) != codes.PermissionDenied {
+			log.Errorf("failed to prepare login: %v", err)
 		}
-	}
-
-	activeProf, err = s.profileManager.GetActiveProfileState()
-	if err != nil {
-		log.Errorf("failed to get active profile state: %v", err)
-		return nil, fmt.Errorf("failed to get active profile state: %w", err)
+		return nil, err
 	}

 	log.Infof("active profile: %s for %s", activeProf.ID, activeProf.Username)
@@ -593,11 +607,6 @@ func (s *Server) Login(callerCtx context.Context, msg *proto.LoginRequest) (*pro

 	s.mutex.Unlock()

-	if err := persistLoginOverrides(activeProf, msg.ManagementUrl, msg.OptionalPreSharedKey); err != nil {
-		log.Errorf("failed to persist login overrides: %v", err)
-		return nil, fmt.Errorf("persist login overrides: %w", err)
-	}
-
 	config, _, err := s.getConfig(activeProf)
 	if err != nil {
 		log.Errorf("failed to get active profile config: %v", err)
@@ -980,6 +989,63 @@ func (s *Server) waitForUp(callerCtx context.Context) (*proto.UpResponse, error)
 	}
 }

+// storedProfileConfig loads the on-disk config of the profile a request
+// targets, so a privileged-change decision can be made against the values the
+// profile currently holds. A profile that has no config file yet yields nil,
+// which every caller must read as "nothing enabled yet".
+func (s *Server) storedProfileConfig(handle, username string) (*profilemanager.Config, error) {
+	resolved, err := s.resolveProfileHandle(handle, username)
+	if err != nil {
+		return nil, err
+	}
+
+	path := resolved.Path
+	if path == "" {
+		path = profilemanager.DefaultConfigPath
+	}
+
+	return s.storedConfigAtPath(path)
+}
+
+// storedLoginConfig loads the on-disk config of the profile a login request
+// targets: the one it names, or the active one when it names none. Used to decide
+// a privileged change before the request is allowed to switch profiles.
+func (s *Server) storedLoginConfig(activeProf *profilemanager.ActiveProfileState, msg *proto.LoginRequest) (*profilemanager.Config, error) {
+	if msg.ProfileName == nil {
+		cfgPath, err := activeProf.FilePath()
+		if err != nil {
+			return nil, fmt.Errorf("active profile file path: %w", err)
+		}
+		return s.storedConfigAtPath(cfgPath)
+	}
+
+	// Mirrors switchProfileIfNeeded: the default profile resolves without a
+	// username, so this reads the same profile the switch would activate.
+	handle := *msg.ProfileName
+	username := ""
+	if handle != profilemanager.DefaultProfileName {
+		username = msg.GetUsername()
+	}
+	return s.storedProfileConfig(handle, username)
+}
+
+// storedConfigAtPath reads a profile config file, yielding nil when it does not
+// exist yet.
+func (s *Server) storedConfigAtPath(path string) (*profilemanager.Config, error) {
+	if _, err := os.Stat(path); err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil //nolint:nilnil
+		}
+		return nil, fmt.Errorf("stat profile config: %w", err)
+	}
+
+	cfg, err := profilemanager.GetConfig(path)
+	if err != nil {
+		return nil, fmt.Errorf("read profile config: %w", err)
+	}
+	return cfg, nil
+}
+
 // resolveProfileHandle resolves a wire-level profile handle (display
 // name, ID, or unique ID prefix) to a concrete profile. Returns gRPC
 // status errors so handlers can return them directly.
@@ -1197,6 +1263,12 @@ func (s *Server) handleProfileLogout(ctx context.Context, msg *proto.LogoutReque

 	if err := s.logoutFromProfile(ctx, resolved); err != nil {
 		log.Errorf("failed to logout from profile %s: %v", resolved.ID, err)
+		// A refused deregistration is already a status error carrying the reason
+		// and the command to run; rewrapping it as Internal would flatten both
+		// into a gRPC dump for the user.
+		if _, isStatus := gstatus.FromError(err); isStatus {
+			return nil, err
+		}
 		return nil, gstatus.Errorf(codes.Internal, "logout: %v", err)
 	}

@@ -1318,6 +1390,13 @@ func (s *Server) sendLogoutRequest(ctx context.Context) error {
 }

 func (s *Server) sendLogoutRequestWithConfig(ctx context.Context, config *profilemanager.Config) error {
+	// Privilege gate: deregistering frees this machine's key to be registered
+	// against another management server, which is only restricted while the SSH
+	// server makes that a privilege handover.
+	if err := requirePrivilegeForDeregistration(ctx, config); err != nil {
+		return err
+	}
+
 	key, err := wgtypes.ParseKey(config.PrivateKey)
 	if err != nil {
 		return fmt.Errorf("parse private key: %w", err)
@@ -2063,7 +2142,10 @@ func (s *Server) RemoveProfile(ctx context.Context, msg *proto.RemoveProfileRequ
 	}

 	if err := s.logoutFromProfile(ctx, resolved); err != nil {
-		log.Warnf("failed to logout from profile %s before removal: %v", resolved.ID, err)
+		// Deregistration is best-effort here: the local profile is removed
+		// either way, so an unprivileged caller leaves the peer registered on
+		// the management server rather than being blocked from removing it.
+		log.Warnf("removing profile %s locally without deregistering it: %v", resolved.ID, err)
 	}

 	if err := s.profileManager.RemoveProfile(resolved.ID, msg.Username); err != nil {
@@ -2360,6 +2442,69 @@ func sendTerminalNotification() error {

 // persistLoginOverrides writes management URL and pre-shared key from a LoginRequest to the
 // active profile config so that subsequent reads pick them up. Empty/nil values are ignored.
+// afterLoginPreCheck is a seam for tests to run a concurrent config change
+// between Login's first privilege check and the authoritative one.
+var afterLoginPreCheck func()
+
+// authorizeAndPrepareLogin makes the authoritative privilege decision for a login
+// and, when it passes, carries out every state change that decision authorizes:
+// cancelling an login already in progress, switching to the requested profile, and
+// persisting the config overrides the request carries.
+//
+// All of it happens under guardedConfigMu, which SetConfig also holds across its
+// own check and write. Login's earlier check refuses the ordinary case before any
+// of this is reached; this one exists because that check is not synchronized
+// against a concurrent privileged request that enables the SSH server, and a
+// caller refused here must not have cancelled or switched anything either.
+func (s *Server) authorizeAndPrepareLogin(callerCtx context.Context, msg *proto.LoginRequest, activeProf *profilemanager.ActiveProfileState) (context.Context, *profilemanager.ActiveProfileState, error) {
+	if afterLoginPreCheck != nil {
+		afterLoginPreCheck()
+	}
+
+	s.guardedConfigMu.Lock()
+	defer s.guardedConfigMu.Unlock()
+
+	stored, err := s.storedLoginConfig(activeProf, msg)
+	if err != nil {
+		return nil, nil, err
+	}
+	if err := requirePrivilegeForConfigChange(callerCtx, stored, privilegedChangeFromLogin(msg)); err != nil {
+		return nil, nil, err
+	}
+
+	s.mutex.Lock()
+	if s.actCancel != nil {
+		s.actCancel()
+	}
+	ctx, cancel := context.WithCancel(callerCtx)
+	if md, ok := metadata.FromIncomingContext(callerCtx); ok {
+		ctx = metadata.NewOutgoingContext(ctx, md)
+	}
+	s.actCancel = cancel
+	s.mutex.Unlock()
+
+	if err := RestoreResidualState(s.rootCtx, s.profileManager.GetStatePath()); err != nil {
+		log.Warnf(errRestoreResidualState, err)
+	}
+
+	if msg.ProfileName != nil {
+		if _, err := s.switchProfileIfNeeded(*msg.ProfileName, msg.Username, activeProf); err != nil {
+			return nil, nil, fmt.Errorf("switch profile: %w", err)
+		}
+	}
+
+	activeProf, err = s.profileManager.GetActiveProfileState()
+	if err != nil {
+		return nil, nil, fmt.Errorf("active profile state: %w", err)
+	}
+
+	if err := persistLoginOverrides(activeProf, msg.ManagementUrl, msg.OptionalPreSharedKey); err != nil {
+		return nil, nil, fmt.Errorf("persist login overrides: %w", err)
+	}
+
+	return ctx, activeProf, nil
+}
+
 func persistLoginOverrides(activeProf *profilemanager.ActiveProfileState, managementURL string, preSharedKey *string) error {
 	if preSharedKey != nil && *preSharedKey == "" {
 		preSharedKey = nil
--- a/client/server/setconfig_mdm_test.go
+++ b/client/server/setconfig_mdm_test.go
@@ -66,7 +66,11 @@ func setupServerWithProfile(t *testing.T) (s *Server, ctx context.Context, profN
 		Username: currUser.Username,
 	}))

-	ctx = context.Background()
+	// The privileged-change gate reads the caller's kernel identity from the
+	// context, which a real caller gets from the daemon's transport credentials.
+	// This test drives the handler directly, so it stands in for a root caller;
+	// without an identity the gate would (correctly) refuse the SSH fields.
+	ctx = privilegedTestCtx()
 	s = New(ctx, "console", "", false, false, false, false)
 	return s, ctx, profName, currUser.Username, cfgPath
 }
--- a/client/server/setconfig_test.go
+++ b/client/server/setconfig_test.go
@@ -1,7 +1,6 @@
 package server

 import (
-	"context"
 	"os/user"
 	"path/filepath"
 	"reflect"
@@ -52,7 +51,11 @@ func TestSetConfig_AllFieldsSaved(t *testing.T) {
 	})
 	require.NoError(t, err)

-	ctx := context.Background()
+	// The privileged-change gate reads the caller's kernel identity from the
+	// context, which a real caller gets from the daemon's transport credentials.
+	// This test drives the handler directly, so it stands in for a root caller;
+	// without an identity the gate would (correctly) refuse the SSH fields.
+	ctx := privilegedTestCtx()
 	s := New(ctx, "console", "", false, false, false, false)

 	rosenpassEnabled := true
--- a/client/server/ssh_gate.go
+++ b/client/server/ssh_gate.go
@@ -0,0 +1,282 @@
+package server
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"runtime"
+	"strings"
+
+	log "github.com/sirupsen/logrus"
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	gstatus "google.golang.org/grpc/status"
+
+	"github.com/netbirdio/netbird/client/internal/daemonaddr"
+	"github.com/netbirdio/netbird/client/internal/ipcauth"
+	"github.com/netbirdio/netbird/client/internal/profilemanager"
+	"github.com/netbirdio/netbird/client/proto"
+	"github.com/netbirdio/netbird/util"
+)
+
+// The daemon runs as root/LocalSystem, so a handful of config changes cross the
+// user-to-root boundary and are restricted to privileged callers:
+//
+//   - Enabling SSH root login, or disabling SSH authentication, turns the
+//     daemon's SSH server into a root (or unauthenticated) shell.
+//   - Enabling the SSH server at all is what makes the above reachable, and a
+//     profile the caller owns is not a privilege they hold.
+//   - While the SSH server is enabled, repointing the profile at another
+//     management identity hands SSH authorization decisions, including which
+//     keys and users are accepted, to whoever controls that identity. Changing
+//     the management URL and deregistering the peer are both ways to do that.
+//
+// Everything else stays unauthenticated, so this is not an authorization model:
+// it only refuses the changes that would let a local user become root. A caller
+// whose identity cannot be established is refused as well.
+
+// privilegedConfigChange is the subset of a config request that crosses the
+// user-to-root boundary. Fields are nil or empty when the request leaves them
+// untouched.
+type privilegedConfigChange struct {
+	managementURL    string
+	serverSSHAllowed *bool
+	enableSSHRoot    *bool
+	disableSSHAuth   *bool
+}
+
+func privilegedChangeFromSetConfig(msg *proto.SetConfigRequest) privilegedConfigChange {
+	return privilegedConfigChange{
+		managementURL:    msg.GetManagementUrl(),
+		serverSSHAllowed: msg.ServerSSHAllowed,
+		enableSSHRoot:    msg.EnableSSHRoot,
+		disableSSHAuth:   msg.DisableSSHAuth,
+	}
+}
+
+func privilegedChangeFromLogin(msg *proto.LoginRequest) privilegedConfigChange {
+	return privilegedConfigChange{
+		managementURL:    msg.GetManagementUrl(),
+		serverSSHAllowed: msg.ServerSSHAllowed,
+		enableSSHRoot:    msg.EnableSSHRoot,
+		disableSSHAuth:   msg.DisableSSHAuth,
+	}
+}
+
+// requirePrivilegeForConfigChange refuses the privileged parts of a config
+// change when the caller is not root/administrator. stored is the profile's
+// current config, or nil when it has none yet.
+//
+// Each check compares against the stored value so that a request restating a
+// value it does not change is never refused: a UI that submits the whole
+// settings form must not start failing once an administrator has enabled SSH.
+func requirePrivilegeForConfigChange(ctx context.Context, stored *profilemanager.Config, change privilegedConfigChange) error {
+	if enables(storedFlag(stored, func(c *profilemanager.Config) *bool { return c.EnableSSHRoot }), change.enableSSHRoot) {
+		return denyPrivileged(ctx, "enabling SSH root login", ipcauth.UpCommand("--enable-ssh-root"))
+	}
+
+	if enables(storedFlag(stored, func(c *profilemanager.Config) *bool { return c.DisableSSHAuth }), change.disableSSHAuth) {
+		return denyPrivileged(ctx, "disabling SSH authentication", ipcauth.UpCommand("--disable-ssh-auth"))
+	}
+
+	if enables(sshServerCurrentlyAllowed(stored), change.serverSSHAllowed) {
+		return denyPrivileged(ctx, "enabling the NetBird SSH server", ipcauth.UpCommand("--allow-server-ssh"))
+	}
+
+	// Only guard the management binding while the SSH server is enabled: that is
+	// when the management identity decides who may open a shell here.
+	if !sshServerEnabled(stored) {
+		return nil
+	}
+
+	if change.managementURL != "" && !sameManagementURL(stored.ManagementURL, change.managementURL) {
+		return denyPrivileged(ctx,
+			"changing the management URL while the NetBird SSH server is enabled",
+			ipcauth.UpCommand("-m "+change.managementURL))
+	}
+
+	return nil
+}
+
+// requirePrivilegeForDeregistration refuses to deregister the peer from the
+// management server when the caller is not privileged and the profile has the
+// SSH server enabled. Deregistering frees the peer's key to be registered
+// against another management identity, which is the same handover the
+// management URL check refuses.
+//
+// Callers that treat deregistration as best-effort (profile removal) continue
+// without it; callers that were asked to deregister surface the error.
+func requirePrivilegeForDeregistration(ctx context.Context, cfg *profilemanager.Config) error {
+	if !sshServerEnabled(cfg) {
+		return nil
+	}
+
+	return denyPrivileged(ctx,
+		"deregistering this peer while the NetBird SSH server is enabled",
+		ipcauth.ElevatedCommand("netbird logout"))
+}
+
+// denyPrivileged returns nil when the caller is privileged, and otherwise a
+// PermissionDenied whose message names the action and the command that performs
+// it with the privileges it needs. The same summary and command ride along as an
+// ErrorInfo detail so the CLI and the UI can present them without parsing text.
+//
+// action reads as the subject of a sentence ("enabling SSH root login"), and
+// command is the equivalent command, already elevated for the platform.
+func denyPrivileged(ctx context.Context, action, command string) error {
+	id, ok := ipcauth.CallerIdentity(ctx)
+	if !ok {
+		log.Warnf("denying %s: the caller's identity cannot be verified on this control channel", action)
+		return privilegeError(unidentifiedSummary(action), reinstallCommand())
+	}
+
+	if ipcauth.IsPrivilegedCaller(id) {
+		log.Infof("allowing %s for privileged caller %s", action, id)
+		return nil
+	}
+
+	log.Warnf("denying %s for unprivileged caller %s", action, id)
+	actor, command := requiredActor(command)
+	return privilegeError(privilegeSummary(action, actor), command)
+}
+
+// requiredActor names who may perform the operation and adjusts the command to
+// match. A daemon that is not itself privileged delegates to its own identity, so
+// telling that host's user to become root is wrong twice over: root is not what the
+// daemon checks for, and a rootless container has neither root nor sudo.
+func requiredActor(command string) (string, string) {
+	self, delegates := ipcauth.SelfDelegatesTo()
+	if !delegates {
+		return ipcauth.PrivilegedActor(), command
+	}
+	return fmt.Sprintf("the user the daemon runs as (%s)", self), strings.ReplaceAll(command, "sudo ", "")
+}
+
+// privilegeError builds the PermissionDenied carrying summary and command.
+func privilegeError(summary, command string) error {
+	st := gstatus.New(codes.PermissionDenied, fmt.Sprintf("%s\n\n%s", summary, command))
+
+	detailed, err := st.WithDetails(&errdetails.ErrorInfo{
+		Reason: ipcauth.ErrorReasonPrivilegeRequired,
+		Domain: ipcauth.ErrorDomain,
+		Metadata: map[string]string{
+			ipcauth.ErrorMetaSummary: summary,
+			ipcauth.ErrorMetaCommand: command,
+		},
+	})
+	if err != nil {
+		log.Debugf("attach privilege error detail: %v", err)
+		return st.Err()
+	}
+	return detailed.Err()
+}
+
+// privilegeSummary states what is refused and what it needs, in one sentence
+// that reads the same in a dialog and in a terminal.
+func privilegeSummary(action, actor string) string {
+	return fmt.Sprintf("%s requires %s.", capitalize(action), actor)
+}
+
+// unidentifiedSummary covers a control channel that carries no caller identity.
+// Elevating does not help there, so it points at the daemon's socket instead.
+func unidentifiedSummary(action string) string {
+	return fmt.Sprintf("%s requires %s, and the daemon cannot verify who is calling over its current socket. "+
+		"Reinstall the service on a socket that carries the caller's identity.", capitalize(action), ipcauth.PrivilegedActor())
+}
+
+// reinstallCommand is the command that moves the daemon onto a socket whose
+// callers can be identified.
+func reinstallCommand() string {
+	if runtime.GOOS == "windows" {
+		return fmt.Sprintf("netbird service install --daemon-addr %s", daemonaddr.WindowsPipeAddr)
+	}
+	return "sudo netbird service install --daemon-addr unix:///var/run/netbird.sock"
+}
+
+func capitalize(s string) string {
+	if s == "" {
+		return s
+	}
+	return strings.ToUpper(s[:1]) + s[1:]
+}
+
+// enables reports whether requested turns a flag on that is currently off. A
+// request that restates the stored value, or turns the flag off, is not a
+// privileged change.
+func enables(stored, requested *bool) bool {
+	if requested == nil || !*requested {
+		return false
+	}
+	return stored == nil || !*stored
+}
+
+// storedFlag reads a flag from the stored config, tolerating a config that does
+// not exist yet.
+func storedFlag(cfg *profilemanager.Config, get func(*profilemanager.Config) *bool) *bool {
+	if cfg == nil {
+		return nil
+	}
+	return get(cfg)
+}
+
+// sshServerEnabled reports whether the profile currently runs the SSH server.
+//
+// A nil flag means ON, matching what the engine does with the same config
+// (util.ReturnBoolWithDefaultTrue in internal/connect.go, kept for configs written
+// before the flag existed). Reading it as OFF here would open the management-URL
+// and deregistration guards on exactly those legacy hosts, whose SSH server is
+// running. Configs loaded through profilemanager have already been materialised by
+// apply(), so this is the same answer by a route that does not depend on that.
+func sshServerEnabled(cfg *profilemanager.Config) bool {
+	if cfg == nil {
+		return false
+	}
+	return util.ReturnBoolWithDefaultTrue(cfg.ServerSSHAllowed)
+}
+
+// sshServerCurrentlyAllowed is the value an enable request is compared against. It
+// shares sshServerEnabled's nil-means-on default, so restating "on" for a legacy
+// config is correctly seen as no change.
+func sshServerCurrentlyAllowed(cfg *profilemanager.Config) *bool {
+	enabled := sshServerEnabled(cfg)
+	if cfg == nil {
+		return nil
+	}
+	return &enabled
+}
+
+// sameManagementURL reports whether requested addresses the same management
+// server as stored, comparing scheme, host and effective port so that an
+// equivalent spelling ("https://api.netbird.io" for a stored
+// "https://api.netbird.io:443") is not treated as a change. It fails closed:
+// anything unparseable counts as a change and therefore needs privilege.
+func sameManagementURL(stored *url.URL, requested string) bool {
+	if stored == nil {
+		return false
+	}
+
+	// Normalise the requested URL through the config layer's own parser, so the
+	// comparison cannot drift from how the value would actually be stored.
+	parsed, err := profilemanager.ParseServiceURL("Management URL", requested)
+	if err != nil {
+		return false
+	}
+
+	return stored.Scheme == parsed.Scheme &&
+		stored.Hostname() == parsed.Hostname() &&
+		effectivePort(stored) == effectivePort(parsed)
+}
+
+func effectivePort(u *url.URL) string {
+	if port := u.Port(); port != "" {
+		return port
+	}
+	switch u.Scheme {
+	case "https":
+		return "443"
+	case "http":
+		return "80"
+	default:
+		return ""
+	}
+}
--- a/client/server/ssh_gate_test.go
+++ b/client/server/ssh_gate_test.go
@@ -0,0 +1,348 @@
+package server
+
+import (
+	"context"
+	"net/url"
+	"os"
+	"runtime"
+	"strings"
+	"testing"
+
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/peer"
+	gstatus "google.golang.org/grpc/status"
+
+	"github.com/netbirdio/netbird/client/internal/ipcauth"
+	"github.com/netbirdio/netbird/client/internal/profilemanager"
+)
+
+// ctxWithIdentity builds a request context carrying the identity the transport
+// credentials would have attached.
+func ctxWithIdentity(id ipcauth.Identity) context.Context {
+	return peer.NewContext(context.Background(), &peer.Peer{
+		AuthInfo: ipcauth.AuthInfo{
+			CommonAuthInfo: credentials.CommonAuthInfo{SecurityLevel: credentials.NoSecurity},
+			Identity:       id,
+		},
+	})
+}
+
+// unprivUID is deliberately not this process's own uid. An unprivileged daemon
+// treats a caller sharing its identity as privileged (rootless containers), and
+// the test binary would otherwise stand in for both the daemon and the caller.
+// os.Geteuid returns -1 on Windows, where identities are SIDs instead and this is
+// unused.
+var unprivUID = uint32(os.Geteuid() + 1)
+
+// The fabricated identities have to be shaped like the platform's: a uid says
+// nothing on Windows, and a zero uid there would read as root and be privileged.
+func rootCtx() context.Context { return ctxWithIdentity(privilegedIdentity()) }
+func userCtx() context.Context { return ctxWithIdentity(unprivilegedIdentity()) }
+
+func privilegedIdentity() ipcauth.Identity {
+	if runtime.GOOS == "windows" {
+		// LocalSystem, which is what the Windows service account is.
+		return ipcauth.Identity{SID: "S-1-5-18"}
+	}
+	return ipcauth.Identity{UID: 0}
+}
+
+func unprivilegedIdentity() ipcauth.Identity {
+	if runtime.GOOS == "windows" {
+		// A plain user SID: no groups, so no BUILTIN\Administrators, and not
+		// elevated.
+		return ipcauth.Identity{SID: "S-1-5-21-1-2-3-1001"}
+	}
+	return ipcauth.Identity{UID: unprivUID, GID: unprivUID}
+}
+func noIdentityCtx() context.Context { return context.Background() }
+
+func boolPtr(v bool) *bool { return &v }
+
+func mustURL(t *testing.T, raw string) *url.URL {
+	t.Helper()
+	u, err := url.Parse(raw)
+	if err != nil {
+		t.Fatalf("parse %q: %v", raw, err)
+	}
+	return u
+}
+
+func assertDenied(t *testing.T, err error) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected the change to be refused, got nil")
+	}
+	st := gstatus.Convert(err)
+	if st.Code() != codes.PermissionDenied {
+		t.Fatalf("code = %v, want PermissionDenied", st.Code())
+	}
+	// The refusal must be machine-readable: the CLI and the UI render the
+	// summary and command from the detail rather than parsing the message.
+	var info *errdetails.ErrorInfo
+	for _, d := range st.Details() {
+		if got, ok := d.(*errdetails.ErrorInfo); ok {
+			info = got
+		}
+	}
+	if info == nil {
+		t.Fatal("refusal carries no ErrorInfo detail")
+	}
+	if info.GetReason() != ipcauth.ErrorReasonPrivilegeRequired || info.GetDomain() != ipcauth.ErrorDomain {
+		t.Fatalf("detail = %s/%s, want %s/%s", info.GetDomain(), info.GetReason(), ipcauth.ErrorDomain, ipcauth.ErrorReasonPrivilegeRequired)
+	}
+	if info.GetMetadata()[ipcauth.ErrorMetaSummary] == "" {
+		t.Error("detail carries no summary")
+	}
+	if info.GetMetadata()[ipcauth.ErrorMetaCommand] == "" {
+		t.Error("detail carries no command")
+	}
+}
+
+func assertAllowed(t *testing.T, err error) {
+	t.Helper()
+	if err != nil {
+		t.Fatalf("expected the change to be allowed, got %v", err)
+	}
+}
+
+func TestRequirePrivilegeForConfigChange_SSHFlags(t *testing.T) {
+	tests := []struct {
+		name       string
+		stored     *profilemanager.Config
+		change     privilegedConfigChange
+		privileged bool
+		wantDeny   bool
+	}{
+		{
+			name:     "enabling the ssh server unprivileged is refused",
+			stored:   &profilemanager.Config{ServerSSHAllowed: boolPtr(false)},
+			change:   privilegedConfigChange{serverSSHAllowed: boolPtr(true)},
+			wantDeny: true,
+		},
+		{
+			name:       "enabling the ssh server as root is allowed",
+			stored:     &profilemanager.Config{ServerSSHAllowed: boolPtr(false)},
+			change:     privilegedConfigChange{serverSSHAllowed: boolPtr(true)},
+			privileged: true,
+		},
+		{
+			name:   "restating an already enabled ssh server is not a change",
+			stored: &profilemanager.Config{ServerSSHAllowed: boolPtr(true)},
+			change: privilegedConfigChange{serverSSHAllowed: boolPtr(true)},
+		},
+		{
+			name:   "turning the ssh server off is not guarded",
+			stored: &profilemanager.Config{ServerSSHAllowed: boolPtr(true)},
+			change: privilegedConfigChange{serverSSHAllowed: boolPtr(false)},
+		},
+		{
+			name:     "a profile with no config yet counts as off, so enabling is refused",
+			stored:   nil,
+			change:   privilegedConfigChange{serverSSHAllowed: boolPtr(true)},
+			wantDeny: true,
+		},
+		{
+			name:     "enabling ssh root login unprivileged is refused",
+			stored:   &profilemanager.Config{EnableSSHRoot: boolPtr(false)},
+			change:   privilegedConfigChange{enableSSHRoot: boolPtr(true)},
+			wantDeny: true,
+		},
+		{
+			name:   "restating ssh root login is not a change",
+			stored: &profilemanager.Config{EnableSSHRoot: boolPtr(true)},
+			change: privilegedConfigChange{enableSSHRoot: boolPtr(true)},
+		},
+		{
+			name:   "turning ssh root login off is not guarded",
+			stored: &profilemanager.Config{EnableSSHRoot: boolPtr(true)},
+			change: privilegedConfigChange{enableSSHRoot: boolPtr(false)},
+		},
+		{
+			name:     "disabling ssh authentication unprivileged is refused",
+			stored:   &profilemanager.Config{DisableSSHAuth: boolPtr(false)},
+			change:   privilegedConfigChange{disableSSHAuth: boolPtr(true)},
+			wantDeny: true,
+		},
+		{
+			name:   "re-enabling ssh authentication is not guarded",
+			stored: &profilemanager.Config{DisableSSHAuth: boolPtr(true)},
+			change: privilegedConfigChange{disableSSHAuth: boolPtr(false)},
+		},
+		{
+			name:   "a request that touches none of the guarded fields is allowed",
+			stored: &profilemanager.Config{ServerSSHAllowed: boolPtr(false)},
+			change: privilegedConfigChange{},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ctx := userCtx()
+			if tt.privileged {
+				ctx = rootCtx()
+			}
+			err := requirePrivilegeForConfigChange(ctx, tt.stored, tt.change)
+			if tt.wantDeny {
+				assertDenied(t, err)
+				return
+			}
+			assertAllowed(t, err)
+		})
+	}
+}
+
+func TestRequirePrivilegeForConfigChange_ManagementURL(t *testing.T) {
+	sshOn := func(raw string) *profilemanager.Config {
+		return &profilemanager.Config{ServerSSHAllowed: boolPtr(true), ManagementURL: mustURL(t, raw)}
+	}
+	sshOff := func(raw string) *profilemanager.Config {
+		return &profilemanager.Config{ServerSSHAllowed: boolPtr(false), ManagementURL: mustURL(t, raw)}
+	}
+
+	tests := []struct {
+		name       string
+		stored     *profilemanager.Config
+		requested  string
+		privileged bool
+		wantDeny   bool
+	}{
+		{
+			name:      "moving the binding while ssh is enabled is refused",
+			stored:    sshOn("https://api.netbird.io:443"),
+			requested: "https://attacker.example.com:443",
+			wantDeny:  true,
+		},
+		{
+			name:       "moving the binding as root is allowed",
+			stored:     sshOn("https://api.netbird.io:443"),
+			requested:  "https://selfhosted.example.com:443",
+			privileged: true,
+		},
+		{
+			name:      "the same url restated is not a change",
+			stored:    sshOn("https://api.netbird.io:443"),
+			requested: "https://api.netbird.io:443",
+		},
+		{
+			name:      "an equivalent spelling of the same url is not a change",
+			stored:    sshOn("https://api.netbird.io:443"),
+			requested: "https://api.netbird.io",
+		},
+		{
+			name:      "an equivalent spelling with an explicit http port is not a change",
+			stored:    sshOn("http://mgmt.internal:80"),
+			requested: "http://mgmt.internal",
+		},
+		{
+			name:      "a different port on the same host is a change",
+			stored:    sshOn("https://api.netbird.io:443"),
+			requested: "https://api.netbird.io:8443",
+			wantDeny:  true,
+		},
+		{
+			name:      "a different scheme on the same host is a change",
+			stored:    sshOn("https://mgmt.internal:443"),
+			requested: "http://mgmt.internal:443",
+			wantDeny:  true,
+		},
+		{
+			name:      "with ssh disabled the binding is not guarded at all",
+			stored:    sshOff("https://api.netbird.io:443"),
+			requested: "https://attacker.example.com:443",
+		},
+		{
+			name:      "an unparseable url fails closed",
+			stored:    sshOn("https://api.netbird.io:443"),
+			requested: "ht tp://%zz",
+			wantDeny:  true,
+		},
+		{
+			name:      "an empty url leaves the binding alone",
+			stored:    sshOn("https://api.netbird.io:443"),
+			requested: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ctx := userCtx()
+			if tt.privileged {
+				ctx = rootCtx()
+			}
+			err := requirePrivilegeForConfigChange(ctx, tt.stored, privilegedConfigChange{managementURL: tt.requested})
+			if tt.wantDeny {
+				assertDenied(t, err)
+				return
+			}
+			assertAllowed(t, err)
+		})
+	}
+}
+
+// A caller the daemon cannot identify must be refused, not trusted: that is the
+// state on a TCP daemon socket, where no peer credentials exist.
+func TestRequirePrivilegeForConfigChange_UnidentifiedCallerIsRefused(t *testing.T) {
+	err := requirePrivilegeForConfigChange(noIdentityCtx(),
+		&profilemanager.Config{ServerSSHAllowed: boolPtr(false)},
+		privilegedConfigChange{serverSSHAllowed: boolPtr(true)})
+	assertDenied(t, err)
+
+	// The guidance must point at the socket rather than at sudo, since elevating
+	// would not help.
+	st := gstatus.Convert(err)
+	if !strings.Contains(st.Message(), "service install") {
+		t.Errorf("message %q does not tell the operator how to fix the socket", st.Message())
+	}
+}
+
+func TestRequirePrivilegeForDeregistration(t *testing.T) {
+	tests := []struct {
+		name       string
+		cfg        *profilemanager.Config
+		privileged bool
+		wantDeny   bool
+	}{
+		{
+			name:     "deregistering while ssh is enabled is refused",
+			cfg:      &profilemanager.Config{ServerSSHAllowed: boolPtr(true)},
+			wantDeny: true,
+		},
+		{
+			name:       "deregistering while ssh is enabled is allowed for root",
+			cfg:        &profilemanager.Config{ServerSSHAllowed: boolPtr(true)},
+			privileged: true,
+		},
+		{
+			name: "deregistering with ssh disabled is not guarded",
+			cfg:  &profilemanager.Config{ServerSSHAllowed: boolPtr(false)},
+		},
+		{
+			name: "deregistering a profile with no config is not guarded",
+			cfg:  nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ctx := userCtx()
+			if tt.privileged {
+				ctx = rootCtx()
+			}
+			err := requirePrivilegeForDeregistration(ctx, tt.cfg)
+			if tt.wantDeny {
+				assertDenied(t, err)
+				return
+			}
+			assertAllowed(t, err)
+		})
+	}
+}
+
+// privilegedTestCtx is the context a handler-level test should use when it is
+// standing in for a root/administrator caller. Tests that drive the handlers
+// directly have no transport credentials, and the privileged-change gate refuses
+// a caller it cannot identify.
+func privilegedTestCtx() context.Context { return rootCtx() }