Add IPv6 cases to relay WS prepareURL tests

This change enables admins to configure posture checks for connecting public IPs of their peers.

It changes the behavior of the check as well and now the evaluation is if the received network is part of the configured network.

.github/workflows/release.yml

@@ -114,7 +114,7 @@ jobs:
           retention-days: 30
 
   release:
-    runs-on: ubuntu-latest-m
+    runs-on: ubuntu-24.04-8-core
     outputs:
       release_artifact_url: ${{ steps.upload_release.outputs.artifact-url }}
       linux_packages_artifact_url: ${{ steps.upload_linux_packages.outputs.artifact-url }}
@@ -455,6 +455,151 @@ jobs:
           path: dist/
           retention-days: 3
 
+  test_windows_installer:
+    name: "Windows Installer / Build Test"
+    runs-on: windows-2022
+    needs: [release, release_ui]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            wintun_arch: amd64
+          - arch: arm64
+            wintun_arch: arm64
+    defaults:
+      run:
+        shell: powershell
+    env:
+      PackageWorkdir: netbird_windows_${{ matrix.arch }}
+      downloadPath: '${{ github.workspace }}\temp'
+    steps:
+      - name: Parse semver string
+        id: semver_parser
+        uses: booxmedialtd/ws-action-parse-semver@v1
+        with:
+          input_string: ${{ (startsWith(github.ref, 'refs/tags/v') && github.ref) || 'refs/tags/v0.0.0' }}
+          version_extractor_regex: '\/v(.*)$'
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Add 7-Zip to PATH
+        run: echo "C:\Program Files\7-Zip" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+      - name: Download release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: release
+          path: release
+
+      - name: Download UI release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: release-ui
+          path: release-ui
+
+      - name: Stage binaries into dist
+        run: |
+          $workdir = "dist\${{ env.PackageWorkdir }}"
+          New-Item -ItemType Directory -Force -Path $workdir | Out-Null
+          $client = Get-ChildItem -Recurse -Path release -Filter "netbird_*_windows_${{ matrix.arch }}.tar.gz" | Select-Object -First 1
+          $ui = Get-ChildItem -Recurse -Path release-ui -Filter "netbird-ui-windows_*_windows_${{ matrix.arch }}.tar.gz" | Select-Object -First 1
+          if (-not $client) { Write-Host "::error::client tarball not found for ${{ matrix.arch }}"; exit 1 }
+          if (-not $ui) { Write-Host "::error::ui tarball not found for ${{ matrix.arch }}"; exit 1 }
+          Write-Host "Client: $($client.FullName)"
+          Write-Host "UI:     $($ui.FullName)"
+          tar -zvxf $client.FullName -C $workdir
+          tar -zvxf $ui.FullName -C $workdir
+          Get-ChildItem $workdir
+
+      - name: Download wintun
+        uses: carlosperate/download-file-action@v2
+        id: download-wintun
+        with:
+          file-url: https://pkgs.netbird.io/wintun/wintun-0.14.1.zip
+          file-name: wintun.zip
+          location: ${{ env.downloadPath }}
+          sha256: '07c256185d6ee3652e09fa55c0b673e2624b565e02c4b9091c79ca7d2f24ef51'
+
+      - name: Decompress wintun files
+        run: tar -zvxf "${{ steps.download-wintun.outputs.file-path }}" -C ${{ env.downloadPath }}
+
+      - name: Move wintun.dll into dist
+        run: mv ${{ env.downloadPath }}\wintun\bin\${{ matrix.wintun_arch }}\wintun.dll ${{ github.workspace }}\dist\${{ env.PackageWorkdir }}\
+
+      - name: Download Mesa3D (amd64 only)
+        uses: carlosperate/download-file-action@v2
+        id: download-mesa3d
+        if: matrix.arch == 'amd64'
+        with:
+          file-url: https://downloads.fdossena.com/Projects/Mesa3D/Builds/MesaForWindows-x64-20.1.8.7z
+          file-name: mesa3d.7z
+          location: ${{ env.downloadPath }}
+          sha256: '71c7cb64ec229a1d6b8d62fa08e1889ed2bd17c0eeede8689daf0f25cb31d6b9'
+
+      - name: Extract Mesa3D driver (amd64 only)
+        if: matrix.arch == 'amd64'
+        run: 7z x -o"${{ env.downloadPath }}" "${{ env.downloadPath }}/mesa3d.7z"
+
+      - name: Move opengl32.dll into dist (amd64 only)
+        if: matrix.arch == 'amd64'
+        run: mv ${{ env.downloadPath }}\opengl32.dll ${{ github.workspace }}\dist\${{ env.PackageWorkdir }}\
+
+      - name: Download EnVar plugin for NSIS
+        uses: carlosperate/download-file-action@v2
+        with:
+          file-url: https://nsis.sourceforge.io/mediawiki/images/7/7f/EnVar_plugin.zip
+          file-name: envar_plugin.zip
+          location: ${{ github.workspace }}
+
+      - name: Extract EnVar plugin
+        run: 7z x -o"${{ github.workspace }}/NSIS_Plugins" "${{ github.workspace }}/envar_plugin.zip"
+
+      - name: Download ShellExecAsUser plugin for NSIS (amd64 only)
+        uses: carlosperate/download-file-action@v2
+        if: matrix.arch == 'amd64'
+        with:
+          file-url: https://nsis.sourceforge.io/mediawiki/images/6/68/ShellExecAsUser_amd64-Unicode.7z
+          file-name: ShellExecAsUser_amd64-Unicode.7z
+          location: ${{ github.workspace }}
+
+      - name: Extract ShellExecAsUser plugin (amd64 only)
+        if: matrix.arch == 'amd64'
+        run: 7z x -o"${{ github.workspace }}/NSIS_Plugins" "${{ github.workspace }}/ShellExecAsUser_amd64-Unicode.7z"
+
+      - name: Build NSIS installer
+        uses: joncloud/makensis-action@v3.3
+        with:
+          additional-plugin-paths: ${{ github.workspace }}/NSIS_Plugins/Plugins
+          script-file: client/installer.nsis
+          arguments: "/V4 /DARCH=${{ matrix.arch }}"
+        env:
+          APPVER: ${{ steps.semver_parser.outputs.major }}.${{ steps.semver_parser.outputs.minor }}.${{ steps.semver_parser.outputs.patch }}.${{ github.run_id }}
+
+      - name: Rename NSIS installer
+        run: mv netbird-installer.exe netbird_installer_test_windows_${{ matrix.arch }}.exe
+
+      - name: Install WiX
+        run: |
+          dotnet tool install --global wix --version 6.0.2
+          wix extension add WixToolset.Util.wixext/6.0.2
+
+      - name: Build MSI installer
+        env:
+          NETBIRD_VERSION: "${{ steps.semver_parser.outputs.fullversion }}"
+        run: wix build -arch ${{ matrix.arch == 'amd64' && 'x64' || 'arm64' }} -ext WixToolset.Util.wixext -o netbird_installer_test_windows_${{ matrix.arch }}.msi .\client\netbird.wxs -d ProcessorArchitecture=${{ matrix.arch == 'amd64' && 'x64' || 'arm64' }} -d ArchSuffix=${{ matrix.arch }}
+
+      - name: Upload installer artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-installer-test-${{ matrix.arch }}
+          path: |
+            netbird_installer_test_windows_${{ matrix.arch }}.exe
+            netbird_installer_test_windows_${{ matrix.arch }}.msi
+          retention-days: 3
+
   comment_release_artifacts:
     name: Comment release artifacts
     runs-on: ubuntu-latest
@@ -554,7 +699,7 @@ jobs:
 
   trigger_signer:
     runs-on: ubuntu-latest
-    needs: [release, release_ui, release_ui_darwin]
+    needs: [release, release_ui, release_ui_darwin, test_windows_installer]
     if: startsWith(github.ref, 'refs/tags/')
     steps:
       - name: Trigger binaries sign pipelines

.github/workflows/sync-tag.yml

@@ -9,6 +9,8 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}-${{ github.head_ref || github.actor_id }}
   cancel-in-progress: true
 
+# Receiving workflows (cloud sync-tag, mobile bump-netbird) expect the short
+# tag form (e.g. v0.30.0), not refs/tags/v0.30.0 — github.ref_name, not github.ref.
 jobs:
   trigger_sync_tag:
     runs-on: ubuntu-latest
@@ -20,4 +22,30 @@ jobs:
           ref: main
           repo: ${{ secrets.UPSTREAM_REPO }}
           token: ${{ secrets.NC_GITHUB_TOKEN }}
+          inputs: '{ "tag": "${{ github.ref_name }}" }'
+
+  trigger_android_bump:
+    runs-on: ubuntu-latest
+    if: github.event.created && !github.event.deleted && startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-')
+    steps:
+      - name: Trigger android-client submodule bump
+        uses: benc-uk/workflow-dispatch@7a027648b88c2413826b6ddd6c76114894dc5ec4 # v1.3.1
+        with:
+          workflow: bump-netbird.yml
+          ref: main
+          repo: netbirdio/android-client
+          token: ${{ secrets.NC_GITHUB_TOKEN }}
+          inputs: '{ "tag": "${{ github.ref_name }}" }'
+
+  trigger_ios_bump:
+    runs-on: ubuntu-latest
+    if: github.event.created && !github.event.deleted && startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-')
+    steps:
+      - name: Trigger ios-client submodule bump
+        uses: benc-uk/workflow-dispatch@7a027648b88c2413826b6ddd6c76114894dc5ec4 # v1.3.1
+        with:
+          workflow: bump-netbird.yml
+          ref: main
+          repo: netbirdio/ios-client
+          token: ${{ secrets.NC_GITHUB_TOKEN }}
           inputs: '{ "tag": "${{ github.ref_name }}" }'

client/cmd/testutil_test.go

@@ -135,7 +135,7 @@ func startManagement(t *testing.T, config *config.Config, testFile string) (*grp
 	if err != nil {
 		t.Fatal(err)
 	}
-	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, &mgmt.MockIntegratedValidator{}, networkMapController, nil)
+	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, &mgmt.MockIntegratedValidator{}, networkMapController, nil, nil)
 	if err != nil {
 		t.Fatal(err)
 	}

client/installer.nsis

@@ -201,6 +201,8 @@ Pop $0
 
 Function .onInit
 StrCpy $INSTDIR "${INSTALL_DIR}"
+; Default autostart to enabled so silent installs (/S) match the interactive default
+StrCpy $AutostartEnabled "1"
 
 ; Pre-0.70.1 installers ran without SetRegView, so their uninstall keys live
 ; in the 32-bit view. Fall back to it so upgrades still find them.

client/internal/engine_test.go

@@ -1671,7 +1671,7 @@ func startManagement(t *testing.T, dataDir, testFile string) (*grpc.Server, stri
 	if err != nil {
 		return nil, "", err
 	}
-	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, &server.MockIntegratedValidator{}, networkMapController, nil)
+	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, &server.MockIntegratedValidator{}, networkMapController, nil, nil)
 	if err != nil {
 		return nil, "", err
 	}

client/internal/lazyconn/activity/listener_bind_test.go

@@ -3,7 +3,6 @@ package activity
 import (
 	"net"
 	"net/netip"
-	"runtime"
 	"testing"
 	"time"
 
@@ -18,10 +17,6 @@ import (
 	peerid "github.com/netbirdio/netbird/client/internal/peer/id"
 )
 
-func isBindListenerPlatform() bool {
-	return runtime.GOOS == "windows" || runtime.GOOS == "js"
-}
-
 // mockEndpointManager implements device.EndpointManager for testing
 type mockEndpointManager struct {
 	endpoints map[netip.Addr]net.Conn
@@ -181,10 +176,6 @@ func TestBindListener_Close(t *testing.T) {
 }
 
 func TestManager_BindMode(t *testing.T) {
-	if !isBindListenerPlatform() {
-		t.Skip("BindListener only used on Windows/JS platforms")
-	}
-
 	mockEndpointMgr := newMockEndpointManager()
 	mockIface := &MockWGIfaceBind{endpointMgr: mockEndpointMgr}
 
@@ -226,10 +217,6 @@ func TestManager_BindMode(t *testing.T) {
 }
 
 func TestManager_BindMode_MultiplePeers(t *testing.T) {
-	if !isBindListenerPlatform() {
-		t.Skip("BindListener only used on Windows/JS platforms")
-	}
-
 	mockEndpointMgr := newMockEndpointManager()
 	mockIface := &MockWGIfaceBind{endpointMgr: mockEndpointMgr}
 

client/internal/lazyconn/activity/manager.go

@@ -4,14 +4,12 @@ import (
 	"errors"
 	"net"
 	"net/netip"
-	"runtime"
 	"sync"
 	"time"
 
 	log "github.com/sirupsen/logrus"
 	"golang.zx2c4.com/wireguard/wgctrl/wgtypes"
 
-	"github.com/netbirdio/netbird/client/iface/netstack"
 	"github.com/netbirdio/netbird/client/iface/wgaddr"
 	"github.com/netbirdio/netbird/client/internal/lazyconn"
 	peerid "github.com/netbirdio/netbird/client/internal/peer/id"
@@ -75,16 +73,6 @@ func (m *Manager) createListener(peerCfg lazyconn.PeerConfig) (listener, error)
 		return NewUDPListener(m.wgIface, peerCfg)
 	}
 
-	// BindListener is used on Windows, JS, and netstack platforms:
-	// - JS: Cannot listen to UDP sockets
-	// - Windows: IP_UNICAST_IF socket option forces packets out the interface the default
-	//   gateway points to, preventing them from reaching the loopback interface.
-	// - Netstack: Allows multiple instances on the same host without port conflicts.
-	// BindListener bypasses these issues by passing data directly through the bind.
-	if runtime.GOOS != "windows" && runtime.GOOS != "js" && !netstack.IsEnabled() {
-		return NewUDPListener(m.wgIface, peerCfg)
-	}
-
 	provider, ok := m.wgIface.(bindProvider)
 	if !ok {
 		return nil, errors.New("interface claims userspace bind but doesn't implement bindProvider")

client/internal/routemanager/systemops/systemops_darwin.go

@@ -89,8 +89,16 @@ func (r *SysOps) installScopedDefaultFor(unspec netip.Addr) (bool, error) {
 		return false, fmt.Errorf("unusable default nexthop for %s (no interface)", unspec)
 	}
 
+	reused := false
 	if err := r.addScopedDefault(unspec, nexthop); err != nil {
-		return false, fmt.Errorf("add scoped default on %s: %w", nexthop.Intf.Name, err)
+		if !errors.Is(err, unix.EEXIST) {
+			return false, fmt.Errorf("add scoped default on %s: %w", nexthop.Intf.Name, err)
+		}
+		// macOS installs its own RTF_IFSCOPE defaults for primary service
+		// selection on multi-NIC setups, so a route on this ifindex can
+		// already exist before we try. Binding to it via IP[V6]_BOUND_IF
+		// still produces the scoped lookup we need.
+		reused = true
 	}
 
 	af := unix.AF_INET
@@ -102,7 +110,11 @@ func (r *SysOps) installScopedDefaultFor(unspec netip.Addr) (bool, error) {
 	if nexthop.IP.IsValid() {
 		via = nexthop.IP.String()
 	}
-	log.Infof("installed scoped default route via %s on %s for %s", via, nexthop.Intf.Name, afOf(unspec))
+	verb := "installed"
+	if reused {
+		verb = "reused existing"
+	}
+	log.Infof("%s scoped default route via %s on %s for %s", verb, via, nexthop.Intf.Name, afOf(unspec))
 	return true, nil
 }
 

client/netbird.wxs

@@ -13,6 +13,9 @@
 
 		<MajorUpgrade AllowSameVersionUpgrades='yes' DowngradeErrorMessage="A newer version of [ProductName] is already installed. Setup will now exit."/>
 
+		<!-- Autostart: enabled by default, disable with AUTOSTART=0 on the msiexec command line -->
+		<Property Id="AUTOSTART" Value="1" />
+
 		<StandardDirectory Id="ProgramFiles64Folder">
 			<Directory Id="NetbirdInstallDir" Name="Netbird">
 				<Component Id="NetbirdFiles" Guid="db3165de-cc6e-4922-8396-9d892950e23e" Bitness="always64">
@@ -63,9 +66,20 @@
 			</Component>
 		</StandardDirectory>
 
+		<StandardDirectory Id="CommonAppDataFolder">
+			<Directory Id="NetbirdAutoStartDir" Name="Netbird">
+				<Component Id="NetbirdAutoStart" Guid="b199eaca-b0dd-4032-af19-679cfad48eb3" Bitness="always64" Condition='AUTOSTART = "1"'>
+					<RegistryValue Root="HKLM" Key="Software\Microsoft\Windows\CurrentVersion\Run"
+						Name="Netbird" Value="&quot;[NetbirdInstallDir]netbird-ui.exe&quot;"
+						Type="string" KeyPath="yes" />
+				</Component>
+			</Directory>
+		</StandardDirectory>
+
 		<ComponentGroup Id="NetbirdFilesComponent">
 			<ComponentRef Id="NetbirdFiles" />
 			<ComponentRef Id="NetbirdAumidRegistry" />
+			<ComponentRef Id="NetbirdAutoStart" />
 		</ComponentGroup>
 
 		<util:CloseApplication Id="CloseNetBird" CloseMessage="no" Target="netbird.exe" RebootPrompt="no" />

client/server/server_test.go

@@ -335,7 +335,7 @@ func startManagement(t *testing.T, signalAddr string, counter *int) (*grpc.Serve
 	if err != nil {
 		return nil, "", err
 	}
-	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, &server.MockIntegratedValidator{}, networkMapController, nil)
+	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, &server.MockIntegratedValidator{}, networkMapController, nil, nil)
 	if err != nil {
 		return nil, "", err
 	}

management/internals/controllers/network_map/controller/controller.go

@@ -257,7 +257,10 @@ func (c *Controller) bufferSendUpdateAccountPeers(ctx context.Context, accountID
 
 // UpdatePeers updates all peers that belong to an account.
 // Should be called when changes have to be synced to peers.
-func (c *Controller) UpdateAccountPeers(ctx context.Context, accountID string) error {
+func (c *Controller) UpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) error {
+	if c.accountManagerMetrics != nil {
+		c.accountManagerMetrics.CountUpdateAccountPeersTriggered(string(reason.Resource), string(reason.Operation))
+	}
 	return c.sendUpdateAccountPeers(ctx, accountID)
 }
 
@@ -331,9 +334,13 @@ func (c *Controller) UpdateAccountPeer(ctx context.Context, accountId string, pe
 	return nil
 }
 
-func (c *Controller) BufferUpdateAccountPeers(ctx context.Context, accountID string) error {
+func (c *Controller) BufferUpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) error {
 	log.WithContext(ctx).Tracef("buffer updating peers for account %s from %s", accountID, util.GetCallerName())
 
+	if c.accountManagerMetrics != nil {
+		c.accountManagerMetrics.CountUpdateAccountPeersTriggered(string(reason.Resource), string(reason.Operation))
+	}
+
 	bufUpd, _ := c.accountUpdateLocks.LoadOrStore(accountID, &bufferUpdate{})
 	b := bufUpd.(*bufferUpdate)
 
@@ -348,14 +355,14 @@ func (c *Controller) BufferUpdateAccountPeers(ctx context.Context, accountID str
 
 	go func() {
 		defer b.mu.Unlock()
-		_ = c.UpdateAccountPeers(ctx, accountID)
+		_ = c.sendUpdateAccountPeers(ctx, accountID)
 		if !b.update.Load() {
 			return
 		}
 		b.update.Store(false)
 		if b.next == nil {
 			b.next = time.AfterFunc(time.Duration(c.updateAccountPeersBufferInterval.Load()), func() {
-				_ = c.UpdateAccountPeers(ctx, accountID)
+				_ = c.sendUpdateAccountPeers(ctx, accountID)
 			})
 			return
 		}

management/internals/controllers/network_map/interface.go

@@ -18,9 +18,9 @@ const (
 )
 
 type Controller interface {
-	UpdateAccountPeers(ctx context.Context, accountID string) error
+	UpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) error
 	UpdateAccountPeer(ctx context.Context, accountId string, peerId string) error
-	BufferUpdateAccountPeers(ctx context.Context, accountID string) error
+	BufferUpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) error
 	GetValidatedPeerWithMap(ctx context.Context, isRequiresApproval bool, accountID string, p *nbpeer.Peer) (*nbpeer.Peer, *types.NetworkMap, []*posture.Checks, int64, error)
 	GetDNSDomain(settings *types.Settings) string
 	StartWarmup(context.Context)

management/internals/controllers/network_map/interface_mock.go

@@ -44,17 +44,17 @@ func (m *MockController) EXPECT() *MockControllerMockRecorder {
 }
 
 // BufferUpdateAccountPeers mocks base method.
-func (m *MockController) BufferUpdateAccountPeers(ctx context.Context, accountID string) error {
+func (m *MockController) BufferUpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) error {
 	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "BufferUpdateAccountPeers", ctx, accountID)
+	ret := m.ctrl.Call(m, "BufferUpdateAccountPeers", ctx, accountID, reason)
 	ret0, _ := ret[0].(error)
 	return ret0
 }
 
 // BufferUpdateAccountPeers indicates an expected call of BufferUpdateAccountPeers.
-func (mr *MockControllerMockRecorder) BufferUpdateAccountPeers(ctx, accountID any) *gomock.Call {
+func (mr *MockControllerMockRecorder) BufferUpdateAccountPeers(ctx, accountID, reason any) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
-	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "BufferUpdateAccountPeers", reflect.TypeOf((*MockController)(nil).BufferUpdateAccountPeers), ctx, accountID)
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "BufferUpdateAccountPeers", reflect.TypeOf((*MockController)(nil).BufferUpdateAccountPeers), ctx, accountID, reason)
 }
 
 // CountStreams mocks base method.
@@ -238,15 +238,15 @@ func (mr *MockControllerMockRecorder) UpdateAccountPeer(ctx, accountId, peerId a
 }
 
 // UpdateAccountPeers mocks base method.
-func (m *MockController) UpdateAccountPeers(ctx context.Context, accountID string) error {
+func (m *MockController) UpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) error {
 	m.ctrl.T.Helper()
-	ret := m.ctrl.Call(m, "UpdateAccountPeers", ctx, accountID)
+	ret := m.ctrl.Call(m, "UpdateAccountPeers", ctx, accountID, reason)
 	ret0, _ := ret[0].(error)
 	return ret0
 }
 
 // UpdateAccountPeers indicates an expected call of UpdateAccountPeers.
-func (mr *MockControllerMockRecorder) UpdateAccountPeers(ctx, accountID any) *gomock.Call {
+func (mr *MockControllerMockRecorder) UpdateAccountPeers(ctx, accountID, reason any) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
-	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "UpdateAccountPeers", reflect.TypeOf((*MockController)(nil).UpdateAccountPeers), ctx, accountID)
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "UpdateAccountPeers", reflect.TypeOf((*MockController)(nil).UpdateAccountPeers), ctx, accountID, reason)
 }

management/internals/modules/peers/ephemeral/manager/ephemeral_test.go

@@ -62,7 +62,7 @@ func (a *MockAccountManager) GetDeletePeerCalls() int {
 	return a.deletePeerCalls
 }
 
-func (a *MockAccountManager) BufferUpdateAccountPeers(ctx context.Context, accountID string) {
+func (a *MockAccountManager) BufferUpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) {
 	a.mu.Lock()
 	defer a.mu.Unlock()
 	if a.bufferUpdateCalls == nil {
@@ -248,7 +248,7 @@ func TestCleanupSchedulingBehaviorIsBatched(t *testing.T) {
 					return err
 				}
 			}
-			mockAM.BufferUpdateAccountPeers(ctx, accountID)
+			mockAM.BufferUpdateAccountPeers(ctx, accountID, types.UpdateReason{})
 			return nil
 		}).
 		Times(1)

management/internals/modules/peers/manager.go

@@ -20,6 +20,7 @@ import (
 	"github.com/netbirdio/netbird/management/server/permissions/modules"
 	"github.com/netbirdio/netbird/management/server/permissions/operations"
 	"github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
@@ -178,7 +179,7 @@ func (m *managerImpl) DeletePeers(ctx context.Context, accountID string, peerIDs
 		}
 	}
 
-	m.accountManager.UpdateAccountPeers(ctx, accountID)
+	m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourcePeer, Operation: types.UpdateOperationDelete})
 
 	return nil
 }

management/internals/modules/reverseproxy/service/manager/l4_port_test.go

@@ -85,7 +85,7 @@ func setupL4Test(t *testing.T, customPortsSupported *bool) (*Manager, store.Stor
 
 	accountMgr := &mock_server.MockAccountManager{
 		StoreEventFunc:         func(_ context.Context, _, _, _ string, _ activity.ActivityDescriber, _ map[string]any) {},
-		UpdateAccountPeersFunc: func(_ context.Context, _ string) {},
+		UpdateAccountPeersFunc: func(_ context.Context, _ string, _ types.UpdateReason) {},
 		GetGroupByNameFunc: func(ctx context.Context, groupName, accountID, userID string) (*types.Group, error) {
 			return testStore.GetGroupByName(ctx, store.LockingStrengthNone, accountID, groupName)
 		},

management/internals/modules/reverseproxy/service/manager/manager.go

@@ -25,6 +25,7 @@ import (
 	"github.com/netbirdio/netbird/management/server/permissions/modules"
 	"github.com/netbirdio/netbird/management/server/permissions/operations"
 	"github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
@@ -231,7 +232,7 @@ func (m *Manager) CreateService(ctx context.Context, accountID, userID string, s
 
 	m.proxyController.SendServiceUpdateToCluster(ctx, accountID, s.ToProtoMapping(service.Create, "", m.proxyController.GetOIDCValidationConfig()), s.ProxyCluster)
 
-	m.accountManager.UpdateAccountPeers(ctx, accountID)
+	m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceService, Operation: types.UpdateOperationCreate})
 
 	return s, nil
 }
@@ -515,7 +516,7 @@ func (m *Manager) UpdateService(ctx context.Context, accountID, userID string, s
 	}
 
 	m.sendServiceUpdateNotifications(ctx, accountID, service, updateInfo)
-	m.accountManager.UpdateAccountPeers(ctx, accountID)
+	m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceService, Operation: types.UpdateOperationUpdate})
 
 	return service, nil
 }
@@ -819,7 +820,7 @@ func (m *Manager) DeleteService(ctx context.Context, accountID, userID, serviceI
 
 	m.proxyController.SendServiceUpdateToCluster(ctx, accountID, s.ToProtoMapping(service.Delete, "", m.proxyController.GetOIDCValidationConfig()), s.ProxyCluster)
 
-	m.accountManager.UpdateAccountPeers(ctx, accountID)
+	m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceService, Operation: types.UpdateOperationDelete})
 
 	return nil
 }
@@ -860,7 +861,7 @@ func (m *Manager) DeleteAllServices(ctx context.Context, accountID, userID strin
 		m.proxyController.SendServiceUpdateToCluster(ctx, accountID, svc.ToProtoMapping(service.Delete, "", oidcCfg), svc.ProxyCluster)
 	}
 
-	m.accountManager.UpdateAccountPeers(ctx, accountID)
+	m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceService, Operation: types.UpdateOperationDelete})
 
 	return nil
 }
@@ -916,7 +917,7 @@ func (m *Manager) ReloadService(ctx context.Context, accountID, serviceID string
 
 	m.proxyController.SendServiceUpdateToCluster(ctx, accountID, s.ToProtoMapping(service.Update, "", m.proxyController.GetOIDCValidationConfig()), s.ProxyCluster)
 
-	m.accountManager.UpdateAccountPeers(ctx, accountID)
+	m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceService, Operation: types.UpdateOperationUpdate})
 
 	return nil
 }
@@ -1098,7 +1099,7 @@ func (m *Manager) CreateServiceFromPeer(ctx context.Context, accountID, peerID s
 	}
 
 	m.proxyController.SendServiceUpdateToCluster(ctx, accountID, svc.ToProtoMapping(service.Create, "", m.proxyController.GetOIDCValidationConfig()), svc.ProxyCluster)
-	m.accountManager.UpdateAccountPeers(ctx, accountID)
+	m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceService, Operation: types.UpdateOperationCreate})
 
 	serviceURL := "https://" + svc.Domain
 	if service.IsL4Protocol(svc.Mode) {
@@ -1210,7 +1211,7 @@ func (m *Manager) deletePeerService(ctx context.Context, accountID, peerID, serv
 
 	m.proxyController.SendServiceUpdateToCluster(ctx, accountID, svc.ToProtoMapping(service.Delete, "", m.proxyController.GetOIDCValidationConfig()), svc.ProxyCluster)
 
-	m.accountManager.UpdateAccountPeers(ctx, accountID)
+	m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceService, Operation: types.UpdateOperationDelete})
 
 	return nil
 }
@@ -1261,7 +1262,7 @@ func (m *Manager) deleteExpiredPeerService(ctx context.Context, accountID, peerI
 	meta := addPeerInfoToEventMeta(svc.EventMeta(), peer)
 	m.accountManager.StoreEvent(ctx, peerID, serviceID, accountID, activity.PeerServiceExposeExpired, meta)
 	m.proxyController.SendServiceUpdateToCluster(ctx, accountID, svc.ToProtoMapping(service.Delete, "", m.proxyController.GetOIDCValidationConfig()), svc.ProxyCluster)
-	m.accountManager.UpdateAccountPeers(ctx, accountID)
+	m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceService, Operation: types.UpdateOperationDelete})
 
 	return nil
 }

management/internals/modules/reverseproxy/service/manager/manager_test.go

@@ -447,7 +447,7 @@ func TestDeletePeerService_SourcePeerValidation(t *testing.T) {
 			StoreEventFunc: func(_ context.Context, _, _, _ string, activityID activity.ActivityDescriber, _ map[string]any) {
 				storedActivity = activityID.(activity.Activity)
 			},
-			UpdateAccountPeersFunc: func(_ context.Context, _ string) {},
+			UpdateAccountPeersFunc: func(_ context.Context, _ string, _ types.UpdateReason) {},
 		}
 
 		mockStore.EXPECT().
@@ -549,7 +549,7 @@ func TestDeletePeerService_SourcePeerValidation(t *testing.T) {
 			StoreEventFunc: func(_ context.Context, _, _, _ string, activityID activity.ActivityDescriber, _ map[string]any) {
 				storedActivity = activityID.(activity.Activity)
 			},
-			UpdateAccountPeersFunc: func(_ context.Context, _ string) {},
+			UpdateAccountPeersFunc: func(_ context.Context, _ string, _ types.UpdateReason) {},
 		}
 
 		mockStore.EXPECT().
@@ -593,7 +593,7 @@ func TestDeletePeerService_SourcePeerValidation(t *testing.T) {
 			StoreEventFunc: func(_ context.Context, _, _, _ string, _ activity.ActivityDescriber, meta map[string]any) {
 				storedMeta = meta
 			},
-			UpdateAccountPeersFunc: func(_ context.Context, _ string) {},
+			UpdateAccountPeersFunc: func(_ context.Context, _ string, _ types.UpdateReason) {},
 		}
 
 		mockStore.EXPECT().
@@ -704,7 +704,7 @@ func setupIntegrationTest(t *testing.T) (*Manager, store.Store) {
 
 	accountMgr := &mock_server.MockAccountManager{
 		StoreEventFunc:         func(_ context.Context, _, _, _ string, _ activity.ActivityDescriber, _ map[string]any) {},
-		UpdateAccountPeersFunc: func(_ context.Context, _ string) {},
+		UpdateAccountPeersFunc: func(_ context.Context, _ string, _ types.UpdateReason) {},
 		GetGroupByNameFunc: func(ctx context.Context, groupName, accountID, userID string) (*types.Group, error) {
 			return testStore.GetGroupByName(ctx, store.LockingStrengthNone, accountID, groupName)
 		},
@@ -1173,7 +1173,7 @@ func TestDeleteService_DeletesTargets(t *testing.T) {
 	mockAcct.EXPECT().
 		StoreEvent(ctx, userID, service.ID, accountID, activity.ServiceDeleted, gomock.Any())
 	mockAcct.EXPECT().
-		UpdateAccountPeers(ctx, accountID)
+		UpdateAccountPeers(ctx, accountID, gomock.Any())
 
 	err = mgr.DeleteService(ctx, accountID, userID, service.ID)
 	require.NoError(t, err)

management/internals/modules/zones/manager/manager.go

@@ -11,6 +11,7 @@ import (
 	"github.com/netbirdio/netbird/management/server/permissions/modules"
 	"github.com/netbirdio/netbird/management/server/permissions/operations"
 	"github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
@@ -144,7 +145,7 @@ func (m *managerImpl) UpdateZone(ctx context.Context, accountID, userID string,
 
 	m.accountManager.StoreEvent(ctx, userID, zone.ID, accountID, activity.DNSZoneUpdated, zone.EventMeta())
 
-	go m.accountManager.UpdateAccountPeers(ctx, accountID)
+	go m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceZone, Operation: types.UpdateOperationUpdate})
 
 	return zone, nil
 }
@@ -206,7 +207,7 @@ func (m *managerImpl) DeleteZone(ctx context.Context, accountID, userID, zoneID
 		event()
 	}
 
-	go m.accountManager.UpdateAccountPeers(ctx, accountID)
+	go m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceZone, Operation: types.UpdateOperationDelete})
 
 	return nil
 }

management/internals/modules/zones/records/manager/manager.go

@@ -13,6 +13,7 @@ import (
 	"github.com/netbirdio/netbird/management/server/permissions/modules"
 	"github.com/netbirdio/netbird/management/server/permissions/operations"
 	"github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
@@ -95,7 +96,7 @@ func (m *managerImpl) CreateRecord(ctx context.Context, accountID, userID, zoneI
 	meta := record.EventMeta(zone.ID, zone.Name)
 	m.accountManager.StoreEvent(ctx, userID, record.ID, accountID, activity.DNSRecordCreated, meta)
 
-	go m.accountManager.UpdateAccountPeers(ctx, accountID)
+	go m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceZoneRecord, Operation: types.UpdateOperationCreate})
 
 	return record, nil
 }
@@ -154,7 +155,7 @@ func (m *managerImpl) UpdateRecord(ctx context.Context, accountID, userID, zoneI
 	meta := record.EventMeta(zone.ID, zone.Name)
 	m.accountManager.StoreEvent(ctx, userID, record.ID, accountID, activity.DNSRecordUpdated, meta)
 
-	go m.accountManager.UpdateAccountPeers(ctx, accountID)
+	go m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceZoneRecord, Operation: types.UpdateOperationUpdate})
 
 	return record, nil
 }
@@ -201,7 +202,7 @@ func (m *managerImpl) DeleteRecord(ctx context.Context, accountID, userID, zoneI
 	meta := record.EventMeta(zone.ID, zone.Name)
 	m.accountManager.StoreEvent(ctx, userID, recordID, accountID, activity.DNSRecordDeleted, meta)
 
-	go m.accountManager.UpdateAccountPeers(ctx, accountID)
+	go m.accountManager.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceZoneRecord, Operation: types.UpdateOperationDelete})
 
 	return nil
 }

management/internals/server/boot.go

@@ -173,7 +173,7 @@ func (s *BaseServer) GRPCServer() *grpc.Server {
 		}
 
 		gRPCAPIHandler := grpc.NewServer(gRPCOpts...)
-		srv, err := nbgrpc.NewServer(s.Config, s.AccountManager(), s.SettingsManager(), s.JobManager(), s.SecretsManager(), s.Metrics(), s.AuthManager(), s.IntegratedValidator(), s.NetworkMapController(), s.OAuthConfigProvider())
+		srv, err := nbgrpc.NewServer(s.Config, s.AccountManager(), s.SettingsManager(), s.JobManager(), s.SecretsManager(), s.Metrics(), s.AuthManager(), s.IntegratedValidator(), s.NetworkMapController(), s.OAuthConfigProvider(), s.SessionStore())
 		if err != nil {
 			log.Fatalf("failed to create management server: %v", err)
 		}

management/internals/server/controllers.go

@@ -6,6 +6,7 @@ import (
 	log "github.com/sirupsen/logrus"
 
 	"github.com/netbirdio/management-integrations/integrations"
+
 	"github.com/netbirdio/netbird/management/internals/modules/reverseproxy/proxy"
 	proxymanager "github.com/netbirdio/netbird/management/internals/modules/reverseproxy/proxy/manager"
 
@@ -66,6 +67,12 @@ func (s *BaseServer) SecretsManager() grpc.SecretsManager {
 	})
 }
 
+func (s *BaseServer) SessionStore() *auth.SessionStore {
+	return Create(s, func() *auth.SessionStore {
+		return auth.NewSessionStore(s.CacheStore())
+	})
+}
+
 func (s *BaseServer) AuthManager() auth.Manager {
 	audiences := s.Config.GetAuthAudiences()
 	audience := s.Config.HttpConfig.AuthAudience

management/internals/shared/grpc/server.go

@@ -14,6 +14,7 @@ import (
 	"sync/atomic"
 	"time"
 
+	jwtv5 "github.com/golang-jwt/jwt/v5"
 	pb "github.com/golang/protobuf/proto" // nolint
 	"github.com/golang/protobuf/ptypes/timestamp"
 	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/realip"
@@ -67,6 +68,7 @@ type Server struct {
 	appMetrics     telemetry.AppMetrics
 	peerLocks      sync.Map
 	authManager    auth.Manager
+	sessionStore   *auth.SessionStore
 
 	logBlockedPeers          bool
 	blockPeersWithSameConfig bool
@@ -98,6 +100,7 @@ func NewServer(
 	integratedPeerValidator integrated_validator.IntegratedValidator,
 	networkMapController network_map.Controller,
 	oAuthConfigProvider idp.OAuthConfigProvider,
+	sessionStore *auth.SessionStore,
 ) (*Server, error) {
 	if appMetrics != nil {
 		// update gauge based on number of connected peers which is equal to open gRPC streams
@@ -140,6 +143,7 @@ func NewServer(
 		integratedPeerValidator:  integratedPeerValidator,
 		networkMapController:     networkMapController,
 		oAuthConfigProvider:      oAuthConfigProvider,
+		sessionStore:             sessionStore,
 
 		loginFilter: newLoginFilter(),
 
@@ -535,7 +539,7 @@ func (s *Server) cancelPeerRoutinesWithoutLock(ctx context.Context, accountID st
 	log.WithContext(ctx).Debugf("peer %s has been disconnected", peer.Key)
 }
 
-func (s *Server) validateToken(ctx context.Context, jwtToken string) (string, error) {
+func (s *Server) validateToken(ctx context.Context, peerKey, jwtToken string) (string, error) {
 	if s.authManager == nil {
 		return "", status.Errorf(codes.Internal, "missing auth manager")
 	}
@@ -545,6 +549,10 @@ func (s *Server) validateToken(ctx context.Context, jwtToken string) (string, er
 		return "", status.Errorf(codes.InvalidArgument, "invalid jwt token, err: %v", err)
 	}
 
+	if err := s.claimLoginToken(ctx, peerKey, jwtToken, token); err != nil {
+		return "", err
+	}
+
 	// we need to call this method because if user is new, we will automatically add it to existing or create a new account
 	accountId, _, err := s.accountManager.GetAccountIDFromUserAuth(ctx, userAuth)
 	if err != nil {
@@ -828,6 +836,31 @@ func (s *Server) prepareLoginResponse(ctx context.Context, peer *nbpeer.Peer, ne
 	return loginResp, nil
 }
 
+func (s *Server) claimLoginToken(ctx context.Context, peerKey, jwtToken string, token *jwtv5.Token) error {
+	if s.sessionStore == nil || token == nil {
+		return nil
+	}
+
+	exp, err := token.Claims.GetExpirationTime()
+	if err != nil || exp == nil {
+		log.WithContext(ctx).Warnf("JWT has no usable exp claim for peer %s", peerKey)
+		return status.Error(codes.Unauthenticated, "jwt token has no expiration")
+	}
+
+	err = s.sessionStore.RegisterToken(ctx, jwtToken, exp.Time)
+	if err == nil {
+		return nil
+	}
+
+	if errors.Is(err, auth.ErrTokenAlreadyUsed) || errors.Is(err, auth.ErrTokenExpired) {
+		log.WithContext(ctx).Warnf("%v for peer %s", err, peerKey)
+		return status.Error(codes.Unauthenticated, err.Error())
+	}
+
+	log.WithContext(ctx).Warnf("failed to claim JWT for peer %s: %v", peerKey, err)
+	return status.Error(codes.Unavailable, "failed to claim jwt token")
+}
+
 // processJwtToken validates the existence of a JWT token in the login request, and returns the corresponding user ID if
 // the token is valid.
 //
@@ -838,7 +871,7 @@ func (s *Server) processJwtToken(ctx context.Context, loginReq *proto.LoginReque
 	if loginReq.GetJwtToken() != "" {
 		var err error
 		for i := 0; i < 3; i++ {
-			userID, err = s.validateToken(ctx, loginReq.GetJwtToken())
+			userID, err = s.validateToken(ctx, peerKey.String(), loginReq.GetJwtToken())
 			if err == nil {
 				break
 			}

management/server/account.go

@@ -400,7 +400,7 @@ func (am *DefaultAccountManager) UpdateAccountSettings(ctx context.Context, acco
 	}
 
 	if updateAccountPeers || extraSettingsChanged || groupChangesAffectPeers {
-		go am.UpdateAccountPeers(ctx, accountID)
+		go am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceAccountSettings, Operation: types.UpdateOperationUpdate})
 	}
 
 	return newSettings, nil
@@ -1581,7 +1581,7 @@ func (am *DefaultAccountManager) SyncUserJWTGroups(ctx context.Context, userAuth
 
 	if removedGroupAffectsPeers || newGroupsAffectsPeers {
 		log.WithContext(ctx).Tracef("user %s: JWT group membership changed, updating account peers", userAuth.UserId)
-		am.BufferUpdateAccountPeers(ctx, userAuth.AccountId)
+		am.BufferUpdateAccountPeers(ctx, userAuth.AccountId, types.UpdateReason{Resource: types.UpdateResourceUser, Operation: types.UpdateOperationUpdate})
 	}
 
 	return nil

management/server/account/manager.go

@@ -124,8 +124,8 @@ type Manager interface {
 	GetAccountIDForPeerKey(ctx context.Context, peerKey string) (string, error)
 	GetAccountSettings(ctx context.Context, accountID string, userID string) (*types.Settings, error)
 	DeleteSetupKey(ctx context.Context, accountID, userID, keyID string) error
-	UpdateAccountPeers(ctx context.Context, accountID string)
-	BufferUpdateAccountPeers(ctx context.Context, accountID string)
+	UpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason)
+	BufferUpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason)
 	BuildUserInfosForAccount(ctx context.Context, accountID, initiatorUserID string, accountUsers []*types.User) (map[string]*types.UserInfo, error)
 	SyncUserJWTGroups(ctx context.Context, userAuth auth.UserAuth) error
 	GetStore() store.Store

management/server/account/manager_mock.go

@@ -111,15 +111,15 @@ func (mr *MockManagerMockRecorder) ApproveUser(ctx, accountID, initiatorUserID,
 }
 
 // BufferUpdateAccountPeers mocks base method.
-func (m *MockManager) BufferUpdateAccountPeers(ctx context.Context, accountID string) {
+func (m *MockManager) BufferUpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) {
 	m.ctrl.T.Helper()
-	m.ctrl.Call(m, "BufferUpdateAccountPeers", ctx, accountID)
+	m.ctrl.Call(m, "BufferUpdateAccountPeers", ctx, accountID, reason)
 }
 
 // BufferUpdateAccountPeers indicates an expected call of BufferUpdateAccountPeers.
-func (mr *MockManagerMockRecorder) BufferUpdateAccountPeers(ctx, accountID interface{}) *gomock.Call {
+func (mr *MockManagerMockRecorder) BufferUpdateAccountPeers(ctx, accountID, reason interface{}) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
-	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "BufferUpdateAccountPeers", reflect.TypeOf((*MockManager)(nil).BufferUpdateAccountPeers), ctx, accountID)
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "BufferUpdateAccountPeers", reflect.TypeOf((*MockManager)(nil).BufferUpdateAccountPeers), ctx, accountID, reason)
 }
 
 // BuildUserInfosForAccount mocks base method.
@@ -1597,15 +1597,15 @@ func (mr *MockManagerMockRecorder) UpdateAccountOnboarding(ctx, accountID, userI
 }
 
 // UpdateAccountPeers mocks base method.
-func (m *MockManager) UpdateAccountPeers(ctx context.Context, accountID string) {
+func (m *MockManager) UpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) {
 	m.ctrl.T.Helper()
-	m.ctrl.Call(m, "UpdateAccountPeers", ctx, accountID)
+	m.ctrl.Call(m, "UpdateAccountPeers", ctx, accountID, reason)
 }
 
 // UpdateAccountPeers indicates an expected call of UpdateAccountPeers.
-func (mr *MockManagerMockRecorder) UpdateAccountPeers(ctx, accountID interface{}) *gomock.Call {
+func (mr *MockManagerMockRecorder) UpdateAccountPeers(ctx, accountID, reason interface{}) *gomock.Call {
 	mr.mock.ctrl.T.Helper()
-	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "UpdateAccountPeers", reflect.TypeOf((*MockManager)(nil).UpdateAccountPeers), ctx, accountID)
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "UpdateAccountPeers", reflect.TypeOf((*MockManager)(nil).UpdateAccountPeers), ctx, accountID, reason)
 }
 
 // UpdateAccountSettings mocks base method.

management/server/account/pat.go

@@ -0,0 +1,8 @@
+package account
+
+const (
+	// PATMinExpireDays is the minimum allowed Personal Access Token expiration in days.
+	PATMinExpireDays = 1
+	// PATMaxExpireDays is the maximum allowed Personal Access Token expiration in days.
+	PATMaxExpireDays = 365
+)

management/server/auth/session.go

@@ -0,0 +1,61 @@
+package auth
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/eko/gocache/lib/v4/cache"
+	"github.com/eko/gocache/lib/v4/store"
+)
+
+const (
+	usedTokenKeyPrefix = "jwt-used:"
+	usedTokenMarker    = "1"
+)
+
+var (
+	ErrTokenAlreadyUsed = errors.New("JWT already used")
+	ErrTokenExpired     = errors.New("JWT expired")
+)
+
+type SessionStore struct {
+	cache *cache.Cache[string]
+}
+
+func NewSessionStore(cacheStore store.StoreInterface) *SessionStore {
+	return &SessionStore{cache: cache.New[string](cacheStore)}
+}
+
+// RegisterToken records a JWT until its exp time and rejects reuse.
+func (s *SessionStore) RegisterToken(ctx context.Context, token string, expiresAt time.Time) error {
+	ttl := time.Until(expiresAt)
+	if ttl <= 0 {
+		return ErrTokenExpired
+	}
+
+	key := usedTokenKeyPrefix + hashToken(token)
+	_, err := s.cache.Get(ctx, key)
+	if err == nil {
+		return ErrTokenAlreadyUsed
+	}
+
+	var notFound *store.NotFound
+	if !errors.As(err, &notFound) {
+		return fmt.Errorf("failed to lookup used token entry: %w", err)
+	}
+
+	if err := s.cache.Set(ctx, key, usedTokenMarker, store.WithExpiration(ttl)); err != nil {
+		return fmt.Errorf("failed to store used token entry: %w", err)
+	}
+
+	return nil
+}
+
+func hashToken(token string) string {
+	sum := sha256.Sum256([]byte(token))
+	return hex.EncodeToString(sum[:])
+}

management/server/auth/session_test.go

@@ -0,0 +1,82 @@
+package auth
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	nbcache "github.com/netbirdio/netbird/management/server/cache"
+)
+
+func newTestSessionStore(t *testing.T) *SessionStore {
+	t.Helper()
+	cacheStore, err := nbcache.NewStore(context.Background(), time.Hour, time.Hour, 100)
+	require.NoError(t, err)
+	return NewSessionStore(cacheStore)
+}
+
+func TestSessionStore_FirstRegisterSucceeds(t *testing.T) {
+	s := newTestSessionStore(t)
+	ctx := context.Background()
+
+	require.NoError(t, s.RegisterToken(ctx, "token", time.Now().Add(time.Hour)))
+}
+
+func TestSessionStore_RegisterSameTokenTwiceIsRejected(t *testing.T) {
+	s := newTestSessionStore(t)
+	ctx := context.Background()
+	token := "token"
+	exp := time.Now().Add(time.Hour)
+
+	require.NoError(t, s.RegisterToken(ctx, token, exp))
+
+	err := s.RegisterToken(ctx, token, exp)
+	require.Error(t, err)
+	assert.ErrorIs(t, err, ErrTokenAlreadyUsed)
+}
+
+func TestSessionStore_RegisterDifferentTokensAreIndependent(t *testing.T) {
+	s := newTestSessionStore(t)
+	ctx := context.Background()
+	exp := time.Now().Add(time.Hour)
+
+	require.NoError(t, s.RegisterToken(ctx, "tokenA", exp))
+	require.NoError(t, s.RegisterToken(ctx, "tokenB", exp))
+}
+
+func TestSessionStore_RegisterWithPastExpiryIsRejected(t *testing.T) {
+	s := newTestSessionStore(t)
+	ctx := context.Background()
+	token := "token"
+
+	err := s.RegisterToken(ctx, token, time.Now().Add(-time.Second))
+	require.Error(t, err)
+	assert.ErrorIs(t, err, ErrTokenExpired)
+}
+
+func TestSessionStore_EntryEvictsAtTTLAndAllowsReRegistration(t *testing.T) {
+	s := newTestSessionStore(t)
+	ctx := context.Background()
+	token := "token"
+
+	require.NoError(t, s.RegisterToken(ctx, token, time.Now().Add(50*time.Millisecond)))
+
+	err := s.RegisterToken(ctx, token, time.Now().Add(50*time.Millisecond))
+	assert.ErrorIs(t, err, ErrTokenAlreadyUsed)
+
+	time.Sleep(120 * time.Millisecond)
+
+	require.NoError(t, s.RegisterToken(ctx, token, time.Now().Add(time.Hour)))
+}
+
+func TestHashToken_StableAndDoesNotLeak(t *testing.T) {
+	a := hashToken("tokenA")
+	b := hashToken("tokenB")
+	assert.Equal(t, a, hashToken("tokenA"), "hash must be deterministic")
+	assert.NotEqual(t, a, b, "different tokens must hash differently")
+	assert.Len(t, a, 64, "sha256 hex must be 64 chars")
+	assert.NotContains(t, a, "tokenA", "raw token must not appear in hash")
+}

management/server/dns.go

@@ -86,7 +86,7 @@ func (am *DefaultAccountManager) SaveDNSSettings(ctx context.Context, accountID
 	}
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceDNSSettings, Operation: types.UpdateOperationUpdate})
 	}
 
 	return nil

management/server/group.go

@@ -117,7 +117,7 @@ func (am *DefaultAccountManager) CreateGroup(ctx context.Context, accountID, use
 	}
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceGroup, Operation: types.UpdateOperationCreate})
 	}
 
 	return nil
@@ -185,7 +185,7 @@ func (am *DefaultAccountManager) UpdateGroup(ctx context.Context, accountID, use
 	}
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceGroup, Operation: types.UpdateOperationUpdate})
 	}
 
 	return nil
@@ -253,7 +253,7 @@ func (am *DefaultAccountManager) CreateGroups(ctx context.Context, accountID, us
 	}
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceGroup, Operation: types.UpdateOperationCreate})
 	}
 
 	return globalErr
@@ -321,7 +321,7 @@ func (am *DefaultAccountManager) UpdateGroups(ctx context.Context, accountID, us
 	}
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceGroup, Operation: types.UpdateOperationUpdate})
 	}
 
 	return globalErr
@@ -493,7 +493,7 @@ func (am *DefaultAccountManager) GroupAddPeer(ctx context.Context, accountID, gr
 	}
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceGroup, Operation: types.UpdateOperationUpdate})
 	}
 
 	return nil
@@ -531,7 +531,7 @@ func (am *DefaultAccountManager) GroupAddResource(ctx context.Context, accountID
 	}
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceGroup, Operation: types.UpdateOperationUpdate})
 	}
 
 	return nil
@@ -559,7 +559,7 @@ func (am *DefaultAccountManager) GroupDeletePeer(ctx context.Context, accountID,
 	}
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceGroup, Operation: types.UpdateOperationUpdate})
 	}
 
 	return nil
@@ -597,7 +597,7 @@ func (am *DefaultAccountManager) GroupDeleteResource(ctx context.Context, accoun
 	}
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceGroup, Operation: types.UpdateOperationUpdate})
 	}
 
 	return nil

management/server/http/handler.go

@@ -62,9 +62,7 @@ import (
 	"github.com/netbirdio/netbird/management/server/telemetry"
 )
 
-const (
-	apiPrefix = "/api"
-)
+const apiPrefix = "/api"
 
 // NewAPIHandler creates the Management service HTTP API handler registering all the available endpoints.
 func NewAPIHandler(ctx context.Context, accountManager account.Manager, networksManager nbnetworks.Manager, resourceManager resources.Manager, routerManager routers.Manager, groupsManager nbgroups.Manager, LocationManager geolocation.Geolocation, authManager auth.Manager, appMetrics telemetry.AppMetrics, integratedValidator integrated_validator.IntegratedValidator, proxyController port_forwarding.Controller, permissionsManager permissions.Manager, peersManager nbpeers.Manager, settingsManager settings.Manager, zManager zones.Manager, rManager records.Manager, networkMapController network_map.Controller, idpManager idpmanager.Manager, serviceManager service.Manager, reverseProxyDomainManager *manager.Manager, reverseProxyAccessLogsManager accesslogs.Manager, proxyGRPCServer *nbgrpc.ProxyServiceServer, trustedHTTPProxies []netip.Prefix, rateLimiter *middleware.APIRateLimiter) (http.Handler, error) {
@@ -141,7 +139,7 @@ func NewAPIHandler(ctx context.Context, accountManager account.Manager, networks
 	zonesManager.RegisterEndpoints(router, zManager)
 	recordsManager.RegisterEndpoints(router, rManager)
 	idp.AddEndpoints(accountManager, router)
-	instance.AddEndpoints(instanceManager, router)
+	instance.AddEndpoints(instanceManager, accountManager, router)
 	instance.AddVersionEndpoint(instanceManager, router)
 	if serviceManager != nil && reverseProxyDomainManager != nil {
 		reverseproxymanager.RegisterEndpoints(serviceManager, *reverseProxyDomainManager, reverseProxyAccessLogsManager, permissionsManager, router)

management/server/http/handlers/instance/instance_handler.go

@@ -7,6 +7,7 @@ import (
 	"github.com/gorilla/mux"
 	log "github.com/sirupsen/logrus"
 
+	"github.com/netbirdio/netbird/management/server/account"
 	nbinstance "github.com/netbirdio/netbird/management/server/instance"
 	"github.com/netbirdio/netbird/shared/management/http/api"
 	"github.com/netbirdio/netbird/shared/management/http/util"
@@ -15,13 +16,15 @@ import (
 // handler handles the instance setup HTTP endpoints
 type handler struct {
 	instanceManager nbinstance.Manager
+	setupManager    *nbinstance.SetupService
 }
 
 // AddEndpoints registers the instance setup endpoints.
 // These endpoints bypass authentication for initial setup.
-func AddEndpoints(instanceManager nbinstance.Manager, router *mux.Router) {
+func AddEndpoints(instanceManager nbinstance.Manager, accountManager account.Manager, router *mux.Router) {
 	h := &handler{
 		instanceManager: instanceManager,
+		setupManager:    nbinstance.NewSetupService(instanceManager, accountManager),
 	}
 
 	router.HandleFunc("/instance", h.getInstanceStatus).Methods("GET", "OPTIONS")
@@ -55,24 +58,36 @@ func (h *handler) getInstanceStatus(w http.ResponseWriter, r *http.Request) {
 // setup creates the initial admin user for the instance.
 // This endpoint is unauthenticated but only works when setup is required.
 func (h *handler) setup(w http.ResponseWriter, r *http.Request) {
+	ctx := r.Context()
+
 	var req api.SetupRequest
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 		util.WriteErrorResponse("invalid request body", http.StatusBadRequest, w)
 		return
 	}
 
-	userData, err := h.instanceManager.CreateOwnerUser(r.Context(), req.Email, req.Password, req.Name)
+	result, err := h.setupManager.SetupOwner(ctx, req.Email, req.Password, req.Name, nbinstance.SetupOptions{
+		CreatePAT:       req.CreatePat != nil && *req.CreatePat,
+		PATExpireInDays: req.PatExpireIn,
+	})
 	if err != nil {
-		util.WriteError(r.Context(), err, w)
+		util.WriteError(ctx, err, w)
 		return
 	}
 
-	log.WithContext(r.Context()).Infof("instance setup completed: created user %s", req.Email)
+	log.WithContext(ctx).Infof("instance setup completed: created user %s", req.Email)
 
-	util.WriteJSONObject(r.Context(), w, api.SetupResponse{
-		UserId: userData.ID,
-		Email:  userData.Email,
-	})
+	resp := api.SetupResponse{
+		UserId: result.User.ID,
+		Email:  result.User.Email,
+	}
+
+	if result.PATPlainToken != "" {
+		resp.PersonalAccessToken = &result.PATPlainToken
+	}
+
+	w.Header().Set("Cache-Control", "no-store")
+	util.WriteJSONObject(ctx, w, resp)
 }
 
 // getVersionInfo returns version information for NetBird components.

management/server/http/handlers/instance/instance_handler_test.go

@@ -10,12 +10,18 @@ import (
 	"net/mail"
 	"testing"
 
+	"github.com/golang/mock/gomock"
 	"github.com/gorilla/mux"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
+	"github.com/netbirdio/netbird/management/server/account"
 	"github.com/netbirdio/netbird/management/server/idp"
 	nbinstance "github.com/netbirdio/netbird/management/server/instance"
+	"github.com/netbirdio/netbird/management/server/mock_server"
+	nbstore "github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
+	"github.com/netbirdio/netbird/shared/auth"
 	"github.com/netbirdio/netbird/shared/management/http/api"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
@@ -25,6 +31,7 @@ type mockInstanceManager struct {
 	isSetupRequired   bool
 	isSetupRequiredFn func(ctx context.Context) (bool, error)
 	createOwnerUserFn func(ctx context.Context, email, password, name string) (*idp.UserData, error)
+	rollbackSetupFn   func(ctx context.Context, userID string) error
 	getVersionInfoFn  func(ctx context.Context) (*nbinstance.VersionInfo, error)
 }
 
@@ -67,6 +74,13 @@ func (m *mockInstanceManager) CreateOwnerUser(ctx context.Context, email, passwo
 	}, nil
 }
 
+func (m *mockInstanceManager) RollbackSetup(ctx context.Context, userID string) error {
+	if m.rollbackSetupFn != nil {
+		return m.rollbackSetupFn(ctx, userID)
+	}
+	return nil
+}
+
 func (m *mockInstanceManager) GetVersionInfo(ctx context.Context) (*nbinstance.VersionInfo, error) {
 	if m.getVersionInfoFn != nil {
 		return m.getVersionInfoFn(ctx)
@@ -82,8 +96,12 @@ func (m *mockInstanceManager) GetVersionInfo(ctx context.Context) (*nbinstance.V
 var _ nbinstance.Manager = (*mockInstanceManager)(nil)
 
 func setupTestRouter(manager nbinstance.Manager) *mux.Router {
+	return setupTestRouterWithPAT(manager, nil)
+}
+
+func setupTestRouterWithPAT(manager nbinstance.Manager, accountManager account.Manager) *mux.Router {
 	router := mux.NewRouter()
-	AddEndpoints(manager, router)
+	AddEndpoints(manager, accountManager, router)
 	return router
 }
 
@@ -161,6 +179,7 @@ func TestSetup_Success(t *testing.T) {
 	router.ServeHTTP(rec, req)
 
 	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, "no-store", rec.Header().Get("Cache-Control"))
 
 	var response api.SetupResponse
 	err := json.NewDecoder(rec.Body).Decode(&response)
@@ -293,6 +312,239 @@ func TestSetup_ManagerError(t *testing.T) {
 	assert.Equal(t, http.StatusInternalServerError, rec.Code)
 }
 
+func TestSetup_PAT_FeatureDisabled_IgnoresCreatePAT(t *testing.T) {
+	t.Setenv(nbinstance.SetupPATEnabledEnvKey, "false")
+
+	manager := &mockInstanceManager{isSetupRequired: true}
+	// NB_SETUP_PAT_ENABLED=false: request fields must be silently ignored
+	router := setupTestRouterWithPAT(manager, &mock_server.MockAccountManager{})
+
+	body := `{"email": "admin@example.com", "password": "securepassword123", "name": "Admin", "create_pat": true}`
+	req := httptest.NewRequest(http.MethodPost, "/setup", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+
+	router.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	var response api.SetupResponse
+	require.NoError(t, json.NewDecoder(rec.Body).Decode(&response))
+	assert.Nil(t, response.PersonalAccessToken)
+}
+
+func TestSetup_PAT_FlagOmitted_NoPAT(t *testing.T) {
+	t.Setenv(nbinstance.SetupPATEnabledEnvKey, "true")
+
+	manager := &mockInstanceManager{isSetupRequired: true}
+	router := setupTestRouterWithPAT(manager, &mock_server.MockAccountManager{})
+
+	body := `{"email": "admin@example.com", "password": "securepassword123", "name": "Admin"}`
+	req := httptest.NewRequest(http.MethodPost, "/setup", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+
+	router.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	var response api.SetupResponse
+	require.NoError(t, json.NewDecoder(rec.Body).Decode(&response))
+	assert.Nil(t, response.PersonalAccessToken)
+}
+
+func TestSetup_PAT_MissingExpireIn_DefaultsToOneDay(t *testing.T) {
+	t.Setenv(nbinstance.SetupPATEnabledEnvKey, "true")
+
+	createCalled := false
+	manager := &mockInstanceManager{
+		isSetupRequired: true,
+		createOwnerUserFn: func(ctx context.Context, email, password, name string) (*idp.UserData, error) {
+			createCalled = true
+			return &idp.UserData{ID: "u1", Email: email, Name: name}, nil
+		},
+	}
+	accountMgr := &mock_server.MockAccountManager{
+		GetAccountIDByUserIdFunc: func(_ context.Context, userAuth auth.UserAuth) (string, error) {
+			assert.Equal(t, "u1", userAuth.UserId)
+			return "acc-1", nil
+		},
+		CreatePATFunc: func(_ context.Context, accountID, initiator, target, name string, expiresIn int) (*types.PersonalAccessTokenGenerated, error) {
+			assert.Equal(t, "acc-1", accountID)
+			assert.Equal(t, "u1", initiator)
+			assert.Equal(t, "u1", target)
+			assert.Equal(t, "setup-token", name)
+			assert.Equal(t, 1, expiresIn)
+			return &types.PersonalAccessTokenGenerated{PlainToken: "nbp_plain"}, nil
+		},
+	}
+	router := setupTestRouterWithPAT(manager, accountMgr)
+
+	body := `{"email": "admin@example.com", "password": "securepassword123", "name": "Admin", "create_pat": true}`
+	req := httptest.NewRequest(http.MethodPost, "/setup", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+
+	router.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, "no-store", rec.Header().Get("Cache-Control"))
+	assert.True(t, createCalled)
+	var response api.SetupResponse
+	require.NoError(t, json.NewDecoder(rec.Body).Decode(&response))
+	require.NotNil(t, response.PersonalAccessToken)
+	assert.Equal(t, "nbp_plain", *response.PersonalAccessToken)
+}
+
+func TestSetup_PAT_ExpireOutOfRange(t *testing.T) {
+	t.Setenv(nbinstance.SetupPATEnabledEnvKey, "true")
+
+	manager := &mockInstanceManager{isSetupRequired: true}
+	router := setupTestRouterWithPAT(manager, &mock_server.MockAccountManager{})
+
+	body := `{"email": "admin@example.com", "password": "securepassword123", "name": "Admin", "create_pat": true, "pat_expire_in": 0}`
+	req := httptest.NewRequest(http.MethodPost, "/setup", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+
+	router.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code)
+}
+
+func TestSetup_PAT_Success(t *testing.T) {
+	t.Setenv(nbinstance.SetupPATEnabledEnvKey, "true")
+
+	manager := &mockInstanceManager{
+		isSetupRequired: true,
+		createOwnerUserFn: func(ctx context.Context, email, password, name string) (*idp.UserData, error) {
+			return &idp.UserData{ID: "owner-id", Email: email, Name: name}, nil
+		},
+	}
+
+	gotAccountArgs := struct {
+		userID string
+		email  string
+	}{}
+	accountMgr := &mock_server.MockAccountManager{
+		GetAccountIDByUserIdFunc: func(_ context.Context, userAuth auth.UserAuth) (string, error) {
+			gotAccountArgs.userID = userAuth.UserId
+			gotAccountArgs.email = userAuth.Email
+			return "acc-1", nil
+		},
+		CreatePATFunc: func(_ context.Context, accountID, initiator, target, name string, expiresIn int) (*types.PersonalAccessTokenGenerated, error) {
+			assert.Equal(t, "acc-1", accountID)
+			assert.Equal(t, "owner-id", initiator)
+			assert.Equal(t, "owner-id", target)
+			assert.Equal(t, "setup-token", name)
+			assert.Equal(t, 30, expiresIn)
+			return &types.PersonalAccessTokenGenerated{PlainToken: "nbp_plain"}, nil
+		},
+	}
+
+	router := setupTestRouterWithPAT(manager, accountMgr)
+
+	body := `{"email": "admin@example.com", "password": "securepassword123", "name": "Admin", "create_pat": true, "pat_expire_in": 30}`
+	req := httptest.NewRequest(http.MethodPost, "/setup", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+
+	router.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, "no-store", rec.Header().Get("Cache-Control"))
+	var response api.SetupResponse
+	require.NoError(t, json.NewDecoder(rec.Body).Decode(&response))
+	assert.Equal(t, "owner-id", response.UserId)
+	require.NotNil(t, response.PersonalAccessToken)
+	assert.Equal(t, "nbp_plain", *response.PersonalAccessToken)
+	assert.Equal(t, "owner-id", gotAccountArgs.userID)
+	assert.Equal(t, "admin@example.com", gotAccountArgs.email)
+}
+
+func TestSetup_PAT_AccountCreationFails_Rollback(t *testing.T) {
+	t.Setenv(nbinstance.SetupPATEnabledEnvKey, "true")
+
+	ctrl := gomock.NewController(t)
+	accountStore := nbstore.NewMockStore(ctrl)
+	accountStore.EXPECT().GetAccountIDByUserID(gomock.Any(), nbstore.LockingStrengthNone, "owner-id").Return("", status.NewAccountNotFoundError("owner-id"))
+
+	rolledBackFor := ""
+	manager := &mockInstanceManager{
+		isSetupRequired: true,
+		createOwnerUserFn: func(ctx context.Context, email, password, name string) (*idp.UserData, error) {
+			return &idp.UserData{ID: "owner-id", Email: email, Name: name}, nil
+		},
+		rollbackSetupFn: func(_ context.Context, userID string) error {
+			rolledBackFor = userID
+			return nil
+		},
+	}
+	accountMgr := &mock_server.MockAccountManager{
+		GetAccountIDByUserIdFunc: func(_ context.Context, _ auth.UserAuth) (string, error) {
+			return "", errors.New("db down")
+		},
+		GetStoreFunc: func() nbstore.Store {
+			return accountStore
+		},
+	}
+
+	router := setupTestRouterWithPAT(manager, accountMgr)
+
+	body := `{"email": "admin@example.com", "password": "securepassword123", "name": "Admin", "create_pat": true, "pat_expire_in": 30}`
+	req := httptest.NewRequest(http.MethodPost, "/setup", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+
+	router.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusInternalServerError, rec.Code)
+	assert.Equal(t, "owner-id", rolledBackFor, "RollbackSetup must be called with the created user id")
+}
+
+func TestSetup_PAT_CreatePATFails_Rollback(t *testing.T) {
+	t.Setenv(nbinstance.SetupPATEnabledEnvKey, "true")
+
+	ctrl := gomock.NewController(t)
+	accountStore := nbstore.NewMockStore(ctrl)
+	account := &types.Account{Id: "acc-1"}
+	accountStore.EXPECT().GetAccount(gomock.Any(), "acc-1").Return(account, nil)
+	accountStore.EXPECT().DeleteAccount(gomock.Any(), account).Return(nil)
+
+	rolledBackFor := ""
+	manager := &mockInstanceManager{
+		isSetupRequired: true,
+		createOwnerUserFn: func(ctx context.Context, email, password, name string) (*idp.UserData, error) {
+			return &idp.UserData{ID: "owner-id", Email: email, Name: name}, nil
+		},
+		rollbackSetupFn: func(_ context.Context, userID string) error {
+			rolledBackFor = userID
+			return nil
+		},
+	}
+	accountMgr := &mock_server.MockAccountManager{
+		GetAccountIDByUserIdFunc: func(_ context.Context, _ auth.UserAuth) (string, error) {
+			return "acc-1", nil
+		},
+		CreatePATFunc: func(_ context.Context, _, _, _, _ string, _ int) (*types.PersonalAccessTokenGenerated, error) {
+			return nil, status.Errorf(status.Internal, "token store unavailable")
+		},
+		GetStoreFunc: func() nbstore.Store {
+			return accountStore
+		},
+	}
+
+	router := setupTestRouterWithPAT(manager, accountMgr)
+
+	body := `{"email": "admin@example.com", "password": "securepassword123", "name": "Admin", "create_pat": true, "pat_expire_in": 30}`
+	req := httptest.NewRequest(http.MethodPost, "/setup", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+
+	router.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusInternalServerError, rec.Code)
+	assert.Equal(t, "owner-id", rolledBackFor, "RollbackSetup must be called when CreatePAT fails")
+}
+
 func TestGetVersionInfo_Success(t *testing.T) {
 	manager := &mockInstanceManager{}
 	router := mux.NewRouter()

management/server/instance/manager.go

@@ -12,6 +12,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/dexidp/dex/storage"
 	goversion "github.com/hashicorp/go-version"
 	log "github.com/sirupsen/logrus"
 
@@ -60,6 +61,13 @@ type Manager interface {
 	// This should only be called when IsSetupRequired returns true.
 	CreateOwnerUser(ctx context.Context, email, password, name string) (*idp.UserData, error)
 
+	// RollbackSetup reverses a successful CreateOwnerUser by deleting the user
+	// from the embedded IDP and reloading setupRequired from persistent state, so
+	// /api/setup can be retried only when no accounts or local users remain. Used
+	// when post-user steps (account or PAT creation) fail and the caller wants a
+	// clean slate.
+	RollbackSetup(ctx context.Context, userID string) error
+
 	// GetVersionInfo returns version information for NetBird components.
 	GetVersionInfo(ctx context.Context) (*VersionInfo, error)
 }
@@ -70,6 +78,7 @@ type instanceStore interface {
 
 type embeddedIdP interface {
 	CreateUserWithPassword(ctx context.Context, email, password, name string) (*idp.UserData, error)
+	DeleteUser(ctx context.Context, userID string) error
 	GetAllAccounts(ctx context.Context) (map[string][]*idp.UserData, error)
 }
 
@@ -187,6 +196,51 @@ func (m *DefaultManager) CreateOwnerUser(ctx context.Context, email, password, n
 	return userData, nil
 }
 
+// RollbackSetup undoes a successful CreateOwnerUser: deletes the user from the
+// embedded IDP and reloads setupRequired from persistent state.
+func (m *DefaultManager) RollbackSetup(ctx context.Context, userID string) error {
+	if m.embeddedIdpManager == nil {
+		return errors.New("embedded IDP is not enabled")
+	}
+
+	var deleteErr error
+	if err := m.embeddedIdpManager.DeleteUser(ctx, userID); err != nil {
+		if isNotFoundError(err) {
+			log.WithContext(ctx).Debugf("setup rollback user %s already deleted", userID)
+		} else {
+			deleteErr = fmt.Errorf("failed to delete user from embedded IdP: %w", err)
+		}
+	}
+
+	if err := m.loadSetupRequired(ctx); err != nil {
+		reloadErr := fmt.Errorf("failed to reload setup state after rollback: %w", err)
+		if deleteErr != nil {
+			return errors.Join(deleteErr, reloadErr)
+		}
+		return reloadErr
+	}
+
+	if deleteErr != nil {
+		return deleteErr
+	}
+
+	log.WithContext(ctx).Infof("rolled back setup for user %s", userID)
+	return nil
+}
+
+func isNotFoundError(err error) bool {
+	if err == nil {
+		return false
+	}
+	if errors.Is(err, storage.ErrNotFound) {
+		return true
+	}
+	if s, ok := status.FromError(err); ok {
+		return s.Type() == status.NotFound
+	}
+	return false
+}
+
 func (m *DefaultManager) checkSetupRequiredFromDB(ctx context.Context) error {
 	numAccounts, err := m.store.GetAccountsCounter(ctx)
 	if err != nil {

management/server/instance/manager_test.go

@@ -10,16 +10,19 @@ import (
 	"testing"
 	"time"
 
+	"github.com/dexidp/dex/storage"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"github.com/netbirdio/netbird/management/server/idp"
+	"github.com/netbirdio/netbird/shared/management/status"
 )
 
 type mockIdP struct {
-	mu              sync.Mutex
-	createUserFunc  func(ctx context.Context, email, password, name string) (*idp.UserData, error)
-	users           map[string][]*idp.UserData
+	mu                sync.Mutex
+	createUserFunc    func(ctx context.Context, email, password, name string) (*idp.UserData, error)
+	deleteUserFunc    func(ctx context.Context, userID string) error
+	users             map[string][]*idp.UserData
 	getAllAccountsErr error
 }
 
@@ -30,6 +33,13 @@ func (m *mockIdP) CreateUserWithPassword(ctx context.Context, email, password, n
 	return &idp.UserData{ID: "test-user-id", Email: email, Name: name}, nil
 }
 
+func (m *mockIdP) DeleteUser(ctx context.Context, userID string) error {
+	if m.deleteUserFunc != nil {
+		return m.deleteUserFunc(ctx, userID)
+	}
+	return nil
+}
+
 func (m *mockIdP) GetAllAccounts(_ context.Context) (map[string][]*idp.UserData, error) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -223,6 +233,77 @@ func TestIsSetupRequired_ReturnsFlag(t *testing.T) {
 	assert.False(t, required)
 }
 
+func TestRollbackSetup_UserAlreadyDeletedIsSuccess(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+	}{
+		{
+			name: "management status not found",
+			err:  status.NewUserNotFoundError("owner-id"),
+		},
+		{
+			name: "dex storage not found",
+			err:  fmt.Errorf("failed to get user for deletion: %w", storage.ErrNotFound),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			idpMock := &mockIdP{
+				deleteUserFunc: func(_ context.Context, userID string) error {
+					assert.Equal(t, "owner-id", userID)
+					return tt.err
+				},
+			}
+			mgr := newTestManager(idpMock, &mockStore{})
+			mgr.setupRequired = false
+
+			err := mgr.RollbackSetup(context.Background(), "owner-id")
+			require.NoError(t, err)
+
+			required, err := mgr.IsSetupRequired(context.Background())
+			require.NoError(t, err)
+			assert.True(t, required, "setup should be required when no accounts or local users remain")
+		})
+	}
+}
+
+func TestRollbackSetup_RecomputesSetupStateWhenAccountStillExists(t *testing.T) {
+	idpMock := &mockIdP{
+		deleteUserFunc: func(_ context.Context, _ string) error {
+			return status.NewUserNotFoundError("owner-id")
+		},
+	}
+	mgr := newTestManager(idpMock, &mockStore{accountsCount: 1})
+	mgr.setupRequired = true
+
+	err := mgr.RollbackSetup(context.Background(), "owner-id")
+	require.NoError(t, err)
+
+	required, err := mgr.IsSetupRequired(context.Background())
+	require.NoError(t, err)
+	assert.False(t, required, "setup should not be required while an account still exists")
+}
+
+func TestRollbackSetup_ReturnsDeleteErrorButReloadsSetupState(t *testing.T) {
+	idpMock := &mockIdP{
+		deleteUserFunc: func(_ context.Context, _ string) error {
+			return errors.New("idp unavailable")
+		},
+	}
+	mgr := newTestManager(idpMock, &mockStore{})
+	mgr.setupRequired = false
+
+	err := mgr.RollbackSetup(context.Background(), "owner-id")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "idp unavailable")
+
+	required, err := mgr.IsSetupRequired(context.Background())
+	require.NoError(t, err)
+	assert.True(t, required, "setup state should be reloaded even when user deletion fails")
+}
+
 func TestDefaultManager_ValidateSetupRequest(t *testing.T) {
 	manager := &DefaultManager{setupRequired: true}
 

management/server/instance/setup_service.go

@@ -0,0 +1,216 @@
+package instance
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	log "github.com/sirupsen/logrus"
+
+	"github.com/netbirdio/netbird/management/server/account"
+	"github.com/netbirdio/netbird/management/server/idp"
+	"github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/shared/auth"
+	"github.com/netbirdio/netbird/shared/management/status"
+)
+
+const (
+	setupPATTokenName = "setup-token"
+
+	// SetupPATEnabledEnvKey enables setup-time Personal Access Token creation.
+	SetupPATEnabledEnvKey = "NB_SETUP_PAT_ENABLED"
+
+	setupPATDefaultExpireDays = 1
+)
+
+// SetupOptions controls optional work performed during initial instance setup.
+type SetupOptions struct {
+	// CreatePAT requests creation of a setup Personal Access Token. It is honored
+	// only when SetupPATEnabledEnvKey is set to "true".
+	CreatePAT bool
+	// PATExpireInDays defaults to 1 day when CreatePAT is requested and setup PAT
+	// creation is enabled.
+	PATExpireInDays *int
+}
+
+// SetupResult contains resources created during initial instance setup.
+type SetupResult struct {
+	User          *idp.UserData
+	PATPlainToken string
+}
+
+// SetupService orchestrates the initial setup use case across the instance and
+// account bounded contexts and owns the compensation logic when a later step
+// fails.
+type SetupService struct {
+	instanceManager Manager
+	accountManager  account.Manager
+	setupPATEnabled bool
+}
+
+// NewSetupService creates a setup use-case service.
+func NewSetupService(instanceManager Manager, accountManager account.Manager) *SetupService {
+	return &SetupService{
+		instanceManager: instanceManager,
+		accountManager:  accountManager,
+		setupPATEnabled: os.Getenv(SetupPATEnabledEnvKey) == "true",
+	}
+}
+
+func normalizeSetupOptions(opts SetupOptions, setupPATEnabled bool) (SetupOptions, error) {
+	if !opts.CreatePAT {
+		return opts, nil
+	}
+
+	if !setupPATEnabled {
+		opts.CreatePAT = false
+		opts.PATExpireInDays = nil
+		return opts, nil
+	}
+
+	if opts.PATExpireInDays == nil {
+		defaultExpireInDays := setupPATDefaultExpireDays
+		opts.PATExpireInDays = &defaultExpireInDays
+	}
+
+	if *opts.PATExpireInDays < account.PATMinExpireDays || *opts.PATExpireInDays > account.PATMaxExpireDays {
+		return opts, status.Errorf(status.InvalidArgument, "pat_expire_in must be between %d and %d", account.PATMinExpireDays, account.PATMaxExpireDays)
+	}
+
+	return opts, nil
+}
+
+// SetupOwner creates the initial owner user and, when requested and enabled by
+// SetupPATEnabledEnvKey, provisions the account and a setup Personal Access
+// Token. If account or PAT provisioning fails, created resources are rolled
+// back so setup can be retried. If account rollback fails, user rollback is
+// skipped to avoid leaving an account without its owner user.
+func (m *SetupService) SetupOwner(ctx context.Context, email, password, name string, opts SetupOptions) (*SetupResult, error) {
+	opts, err := normalizeSetupOptions(opts, m.setupPATEnabled)
+	if err != nil {
+		return nil, err
+	}
+
+	if opts.CreatePAT && m.accountManager == nil {
+		return nil, fmt.Errorf("account manager is required to create setup PAT")
+	}
+
+	userData, err := m.instanceManager.CreateOwnerUser(ctx, email, password, name)
+	if err != nil {
+		return nil, err
+	}
+
+	result := &SetupResult{User: userData}
+	if !opts.CreatePAT {
+		return result, nil
+	}
+
+	userAuth := auth.UserAuth{
+		UserId: userData.ID,
+		Email:  userData.Email,
+		Name:   userData.Name,
+	}
+
+	accountID, err := m.accountManager.GetAccountIDByUserID(ctx, userAuth)
+	if err != nil {
+		err = fmt.Errorf("create account for setup user: %w", err)
+		if rollbackErr := m.rollbackSetup(ctx, userData.ID, "account provisioning failed", err, ""); rollbackErr != nil {
+			return nil, fmt.Errorf("%w; failed to roll back setup resources: %v", err, rollbackErr)
+		}
+		return nil, err
+	}
+
+	pat, err := m.accountManager.CreatePAT(ctx, accountID, userData.ID, userData.ID, setupPATTokenName, *opts.PATExpireInDays)
+	if err != nil {
+		err = fmt.Errorf("create setup PAT: %w", err)
+		if rollbackErr := m.rollbackSetup(ctx, userData.ID, "setup PAT provisioning failed", err, accountID); rollbackErr != nil {
+			return nil, fmt.Errorf("%w; failed to roll back setup resources: %v", err, rollbackErr)
+		}
+		return nil, err
+	}
+
+	result.PATPlainToken = pat.PlainToken
+	return result, nil
+}
+
+func (m *SetupService) rollbackSetup(ctx context.Context, userID, reason string, origErr error, accountID string) error {
+	if accountID == "" {
+		resolvedAccountID, err := m.lookupSetupAccountIDForRollback(ctx, userID)
+		if err != nil {
+			rollbackErr := fmt.Errorf("resolve setup account for rollback: %w", err)
+			log.WithContext(ctx).Errorf("failed to resolve setup account for user %s after %s: original error: %v, rollback error: %v", userID, reason, origErr, rollbackErr)
+			return rollbackErr
+		}
+		accountID = resolvedAccountID
+	}
+
+	if accountID != "" {
+		if err := m.rollbackSetupAccount(ctx, accountID); err != nil {
+			rollbackErr := fmt.Errorf("roll back setup account %s: %w", accountID, err)
+			log.WithContext(ctx).Errorf("failed to roll back setup account %s for user %s after %s: original error: %v, rollback error: %v", accountID, userID, reason, origErr, rollbackErr)
+			return rollbackErr
+		}
+		log.WithContext(ctx).Warnf("rolled back setup account %s for user %s after %s: %v", accountID, userID, reason, origErr)
+	}
+
+	if err := m.instanceManager.RollbackSetup(ctx, userID); err != nil {
+		rollbackErr := fmt.Errorf("roll back setup user %s: %w", userID, err)
+		log.WithContext(ctx).Errorf("failed to roll back setup user %s after %s: original error: %v, rollback error: %v", userID, reason, origErr, rollbackErr)
+		return rollbackErr
+	}
+	log.WithContext(ctx).Warnf("rolled back setup user %s after %s: %v", userID, reason, origErr)
+	return nil
+}
+
+func (m *SetupService) lookupSetupAccountIDForRollback(ctx context.Context, userID string) (string, error) {
+	if m.accountManager == nil {
+		return "", fmt.Errorf("account manager is required to resolve setup account")
+	}
+
+	accountStore := m.accountManager.GetStore()
+	if accountStore == nil {
+		return "", fmt.Errorf("account store is unavailable")
+	}
+
+	accountID, err := accountStore.GetAccountIDByUserID(ctx, store.LockingStrengthNone, userID)
+	if err != nil {
+		if isNotFoundError(err) {
+			return "", nil
+		}
+		return "", fmt.Errorf("get setup account ID for rollback: %w", err)
+	}
+
+	return accountID, nil
+}
+
+// rollbackSetupAccount removes only the setup-created account data from the
+// store. It intentionally avoids accountManager.DeleteAccount because the normal
+// account deletion path also deletes users from the IdP; embedded IdP cleanup is
+// owned by instanceManager.RollbackSetup.
+func (m *SetupService) rollbackSetupAccount(ctx context.Context, accountID string) error {
+	if m.accountManager == nil {
+		return fmt.Errorf("account manager is required to roll back setup account")
+	}
+
+	accountStore := m.accountManager.GetStore()
+	if accountStore == nil {
+		return fmt.Errorf("account store is unavailable")
+	}
+
+	account, err := accountStore.GetAccount(ctx, accountID)
+	if err != nil {
+		if isNotFoundError(err) {
+			return nil
+		}
+		return fmt.Errorf("get setup account for rollback: %w", err)
+	}
+
+	if err := accountStore.DeleteAccount(ctx, account); err != nil {
+		if isNotFoundError(err) {
+			return nil
+		}
+		return fmt.Errorf("delete setup account for rollback: %w", err)
+	}
+
+	return nil
+}

management/server/instance/setup_service_test.go

@@ -0,0 +1,318 @@
+package instance
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/golang/mock/gomock"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/management/server/idp"
+	"github.com/netbirdio/netbird/management/server/mock_server"
+	nbstore "github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
+	"github.com/netbirdio/netbird/shared/auth"
+	"github.com/netbirdio/netbird/shared/management/status"
+)
+
+type setupInstanceManagerMock struct {
+	createOwnerUserFn func(ctx context.Context, email, password, name string) (*idp.UserData, error)
+	rollbackSetupFn   func(ctx context.Context, userID string) error
+}
+
+func (m *setupInstanceManagerMock) IsSetupRequired(context.Context) (bool, error) {
+	return true, nil
+}
+
+func (m *setupInstanceManagerMock) CreateOwnerUser(ctx context.Context, email, password, name string) (*idp.UserData, error) {
+	if m.createOwnerUserFn != nil {
+		return m.createOwnerUserFn(ctx, email, password, name)
+	}
+	return &idp.UserData{ID: "owner-id", Email: email, Name: name}, nil
+}
+
+func (m *setupInstanceManagerMock) RollbackSetup(ctx context.Context, userID string) error {
+	if m.rollbackSetupFn != nil {
+		return m.rollbackSetupFn(ctx, userID)
+	}
+	return nil
+}
+
+func (m *setupInstanceManagerMock) GetVersionInfo(context.Context) (*VersionInfo, error) {
+	return &VersionInfo{}, nil
+}
+
+var _ Manager = (*setupInstanceManagerMock)(nil)
+
+func intPtr(v int) *int {
+	return &v
+}
+
+func TestSetupOwner_PATFeatureDisabled_IgnoresCreatePAT(t *testing.T) {
+	t.Setenv(SetupPATEnabledEnvKey, "false")
+
+	createCalls := 0
+	setupManager := NewSetupService(
+		&setupInstanceManagerMock{
+			createOwnerUserFn: func(_ context.Context, email, _, name string) (*idp.UserData, error) {
+				createCalls++
+				return &idp.UserData{ID: "owner-id", Email: email, Name: name}, nil
+			},
+		},
+		&mock_server.MockAccountManager{},
+	)
+
+	result, err := setupManager.SetupOwner(context.Background(), "admin@example.com", "securepassword123", "Admin", SetupOptions{
+		CreatePAT: true,
+	})
+
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	assert.Equal(t, "owner-id", result.User.ID)
+	assert.Empty(t, result.PATPlainToken)
+	assert.Equal(t, 1, createCalls)
+}
+
+func TestSetupOwner_PATFeatureEnabled_MissingExpireDefaultsToOneDay(t *testing.T) {
+	t.Setenv(SetupPATEnabledEnvKey, "true")
+
+	createCalled := false
+	setupManager := NewSetupService(
+		&setupInstanceManagerMock{
+			createOwnerUserFn: func(_ context.Context, email, _, name string) (*idp.UserData, error) {
+				createCalled = true
+				return &idp.UserData{ID: "owner-id", Email: email, Name: name}, nil
+			},
+		},
+		&mock_server.MockAccountManager{
+			GetAccountIDByUserIdFunc: func(_ context.Context, userAuth auth.UserAuth) (string, error) {
+				assert.Equal(t, "owner-id", userAuth.UserId)
+				return "acc-1", nil
+			},
+			CreatePATFunc: func(_ context.Context, accountID, initiatorUserID, targetUserID, tokenName string, expiresIn int) (*types.PersonalAccessTokenGenerated, error) {
+				assert.Equal(t, "acc-1", accountID)
+				assert.Equal(t, "owner-id", initiatorUserID)
+				assert.Equal(t, "owner-id", targetUserID)
+				assert.Equal(t, setupPATTokenName, tokenName)
+				assert.Equal(t, setupPATDefaultExpireDays, expiresIn)
+				return &types.PersonalAccessTokenGenerated{PlainToken: "nbp_plain"}, nil
+			},
+		},
+	)
+
+	result, err := setupManager.SetupOwner(context.Background(), "admin@example.com", "securepassword123", "Admin", SetupOptions{
+		CreatePAT: true,
+	})
+
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	assert.True(t, createCalled)
+	assert.Equal(t, "nbp_plain", result.PATPlainToken)
+}
+
+func TestSetupOwner_PATFeatureEnabled_MissingAccountManagerFailsBeforeCreateUser(t *testing.T) {
+	t.Setenv(SetupPATEnabledEnvKey, "true")
+
+	createCalled := false
+	rollbackCalled := false
+	setupManager := NewSetupService(
+		&setupInstanceManagerMock{
+			createOwnerUserFn: func(_ context.Context, email, _, name string) (*idp.UserData, error) {
+				createCalled = true
+				return &idp.UserData{ID: "owner-id", Email: email, Name: name}, nil
+			},
+			rollbackSetupFn: func(_ context.Context, _ string) error {
+				rollbackCalled = true
+				return nil
+			},
+		},
+		nil,
+	)
+
+	result, err := setupManager.SetupOwner(context.Background(), "admin@example.com", "securepassword123", "Admin", SetupOptions{
+		CreatePAT: true,
+	})
+
+	require.Error(t, err)
+	assert.Nil(t, result)
+	assert.Contains(t, err.Error(), "account manager is required")
+	assert.False(t, createCalled)
+	assert.False(t, rollbackCalled)
+}
+
+func TestSetupOwner_AccountProvisioningFails_RollsBackSideEffectAccountAndUser(t *testing.T) {
+	t.Setenv(SetupPATEnabledEnvKey, "true")
+
+	ctrl := gomock.NewController(t)
+	accountStore := nbstore.NewMockStore(ctrl)
+	account := &types.Account{Id: "acc-1"}
+	accountStore.EXPECT().GetAccountIDByUserID(gomock.Any(), nbstore.LockingStrengthNone, "owner-id").Return("acc-1", nil)
+	accountStore.EXPECT().GetAccount(gomock.Any(), "acc-1").Return(account, nil)
+	accountStore.EXPECT().DeleteAccount(gomock.Any(), account).Return(nil)
+
+	rolledBackFor := ""
+	rollbackCalls := 0
+	setupManager := NewSetupService(
+		&setupInstanceManagerMock{
+			rollbackSetupFn: func(_ context.Context, userID string) error {
+				rollbackCalls++
+				rolledBackFor = userID
+				return nil
+			},
+		},
+		&mock_server.MockAccountManager{
+			GetAccountIDByUserIdFunc: func(_ context.Context, userAuth auth.UserAuth) (string, error) {
+				assert.Equal(t, "owner-id", userAuth.UserId)
+				return "", errors.New("metadata update failed")
+			},
+			GetStoreFunc: func() nbstore.Store {
+				return accountStore
+			},
+		},
+	)
+
+	result, err := setupManager.SetupOwner(context.Background(), "admin@example.com", "securepassword123", "Admin", SetupOptions{
+		CreatePAT:       true,
+		PATExpireInDays: intPtr(30),
+	})
+
+	require.Error(t, err)
+	assert.Nil(t, result)
+	assert.Contains(t, err.Error(), "create account for setup user")
+	assert.Equal(t, "owner-id", rolledBackFor)
+	assert.Equal(t, 1, rollbackCalls)
+}
+
+func TestSetupOwner_CreatePATFails_RollsBackSetupAccountAndUser(t *testing.T) {
+	t.Setenv(SetupPATEnabledEnvKey, "true")
+
+	ctrl := gomock.NewController(t)
+	accountStore := nbstore.NewMockStore(ctrl)
+	account := &types.Account{Id: "acc-1"}
+	accountStore.EXPECT().GetAccount(gomock.Any(), "acc-1").Return(account, nil)
+	accountStore.EXPECT().DeleteAccount(gomock.Any(), account).Return(nil)
+
+	rollbackCalls := 0
+	setupManager := NewSetupService(
+		&setupInstanceManagerMock{
+			rollbackSetupFn: func(_ context.Context, userID string) error {
+				rollbackCalls++
+				assert.Equal(t, "owner-id", userID)
+				return nil
+			},
+		},
+		&mock_server.MockAccountManager{
+			GetAccountIDByUserIdFunc: func(_ context.Context, userAuth auth.UserAuth) (string, error) {
+				assert.Equal(t, "owner-id", userAuth.UserId)
+				return "acc-1", nil
+			},
+			CreatePATFunc: func(_ context.Context, accountID, initiatorUserID, targetUserID, tokenName string, expiresIn int) (*types.PersonalAccessTokenGenerated, error) {
+				assert.Equal(t, "acc-1", accountID)
+				assert.Equal(t, "owner-id", initiatorUserID)
+				assert.Equal(t, "owner-id", targetUserID)
+				assert.Equal(t, setupPATTokenName, tokenName)
+				assert.Equal(t, 30, expiresIn)
+				return nil, status.Errorf(status.Internal, "token store unavailable")
+			},
+			GetStoreFunc: func() nbstore.Store {
+				return accountStore
+			},
+		},
+	)
+
+	result, err := setupManager.SetupOwner(context.Background(), "admin@example.com", "securepassword123", "Admin", SetupOptions{
+		CreatePAT:       true,
+		PATExpireInDays: intPtr(30),
+	})
+
+	require.Error(t, err)
+	assert.Nil(t, result)
+	assert.Contains(t, err.Error(), "create setup PAT")
+	assert.Equal(t, 1, rollbackCalls)
+}
+
+func TestSetupOwner_CreatePATFails_AccountAlreadyGoneStillRollsBackUser(t *testing.T) {
+	t.Setenv(SetupPATEnabledEnvKey, "true")
+
+	ctrl := gomock.NewController(t)
+	accountStore := nbstore.NewMockStore(ctrl)
+	accountStore.EXPECT().GetAccount(gomock.Any(), "acc-1").Return(nil, status.NewAccountNotFoundError("acc-1"))
+
+	rolledBackFor := ""
+	rollbackCalls := 0
+	setupManager := NewSetupService(
+		&setupInstanceManagerMock{
+			rollbackSetupFn: func(_ context.Context, userID string) error {
+				rollbackCalls++
+				rolledBackFor = userID
+				return nil
+			},
+		},
+		&mock_server.MockAccountManager{
+			GetAccountIDByUserIdFunc: func(_ context.Context, _ auth.UserAuth) (string, error) {
+				return "acc-1", nil
+			},
+			CreatePATFunc: func(_ context.Context, _, _, _, _ string, _ int) (*types.PersonalAccessTokenGenerated, error) {
+				return nil, errors.New("token failure")
+			},
+			GetStoreFunc: func() nbstore.Store {
+				return accountStore
+			},
+		},
+	)
+
+	result, err := setupManager.SetupOwner(context.Background(), "admin@example.com", "securepassword123", "Admin", SetupOptions{
+		CreatePAT:       true,
+		PATExpireInDays: intPtr(30),
+	})
+
+	require.Error(t, err)
+	assert.Nil(t, result)
+	assert.Contains(t, err.Error(), "create setup PAT")
+	assert.Equal(t, "owner-id", rolledBackFor)
+	assert.Equal(t, 1, rollbackCalls)
+}
+
+func TestSetupOwner_CreatePATFails_AccountRollbackFailureStopsBeforeUserRollback(t *testing.T) {
+	t.Setenv(SetupPATEnabledEnvKey, "true")
+
+	ctrl := gomock.NewController(t)
+	accountStore := nbstore.NewMockStore(ctrl)
+	account := &types.Account{Id: "acc-1"}
+	accountStore.EXPECT().GetAccount(gomock.Any(), "acc-1").Return(account, nil)
+	accountStore.EXPECT().DeleteAccount(gomock.Any(), account).Return(errors.New("delete failed"))
+
+	rollbackCalls := 0
+	setupManager := NewSetupService(
+		&setupInstanceManagerMock{
+			rollbackSetupFn: func(_ context.Context, userID string) error {
+				rollbackCalls++
+				return nil
+			},
+		},
+		&mock_server.MockAccountManager{
+			GetAccountIDByUserIdFunc: func(_ context.Context, _ auth.UserAuth) (string, error) {
+				return "acc-1", nil
+			},
+			CreatePATFunc: func(_ context.Context, _, _, _, _ string, _ int) (*types.PersonalAccessTokenGenerated, error) {
+				return nil, errors.New("token failure")
+			},
+			GetStoreFunc: func() nbstore.Store {
+				return accountStore
+			},
+		},
+	)
+
+	result, err := setupManager.SetupOwner(context.Background(), "admin@example.com", "securepassword123", "Admin", SetupOptions{
+		CreatePAT:       true,
+		PATExpireInDays: intPtr(30),
+	})
+
+	require.Error(t, err)
+	assert.Nil(t, result)
+	assert.Contains(t, err.Error(), "create setup PAT")
+	assert.Contains(t, err.Error(), "failed to roll back setup resources")
+	assert.Equal(t, 0, rollbackCalls)
+}

management/server/management_proto_test.go

@@ -391,7 +391,7 @@ func startManagementForTest(t *testing.T, testFile string, config *config.Config
 		return nil, nil, "", cleanup, err
 	}
 
-	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, MockIntegratedValidator{}, networkMapController, nil)
+	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, MockIntegratedValidator{}, networkMapController, nil, nil)
 	if err != nil {
 		return nil, nil, "", cleanup, err
 	}

management/server/management_test.go

@@ -256,6 +256,7 @@ func startServer(
 		server.MockIntegratedValidator{},
 		networkMapController,
 		nil,
+		nil,
 	)
 	if err != nil {
 		t.Fatalf("failed creating management server: %v", err)

management/server/mock_server/account_mock.go

@@ -128,8 +128,8 @@ type MockAccountManager struct {
 	GetOrCreateAccountByPrivateDomainFunc func(ctx context.Context, initiatorId, domain string) (*types.Account, bool, error)
 
 	AllowSyncFunc                  func(string, uint64) bool
-	UpdateAccountPeersFunc         func(ctx context.Context, accountID string)
-	BufferUpdateAccountPeersFunc   func(ctx context.Context, accountID string)
+	UpdateAccountPeersFunc         func(ctx context.Context, accountID string, reason types.UpdateReason)
+	BufferUpdateAccountPeersFunc   func(ctx context.Context, accountID string, reason types.UpdateReason)
 	RecalculateNetworkMapCacheFunc func(ctx context.Context, accountId string) error
 
 	GetIdentityProviderFunc    func(ctx context.Context, accountID, idpID, userID string) (*types.IdentityProvider, error)
@@ -200,15 +200,15 @@ func (am *MockAccountManager) UpdateGroups(ctx context.Context, accountID, userI
 	return status.Errorf(codes.Unimplemented, "method UpdateGroups is not implemented")
 }
 
-func (am *MockAccountManager) UpdateAccountPeers(ctx context.Context, accountID string) {
+func (am *MockAccountManager) UpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) {
 	if am.UpdateAccountPeersFunc != nil {
-		am.UpdateAccountPeersFunc(ctx, accountID)
+		am.UpdateAccountPeersFunc(ctx, accountID, reason)
 	}
 }
 
-func (am *MockAccountManager) BufferUpdateAccountPeers(ctx context.Context, accountID string) {
+func (am *MockAccountManager) BufferUpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) {
 	if am.BufferUpdateAccountPeersFunc != nil {
-		am.BufferUpdateAccountPeersFunc(ctx, accountID)
+		am.BufferUpdateAccountPeersFunc(ctx, accountID, reason)
 	}
 }
 

management/server/nameserver.go

@@ -82,7 +82,7 @@ func (am *DefaultAccountManager) CreateNameServerGroup(ctx context.Context, acco
 	am.StoreEvent(ctx, userID, newNSGroup.ID, accountID, activity.NameserverGroupCreated, newNSGroup.EventMeta())
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceNameServerGroup, Operation: types.UpdateOperationCreate})
 	}
 
 	return newNSGroup.Copy(), nil
@@ -133,7 +133,7 @@ func (am *DefaultAccountManager) SaveNameServerGroup(ctx context.Context, accoun
 	am.StoreEvent(ctx, userID, nsGroupToSave.ID, accountID, activity.NameserverGroupUpdated, nsGroupToSave.EventMeta())
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceNameServerGroup, Operation: types.UpdateOperationUpdate})
 	}
 
 	return nil
@@ -176,7 +176,7 @@ func (am *DefaultAccountManager) DeleteNameServerGroup(ctx context.Context, acco
 	am.StoreEvent(ctx, userID, nsGroup.ID, accountID, activity.NameserverGroupDeleted, nsGroup.EventMeta())
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceNameServerGroup, Operation: types.UpdateOperationDelete})
 	}
 
 	return nil

management/server/networks/manager.go

@@ -15,6 +15,7 @@ import (
 	"github.com/netbirdio/netbird/management/server/permissions/modules"
 	"github.com/netbirdio/netbird/management/server/permissions/operations"
 	"github.com/netbirdio/netbird/management/server/store"
+	serverTypes "github.com/netbirdio/netbird/management/server/types"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
@@ -177,7 +178,7 @@ func (m *managerImpl) DeleteNetwork(ctx context.Context, accountID, userID, netw
 		event()
 	}
 
-	go m.accountManager.UpdateAccountPeers(ctx, accountID)
+	go m.accountManager.UpdateAccountPeers(ctx, accountID, serverTypes.UpdateReason{Resource: serverTypes.UpdateResourceNetwork, Operation: serverTypes.UpdateOperationDelete})
 
 	return nil
 }

management/server/networks/resources/manager.go

@@ -162,7 +162,7 @@ func (m *managerImpl) CreateResource(ctx context.Context, userID string, resourc
 		event()
 	}
 
-	go m.accountManager.UpdateAccountPeers(ctx, resource.AccountID)
+	go m.accountManager.UpdateAccountPeers(ctx, resource.AccountID, nbtypes.UpdateReason{Resource: nbtypes.UpdateResourceNetworkResource, Operation: nbtypes.UpdateOperationCreate})
 
 	return resource, nil
 }
@@ -270,7 +270,7 @@ func (m *managerImpl) UpdateResource(ctx context.Context, userID string, resourc
 		}
 	}()
 
-	go m.accountManager.UpdateAccountPeers(ctx, resource.AccountID)
+	go m.accountManager.UpdateAccountPeers(ctx, resource.AccountID, nbtypes.UpdateReason{Resource: nbtypes.UpdateResourceNetworkResource, Operation: nbtypes.UpdateOperationUpdate})
 
 	return resource, nil
 }
@@ -352,7 +352,7 @@ func (m *managerImpl) DeleteResource(ctx context.Context, accountID, userID, net
 		event()
 	}
 
-	go m.accountManager.UpdateAccountPeers(ctx, accountID)
+	go m.accountManager.UpdateAccountPeers(ctx, accountID, nbtypes.UpdateReason{Resource: nbtypes.UpdateResourceNetworkResource, Operation: nbtypes.UpdateOperationDelete})
 
 	return nil
 }

management/server/networks/routers/manager.go

@@ -15,6 +15,7 @@ import (
 	"github.com/netbirdio/netbird/management/server/permissions/modules"
 	"github.com/netbirdio/netbird/management/server/permissions/operations"
 	"github.com/netbirdio/netbird/management/server/store"
+	serverTypes "github.com/netbirdio/netbird/management/server/types"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
@@ -119,7 +120,7 @@ func (m *managerImpl) CreateRouter(ctx context.Context, userID string, router *t
 
 	m.accountManager.StoreEvent(ctx, userID, router.ID, router.AccountID, activity.NetworkRouterCreated, router.EventMeta(network))
 
-	go m.accountManager.UpdateAccountPeers(ctx, router.AccountID)
+	go m.accountManager.UpdateAccountPeers(ctx, router.AccountID, serverTypes.UpdateReason{Resource: serverTypes.UpdateResourceNetworkRouter, Operation: serverTypes.UpdateOperationCreate})
 
 	return router, nil
 }
@@ -183,7 +184,7 @@ func (m *managerImpl) UpdateRouter(ctx context.Context, userID string, router *t
 
 	m.accountManager.StoreEvent(ctx, userID, router.ID, router.AccountID, activity.NetworkRouterUpdated, router.EventMeta(network))
 
-	go m.accountManager.UpdateAccountPeers(ctx, router.AccountID)
+	go m.accountManager.UpdateAccountPeers(ctx, router.AccountID, serverTypes.UpdateReason{Resource: serverTypes.UpdateResourceNetworkRouter, Operation: serverTypes.UpdateOperationUpdate})
 
 	return router, nil
 }
@@ -217,7 +218,7 @@ func (m *managerImpl) DeleteRouter(ctx context.Context, accountID, userID, netwo
 
 	event()
 
-	go m.accountManager.UpdateAccountPeers(ctx, accountID)
+	go m.accountManager.UpdateAccountPeers(ctx, accountID, serverTypes.UpdateReason{Resource: serverTypes.UpdateResourceNetworkRouter, Operation: serverTypes.UpdateOperationDelete})
 
 	return nil
 }

management/server/peer.go

@@ -1221,12 +1221,12 @@ func (am *DefaultAccountManager) GetPeer(ctx context.Context, accountID, peerID,
 
 // UpdateAccountPeers updates all peers that belong to an account.
 // Should be called when changes have to be synced to peers.
-func (am *DefaultAccountManager) UpdateAccountPeers(ctx context.Context, accountID string) {
-	_ = am.networkMapController.UpdateAccountPeers(ctx, accountID)
+func (am *DefaultAccountManager) UpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) {
+	_ = am.networkMapController.UpdateAccountPeers(ctx, accountID, reason)
 }
 
-func (am *DefaultAccountManager) BufferUpdateAccountPeers(ctx context.Context, accountID string) {
-	_ = am.networkMapController.BufferUpdateAccountPeers(ctx, accountID)
+func (am *DefaultAccountManager) BufferUpdateAccountPeers(ctx context.Context, accountID string, reason types.UpdateReason) {
+	_ = am.networkMapController.BufferUpdateAccountPeers(ctx, accountID, reason)
 }
 
 // UpdateAccountPeer updates a single peer that belongs to an account.

management/server/peer_test.go

@@ -975,7 +975,7 @@ func BenchmarkUpdateAccountPeers(b *testing.B) {
 			start := time.Now()
 
 			for i := 0; i < b.N; i++ {
-				manager.UpdateAccountPeers(ctx, account.Id)
+				manager.UpdateAccountPeers(ctx, account.Id, types.UpdateReason{})
 			}
 
 			duration := time.Since(start)
@@ -1033,7 +1033,7 @@ func testUpdateAccountPeers(t *testing.T) {
 				peerChannels[peerID] = updateManager.CreateChannel(ctx, peerID)
 			}
 
-			manager.UpdateAccountPeers(ctx, account.Id)
+			manager.UpdateAccountPeers(ctx, account.Id, types.UpdateReason{})
 
 			for _, channel := range peerChannels {
 				update := <-channel

management/server/policy.go

@@ -96,7 +96,11 @@ func (am *DefaultAccountManager) SavePolicy(ctx context.Context, accountID, user
 	am.StoreEvent(ctx, userID, policy.ID, accountID, action, policy.EventMeta())
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		policyOp := types.UpdateOperationCreate
+		if isUpdate {
+			policyOp = types.UpdateOperationUpdate
+		}
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourcePolicy, Operation: policyOp})
 	}
 
 	return policy, nil
@@ -139,7 +143,7 @@ func (am *DefaultAccountManager) DeletePolicy(ctx context.Context, accountID, po
 	am.StoreEvent(ctx, userID, policyID, accountID, activity.PolicyRemoved, policy.EventMeta())
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourcePolicy, Operation: types.UpdateOperationDelete})
 	}
 
 	return nil

management/server/posture/network.go

@@ -17,19 +17,48 @@ type PeerNetworkRangeCheck struct {
 
 var _ Check = (*PeerNetworkRangeCheck)(nil)
 
+// prefixContains reports whether outer fully contains inner (equal counts as contained).
+// Requires the same address family, that outer is no more specific than inner (its
+// netmask is shorter or equal), and that inner's network address falls inside outer.
+// This is stricter than netip.Prefix.Contains(Addr) — a peer's /24 NIC will not match a
+// configured /32 rule, since the rule covers a single host but the NIC describes a whole
+// subnet whose host bits are unknown.
+func prefixContains(outer, inner netip.Prefix) bool {
+	outer = outer.Masked()
+	inner = inner.Masked()
+	return outer.Bits() <= inner.Bits() &&
+		outer.Addr().BitLen() == inner.Addr().BitLen() && // same family
+		outer.Contains(inner.Addr())
+}
+
+// Check evaluates configured ranges against the peer's local network interface prefixes
+// and its public connection IP (as a /32 or /128). A configured range matches when it
+// fully contains one of those prefixes, so operators can target both private subnets
+// and public CIDRs (e.g. 1.0.0.0/24, 2.2.2.2/32). Including the connection IP is what
+// lets a public-range posture check work — peer.Meta.NetworkAddresses only carries
+// local NIC addresses.
 func (p *PeerNetworkRangeCheck) Check(ctx context.Context, peer nbpeer.Peer) (bool, error) {
-	if len(peer.Meta.NetworkAddresses) == 0 {
+	peerPrefixes := make([]netip.Prefix, 0, len(peer.Meta.NetworkAddresses)+1)
+	for _, peerNetAddr := range peer.Meta.NetworkAddresses {
+		peerPrefixes = append(peerPrefixes, peerNetAddr.NetIP)
+	}
+	// Unmap collapses 4-in-6 forms (::ffff:a.b.c.d) so an IPv4 range matches.
+	if connIP := peer.Location.ConnectionIP; len(connIP) > 0 {
+		if addr, ok := netip.AddrFromSlice(connIP); ok {
+			addr = addr.Unmap()
+			peerPrefixes = append(peerPrefixes, netip.PrefixFrom(addr, addr.BitLen()))
+		}
+	}
+
+	if len(peerPrefixes) == 0 {
 		return false, fmt.Errorf("peer's does not contain peer network range addresses")
 	}
 
-	maskedPrefixes := make([]netip.Prefix, 0, len(p.Ranges))
-	for _, prefix := range p.Ranges {
-		maskedPrefixes = append(maskedPrefixes, prefix.Masked())
-	}
-
-	for _, peerNetAddr := range peer.Meta.NetworkAddresses {
-		peerMaskedPrefix := peerNetAddr.NetIP.Masked()
-		if slices.Contains(maskedPrefixes, peerMaskedPrefix) {
+	for _, peerPrefix := range peerPrefixes {
+		for _, rangePrefix := range p.Ranges {
+			if !prefixContains(rangePrefix, peerPrefix) {
+				continue
+			}
 			switch p.Action {
 			case CheckActionDeny:
 				return false, nil

management/server/posture/network_test.go

@@ -2,6 +2,7 @@ package posture
 
 import (
 	"context"
+	"net"
 	"net/netip"
 	"testing"
 
@@ -134,6 +135,205 @@ func TestPeerNetworkRangeCheck_Check(t *testing.T) {
 			wantErr: true,
 			isValid: false,
 		},
+		{
+			name: "Peer connection IP matches the denied /32",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionDeny,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("109.41.115.194/32"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Meta: nbpeer.PeerSystemMeta{
+					NetworkAddresses: []nbpeer.NetworkAddress{
+						{NetIP: netip.MustParsePrefix("192.168.0.123/24")},
+					},
+				},
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("109.41.115.194")},
+			},
+			wantErr: false,
+			isValid: false,
+		},
+		{
+			name: "Peer connection IP does not match the denied /32",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionDeny,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("109.41.115.194/32"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Meta: nbpeer.PeerSystemMeta{
+					NetworkAddresses: []nbpeer.NetworkAddress{
+						{NetIP: netip.MustParsePrefix("192.168.0.123/24")},
+					},
+				},
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("8.8.8.8")},
+			},
+			wantErr: false,
+			isValid: true,
+		},
+		{
+			name: "Peer connection IP matches the allowed /32 with no NetworkAddresses",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionAllow,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("109.41.115.194/32"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("109.41.115.194")},
+			},
+			wantErr: false,
+			isValid: true,
+		},
+		{
+			name: "IPv6 connection IP matches the denied /128",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionDeny,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("2001:db8::1/128"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("2001:db8::1")},
+			},
+			wantErr: false,
+			isValid: false,
+		},
+		{
+			name: "IPv6 connection IP does not match the denied /128",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionDeny,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("2001:db8::1/128"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("2001:db8::2")},
+			},
+			wantErr: false,
+			isValid: true,
+		},
+		{
+			name: "IPv4-mapped IPv6 connection IP matches IPv4 /32",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionDeny,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("109.41.115.194/32"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("::ffff:109.41.115.194")},
+			},
+			wantErr: false,
+			isValid: false,
+		},
+		{
+			name: "Connection IP falls inside an allowed /24 range",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionAllow,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("1.0.0.0/24"),
+					netip.MustParsePrefix("2.2.2.2/32"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("1.0.0.55")},
+			},
+			wantErr: false,
+			isValid: true,
+		},
+		{
+			name: "Connection IP falls inside an allowed /23 range",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionAllow,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("3.0.0.0/23"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("3.0.1.200")},
+			},
+			wantErr: false,
+			isValid: true,
+		},
+		{
+			name: "Connection IP outside the allowed /24 range",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionAllow,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("1.0.0.0/24"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("1.0.1.5")},
+			},
+			wantErr: false,
+			isValid: false,
+		},
+		{
+			name: "Connection IP inside a denied /24 range",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionDeny,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("1.0.0.0/24"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Location: nbpeer.Location{ConnectionIP: net.ParseIP("1.0.0.7")},
+			},
+			wantErr: false,
+			isValid: false,
+		},
+		{
+			name: "Local NIC /24 does not match a /32 rule even if host bit lines up",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionAllow,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("192.168.0.5/32"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Meta: nbpeer.PeerSystemMeta{
+					NetworkAddresses: []nbpeer.NetworkAddress{
+						{NetIP: netip.MustParsePrefix("192.168.0.5/24")},
+					},
+				},
+			},
+			wantErr: false,
+			isValid: false,
+		},
+		{
+			name: "Local NIC address inside an allowed /16 range",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionAllow,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("192.168.0.0/16"),
+				},
+			},
+			peer: nbpeer.Peer{
+				Meta: nbpeer.PeerSystemMeta{
+					NetworkAddresses: []nbpeer.NetworkAddress{
+						{NetIP: netip.MustParsePrefix("192.168.5.7/24")},
+					},
+				},
+			},
+			wantErr: false,
+			isValid: true,
+		},
+		{
+			name: "Empty NetworkAddresses and empty ConnectionIP still errors",
+			check: PeerNetworkRangeCheck{
+				Action: CheckActionDeny,
+				Ranges: []netip.Prefix{
+					netip.MustParsePrefix("109.41.115.194/32"),
+				},
+			},
+			peer:    nbpeer.Peer{},
+			wantErr: true,
+			isValid: false,
+		},
 	}
 
 	for _, tt := range tests {

management/server/posture_checks.go

@@ -11,6 +11,7 @@ import (
 	"github.com/netbirdio/netbird/management/server/permissions/operations"
 	"github.com/netbirdio/netbird/management/server/posture"
 	"github.com/netbirdio/netbird/management/server/store"
+	"github.com/netbirdio/netbird/management/server/types"
 	"github.com/netbirdio/netbird/shared/management/status"
 )
 
@@ -76,7 +77,11 @@ func (am *DefaultAccountManager) SavePostureChecks(ctx context.Context, accountI
 	am.StoreEvent(ctx, userID, postureChecks.ID, accountID, action, postureChecks.EventMeta())
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		postureOp := types.UpdateOperationCreate
+		if isUpdate {
+			postureOp = types.UpdateOperationUpdate
+		}
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourcePostureCheck, Operation: postureOp})
 	}
 
 	return postureChecks, nil

management/server/route.go

@@ -191,7 +191,7 @@ func (am *DefaultAccountManager) CreateRoute(ctx context.Context, accountID stri
 	am.StoreEvent(ctx, userID, string(newRoute.ID), accountID, activity.RouteCreated, newRoute.EventMeta())
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceRoute, Operation: types.UpdateOperationCreate})
 	}
 
 	return newRoute, nil
@@ -245,7 +245,7 @@ func (am *DefaultAccountManager) SaveRoute(ctx context.Context, accountID, userI
 	am.StoreEvent(ctx, userID, string(routeToSave.ID), accountID, activity.RouteUpdated, routeToSave.EventMeta())
 
 	if oldRouteAffectsPeers || newRouteAffectsPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceRoute, Operation: types.UpdateOperationUpdate})
 	}
 
 	return nil
@@ -288,7 +288,7 @@ func (am *DefaultAccountManager) DeleteRoute(ctx context.Context, accountID stri
 	am.StoreEvent(ctx, userID, string(route.ID), accountID, activity.RouteRemoved, route.EventMeta())
 
 	if updateAccountPeers {
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceRoute, Operation: types.UpdateOperationDelete})
 	}
 
 	return nil

management/server/telemetry/accountmanager_metrics.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"time"
 
+	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/metric"
 )
 
@@ -11,6 +12,7 @@ import (
 type AccountManagerMetrics struct {
 	ctx                          context.Context
 	updateAccountPeersDurationMs metric.Float64Histogram
+	updateAccountPeersCounter    metric.Int64Counter
 	getPeerNetworkMapDurationMs  metric.Float64Histogram
 	networkMapObjectCount        metric.Int64Histogram
 	peerMetaUpdateCount          metric.Int64Counter
@@ -48,6 +50,13 @@ func NewAccountManagerMetrics(ctx context.Context, meter metric.Meter) (*Account
 		return nil, err
 	}
 
+	updateAccountPeersCounter, err := meter.Int64Counter("management.account.update.account.peers.counter",
+		metric.WithUnit("1"),
+		metric.WithDescription("Number of account peers updates triggered, labeled by resource and operation"))
+	if err != nil {
+		return nil, err
+	}
+
 	peerMetaUpdateCount, err := meter.Int64Counter("management.account.peer.meta.update.counter",
 		metric.WithUnit("1"),
 		metric.WithDescription("Number of updates with new meta data from the peers"))
@@ -59,6 +68,7 @@ func NewAccountManagerMetrics(ctx context.Context, meter metric.Meter) (*Account
 		ctx:                          ctx,
 		getPeerNetworkMapDurationMs:  getPeerNetworkMapDurationMs,
 		updateAccountPeersDurationMs: updateAccountPeersDurationMs,
+		updateAccountPeersCounter:    updateAccountPeersCounter,
 		networkMapObjectCount:        networkMapObjectCount,
 		peerMetaUpdateCount:          peerMetaUpdateCount,
 	}, nil
@@ -80,6 +90,16 @@ func (metrics *AccountManagerMetrics) CountNetworkMapObjects(count int64) {
 	metrics.networkMapObjectCount.Record(metrics.ctx, count)
 }
 
+// CountUpdateAccountPeersTriggered increments the counter for account peers updates with resource and operation labels.
+func (metrics *AccountManagerMetrics) CountUpdateAccountPeersTriggered(resource, operation string) {
+	metrics.updateAccountPeersCounter.Add(metrics.ctx, 1,
+		metric.WithAttributes(
+			attribute.String("resource", resource),
+			attribute.String("operation", operation),
+		),
+	)
+}
+
 // CountPeerMetUpdate counts the number of peer meta updates
 func (metrics *AccountManagerMetrics) CountPeerMetUpdate() {
 	metrics.peerMetaUpdateCount.Add(metrics.ctx, 1)

management/server/types/update_reason.go

@@ -0,0 +1,37 @@
+package types
+
+// UpdateReason describes why an account peers update was triggered.
+type UpdateReason struct {
+	Resource  UpdateResource
+	Operation UpdateOperation
+}
+
+// UpdateResource represents the kind of resource that triggered an account peers update.
+type UpdateResource string
+
+const (
+	UpdateResourceAccountSettings UpdateResource = "account_settings"
+	UpdateResourceDNSSettings     UpdateResource = "dns_settings"
+	UpdateResourceGroup           UpdateResource = "group"
+	UpdateResourceNameServerGroup UpdateResource = "nameserver_group"
+	UpdateResourcePolicy          UpdateResource = "policy"
+	UpdateResourcePostureCheck    UpdateResource = "posture_check"
+	UpdateResourceRoute           UpdateResource = "route"
+	UpdateResourceUser            UpdateResource = "user"
+	UpdateResourcePeer            UpdateResource = "peer"
+	UpdateResourceNetwork         UpdateResource = "network"
+	UpdateResourceNetworkResource UpdateResource = "network_resource"
+	UpdateResourceNetworkRouter   UpdateResource = "network_router"
+	UpdateResourceService         UpdateResource = "service"
+	UpdateResourceZone            UpdateResource = "zone"
+	UpdateResourceZoneRecord      UpdateResource = "zone_record"
+)
+
+// UpdateOperation represents the kind of change that triggered the update.
+type UpdateOperation string
+
+const (
+	UpdateOperationCreate UpdateOperation = "create"
+	UpdateOperationUpdate UpdateOperation = "update"
+	UpdateOperationDelete UpdateOperation = "delete"
+)

management/server/user.go

@@ -15,6 +15,7 @@ import (
 	log "github.com/sirupsen/logrus"
 
 	"github.com/netbirdio/netbird/idp/dex"
+	"github.com/netbirdio/netbird/management/server/account"
 	"github.com/netbirdio/netbird/management/server/activity"
 	"github.com/netbirdio/netbird/management/server/idp"
 	nbpeer "github.com/netbirdio/netbird/management/server/peer"
@@ -395,8 +396,8 @@ func (am *DefaultAccountManager) CreatePAT(ctx context.Context, accountID string
 		return nil, status.Errorf(status.InvalidArgument, "token name can't be empty")
 	}
 
-	if expiresIn < 1 || expiresIn > 365 {
-		return nil, status.Errorf(status.InvalidArgument, "expiration has to be between 1 and 365")
+	if expiresIn < account.PATMinExpireDays || expiresIn > account.PATMaxExpireDays {
+		return nil, status.Errorf(status.InvalidArgument, "expiration has to be between %d and %d", account.PATMinExpireDays, account.PATMaxExpireDays)
 	}
 
 	allowed, err := am.permissionsManager.ValidateUserPermissions(ctx, accountID, initiatorUserID, modules.Pats, operations.Create)
@@ -675,7 +676,7 @@ func (am *DefaultAccountManager) SaveOrAddUsers(ctx context.Context, accountID,
 		if err = am.Store.IncrementNetworkSerial(ctx, accountID); err != nil {
 			return nil, fmt.Errorf("failed to increment network serial: %w", err)
 		}
-		am.UpdateAccountPeers(ctx, accountID)
+		am.UpdateAccountPeers(ctx, accountID, types.UpdateReason{Resource: types.UpdateResourceUser, Operation: types.UpdateOperationUpdate})
 	}
 
 	return updatedUsersInfo, globalErr

shared/management/client/client_test.go

@@ -138,7 +138,7 @@ func startManagement(t *testing.T) (*grpc.Server, net.Listener) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, mgmt.MockIntegratedValidator{}, networkMapController, nil)
+	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, jobManager, secretsManager, nil, nil, mgmt.MockIntegratedValidator{}, networkMapController, nil, nil)
 	if err != nil {
 		t.Fatal(err)
 	}

shared/management/http/api/openapi.yml

@@ -1687,15 +1687,18 @@ components:
         - locations
         - action
     PeerNetworkRangeCheck:
-      description: Posture check for allow or deny access based on peer local network addresses
+      description: |
+        Posture check for allow or deny access based on the peer's IP addresses. A range matches when it
+        contains any of the peer's local network interface IPs or its public connection (NAT egress) IP,
+        so ranges may target private subnets, public CIDRs, or single hosts via a /32 or /128.
       type: object
       properties:
         ranges:
-          description: List of peer network ranges in CIDR notation
+          description: List of network ranges in CIDR notation, matched against the peer's local interface IPs and its public connection IP
           type: array
           items:
             type: string
-          example: [ "192.168.1.0/24", "10.0.0.0/8", "2001:db8:1234:1a00::/56" ]
+          example: [ "192.168.1.0/24", "10.0.0.0/8", "1.0.0.0/24", "2.2.2.2/32", "2001:db8:1234:1a00::/56" ]
         action:
           description: Action to take upon policy match
           type: string
@@ -3426,6 +3429,17 @@ components:
           description: Display name for the admin user (defaults to email if not provided)
           type: string
           example: Admin User
+        create_pat:
+          description: If true and the server has setup-time PAT issuance enabled (NB_SETUP_PAT_ENABLED=true), create a Personal Access Token for the new owner user and return it in the response. Ignored when the server feature is disabled.
+          type: boolean
+          example: true
+        pat_expire_in:
+          description: Expiration of the Personal Access Token in days. Applies only when create_pat is true and the server feature is enabled. Defaults to 1 day when omitted.
+          type: integer
+          minimum: 1
+          maximum: 365
+          default: 1
+          example: 30
       required:
         - email
         - password
@@ -3442,6 +3456,12 @@ components:
           description: Email address of the created user
           type: string
           example: admin@example.com
+        personal_access_token:
+          description: Plain text Personal Access Token created during setup. Present only when create_pat was requested and the NB_SETUP_PAT_ENABLED feature was enabled on the server.
+          type: string
+          format: password
+          readOnly: true
+          example: nbp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
       required:
         - user_id
         - email
@@ -4980,7 +5000,10 @@ paths:
   /api/setup:
     post:
       summary: Setup Instance
-      description: Creates the initial admin user for the instance. This endpoint does not require authentication but only works when setup is required (no accounts exist and embedded IDP is enabled).
+      description: |
+        Creates the initial admin user for the instance. This endpoint does not require authentication but only works when setup is required (no accounts exist and embedded IDP is enabled).
+
+        When the management server is started with `NB_SETUP_PAT_ENABLED=true` and the request includes `create_pat: true`, the endpoint also provisions the NetBird account for the new owner user and returns the plain text Personal Access Token in `personal_access_token`. The optional `pat_expire_in` value applies only when `create_pat` is true and defaults to 1 day when omitted. If a post-user step fails, setup-created resources are rolled back when safe; if account cleanup fails, the owner user is left in place to avoid leaving an account without its admin user.
       tags: [ Instance ]
       security: [ ]
       requestBody:
@@ -4993,6 +5016,12 @@ paths:
       responses:
         '200':
           description: Setup completed successfully
+          headers:
+            Cache-Control:
+              description: Always set to no-store because the response may contain a one-time plain text Personal Access Token.
+              schema:
+                type: string
+                example: no-store
           content:
             application/json:
               schema:

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

@@ -1626,7 +1626,7 @@ type Checks struct {
 	// OsVersionCheck Posture check for the version of operating system
 	OsVersionCheck *OSVersionCheck `json:"os_version_check,omitempty"`
 
-	// PeerNetworkRangeCheck Posture check for allow or deny access based on peer local network addresses
+	// PeerNetworkRangeCheck Posture check for allow or deny access based on the peer's IP addresses. A range matches when it contains any of the peer's local network interface IPs or its public connection (NAT egress) IP, so ranges may target private subnets, public CIDRs, or single hosts via a /32 or /128.
 	PeerNetworkRangeCheck *PeerNetworkRangeCheck `json:"peer_network_range_check,omitempty"`
 
 	// ProcessCheck Posture Check for binaries exist and are running in the peer’s system
@@ -3312,12 +3312,12 @@ type PeerMinimum struct {
 	Name string `json:"name"`
 }
 
-// PeerNetworkRangeCheck Posture check for allow or deny access based on peer local network addresses
+// PeerNetworkRangeCheck Posture check for allow or deny access based on the peer's IP addresses. A range matches when it contains any of the peer's local network interface IPs or its public connection (NAT egress) IP, so ranges may target private subnets, public CIDRs, or single hosts via a /32 or /128.
 type PeerNetworkRangeCheck struct {
 	// Action Action to take upon policy match
 	Action PeerNetworkRangeCheckAction `json:"action"`
 
-	// Ranges List of peer network ranges in CIDR notation
+	// Ranges List of network ranges in CIDR notation, matched against the peer's local interface IPs and its public connection IP
 	Ranges []string `json:"ranges"`
 }
 
@@ -4297,6 +4297,9 @@ type SetupKeyRequest struct {
 
 // SetupRequest Request to set up the initial admin user
 type SetupRequest struct {
+	// CreatePat If true and the server has setup-time PAT issuance enabled (NB_SETUP_PAT_ENABLED=true), create a Personal Access Token for the new owner user and return it in the response. Ignored when the server feature is disabled.
+	CreatePat *bool `json:"create_pat,omitempty"`
+
 	// Email Email address for the admin user
 	Email string `json:"email"`
 
@@ -4305,6 +4308,9 @@ type SetupRequest struct {
 
 	// Password Password for the admin user (minimum 8 characters)
 	Password string `json:"password"`
+
+	// PatExpireIn Expiration of the Personal Access Token in days. Applies only when create_pat is true and the server feature is enabled. Defaults to 1 day when omitted.
+	PatExpireIn *int `json:"pat_expire_in,omitempty"`
 }
 
 // SetupResponse Response after successful instance setup
@@ -4312,6 +4318,9 @@ type SetupResponse struct {
 	// Email Email address of the created user
 	Email string `json:"email"`
 
+	// PersonalAccessToken Plain text Personal Access Token created during setup. Present only when create_pat was requested and the NB_SETUP_PAT_ENABLED feature was enabled on the server.
+	PersonalAccessToken *string `json:"personal_access_token,omitempty"`
+
 	// UserId The ID of the created user
 	UserId string `json:"user_id"`
 }

shared/relay/client/dialer/ws/ws.go

@@ -9,7 +9,6 @@ import (
 	"net"
 	"net/http"
 	"net/url"
-	"strings"
 
 	"github.com/coder/websocket"
 	log "github.com/sirupsen/logrus"
@@ -34,13 +33,7 @@ func (d Dialer) Dial(ctx context.Context, address string) (net.Conn, error) {
 
 	opts := createDialOptions()
 
-	parsedURL, err := url.Parse(wsURL)
-	if err != nil {
-		return nil, err
-	}
-	parsedURL.Path = relay.WebSocketURLPath
-
-	wsConn, resp, err := websocket.Dial(ctx, parsedURL.String(), opts)
+	wsConn, resp, err := websocket.Dial(ctx, wsURL, opts)
 	if err != nil {
 		if errors.Is(err, context.Canceled) {
 			return nil, err
@@ -56,12 +49,24 @@ func (d Dialer) Dial(ctx context.Context, address string) (net.Conn, error) {
 	return conn, nil
 }
 
+// prepareURL rewrites a rel://host[:port] or rels://host[:port] address into a
+// ws://host[:port]/relay or wss://host[:port]/relay URL, preserving any
+// non-standard port from the input.
 func prepareURL(address string) (string, error) {
-	if !strings.HasPrefix(address, "rel:") && !strings.HasPrefix(address, "rels:") {
-		return "", fmt.Errorf("unsupported scheme: %s", address)
+	parsed, err := url.Parse(address)
+	if err != nil {
+		return "", fmt.Errorf("parse relay address %q: %w", address, err)
 	}
-
-	return strings.Replace(address, "rel", "ws", 1), nil
+	switch parsed.Scheme {
+	case "rel":
+		parsed.Scheme = "ws"
+	case "rels":
+		parsed.Scheme = "wss"
+	default:
+		return "", fmt.Errorf("unsupported scheme: %s", parsed.Scheme)
+	}
+	parsed.Path = relay.WebSocketURLPath
+	return parsed.String(), nil
 }
 
 func httpClientNbDialer() *http.Client {

shared/relay/client/dialer/ws/ws_test.go

@@ -0,0 +1,76 @@
+package ws
+
+import (
+	"testing"
+)
+
+func TestPrepareURL(t *testing.T) {
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr bool
+	}{
+		{
+			name:  "rel scheme with non-standard port",
+			input: "rel://test-domain-2:45678",
+			want:  "ws://test-domain-2:45678/relay",
+		},
+		{
+			name:  "rels scheme with non-standard port",
+			input: "rels://test-domain-2:45678",
+			want:  "wss://test-domain-2:45678/relay",
+		},
+		{
+			name:  "rel scheme without port",
+			input: "rel://test-domain-2",
+			want:  "ws://test-domain-2/relay",
+		},
+		{
+			name:  "rels scheme without port",
+			input: "rels://test-domain-2",
+			want:  "wss://test-domain-2/relay",
+		},
+		{
+			name:  "rel scheme with IP and port",
+			input: "rel://1.2.3.4:45678",
+			want:  "ws://1.2.3.4:45678/relay",
+		},
+		{
+			name:  "rel scheme with hostname starting with rel",
+			input: "rel://relay.example.com:45678",
+			want:  "ws://relay.example.com:45678/relay",
+		},
+		{
+			name:  "rel scheme with IPv6 and port",
+			input: "rel://[2001:db8::1]:45678",
+			want:  "ws://[2001:db8::1]:45678/relay",
+		},
+		{
+			name:  "rels scheme with IPv6 loopback and port",
+			input: "rels://[::1]:45678",
+			want:  "wss://[::1]:45678/relay",
+		},
+		{
+			name:    "unsupported scheme",
+			input:   "http://test-domain-2:45678",
+			wantErr: true,
+		},
+		{
+			name:    "no scheme",
+			input:   "test-domain-2:45678",
+			wantErr: true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := prepareURL(tt.input)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("prepareURL(%q) err = %v, wantErr %v", tt.input, err, tt.wantErr)
+			}
+			if got != tt.want {
+				t.Errorf("prepareURL(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}