CHANGELOG: drop unreleased 0.30.0 stub

Release-branch only; the stub tracks unreleased main work.

.github/workflows/build.yml

@@ -38,24 +38,19 @@ jobs:
             '**/flake.lock') }}
           restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
 
-      - name: Run nix build
-        id: build
+      - name: Check vendor hash
+        id: vendorhash
         if: steps.changed-files.outputs.files == 'true'
         run: |
-          nix build |& tee build-result
-          BUILD_STATUS="${PIPESTATUS[0]}"
+          nix develop --command -- go run ./cmd/vendorhash check | tee check-result
+          {
+            grep '^expected_sri=' check-result || true
+            grep '^actual_sri='   check-result || true
+          } >> "$GITHUB_OUTPUT"
 
-          OLD_HASH=$(cat build-result | grep specified: | awk -F ':' '{print $2}' | sed 's/ //g')
-          NEW_HASH=$(cat build-result | grep got: | awk -F ':' '{print $2}' | sed 's/ //g')
-
-          echo "OLD_HASH=$OLD_HASH" >> $GITHUB_OUTPUT
-          echo "NEW_HASH=$NEW_HASH" >> $GITHUB_OUTPUT
-
-          exit $BUILD_STATUS
-
-      - name: Nix gosum diverging
+      - name: Vendor hash diverging
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
-        if: failure() && steps.build.outcome == 'failure'
+        if: failure() && steps.vendorhash.outcome == 'failure'
         with:
           github-token: ${{secrets.GITHUB_TOKEN}}
           script: |
@@ -63,9 +58,13 @@ jobs:
               pull_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              body: 'Nix build failed with wrong gosum, please update "vendorSha256" (${{ steps.build.outputs.OLD_HASH }}) for the "headscale" package in flake.nix with the new SHA: ${{ steps.build.outputs.NEW_HASH }}'
+              body: 'Vendor hash in `flakehashes.json` is stale (was `${{ steps.vendorhash.outputs.expected_sri }}`, should be `${{ steps.vendorhash.outputs.actual_sri }}`). Run `go run ./cmd/vendorhash update` and commit the result.'
             })
 
+      - name: Run nix build
+        if: steps.changed-files.outputs.files == 'true'
+        run: nix build
+
       - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         if: steps.changed-files.outputs.files == 'true'
         with:

.github/workflows/container-main.yml

@@ -59,7 +59,7 @@ jobs:
           nix develop --command -- ko build \
             --bare \
             --platform=linux/amd64,linux/arm64 \
-            --tags=main-${GITHUB_SHA::7} \
+            --tags=main-${GITHUB_SHA::7},development \
             ./cmd/headscale
 
       - name: Push to Docker Hub
@@ -71,7 +71,7 @@ jobs:
           nix develop --command -- ko build \
             --bare \
             --platform=linux/amd64,linux/arm64 \
-            --tags=main-${GITHUB_SHA::7} \
+            --tags=main-${GITHUB_SHA::7},development \
             ./cmd/headscale
 
   binaries:

.github/workflows/gh-action-integration-generator.go

@@ -14,7 +14,7 @@ import (
 // Key is the test function name, value is a list of subtest prefixes.
 // Each prefix becomes a separate CI job as "TestName/prefix".
 //
-// Example: TestAutoApproveMultiNetwork has subtests like:
+// Example: [TestAutoApproveMultiNetwork] has subtests like:
 //   - TestAutoApproveMultiNetwork/authkey-tag-advertiseduringup-false-pol-database
 //   - TestAutoApproveMultiNetwork/webauth-user-advertiseduringup-true-pol-file
 //
@@ -68,6 +68,7 @@ func findTests() []string {
 	args := []string{
 		"--type", "go",
 		"--regexp", "func (Test.+)\\(.*",
+		"--max-depth", "1",
 		"../../integration/",
 		"--replace", "$1",
 		"--sort", "path",

.github/workflows/integration-test-template.yml

@@ -51,6 +51,11 @@ jobs:
         with:
           name: tailscale-head-image
           path: /tmp/artifacts
+      - name: Download tailscale released images
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: tailscale-released-images
+          path: /tmp/artifacts
       - name: Download hi binary
         uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
@@ -67,28 +72,26 @@ jobs:
         with:
           name: postgres-image
           path: /tmp/artifacts
-      - name: Pin Docker to v28 (avoid v29 breaking changes)
+      - name: Force overlay2 storage driver
         run: |
-          # Docker 29 breaks docker build via Go client libraries and
-          # docker load/save with certain tarball formats.
-          # Pin to Docker 28.x until our tooling is updated.
-          # https://github.com/actions/runner-images/issues/13474
-          sudo install -m 0755 -d /etc/apt/keyrings
-          curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-            | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
-          echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
-            https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
-            | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
-          sudo apt-get update -qq
-          VERSION=$(apt-cache madison docker-ce | grep '28\.5' | head -1 | awk '{print $3}')
-          sudo apt-get install -y --allow-downgrades \
-            "docker-ce=${VERSION}" "docker-ce-cli=${VERSION}"
+          sudo mkdir -p /etc/docker
+          echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
           sudo systemctl restart docker
           docker version
+      - name: Login to Docker Hub
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
       - name: Load Docker images, Go cache, and prepare binary
         run: |
           gunzip -c /tmp/artifacts/headscale-image.tar.gz | docker load
           gunzip -c /tmp/artifacts/tailscale-head-image.tar.gz | docker load
+          gunzip -c /tmp/artifacts/tailscale-released-images.tar.gz | docker load
           if [ -f /tmp/artifacts/postgres-image.tar.gz ]; then
             gunzip -c /tmp/artifacts/postgres-image.tar.gz | docker load
           fi
@@ -105,6 +108,12 @@ jobs:
           HEADSCALE_INTEGRATION_POSTGRES_IMAGE: ${{ inputs.postgres_flag == '--postgres=1' && format('postgres:{0}', github.sha) || '' }}
           HEADSCALE_INTEGRATION_GO_CACHE: /tmp/go-cache/go
           HEADSCALE_INTEGRATION_GO_BUILD_CACHE: /tmp/go-cache/.cache/go-build
+          # Mirror the docker/login-action secrets into env so the
+          # dockertestutil.Credentials resolver picks them up directly
+          # (otherwise it falls back to parsing ~/.docker/config.json,
+          # which works but is one step further from the source).
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
         run: /tmp/artifacts/hi run --stats --ts-memory-limit=300 --hs-memory-limit=1500 "^${{ inputs.test }}$" \
           --timeout=120m \
           ${{ inputs.postgres_flag }}

.github/workflows/lint.yml

@@ -12,7 +12,7 @@ jobs:
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
-          fetch-depth: 2
+          fetch-depth: 0
       - name: Get changed files
         id: changed-files
         uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2

.github/workflows/needs-more-info-timer.yml

@@ -58,15 +58,16 @@ jobs:
 
             # Find when needs-more-info was last added
             let events = (gh api $"repos/($env.GH_REPO)/issues/($number)/events"
-              --paginate | from json | flatten)
+              --paginate | from json)
             let label_event = ($events
-              | where event == "labeled" and label.name == "needs-more-info"
+              | where event == "labeled"
+              | where label.name == "needs-more-info"
               | last)
             let label_added_at = ($label_event.created_at | into datetime)
 
             # Check for non-bot comments after the label was added
             let comments = (gh api $"repos/($env.GH_REPO)/issues/($number)/comments"
-              --paginate | from json | flatten)
+              --paginate | from json)
             let human_responses = ($comments
               | where user.type != "Bot"
               | where { ($in.created_at | into datetime) > $label_added_at })

.github/workflows/test-integration.yaml

@@ -9,6 +9,9 @@ concurrency:
 jobs:
   # build: Builds binaries and Docker images once, uploads as artifacts for reuse.
   # build-postgres: Pulls postgres image separately to avoid Docker Hub rate limits.
+  # build-tailscale-released: Pre-pulls released Tailscale images from ghcr.io
+  # so fork PRs (no DOCKERHUB_USERNAME secret) don't hit Docker Hub rate
+  # limits at test time.
   # sqlite: Runs all integration tests with SQLite backend.
   # postgres: Runs a subset of tests with PostgreSQL to verify database compatibility.
   build:
@@ -69,25 +72,26 @@ jobs:
           name: go-cache
           path: go-cache.tar.gz
           retention-days: 10
-      - name: Pin Docker to v28 (avoid v29 breaking changes)
+      - name: Force overlay2 storage driver
         if: steps.changed-files.outputs.files == 'true'
         run: |
-          # Docker 29 breaks docker build via Go client libraries and
-          # docker load/save with certain tarball formats.
-          # Pin to Docker 28.x until our tooling is updated.
+          # Docker 29 runner images default to overlayfs, which breaks
+          # docker build via Go SDK libraries and docker save/load
+          # tarball formats. overlay2 is the long-standing default.
           # https://github.com/actions/runner-images/issues/13474
-          sudo install -m 0755 -d /etc/apt/keyrings
-          curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-            | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
-          echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
-            https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
-            | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
-          sudo apt-get update -qq
-          VERSION=$(apt-cache madison docker-ce | grep '28\.5' | head -1 | awk '{print $3}')
-          sudo apt-get install -y --allow-downgrades \
-            "docker-ce=${VERSION}" "docker-ce-cli=${VERSION}"
+          sudo mkdir -p /etc/docker
+          echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
           sudo systemctl restart docker
           docker version
+      - name: Login to Docker Hub
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
       - name: Build headscale image
         if: steps.changed-files.outputs.files == 'true'
         run: |
@@ -123,24 +127,21 @@ jobs:
     needs: build
     if: needs.build.outputs.files-changed == 'true'
     steps:
-      - name: Pin Docker to v28 (avoid v29 breaking changes)
+      - name: Force overlay2 storage driver
         run: |
-          # Docker 29 breaks docker build via Go client libraries and
-          # docker load/save with certain tarball formats.
-          # Pin to Docker 28.x until our tooling is updated.
-          # https://github.com/actions/runner-images/issues/13474
-          sudo install -m 0755 -d /etc/apt/keyrings
-          curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-            | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
-          echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
-            https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
-            | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
-          sudo apt-get update -qq
-          VERSION=$(apt-cache madison docker-ce | grep '28\.5' | head -1 | awk '{print $3}')
-          sudo apt-get install -y --allow-downgrades \
-            "docker-ce=${VERSION}" "docker-ce-cli=${VERSION}"
+          sudo mkdir -p /etc/docker
+          echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
           sudo systemctl restart docker
           docker version
+      - name: Login to Docker Hub
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
       - name: Pull and save postgres image
         run: |
           docker pull postgres:latest
@@ -152,9 +153,71 @@ jobs:
           name: postgres-image
           path: postgres-image.tar.gz
           retention-days: 10
-  sqlite:
+  build-tailscale-released:
+    runs-on: ubuntu-24.04-arm
     needs: build
     if: needs.build.outputs.files-changed == 'true'
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix', '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+      - name: Force overlay2 storage driver
+        run: |
+          sudo mkdir -p /etc/docker
+          echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
+          sudo systemctl restart docker
+          docker version
+      - name: Login to Docker Hub
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
+      - name: List Tailscale versions to pre-pull
+        id: versions
+        run: |
+          versions=$(nix develop --command go run ./cmd/hi list-versions --set=must --exclude=head)
+          echo "versions=${versions}" >> "$GITHUB_OUTPUT"
+          echo "Pre-pulling: ${versions}"
+      - name: Pull Tailscale images
+        run: |
+          # Releases come from ghcr.io (anonymous, unmetered). The
+          # "unstable" floating tag on ghcr.io has been stale since 2022,
+          # so it still needs to come from Docker Hub. xargs -P 0 fans
+          # out one process per tag and returns non-zero if any pull
+          # fails.
+          refs=""
+          for v in ${{ steps.versions.outputs.versions }}; do
+            if [ "${v}" = "unstable" ]; then
+              refs="${refs} tailscale/tailscale:${v}"
+            else
+              refs="${refs} ghcr.io/tailscale/tailscale:${v}"
+            fi
+          done
+          echo "${refs}" | tr ' ' '\n' | grep -v '^$' \
+            | xargs -P 0 -I{} docker pull "{}"
+          echo "REFS=${refs}" >> "$GITHUB_ENV"
+      - name: Save Tailscale images to tarball
+        run: |
+          # Single docker save with all refs: one consistent snapshot, no
+          # parallel-daemon race.
+          docker save ${REFS} | gzip > tailscale-released-images.tar.gz
+          ls -lh tailscale-released-images.tar.gz
+      - name: Upload Tailscale released images
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: tailscale-released-images
+          path: tailscale-released-images.tar.gz
+          retention-days: 10
+  sqlite:
+    needs: [build, build-tailscale-released]
+    if: needs.build.outputs.files-changed == 'true'
     strategy:
       fail-fast: false
       matrix:
@@ -202,6 +265,8 @@ jobs:
           - TestAuthWebFlowAuthenticationPingAll
           - TestAuthWebFlowLogoutAndReloginSameUser
           - TestAuthWebFlowLogoutAndReloginNewUser
+          - TestPolicyCheckCommand
+          - TestSSHTestsRejectFailingPolicy
           - TestUserCommand
           - TestPreAuthKeyCommand
           - TestPreAuthKeyCommandWithoutExpiry
@@ -239,6 +304,7 @@ jobs:
           - TestHASubnetRouterFailover
           - TestSubnetRouteACL
           - TestEnablingExitRoutes
+          - TestExitRoutesWithAutogroupInternetACL
           - TestSubnetRouterMultiNetwork
           - TestSubnetRouterMultiNetworkExitNode
           - TestAutoApproveMultiNetwork/authkey-tag.*
@@ -249,6 +315,10 @@ jobs:
           - TestAutoApproveMultiNetwork/webauth-group.*
           - TestSubnetRouteACLFiltering
           - TestGrantViaSubnetSteering
+          - TestHASubnetRouterPingFailover
+          - TestHASubnetRouterFailoverBothOffline
+          - TestHASubnetRouterFailoverBothOfflineCablePull
+          - TestHASubnetRouterFailoverDockerDisconnect
           - TestHeadscale
           - TestTailscaleNodesJoiningHeadcale
           - TestSSHOneUserToAll
@@ -262,6 +332,7 @@ jobs:
           - TestSSHCheckModeUnapprovedTimeout
           - TestSSHCheckModeCheckPeriodCLI
           - TestSSHCheckModeAutoApprove
+          - TestSSHCheckModeSessionLossReDelegates
           - TestSSHCheckModeNegativeCLI
           - TestSSHLocalpart
           - TestTagsAuthKeyWithTagRequestDifferentTag
@@ -296,6 +367,9 @@ jobs:
           - TestTagsAuthKeyWithoutUserInheritsTags
           - TestTagsAuthKeyWithoutUserRejectsAdvertisedTags
           - TestTagsAuthKeyConvertToUserViaCLIRegister
+          - TestTS2021WebSocketGET
+          - TestTS2021WASMClientUnderNode
+          - TestTailscaleRustAxum
     uses: ./.github/workflows/integration-test-template.yml
     secrets: inherit
     with:
@@ -303,7 +377,7 @@ jobs:
       postgres_flag: "--postgres=0"
       database_name: "sqlite"
   postgres:
-    needs: [build, build-postgres]
+    needs: [build, build-postgres, build-tailscale-released]
     if: needs.build.outputs.files-changed == 'true'
     strategy:
       fail-fast: false

.golangci.yaml

@@ -13,6 +13,7 @@ linters:
     - gochecknoinits
     - gocognit
     - godox
+    - gomodguard
     - interfacebloat
     - ireturn
     - lll
@@ -30,6 +31,17 @@ linters:
     - wrapcheck
     - wsl
   settings:
+    goconst:
+      # Test fixtures repeat strings (IPs, tags, hostnames) by their
+      # nature; extracting them obscures the test rather than helping.
+      # Production code stays strict.
+      ignore-tests: true
+      # Default is 3. Bump so "happens thrice" cases that are not part
+      # of a shared vocabulary do not get extracted.
+      min-occurrences: 5
+      # Default is 3. Short literals ("set", "get", "new") read better
+      # at call sites than behind a named constant.
+      min-len: 6
     forbidigo:
       forbid:
         # Forbid time.Sleep everywhere with context-appropriate alternatives

.goreleaser.yml

@@ -42,10 +42,9 @@ source:
     - "vendor/"
 
 nfpms:
-  # Configure nFPM for .deb and .rpm releases
+  # Configure nFPM for .deb releases
   #
-  # See https://nfpm.goreleaser.com/configuration/
-  # and https://goreleaser.com/customization/nfpm/
+  # See https://goreleaser.com/customization/package/nfpm/
   #
   # Useful tools for debugging .debs:
   # List file contents: dpkg -c dist/headscale...deb
@@ -79,6 +78,8 @@ nfpms:
         dst: /usr/lib/systemd/system/headscale.service
       - dst: /var/lib/headscale
         type: dir
+      - src: ./config-example.yaml
+        dst: /usr/share/doc/headscale/examples/config-example.yaml
       - src: LICENSE
         dst: /usr/share/doc/headscale/copyright
     scripts:

.pre-commit-config.yaml

@@ -13,6 +13,7 @@ repos:
     rev: v6.0.0
     hooks:
       - id: check-added-large-files
+        args: [--maxkb=1024]
       - id: check-case-conflict
       - id: check-executables-have-shebangs
       - id: check-json
@@ -60,3 +61,11 @@ repos:
         language: system
         types: [go]
         pass_filenames: false
+
+      # vendor-hash keeps flakehashes.json in sync with go.mod/go.sum.
+      - id: vendor-hash
+        name: vendor-hash
+        entry: nix develop --command -- go run ./cmd/vendorhash check
+        language: system
+        files: ^(go\.mod|go\.sum|flakehashes\.json)$
+        pass_filenames: false

AGENTS.md

@@ -198,7 +198,7 @@ databases. The `migrationsRequiringFKDisabled` map in
 
 Headscale enforces **tags XOR user ownership**: every node is either
 tagged (owned by tags) or user-owned (owned by a user namespace), never
-both. This is a load-bearing architectural invariant.
+both. This is a load-bearing architectural rule.
 
 - **Use `node.IsTagged()`** (`hscontrol/types/node.go:221`) to determine
   ownership, not `node.UserID().Valid()`. A tagged node may still have

CHANGELOG.md

@@ -1,8 +1,26 @@
 # CHANGELOG
 
-## 0.29.0 (202x-xx-xx)
+## 0.29.2 (2026-07-01)
 
-**Minimum supported Tailscale client version: v1.76.0**
+**Minimum supported Tailscale client version: v1.80.0**
+
+### Changes
+
+- Fix map generation serializing on the policy lock, so a mass reconnect on `autogroup:self`, via or relay policies no longer stalls clients into `unexpected EOF` retry loops [#3358](https://github.com/juanfont/headscale/pull/3358)
+- Fix `/ts2021` rejecting the WebSocket `GET` upgrade with 405, which prevented Tailscale JS/WASM control clients from connecting [#3359](https://github.com/juanfont/headscale/pull/3359)
+- Gracefully handle nodes with an invalid FQDN (empty or too long) instead of failing map delivery; offending names are logged at startup with the fix command [#3349](https://github.com/juanfont/headscale/pull/3349)
+
+## 0.29.1 (2026-06-18)
+
+**Minimum supported Tailscale client version: v1.80.0**
+
+### Changes
+
+- Fix nodes with `tags='null'` losing their assigned user on upgrade [#3325](https://github.com/juanfont/headscale/pull/3325)
+
+## 0.29.0 (2026-06-17)
+
+**Minimum supported Tailscale client version: v1.80.0**
 
 ### Tailscale ACL compatibility improvements
 
@@ -27,80 +45,288 @@ A new `headscale auth` CLI command group supports the approval flow:
 [#1850](https://github.com/juanfont/headscale/pull/1850)
 [#3180](https://github.com/juanfont/headscale/pull/3180)
 
+### Policy tests (beta)
+
+Headscale now evaluates the `tests` block in a policy file. Tests assert reachability between
+named sources and destinations and cover the whole policy — both `acls` and `grants` rules
+contribute. They run on user-initiated writes via `headscale policy set`, on SIGHUP reload
+(`systemctl reload headscale` / `kill -HUP $(pidof headscale)`), and on `headscale policy check`.
+A failing test rejects the write before it is applied, with the same error message Tailscale SaaS
+would return for the same policy.
+
+At boot a stored policy whose tests no longer pass — for example because a referenced user was
+deleted while the server was offline — logs a warning and the server keeps running. Fix the
+policy and reload.
+
+This feature is **beta** while behavioural coverage against Tailscale SaaS broadens.
+
+[#3229](https://github.com/juanfont/headscale/pull/3229)
+
+### SSH policy tests (beta)
+
+Headscale now evaluates the `sshTests` block in a policy file. Each entry names a source, one or
+more destination hosts, and three optional user lists: `accept` asserts the listed login users
+reach every destination via an accept- or check-action SSH rule, `deny` asserts none of them
+reach any destination, and `check` requires reachability specifically through a check-action
+rule. Tests run on `headscale policy set`, on SIGHUP reload (`systemctl reload headscale` /
+`kill -HUP $(pidof headscale)`), and on `headscale policy check`. A failing test rejects the
+write before it is applied, with the same error message Tailscale SaaS would return for the same
+policy.
+
+At boot a stored policy whose sshTests no longer pass — for example because a referenced user was
+deleted while the server was offline — logs a warning and the server keeps running. Fix the
+policy and reload.
+
+This feature is **beta** while behavioural coverage against Tailscale SaaS broadens.
+
+[#3263](https://github.com/juanfont/headscale/pull/3263)
+
+### SSH rule validation
+
+SSH rule parsing now trims surrounding whitespace on `action`, `users`, `src`, and `dst`,
+rejects empty or wildcard entries in `users`, rejects empty `acceptEnv`, and rejects negative
+`checkPeriod`. `hosts:` aliases are rejected as SSH destinations, non-ASCII tag names are
+rejected at parse time, and the wording for group-nesting cycles matches Tailscale SaaS.
+[#3263](https://github.com/juanfont/headscale/pull/3263)
+
 ### Grants
 
-We now support [Tailscale grants](https://tailscale.com/kb/1324/grants) alongside ACLs. Grants
-extend what you can express in a policy beyond packet filtering: the `app` field controls
-application-level features like Taildrive file sharing and peer relay, and the `via` field steers
-traffic through specific tagged subnet routers or exit nodes. The `ip` field works like an ACL rule.
-Grants can be mixed with ACLs in the same policy file.
+We now support [Tailscale grants](https://tailscale.com/docs/features/access-control/grants)
+alongside ACLs. Grants extend what you can express in a policy beyond packet filtering: the `app`
+field controls application-level features like Taildrive file sharing and peer relay, and the `via`
+field steers traffic through specific tagged subnet routers or exit nodes. The `ip` field works like
+an ACL rule. Grants can be mixed with ACLs in the same policy file.
 [#2180](https://github.com/juanfont/headscale/pull/2180)
 
-As part of this, we added `autogroup:danger-all`. It resolves to `0.0.0.0/0` and `::/0` — all IP
+As part of this, we added `autogroup:danger-all`. It resolves to `0.0.0.0/0` and `::/0`, all IP
 addresses, including those outside the tailnet. This replaces the old behaviour where `*` matched
-all IPs (see BREAKING below). The name is intentionally scary: accepting traffic from the entire
+all IPs (see BREAKING below). The name is intentional: accepting traffic from the entire
 internet is a security-sensitive choice. `autogroup:danger-all` can only be used as a source.
 
+### Node attributes (`nodeAttrs`)
+
+ACL policies now accept a `nodeAttrs` block. Each entry hands a list of
+Tailscale node capabilities to every node matching `target`. The accepted
+target forms are the same as `acls.src` and `grants.src`: users, groups,
+tags, hosts, prefixes, `autogroup:member`, `autogroup:tagged`, and `*`.
+
+```jsonc
+{
+  "randomizeClientPort": true,
+  "nodeAttrs": [
+    { "target": ["autogroup:tagged"], "attr": ["disable-captive-portal-detection"] },
+    { "target": ["alice@example.com"], "attr": ["nextdns:abc123"] },
+  ],
+}
+```
+
+Frequently requested capabilities this unlocks include `magicdns-aaaa`,
+`disable-relay-server`, `disable-captive-portal-detection`,
+`nextdns:<profile>` / `nextdns:no-device-info`, `randomize-client-port`,
+and the Taildrive `drive:share` / `drive:access` pair. The set is not
+limited to these, any string-only cap an operator places in policy
+reaches clients unchanged.
+
+`randomizeClientPort` also lands as a top-level policy field that toggles
+the default for every node, replacing the old server-config knob.
+
+A new `auto_update.enabled` config option controls the tailnet-wide
+default for client auto-update. When true, every node's CapMap carries
+`default-auto-update: [true]` so fresh clients pick up the default
+unless they make a local opt-in / opt-out choice.
+
+Policies that use the `funnel` cap, `ipPool` blocks, or
+`autogroup:admin` / `autogroup:owner` targets are rejected at load —
+those features depend on machinery headscale does not yet ship.
+
+[#3251](https://github.com/juanfont/headscale/pull/3251)
+
+### Taildrive
+
+Taildrive ([file-sync between
+nodes](https://tailscale.com/docs/features/taildrive)) is now
+configurable through policy. Grant `drive:share` to the node that
+hosts files and `drive:access` to nodes that read or write them; pair
+with a `tailscale.com/cap/drive` grant to set the per-share access
+mode:
+
+```jsonc
+{
+  "nodeAttrs": [
+    { "target": ["tag:fileserver"], "attr": ["drive:share"] },
+    { "target": ["autogroup:member"], "attr": ["drive:access"] },
+  ],
+  "grants": [
+    {
+      "src": ["autogroup:member"],
+      "dst": ["tag:fileserver"],
+      "app": {
+        "tailscale.com/cap/drive": [{ "shares": ["*"], "access": "rw" }],
+      },
+    },
+  ],
+}
+```
+
+A wildcard `nodeAttrs` (`"target": ["*"]`) hands the caps to every
+node when fine-grained control is not needed.
+
+### Hostname sanitisation
+
+Hostnames are now santised using Tailscales `magicdns` sanitisation rules, matching Tailscale SaaS behavior. This means that hostnames with non-ASCII characters, special characters, or reserved DNS label characters are now transformed into valid DNS labels for MagicDNS. This improves our previously too strict sanitisation that rejected hostnames based on our guesswork and not based on the Tailscale upstream behaviour.
+
+Examples that previously regressed and now work:
+
+| Input                | Raw (Hostname)       | DNS label (GivenName) |
+| -------------------- | -------------------- | --------------------- |
+| `Joe's Mac mini`     | `Joe's Mac mini`     | `joes-mac-mini`       |
+| `Yuri's MacBook Pro` | `Yuri's MacBook Pro` | `yuris-macbook-pro`   |
+| `Test@Host`          | `Test@Host`          | `test-host`           |
+| `mail.server`        | `mail.server`        | `mail-server`         |
+| `My-PC!`             | `My-PC!`             | `my-pc`               |
+| `我的电脑`           | `我的电脑`           | `node`                |
+
+[#3202](https://github.com/juanfont/headscale/pull/3202)
+
+### HA subnet router health probing
+
+Headscale now actively probes HA subnet routers to detect nodes that are connected but not
+forwarding traffic. The control plane periodically pings HA subnet routers via the Noise
+control channel and fails over to a healthy standby if the primary stops responding. This is
+enabled by default (`node.routes.ha.probe_interval: 10s`, `probe_timeout: 5s`) and only
+active when HA routes exist (2+ nodes advertising the same prefix). Set `probe_interval` to
+`0` to disable. This complements the existing disconnect-based failover, catching "zombie
+connected" routers that maintain their control session but cannot route packets.
+[#3194](https://github.com/juanfont/headscale/pull/3194)
+
 ### BREAKING
 
-- **ACL Policy**: Wildcard (`*`) in ACL sources and destinations now resolves to Tailscale's CGNAT range (`100.64.0.0/10`) and ULA range (`fd7a:115c:a1e0::/48`) instead of all IPs (`0.0.0.0/0` and `::/0`) [#3036](https://github.com/juanfont/headscale/pull/3036)
+#### Hostname handling
+
+- The `GivenName` collision policy changed from an 8-char random hash suffix (`laptop-abc12xyz`) to a monotonic numeric suffix (`laptop`, `laptop-1`, `laptop-2`, …), matching Tailscale SaaS. Empty / all-non-ASCII hostnames now fall back to the literal `node` instead of `invalid-<rand>`. MagicDNS names change on upgrade for any node whose previous label was a random-suffix form; the raw `Hostname` column is unchanged. [#3202](https://github.com/juanfont/headscale/pull/3202)
+
+#### ACL Policy
+
+- Wildcard (`*`) in ACL sources and destinations now resolves to Tailscale's CGNAT range (`100.64.0.0/10`) and ULA range (`fd7a:115c:a1e0::/48`) instead of all IPs (`0.0.0.0/0` and `::/0`) [#3036](https://github.com/juanfont/headscale/pull/3036)
   - This better matches Tailscale's security model where `*` means "any node in the tailnet" rather than "any IP address"
   - Policies that need to match all IP addresses including non-Tailscale IPs should use `autogroup:danger-all` as a source, or explicit CIDR ranges as destinations [#2180](https://github.com/juanfont/headscale/pull/2180)
   - `autogroup:danger-all` can only be used as a source; it cannot be used as a destination
   - **Note**: Users with non-standard IP ranges configured in `prefixes.ipv4` or `prefixes.ipv6` (which is unsupported and produces a warning) will need to explicitly specify their CIDR ranges in ACL rules instead of using `*`
-- **ACL Policy**: Validate autogroup:self source restrictions matching Tailscale behavior - tags, hosts, and IPs are rejected as sources for autogroup:self destinations [#3036](https://github.com/juanfont/headscale/pull/3036)
-  - Policies using tags, hosts, or IP addresses as sources for autogroup:self destinations will now fail validation
-- **Upgrade path**: Headscale now enforces a strict version upgrade path [#3083](https://github.com/juanfont/headscale/pull/3083)
+- Validate `autogroup:self` source restrictions matching Tailscale behavior - tags, hosts, and IPs are rejected as sources for `autogroup:self` destinations [#3036](https://github.com/juanfont/headscale/pull/3036)
+  - Policies using tags, hosts, or IP addresses as sources for `autogroup:self` destinations will now fail validation
+- The `proto:icmp` protocol name now only includes ICMPv4 (protocol 1), matching Tailscale behavior [#3036](https://github.com/juanfont/headscale/pull/3036)
+  - Previously, `proto:icmp` included both ICMPv4 and ICMPv6
+  - Use `proto:ipv6-icmp` or protocol number `58` explicitly for ICMPv6
+
+#### Upgrade Path
+
+- Headscale now enforces a strict version upgrade path [#3083](https://github.com/juanfont/headscale/pull/3083)
   - Skipping minor versions (e.g. 0.27 → 0.29) is blocked; upgrade one minor version at a time
   - Downgrading to a previous minor version is blocked
   - Patch version changes within the same minor are always allowed
-- **ACL Policy**: The `proto:icmp` protocol name now only includes ICMPv4 (protocol 1), matching Tailscale behavior [#3036](https://github.com/juanfont/headscale/pull/3036)
-  - Previously, `proto:icmp` included both ICMPv4 and ICMPv6
-  - Use `proto:ipv6-icmp` or protocol number `58` explicitly for ICMPv6
-- **CLI**: `headscale nodes register` is deprecated in favour of `headscale auth register --auth-id <id> --user <user>` [#1850](https://github.com/juanfont/headscale/pull/1850)
+
+#### Configuration
+
+- The `randomize_client_port` server-config key was removed; the
+  toggle now lives in the policy file as a top-level
+  `randomizeClientPort` field, matching the Tailscale-hosted schema. [#3251](https://github.com/juanfont/headscale/pull/3251)
+  Headscale refuses to start when the old key is set. Move it to the
+  policy file referenced by `policy.path`:
+
+  ```jsonc
+  {
+    "randomizeClientPort": true,
+  }
+  ```
+
+  If you do not have a policy file yet, create one with that minimal
+  content and point `policy.path` at it. The default carries over —
+  empty / absent policy means `randomizeClientPort: false`, matching
+  the previous behaviour for operators who never set the key. Per-node
+  opt-in via `nodeAttrs` is also supported and stacks on top of the
+  global default.
+
+#### CLI
+
+- `headscale nodes register` is deprecated in favour of `headscale auth register --auth-id <id> --user <user>` [#1850](https://github.com/juanfont/headscale/pull/1850)
   - The old command continues to work but will be removed in a future release
 
 ### Changes
 
-- **OIDC registration**: Add a confirmation page before completing node registration, showing the device hostname and machine key fingerprint [#3180](https://github.com/juanfont/headscale/pull/3180)
-- **Debug endpoints**: Omit secret fields (`Pass`, `ClientSecret`, `APIKey`) from `/debug/config` JSON output [#3180](https://github.com/juanfont/headscale/pull/3180)
-- **Debug endpoints**: Route `statsviz` through `tsweb.Protected` [#3180](https://github.com/juanfont/headscale/pull/3180)
-- Remove gRPC reflection from the remote (TCP) server [#3180](https://github.com/juanfont/headscale/pull/3180)
-- **Node Expiry**: Add `node.expiry` configuration option to set a default node key expiry for nodes registered via auth key [#3122](https://github.com/juanfont/headscale/pull/3122)
-  - Tagged nodes (registered with tagged pre-auth keys) are exempt from default expiry
-  - `oidc.expiry` has been removed; use `node.expiry` instead (applies to all registration methods including OIDC)
-  - `ephemeral_node_inactivity_timeout` is deprecated in favour of `node.ephemeral.inactivity_timeout`
-- **SSH Policy**: Add support for `localpart:*@<domain>` in SSH rule `users` field, mapping each matching user's email local-part as their OS username [#3091](https://github.com/juanfont/headscale/pull/3091)
-- **ACL Policy**: Add ICMP and IPv6-ICMP protocols to default filter rules when no protocol is specified [#3036](https://github.com/juanfont/headscale/pull/3036)
-- **ACL Policy**: Fix autogroup:self handling for tagged nodes - tagged nodes no longer incorrectly receive autogroup:self filter rules [#3036](https://github.com/juanfont/headscale/pull/3036)
-- **ACL Policy**: Use CIDR format for autogroup:self destination IPs matching Tailscale behavior [#3036](https://github.com/juanfont/headscale/pull/3036)
-- **ACL Policy**: Merge filter rules with identical SrcIPs and IPProto matching Tailscale behavior - multiple ACL rules with the same source now produce a single FilterRule with combined DstPorts [#3036](https://github.com/juanfont/headscale/pull/3036)
-- Remove deprecated `--namespace` flag from `nodes list`, `nodes register`, and `debug create-node` commands (use `--user` instead) [#3093](https://github.com/juanfont/headscale/pull/3093)
-- Remove deprecated `namespace`/`ns` command aliases for `users` and `machine`/`machines` aliases for `nodes` [#3093](https://github.com/juanfont/headscale/pull/3093)
-- Add SSH `check` action support with OIDC and CLI-based approval flows [#1850](https://github.com/juanfont/headscale/pull/1850)
-- Add `headscale auth register`, `headscale auth approve`, and `headscale auth reject` CLI commands [#1850](https://github.com/juanfont/headscale/pull/1850)
-- Add `auth` related routes to the API. The `auth/register` endpoint now expects data as JSON [#1850](https://github.com/juanfont/headscale/pull/1850)
-- Deprecate `headscale nodes register --key` in favour of `headscale auth register --auth-id` [#1850](https://github.com/juanfont/headscale/pull/1850)
-- Generalise auth templates into reusable `AuthSuccess` and `AuthWeb` components [#1850](https://github.com/juanfont/headscale/pull/1850)
-- Unify auth pipeline with `AuthVerdict` type, supporting registration, reauthentication, and SSH checks [#1850](https://github.com/juanfont/headscale/pull/1850)
-- Add support for policy grants with `ip`, `app`, and `via` fields [#2180](https://github.com/juanfont/headscale/pull/2180)
-- Add `autogroup:danger-all` as a source-only autogroup resolving to all IP addresses [#2180](https://github.com/juanfont/headscale/pull/2180)
-- Add capability grants for Taildrive (`cap/drive`) and peer relay (`cap/relay`) with automatic companion capabilities [#2180](https://github.com/juanfont/headscale/pull/2180)
-- Add per-viewer via route steering — grants with `via` tags control which subnet router or exit node handles traffic for each group of viewers [#2180](https://github.com/juanfont/headscale/pull/2180)
-- Enable Taildrive node attributes on all nodes; actual access is controlled by `cap/drive` grants [#2180](https://github.com/juanfont/headscale/pull/2180)
-- Fix exit nodes incorrectly receiving filter rules for destinations that only overlap via exit routes [#2180](https://github.com/juanfont/headscale/pull/2180)
+#### ACL Policy
+
+- Fix subnet-to-subnet peer visibility — subnet routers now correctly become peers when ACL rules reference only subnet CIDRs as sources, without requiring node IP rules [#3175](https://github.com/juanfont/headscale/pull/3175)
+- Fix filter rule reduction to use only approved subnet routes instead of all advertised routes, matching Tailscale SaaS behavior [#3175](https://github.com/juanfont/headscale/pull/3175)
+- Add ICMP and IPv6-ICMP protocols to default filter rules when no protocol is specified [#3036](https://github.com/juanfont/headscale/pull/3036)
+- Fix autogroup:self handling for tagged nodes - tagged nodes no longer incorrectly receive autogroup:self filter rules [#3036](https://github.com/juanfont/headscale/pull/3036)
+- Use CIDR format for autogroup:self destination IPs matching Tailscale behavior [#3036](https://github.com/juanfont/headscale/pull/3036)
+- Merge filter rules with identical SrcIPs and IPProto matching Tailscale behavior - multiple ACL rules with the same source now produce a single FilterRule with combined DstPorts [#3036](https://github.com/juanfont/headscale/pull/3036)
+- Fix exit nodes incorrectly receiving filter rules for destinations that only overlap via exit routes [#3169](https://github.com/juanfont/headscale/issues/3169) [#3175](https://github.com/juanfont/headscale/pull/3175)
 - Fix address-based aliases (hosts, raw IPs) incorrectly expanding to include the matching node's other address family [#2180](https://github.com/juanfont/headscale/pull/2180)
 - Fix identity-based aliases (tags, users, groups) resolving to IPv4 only; they now include both IPv4 and IPv6 matching Tailscale behavior [#2180](https://github.com/juanfont/headscale/pull/2180)
 - Fix wildcard (`*`) source in ACLs now using actually-approved subnet routes instead of autoApprover policy prefixes [#2180](https://github.com/juanfont/headscale/pull/2180)
 - Fix non-wildcard source IPs being dropped when combined with wildcard `*` in the same ACL rule [#2180](https://github.com/juanfont/headscale/pull/2180)
 - Fix exit node approval not triggering filter rule recalculation for peers [#2180](https://github.com/juanfont/headscale/pull/2180)
 - Policy validation error messages now include field context (e.g., `src=`, `dst=`) and are more descriptive [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Reject policies whose `user@` tokens match multiple DB users; rename the duplicate via `headscale users rename` to load [#3160](https://github.com/juanfont/headscale/issues/3160)
+- Evaluate the policy `tests` block on user-initiated writes across both `acls` and `grants`; reject policies whose tests fail (beta) [#1803](https://github.com/juanfont/headscale/issues/1803)
 
-## 0.28.1 (202x-xx-xx)
+#### Grants
 
-### Changes
+- Add support for policy grants with `ip`, `app`, and `via` fields [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Add `autogroup:danger-all` as a source-only autogroup resolving to all IP addresses [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Add capability grants for Taildrive (`cap/drive`) and peer relay (`cap/relay`) with automatic companion capabilities [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Add per-viewer via route steering — grants with `via` tags control which subnet router or exit node handles traffic for each group of viewers [#2180](https://github.com/juanfont/headscale/pull/2180)
+- Enable Taildrive node attributes on all nodes; actual access is controlled by `cap/drive` grants [#2180](https://github.com/juanfont/headscale/pull/2180)
 
-- **User deletion**: Fix `DestroyUser` deleting all pre-auth keys in the database instead of only the target user's keys [#3155](https://github.com/juanfont/headscale/pull/3155)
+#### SSH Policy
+
+- Add support for `localpart:*@<domain>` in SSH rule `users` field, mapping each matching user's email local-part as their OS username [#3091](https://github.com/juanfont/headscale/pull/3091)
+- Add SSH `check` action support with OIDC and CLI-based approval flows [#1850](https://github.com/juanfont/headscale/pull/1850)
+
+#### CLI
+
+- Add `headscale auth register`, `headscale auth approve`, and `headscale auth reject` CLI commands [#1850](https://github.com/juanfont/headscale/pull/1850)
+- Deprecate `headscale nodes register --key` in favour of `headscale auth register --auth-id` [#1850](https://github.com/juanfont/headscale/pull/1850)
+- `headscale policy check --bypass-grpc-and-access-database-directly` validates `user@` tokens against the live user database [#3160](https://github.com/juanfont/headscale/issues/3160)
+- Remove deprecated `--namespace` flag from `nodes list`, `nodes register`, and `debug create-node` commands (use `--user` instead) [#3093](https://github.com/juanfont/headscale/pull/3093)
+- Remove deprecated `namespace`/`ns` command aliases for `users` and `machine`/`machines` aliases for `nodes` [#3093](https://github.com/juanfont/headscale/pull/3093)
+- Fix `DestroyUser` deleting all pre-auth keys in the database instead of only the target user's keys [#3155](https://github.com/juanfont/headscale/pull/3155)
+- `headscale policy check` evaluates the `tests` block when invoked with `--bypass-grpc-and-access-database-directly`; without the flag it warns instead of running the tests against empty data [#1803](https://github.com/juanfont/headscale/issues/1803)
+
+#### API
+
+- Add `auth` related routes. The `auth/register` endpoint now expects data as JSON [#1850](https://github.com/juanfont/headscale/pull/1850)
+- Remove gRPC reflection from the remote (TCP) server [#3180](https://github.com/juanfont/headscale/pull/3180)
+
+#### OIDC
+
+- Add a confirmation page before completing node registration, showing the device hostname and machine key fingerprint [#3180](https://github.com/juanfont/headscale/pull/3180)
+- Generalise auth templates into reusable `AuthSuccess` and `AuthWeb` components [#1850](https://github.com/juanfont/headscale/pull/1850)
+- Unify auth pipeline with `AuthVerdict` type, supporting registration, reauthentication, and SSH checks [#1850](https://github.com/juanfont/headscale/pull/1850)
+
+#### Configuration
+
+- Add `node.expiry` configuration option to set a default node key expiry for nodes registered via auth key [#3122](https://github.com/juanfont/headscale/pull/3122)
+  - Tagged nodes (registered with tagged pre-auth keys) are exempt from default expiry
+  - `oidc.expiry` has been removed; use `node.expiry` instead (applies to all registration methods including OIDC)
+  - `ephemeral_node_inactivity_timeout` is deprecated in favour of `node.ephemeral.inactivity_timeout`
+- Add `trusted_proxies` to gate `True-Client-IP` / `X-Real-IP` / `X-Forwarded-For` (previously honoured from any client) [#3268](https://github.com/juanfont/headscale/pull/3268)
+
+#### Debug
+
+- Add node connectivity ping page for verifying control-plane reachability [#3183](https://github.com/juanfont/headscale/pull/3183)
+- Omit secret fields (`Pass`, `ClientSecret`, `APIKey`) from `/debug/config` JSON output [#3180](https://github.com/juanfont/headscale/pull/3180)
+- Route `statsviz` through `tsweb.Protected` [#3180](https://github.com/juanfont/headscale/pull/3180)
+
+#### Other
+
+- Remove old migrations for the debian package [#3185](https://github.com/juanfont/headscale/pull/3185)
+- Install `config-example.yaml` as example for the debian package [#3186](https://github.com/juanfont/headscale/pull/3186)
+- Fix user-owned re-registration with zero client expiry and no default storing `0001-01-01 00:00:00` in the database instead of `NULL` [#3199](https://github.com/juanfont/headscale/pull/3199)
+- Fix `tailscaled` restart on a node with no expiry resetting `NULL` to `0001-01-01 00:00:00` in the database, affecting both tagged and untagged nodes [#3197](https://github.com/juanfont/headscale/pull/3197)
+- Backfill `nodes.expiry` rows persisted by older versions as `0001-01-01 00:00:00` to `NULL`, so nodes upgraded from <0.28 stop reporting as expired [#3284](https://github.com/juanfont/headscale/issues/3284)
+- Update reverse proxy documentation for `trusted_proxies` configuration option [#3292](https://github.com/juanfont/headscale/pull/3292)
 
 ## 0.28.0 (2026-02-04)
 
@@ -111,7 +337,7 @@ internet is a security-sensitive choice. `autogroup:danger-all` can only be used
 Tags are now implemented following the Tailscale model where tags and user ownership are mutually exclusive. Devices can be either
 user-owned (authenticated via web/OIDC) or tagged (authenticated via tagged PreAuthKeys). Tagged devices receive their identity from
 tags rather than users, making them suitable for servers and infrastructure. Applying a tag to a device removes user-based
-ownership. See the [Tailscale tags documentation](https://tailscale.com/kb/1068/tags) for details on how tags work.
+ownership. See the [Tailscale tags documentation](https://tailscale.com/docs/features/tags) for details on how tags work.
 
 User-owned nodes can now request tags during registration using `--advertise-tags`. Tags are validated against the `tagOwners` policy
 and applied at registration time. Tags can be managed via the CLI or API after registration. Tagged nodes can return to user-owned
@@ -210,7 +436,7 @@ sequentially through each stable release, selecting the latest patch version ava
 
 - **SSH Policy**: SSH source/destination validation now enforces Tailscale's security model [#3010](https://github.com/juanfont/headscale/issues/3010)
 
-  Per [Tailscale SSH documentation](https://tailscale.com/kb/1193/tailscale-ssh), the following rules are now enforced:
+  Per [Tailscale SSH documentation](https://tailscale.com/docs/features/tailscale-ssh), the following rules are now enforced:
   1. **Tags cannot SSH to user-owned devices**: SSH rules with `tag:*` or `autogroup:tagged` as source cannot have username destinations (e.g., `alice@`) or `autogroup:member`/`autogroup:self` as destination
   2. **Username destinations require same-user source**: If destination is a specific username (e.g., `alice@`), the source must be that exact same user only. Use `autogroup:self` for same-user SSH access instead
 
@@ -339,8 +565,8 @@ DERPMap updates when upstream is changed.
 
 This release adds support for the three missing autogroups: `self`
 (experimental), `member`, and `tagged`. Please refer to the
-[documentation](https://tailscale.com/kb/1018/autogroups/) for a detailed
-explanation.
+[documentation](https://tailscale.com/docs/reference/targets-and-selectors#autogroups)
+for a detailed explanation.
 
 `autogroup:self` is marked as experimental and should be used with caution, but
 we need help testing it. Experimental here means two things; first, generating
@@ -503,7 +729,7 @@ The SSH policy has been reworked to be more consistent with the rest of the
 policy. In addition, several inconsistencies between our implementation and
 Tailscale's upstream has been closed and this might be a breaking change for
 some users. Please refer to the
-[upstream documentation](https://tailscale.com/kb/1337/acl-syntax#tailscale-ssh)
+[upstream documentation](https://tailscale.com/docs/reference/syntax/policy-file#tailscale-ssh)
 for more information on which types are allowed in `src`, `dst` and `users`.
 
 There is one large inconsistency left, we allow `*` as a destination as we
@@ -1017,7 +1243,7 @@ part of adopting [#1460](https://github.com/juanfont/headscale/pull/1460).
 
 - Added support for Tailscale TS2021 protocol [#738](https://github.com/juanfont/headscale/pull/738)
 - Add experimental support for
-  [SSH ACL](https://tailscale.com/kb/1018/acls/#tailscale-ssh) (see docs for
+  [SSH ACL](https://tailscale.com/docs/reference/syntax/policy-file#tailscale-ssh) (see docs for
   limitations) [#847](https://github.com/juanfont/headscale/pull/847)
   - Please note that this support should be considered _partially_ implemented
   - SSH ACLs status:
@@ -1094,7 +1320,7 @@ part of adopting [#1460](https://github.com/juanfont/headscale/pull/1460).
 ### BREAKING
 
 - Old ACL syntax is no longer supported ("users" & "ports" -> "src" & "dst").
-  Please check [the new syntax](https://tailscale.com/kb/1018/acls/).
+  Please check [the new syntax](https://tailscale.com/docs/features/access-control/acls).
 
 ### Changes
 
@@ -1124,7 +1350,7 @@ part of adopting [#1460](https://github.com/juanfont/headscale/pull/1460).
 - Add -c option to specify config file from command line [#285](https://github.com/juanfont/headscale/issues/285)
   [#612](https://github.com/juanfont/headscale/pull/601)
 - Add configuration option to allow Tailscale clients to use a random WireGuard
-  port. [kb/1181/firewalls](https://tailscale.com/kb/1181/firewalls)
+  port. [Tailscale docs](https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport)
   [#624](https://github.com/juanfont/headscale/pull/624)
 - Improve obtuse UX regarding missing configuration
   (`ephemeral_node_inactivity_timeout` not set)

Dockerfile.derper

@@ -1,6 +1,6 @@
 # For testing purposes only
 
-FROM golang:1.26.2-alpine AS build-env
+FROM golang:1.26.4-alpine AS build-env
 
 WORKDIR /go/src
 
@@ -12,7 +12,7 @@ WORKDIR /go/src/tailscale
 ARG TARGETARCH
 RUN GOARCH=$TARGETARCH go install -v ./cmd/derper
 
-FROM alpine:3.22
+FROM alpine:3.23
 RUN apk add --no-cache ca-certificates iptables iproute2 ip6tables curl
 
 COPY --from=build-env /go/bin/* /usr/local/bin/

Dockerfile.integration

@@ -2,7 +2,7 @@
 # and are in no way endorsed by Headscale's maintainers as an
 # official nor supported release or distribution.
 
-FROM docker.io/golang:1.26.1-trixie AS builder
+FROM docker.io/golang:1.26.4-trixie AS builder
 ARG VERSION=dev
 ENV GOPATH /go
 WORKDIR /go/src/headscale

Dockerfile.tailscale-HEAD

@@ -4,7 +4,7 @@
 # This Dockerfile is more or less lifted from tailscale/tailscale
 # to ensure a similar build process when testing the HEAD of tailscale.
 
-FROM golang:1.26.2-alpine AS build-env
+FROM golang:1.26.4-alpine AS build-env
 
 WORKDIR /go/src
 
@@ -36,7 +36,7 @@ RUN GOARCH=$TARGETARCH go install -tags="${BUILD_TAGS}" -ldflags="\
       -X tailscale.com/version.gitCommitStamp=$VERSION_GIT_HASH" \
       -v ./cmd/tailscale ./cmd/tailscaled ./cmd/containerboot
 
-FROM alpine:3.22
+FROM alpine:3.23
 # Upstream: ca-certificates ip6tables iptables iproute2
 # Tests: curl python3 (traceroute via BusyBox)
 RUN apk add --no-cache ca-certificates curl ip6tables iptables iproute2 python3

Dockerfile.tailscale-rs

@@ -0,0 +1,26 @@
+FROM rust:1.95-trixie AS builder
+
+ARG TAILSCALE_RS_REPO=https://github.com/tailscale/tailscale-rs.git
+ARG TAILSCALE_RS_REF=main
+
+WORKDIR /app
+RUN git clone --depth 1 --branch "$TAILSCALE_RS_REF" "$TAILSCALE_RS_REPO" .
+
+# Re-export ts_control's insecure-keyfetch feature through the tailscale
+# crate so the axum example can fetch the headscale control key over
+# plain HTTP. The integration harness serves the control plane without
+# TLS, and upstream only allows plain-HTTP key fetches when this Cargo
+# feature is compiled in.
+RUN sed -i '/^axum = \["dep:axum"\]/a insecure-keyfetch = ["ts_control/insecure-keyfetch"]' Cargo.toml
+
+RUN cargo build --release --features axum,insecure-keyfetch --example axum
+
+FROM debian:trixie-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    ca-certificates \
+    iproute2 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/target/release/examples/axum /usr/local/bin/axum

Dockerfile.wasmclient

@@ -0,0 +1,30 @@
+# For integration testing only.
+#
+# Builds the Tailscale control client (integration/wasmic/wasmclient) for
+# GOOS=js/GOARCH=wasm and packages it with Go's wasm_exec Node runner. The
+# container idles; the integration test execs
+#   node /app/wasm_exec_node.js /app/client.wasm <control-url>
+# to drive a real browser-style WebSocket GET against headscale's /ts2021,
+# guarding the regression in issue #3357.
+
+FROM golang:1.26.4-alpine AS build
+
+WORKDIR /src
+
+# Only the module metadata and the wasm client package are needed to build the
+# js/wasm binary; its imports (tailscale.com/control/controlhttp, ...) resolve
+# from the module proxy.
+COPY go.mod go.sum ./
+COPY integration/wasmic/wasmclient ./integration/wasmic/wasmclient
+
+RUN GOOS=js GOARCH=wasm go build -o /out/client.wasm ./integration/wasmic/wasmclient \
+    && cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" /out/wasm_exec.js \
+    && cp "$(go env GOROOT)/lib/wasm/wasm_exec_node.js" /out/wasm_exec_node.js
+
+FROM node:24-alpine
+
+WORKDIR /app
+COPY --from=build /out/ /app/
+
+# Idle; the test execs the client on demand with the headscale control URL.
+ENTRYPOINT ["tail", "-f", "/dev/null"]

Makefile

@@ -105,6 +105,11 @@ clean:
 .PHONY: dev
 dev: fmt lint test build
 
+# Start a local headscale dev server (use mts to add nodes)
+.PHONY: dev-server
+dev-server:
+	go run ./cmd/dev
+
 # Help target
 .PHONY: help
 help:

README.md

@@ -30,8 +30,8 @@ nodes in the Tailscale network. It assigns the IP addresses of the clients,
 creates the boundaries between each user, enables sharing machines between users,
 and exposes the advertised routes of your nodes.
 
-A [Tailscale network (tailnet)](https://tailscale.com/kb/1136/tailnet/) is private
-network which Tailscale assigns to a user in terms of private users or an
+A [Tailscale network (tailnet)](https://tailscale.com/docs/concepts/tailnet) is
+private network which Tailscale assigns to a user in terms of private users or an
 organisation.
 
 ## Design goal

cmd/dev/README.md

@@ -0,0 +1,96 @@
+# cmd/dev -- Local Development Environment
+
+Starts a headscale server on localhost with a pre-created user and
+pre-auth key. Pair with `mts` to add real tailscale nodes.
+
+## Quick start
+
+```bash
+# Terminal 1: start headscale
+go run ./cmd/dev
+
+# Terminal 2: start mts server
+go tool mts server run
+
+# Terminal 3: add and connect nodes
+go tool mts server add node1
+go tool mts server add node2
+
+# Disable logtail (avoids startup delays, see "Known issues" below)
+for n in node1 node2; do
+  cat > ~/.config/multi-tailscale-dev/$n/env.txt << 'EOF'
+TS_NO_LOGS_NO_SUPPORT=true
+EOF
+done
+
+# Restart nodes so env.txt takes effect
+go tool mts server stop node1 && go tool mts server start node1
+go tool mts server stop node2 && go tool mts server start node2
+
+# Connect to headscale (use the auth key printed by cmd/dev)
+go tool mts node1 up --login-server=http://127.0.0.1:8080 --authkey=<KEY> --reset
+go tool mts node2 up --login-server=http://127.0.0.1:8080 --authkey=<KEY> --reset
+
+# Verify
+go tool mts node1 status
+```
+
+## Flags
+
+| Flag     | Default | Description                  |
+| -------- | ------- | ---------------------------- |
+| `--port` | 8080    | Headscale listen port        |
+| `--keep` | false   | Keep state directory on exit |
+
+The metrics/debug port is `port + 1010` (default 9090) and the gRPC
+port is `port + 42363` (default 50443).
+
+## What it does
+
+1. Builds the headscale binary into a temp directory
+2. Writes a minimal dev config (SQLite, public DERP, debug logging)
+3. Starts `headscale serve` as a subprocess
+4. Creates a "dev" user and a reusable 24h pre-auth key via the CLI
+5. Prints a banner with server URL, auth key, and usage instructions
+6. Blocks until Ctrl+C, then kills headscale
+
+State lives in `/tmp/headscale-dev-*/`. Pass `--keep` to preserve it
+across restarts (useful for inspecting the database or reusing keys).
+
+## Useful endpoints
+
+- `http://127.0.0.1:8080/health` -- health check
+- `http://127.0.0.1:9090/debug/ping` -- interactive ping UI
+- `http://127.0.0.1:9090/debug/ping?node=1` -- quick-ping a node
+- `POST http://127.0.0.1:9090/debug/ping` with `node=<id>` -- trigger ping
+
+## Managing headscale
+
+The banner prints the full path to the built binary and config. Use it
+for any headscale CLI command:
+
+```bash
+/tmp/headscale-dev-*/headscale -c /tmp/headscale-dev-*/config.yaml nodes list
+/tmp/headscale-dev-*/headscale -c /tmp/headscale-dev-*/config.yaml users list
+```
+
+## Known issues
+
+### Logtail delays on mts nodes
+
+Freshly created `mts` instances may take 30+ seconds to start if
+`~/.local/share/tailscale/` contains stale logtail cache from previous
+tailscaled runs. The daemon blocks trying to upload old logs before
+creating its socket.
+
+Fix: write `TS_NO_LOGS_NO_SUPPORT=true` to each instance's `env.txt`
+before starting (or restart after writing). See the quick start above.
+
+### mts node cleanup
+
+`mts` stores state in `~/.config/multi-tailscale-dev/`. Old instances
+accumulate over time. Clean them with:
+
+```bash
+go tool mts server rm <name>
+```

cmd/dev/main.go

@@ -0,0 +1,314 @@
+// cmd/dev starts a local headscale development server with a pre-created
+// user and pre-auth key, ready for connecting tailscale nodes via mts.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"os/exec"
+	"os/signal"
+	"path/filepath"
+	"strconv"
+	"syscall"
+	"time"
+)
+
+var (
+	port = flag.Int("port", 8080, "headscale listen port")
+	keep = flag.Bool("keep", false, "keep state directory on exit")
+)
+
+var errHealthTimeout = errors.New("health check timed out")
+
+var errEmptyAuthKey = errors.New("empty auth key in response")
+
+// maxDevPort is the highest --port value that keeps both the derived
+// metrics port (port+1010) and gRPC port (port+42363) inside the valid
+// 1..65535 TCP range.
+const maxDevPort = 23172
+
+const devConfig = `---
+server_url: http://127.0.0.1:%d
+listen_addr: 127.0.0.1:%d
+metrics_listen_addr: 127.0.0.1:%d
+grpc_listen_addr: 127.0.0.1:%d
+grpc_allow_insecure: true
+
+noise:
+  private_key_path: %s/noise_private.key
+
+prefixes:
+  v4: 100.64.0.0/10
+  v6: fd7a:115c:a1e0::/48
+  allocation: sequential
+
+database:
+  type: sqlite
+  sqlite:
+    path: %s/db.sqlite
+    write_ahead_log: true
+
+derp:
+  server:
+    enabled: false
+  urls:
+    - https://controlplane.tailscale.com/derpmap/default
+  auto_update_enabled: false
+
+dns:
+  magic_dns: true
+  base_domain: headscale.dev
+  override_local_dns: false
+
+log:
+  level: debug
+  format: text
+
+policy:
+  mode: database
+
+unix_socket: %s/headscale.sock
+unix_socket_permission: "0770"
+`
+
+func main() {
+	flag.Parse()
+	log.SetFlags(0)
+
+	if *port < 1 || *port > maxDevPort {
+		log.Fatalf(
+			"--port must be in 1..%d (higher values overflow the derived gRPC port); got %d",
+			maxDevPort, *port,
+		)
+	}
+
+	http.DefaultClient.Timeout = 2 * time.Second
+	http.DefaultClient.CheckRedirect = func(*http.Request, []*http.Request) error {
+		return http.ErrUseLastResponse
+	}
+
+	err := run()
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
+func run() error {
+	metricsPort := *port + 1010 // default 9090
+	grpcPort := *port + 42363   // default 50443
+
+	tmpDir, err := os.MkdirTemp("", "headscale-dev-")
+	if err != nil {
+		return fmt.Errorf("creating temp dir: %w", err)
+	}
+
+	if !*keep {
+		defer os.RemoveAll(tmpDir)
+	}
+
+	// Write config.
+	configPath := filepath.Join(tmpDir, "config.yaml")
+	configContent := fmt.Sprintf(devConfig,
+		*port, *port, metricsPort, grpcPort,
+		tmpDir, tmpDir, tmpDir,
+	)
+
+	err = os.WriteFile(configPath, []byte(configContent), 0o600)
+	if err != nil {
+		return fmt.Errorf("writing config: %w", err)
+	}
+
+	// Build headscale.
+	fmt.Println("Building headscale...")
+
+	hsBin := filepath.Join(tmpDir, "headscale")
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	build := exec.CommandContext(ctx, "go", "build", "-o", hsBin, "./cmd/headscale")
+	build.Stdout = os.Stdout
+	build.Stderr = os.Stderr
+
+	err = build.Run()
+	if err != nil {
+		return fmt.Errorf("building headscale: %w", err)
+	}
+
+	// Start headscale serve.
+	fmt.Println("Starting headscale server...")
+
+	serve := exec.CommandContext(ctx, hsBin, "serve", "-c", configPath)
+	serve.Stdout = os.Stdout
+	serve.Stderr = os.Stderr
+
+	err = serve.Start()
+	if err != nil {
+		return fmt.Errorf("starting headscale: %w", err)
+	}
+
+	// Wait for server to be ready.
+	healthURL := fmt.Sprintf("http://127.0.0.1:%d/health", *port)
+
+	err = waitForHealth(ctx, healthURL, 30*time.Second)
+	if err != nil {
+		return fmt.Errorf("waiting for headscale: %w", err)
+	}
+
+	// Create user.
+	fmt.Println("Creating user and pre-auth key...")
+
+	userJSON, err := runHS(ctx, hsBin, configPath, "users", "create", "dev", "-o", "json")
+	if err != nil {
+		return fmt.Errorf("creating user: %w", err)
+	}
+
+	userID, err := extractUserID(userJSON)
+	if err != nil {
+		return fmt.Errorf("parsing user: %w", err)
+	}
+
+	// Create pre-auth key.
+	keyJSON, err := runHS(
+		ctx, hsBin, configPath,
+		"preauthkeys", "create",
+		"-u", strconv.FormatUint(userID, 10),
+		"--reusable",
+		"-e", "24h",
+		"-o", "json",
+	)
+	if err != nil {
+		return fmt.Errorf("creating pre-auth key: %w", err)
+	}
+
+	authKey, err := extractAuthKey(keyJSON)
+	if err != nil {
+		return fmt.Errorf("parsing pre-auth key: %w", err)
+	}
+
+	// Print banner.
+	fmt.Printf(`
+=== Headscale Dev Environment ===
+  Server:  http://127.0.0.1:%d
+  Metrics: http://127.0.0.1:%d
+  Debug:   http://127.0.0.1:%d/debug/ping
+  Config:  %s
+  State:   %s
+
+Pre-auth key: %s
+
+Connect nodes with mts:
+  go tool mts server run                  # start mts (once, another terminal)
+  go tool mts server add node1            # create a node
+  go tool mts node1 up --login-server=http://127.0.0.1:%d --authkey=%s
+  go tool mts node1 status                # check connection
+
+Manage headscale:
+  %s -c %s nodes list
+  %s -c %s users list
+
+Press Ctrl+C to stop.
+`,
+		*port, metricsPort, metricsPort,
+		configPath, tmpDir,
+		authKey,
+		*port, authKey,
+		hsBin, configPath,
+		hsBin, configPath,
+	)
+
+	// Wait for headscale to exit.
+	err = serve.Wait()
+	if err != nil {
+		// Context cancellation is expected on Ctrl+C.
+		if ctx.Err() != nil {
+			fmt.Println("\nShutting down...")
+
+			return nil
+		}
+
+		return fmt.Errorf("headscale exited: %w", err)
+	}
+
+	return nil
+}
+
+// waitForHealth polls the health endpoint until it returns 200 or the
+// timeout expires.
+func waitForHealth(ctx context.Context, url string, timeout time.Duration) error {
+	deadline := time.Now().Add(timeout)
+
+	for time.Now().Before(deadline) {
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+		if err != nil {
+			return fmt.Errorf("creating request: %w", err)
+		}
+
+		resp, err := http.DefaultClient.Do(req)
+		if err == nil {
+			resp.Body.Close()
+
+			if resp.StatusCode == http.StatusOK {
+				return nil
+			}
+		}
+
+		// Busy-wait is acceptable for a dev tool polling a local server.
+		time.Sleep(200 * time.Millisecond) //nolint:forbidigo
+	}
+
+	return errHealthTimeout
+}
+
+// runHS executes a headscale CLI command and returns its stdout.
+func runHS(ctx context.Context, bin, config string, args ...string) ([]byte, error) {
+	fullArgs := append([]string{"-c", config}, args...)
+	cmd := exec.CommandContext(ctx, bin, fullArgs...)
+	cmd.Stderr = os.Stderr
+
+	return cmd.Output()
+}
+
+// extractUserID parses the JSON output of "users create" and returns the
+// user ID.
+func extractUserID(data []byte) (uint64, error) {
+	var user struct {
+		ID uint64 `json:"id"`
+	}
+
+	err := json.Unmarshal(data, &user)
+	if err != nil {
+		return 0, fmt.Errorf("unmarshalling user JSON: %w (raw: %s)", err, data)
+	}
+
+	return user.ID, nil
+}
+
+// extractAuthKey parses the JSON output of "preauthkeys create" and
+// returns the key string.
+func extractAuthKey(data []byte) (string, error) {
+	var key struct {
+		Key string `json:"key"`
+	}
+
+	err := json.Unmarshal(data, &key)
+	if err != nil {
+		return "", fmt.Errorf("unmarshalling key JSON: %w (raw: %s)", err, data)
+	}
+
+	if key.Key == "" {
+		return "", errEmptyAuthKey
+	}
+
+	return key.Key, nil
+}

cmd/headscale/cli/api_key.go

@@ -41,9 +41,9 @@ var apiKeysCmd = &cobra.Command{
 }
 
 var listAPIKeys = &cobra.Command{
-	Use:     "list",
+	Use:     cmdList,
 	Short:   "List the Api keys for headscale",
-	Aliases: []string{"ls", "show"},
+	Aliases: []string{"ls", cmdShow},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		response, err := client.ListApiKeys(ctx, &v1.ListApiKeysRequest{})
 		if err != nil {
@@ -51,9 +51,8 @@ var listAPIKeys = &cobra.Command{
 		}
 
 		return printListOutput(cmd, response.GetApiKeys(), func() error {
-			tableData := pterm.TableData{
-				{"ID", "Prefix", "Expiration", "Created"},
-			}
+			tableData := make(pterm.TableData, 1, 1+len(response.GetApiKeys()))
+			tableData[0] = []string{"ID", "Prefix", colExpiration, colCreated}
 
 			for _, key := range response.GetApiKeys() {
 				expiration := "-"
@@ -81,8 +80,8 @@ var createAPIKeyCmd = &cobra.Command{
 	Long: `
 Creates a new Api key, the Api key is only visible on creation
 and cannot be retrieved again.
-If you loose a key, create a new one and revoke (expire) the old one.`,
-	Aliases: []string{"c", "new"},
+If you lose a key, create a new one and revoke (expire) the old one.`,
+	Aliases: []string{"c", cmdNew},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		expiration, err := expirationFromFlag(cmd)
 		if err != nil {
@@ -117,9 +116,9 @@ func apiKeyIDOrPrefix(cmd *cobra.Command) (uint64, string, error) {
 }
 
 var expireAPIKeyCmd = &cobra.Command{
-	Use:     "expire",
+	Use:     cmdExpire,
 	Short:   "Expire an ApiKey",
-	Aliases: []string{"revoke", "exp", "e"},
+	Aliases: []string{"revoke", aliasExp, "e"},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		id, prefix, err := apiKeyIDOrPrefix(cmd)
 		if err != nil {
@@ -139,9 +138,9 @@ var expireAPIKeyCmd = &cobra.Command{
 }
 
 var deleteAPIKeyCmd = &cobra.Command{
-	Use:     "delete",
+	Use:     cmdDelete,
 	Short:   "Delete an ApiKey",
-	Aliases: []string{"remove", "del"},
+	Aliases: []string{"remove", aliasDel},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		id, prefix, err := apiKeyIDOrPrefix(cmd)
 		if err != nil {

cmd/headscale/cli/nodes.go

@@ -89,9 +89,9 @@ var registerNodeCmd = &cobra.Command{
 }
 
 var listNodesCmd = &cobra.Command{
-	Use:     "list",
+	Use:     cmdList,
 	Short:   "List nodes",
-	Aliases: []string{"ls", "show"},
+	Aliases: []string{"ls", cmdShow},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		user, _ := cmd.Flags().GetString("user")
 
@@ -101,7 +101,7 @@ var listNodesCmd = &cobra.Command{
 		}
 
 		return printListOutput(cmd, response.GetNodes(), func() error {
-			tableData, err := nodesToPtables(user, response.GetNodes())
+			tableData, err := nodesToPtables(response.GetNodes())
 			if err != nil {
 				return fmt.Errorf("converting to table: %w", err)
 			}
@@ -145,12 +145,12 @@ var listNodeRoutesCmd = &cobra.Command{
 }
 
 var expireNodeCmd = &cobra.Command{
-	Use:   "expire",
+	Use:   cmdExpire,
 	Short: "Expire (log out) a node in your network",
 	Long: `Expiring a node will keep the node in the database and force it to reauthenticate.
 
 Use --disable to disable key expiry (node will never expire).`,
-	Aliases: []string{"logout", "exp", "e"},
+	Aliases: []string{"logout", aliasExp, "e"},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		identifier, _ := cmd.Flags().GetUint64("identifier")
 		disableExpiry, _ := cmd.Flags().GetBool("disable")
@@ -175,8 +175,10 @@ Use --disable to disable key expiry (node will never expire).`,
 		now := time.Now()
 
 		expiryTime := now
+
 		if expiry != "" {
 			var err error
+
 			expiryTime, err = time.Parse(time.RFC3339, expiry)
 			if err != nil {
 				return fmt.Errorf("parsing expiry time: %w", err)
@@ -227,9 +229,9 @@ var renameNodeCmd = &cobra.Command{
 }
 
 var deleteNodeCmd = &cobra.Command{
-	Use:     "delete",
+	Use:     cmdDelete,
 	Short:   "Delete a node",
-	Aliases: []string{"del"},
+	Aliases: []string{aliasDel},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		identifier, _ := cmd.Flags().GetUint64("identifier")
 
@@ -250,7 +252,7 @@ var deleteNodeCmd = &cobra.Command{
 			"Do you want to remove the node %s?",
 			getResponse.GetNode().GetName(),
 		)) {
-			return printOutput(cmd, map[string]string{"Result": "Node not deleted"}, "Node not deleted")
+			return printOutput(cmd, map[string]string{colResult: "Node not deleted"}, "Node not deleted")
 		}
 
 		_, err = client.DeleteNode(ctx, deleteRequest)
@@ -260,7 +262,7 @@ var deleteNodeCmd = &cobra.Command{
 
 		return printOutput(
 			cmd,
-			map[string]string{"Result": "Node deleted"},
+			map[string]string{colResult: "Node deleted"},
 			"Node deleted",
 		)
 	}),
@@ -302,10 +304,7 @@ be assigned to nodes.`,
 	},
 }
 
-func nodesToPtables(
-	currentUser string,
-	nodes []*v1.Node,
-) (pterm.TableData, error) {
+func nodesToPtables(nodes []*v1.Node) (pterm.TableData, error) {
 	tableHeader := []string{
 		"ID",
 		"Hostname",
@@ -317,11 +316,12 @@ func nodesToPtables(
 		"IP addresses",
 		"Ephemeral",
 		"Last seen",
-		"Expiration",
+		colExpiration,
 		"Connected",
 		"Expired",
 	}
-	tableData := pterm.TableData{tableHeader}
+	tableData := make(pterm.TableData, 1, 1+len(nodes))
+	tableData[0] = tableHeader
 
 	for _, node := range nodes {
 		var ephemeral bool
@@ -397,6 +397,7 @@ func nodesToPtables(
 		}
 
 		var ipBuilder strings.Builder
+
 		for _, addr := range node.GetIpAddresses() {
 			ip, err := netip.ParseAddr(addr)
 			if err == nil {
@@ -444,7 +445,8 @@ func nodeRoutesToPtables(
 		"Available",
 		"Serving (Primary)",
 	}
-	tableData := pterm.TableData{tableHeader}
+	tableData := make(pterm.TableData, 1, 1+len(nodes))
+	tableData[0] = tableHeader
 
 	for _, node := range nodes {
 		nodeData := []string{

cmd/headscale/cli/policy.go

@@ -48,6 +48,7 @@ func init() {
 	policyCmd.AddCommand(setPolicy)
 
 	checkPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
+	checkPolicy.Flags().BoolP(bypassFlag, "", false, "Open the database directly (no gRPC, no running server) to resolve user references and to evaluate the policy's tests and sshTests blocks. Required when those checks are needed.")
 	mustMarkRequired(checkPolicy, "file")
 	policyCmd.AddCommand(checkPolicy)
 }
@@ -60,9 +61,10 @@ var policyCmd = &cobra.Command{
 var getPolicy = &cobra.Command{
 	Use:     "get",
 	Short:   "Print the current ACL Policy",
-	Aliases: []string{"show", "view", "fetch"},
+	Aliases: []string{cmdShow, "view", "fetch"},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		var policyData string
+
 		if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
 			if !confirmAction(cmd, "DO NOT run this command if an instance of headscale is running, are you sure headscale is not running?") {
 				return errAborted
@@ -169,6 +171,11 @@ var setPolicy = &cobra.Command{
 var checkPolicy = &cobra.Command{
 	Use:   "check",
 	Short: "Check the Policy file for errors",
+	Long: `
+	Check validates the policy against the server's live users and nodes,
+	running any "tests" or "sshTests" block. By default the command is a
+	thin frontend for a gRPC call to a running headscale; pass --` + bypassFlag + ` to
+	open the database directly when headscale is not running.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		policyPath, _ := cmd.Flags().GetString("file")
 
@@ -177,9 +184,56 @@ var checkPolicy = &cobra.Command{
 			return fmt.Errorf("reading policy file: %w", err)
 		}
 
-		_, err = policy.NewPolicyManager(policyBytes, nil, views.Slice[types.NodeView]{})
+		if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
+			if !confirmAction(cmd, "DO NOT run this command if an instance of headscale is running, are you sure headscale is not running?") {
+				return errAborted
+			}
+
+			d, err := bypassDatabase()
+			if err != nil {
+				return err
+			}
+			defer d.Close()
+
+			users, err := d.ListUsers()
+			if err != nil {
+				return fmt.Errorf("loading users: %w", err)
+			}
+
+			nodes, err := d.ListNodes()
+			if err != nil {
+				return fmt.Errorf("loading nodes: %w", err)
+			}
+
+			// [policy.NewPolicyManager] validates structure and user references
+			// but intentionally skips test evaluation (boot path).
+			// [policy.PolicyManager.SetPolicy] is the user-write boundary and is what runs the
+			// tests and sshTests blocks.
+			pm, err := policy.NewPolicyManager(policyBytes, users, nodes.ViewSlice())
+			if err != nil {
+				return fmt.Errorf("parsing policy file: %w", err)
+			}
+
+			_, err = pm.SetPolicy(policyBytes)
+			if err != nil {
+				return err
+			}
+
+			fmt.Println("Policy is valid")
+
+			return nil
+		}
+
+		ctx, client, conn, cancel, err := newHeadscaleCLIWithConfig()
 		if err != nil {
-			return fmt.Errorf("parsing policy file: %w", err)
+			return fmt.Errorf("connecting to headscale: %w", err)
+		}
+		defer cancel()
+		defer conn.Close()
+
+		_, err = client.CheckPolicy(ctx, &v1.CheckPolicyRequest{Policy: string(policyBytes)})
+		if err != nil {
+			return err
 		}
 
 		fmt.Println("Policy is valid")

cmd/headscale/cli/preauthkeys.go

@@ -42,9 +42,9 @@ var preauthkeysCmd = &cobra.Command{
 }
 
 var listPreAuthKeys = &cobra.Command{
-	Use:     "list",
+	Use:     cmdList,
 	Short:   "List all preauthkeys",
-	Aliases: []string{"ls", "show"},
+	Aliases: []string{"ls", cmdShow},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		response, err := client.ListPreAuthKeys(ctx, &v1.ListPreAuthKeysRequest{})
 		if err != nil {
@@ -52,17 +52,16 @@ var listPreAuthKeys = &cobra.Command{
 		}
 
 		return printListOutput(cmd, response.GetPreAuthKeys(), func() error {
-			tableData := pterm.TableData{
-				{
-					"ID",
-					"Key/Prefix",
-					"Reusable",
-					"Ephemeral",
-					"Used",
-					"Expiration",
-					"Created",
-					"Owner",
-				},
+			tableData := make(pterm.TableData, 1, 1+len(response.GetPreAuthKeys()))
+			tableData[0] = []string{
+				"ID",
+				"Key/Prefix",
+				"Reusable",
+				"Ephemeral",
+				"Used",
+				colExpiration,
+				colCreated,
+				"Owner",
 			}
 
 			for _, key := range response.GetPreAuthKeys() {
@@ -100,7 +99,7 @@ var listPreAuthKeys = &cobra.Command{
 var createPreAuthKeyCmd = &cobra.Command{
 	Use:     "create",
 	Short:   "Creates a new preauthkey",
-	Aliases: []string{"c", "new"},
+	Aliases: []string{"c", cmdNew},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		user, _ := cmd.Flags().GetUint64("user")
 		reusable, _ := cmd.Flags().GetBool("reusable")
@@ -130,9 +129,9 @@ var createPreAuthKeyCmd = &cobra.Command{
 }
 
 var expirePreAuthKeyCmd = &cobra.Command{
-	Use:     "expire",
+	Use:     cmdExpire,
 	Short:   "Expire a preauthkey",
-	Aliases: []string{"revoke", "exp", "e"},
+	Aliases: []string{"revoke", aliasExp, "e"},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		id, _ := cmd.Flags().GetUint64("id")
 
@@ -154,9 +153,9 @@ var expirePreAuthKeyCmd = &cobra.Command{
 }
 
 var deletePreAuthKeyCmd = &cobra.Command{
-	Use:     "delete",
+	Use:     cmdDelete,
 	Short:   "Delete a preauthkey",
-	Aliases: []string{"del", "rm", "d"},
+	Aliases: []string{aliasDel, "rm", "d"},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		id, _ := cmd.Flags().GetUint64("id")
 

cmd/headscale/cli/root.go

@@ -3,7 +3,6 @@ package cli
 import (
 	"os"
 	"runtime"
-	"slices"
 	"strings"
 
 	"github.com/juanfont/headscale/hscontrol/types"
@@ -22,11 +21,6 @@ func init() {
 		return
 	}
 
-	if slices.Contains(os.Args, "policy") && slices.Contains(os.Args, "check") {
-		zerolog.SetGlobalLevel(zerolog.Disabled)
-		return
-	}
-
 	cobra.OnInitialize(initConfig)
 	rootCmd.PersistentFlags().
 		StringVarP(&cfgFile, "config", "c", "", "config file (default is /etc/headscale/config.yaml)")
@@ -36,7 +30,7 @@ func init() {
 		Bool("force", false, "Disable prompts and forces the execution")
 
 	// Re-enable usage output only for flag-parsing errors; runtime errors
-	// from RunE should never dump usage text.
+	// from [cobra.Command.RunE] should never dump usage text.
 	rootCmd.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
 		cmd.SilenceUsage = false
 

cmd/headscale/cli/root_test.go

@@ -4,6 +4,19 @@ import (
 	"testing"
 )
 
+const (
+	v23       = "0.23.0"
+	v23Alpha1 = "0.23.0-alpha.1"
+	v23Beta1  = "0.23.0-beta.1"
+	v23RC1    = "0.23.0-rc.1"
+	v23Dev    = "0.23.0-dev"
+	v231      = "0.23.1"
+
+	v24Alpha1Tag = "v0.24.0-alpha.1"
+	v24RCTag     = "v0.24.0-rc.1"
+	v24Tag       = "v0.24.0"
+)
+
 func TestFilterPreReleasesIfStable(t *testing.T) {
 	tests := []struct {
 		name           string
@@ -14,64 +27,64 @@ func TestFilterPreReleasesIfStable(t *testing.T) {
 	}{
 		{
 			name:           "stable version filters alpha tag",
-			currentVersion: "0.23.0",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v23,
+			tag:            v24Alpha1Tag,
 			expectedFilter: true,
 			description:    "When on stable release, alpha tags should be filtered",
 		},
 		{
 			name:           "stable version filters beta tag",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v0.24.0-beta.2",
 			expectedFilter: true,
 			description:    "When on stable release, beta tags should be filtered",
 		},
 		{
 			name:           "stable version filters rc tag",
-			currentVersion: "0.23.0",
-			tag:            "v0.24.0-rc.1",
+			currentVersion: v23,
+			tag:            v24RCTag,
 			expectedFilter: true,
 			description:    "When on stable release, rc tags should be filtered",
 		},
 		{
 			name:           "stable version allows stable tag",
-			currentVersion: "0.23.0",
-			tag:            "v0.24.0",
+			currentVersion: v23,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on stable release, stable tags should not be filtered",
 		},
 		{
 			name:           "alpha version allows alpha tag",
-			currentVersion: "0.23.0-alpha.1",
+			currentVersion: v23Alpha1,
 			tag:            "v0.24.0-alpha.2",
 			expectedFilter: false,
 			description:    "When on alpha release, alpha tags should not be filtered",
 		},
 		{
 			name:           "alpha version allows beta tag",
-			currentVersion: "0.23.0-alpha.1",
+			currentVersion: v23Alpha1,
 			tag:            "v0.24.0-beta.1",
 			expectedFilter: false,
 			description:    "When on alpha release, beta tags should not be filtered",
 		},
 		{
 			name:           "alpha version allows rc tag",
-			currentVersion: "0.23.0-alpha.1",
-			tag:            "v0.24.0-rc.1",
+			currentVersion: v23Alpha1,
+			tag:            v24RCTag,
 			expectedFilter: false,
 			description:    "When on alpha release, rc tags should not be filtered",
 		},
 		{
 			name:           "alpha version allows stable tag",
-			currentVersion: "0.23.0-alpha.1",
-			tag:            "v0.24.0",
+			currentVersion: v23Alpha1,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on alpha release, stable tags should not be filtered",
 		},
 		{
 			name:           "beta version allows alpha tag",
-			currentVersion: "0.23.0-beta.1",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v23Beta1,
+			tag:            v24Alpha1Tag,
 			expectedFilter: false,
 			description:    "When on beta release, alpha tags should not be filtered",
 		},
@@ -84,28 +97,28 @@ func TestFilterPreReleasesIfStable(t *testing.T) {
 		},
 		{
 			name:           "beta version allows rc tag",
-			currentVersion: "0.23.0-beta.1",
-			tag:            "v0.24.0-rc.1",
+			currentVersion: v23Beta1,
+			tag:            v24RCTag,
 			expectedFilter: false,
 			description:    "When on beta release, rc tags should not be filtered",
 		},
 		{
 			name:           "beta version allows stable tag",
-			currentVersion: "0.23.0-beta.1",
-			tag:            "v0.24.0",
+			currentVersion: v23Beta1,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on beta release, stable tags should not be filtered",
 		},
 		{
 			name:           "rc version allows alpha tag",
-			currentVersion: "0.23.0-rc.1",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v23RC1,
+			tag:            v24Alpha1Tag,
 			expectedFilter: false,
 			description:    "When on rc release, alpha tags should not be filtered",
 		},
 		{
 			name:           "rc version allows beta tag",
-			currentVersion: "0.23.0-rc.1",
+			currentVersion: v23RC1,
 			tag:            "v0.24.0-beta.1",
 			expectedFilter: false,
 			description:    "When on rc release, beta tags should not be filtered",
@@ -119,78 +132,78 @@ func TestFilterPreReleasesIfStable(t *testing.T) {
 		},
 		{
 			name:           "rc version allows stable tag",
-			currentVersion: "0.23.0-rc.1",
-			tag:            "v0.24.0",
+			currentVersion: v23RC1,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on rc release, stable tags should not be filtered",
 		},
 		{
 			name:           "stable version with patch filters alpha",
-			currentVersion: "0.23.1",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v231,
+			tag:            v24Alpha1Tag,
 			expectedFilter: true,
 			description:    "Stable version with patch number should filter alpha tags",
 		},
 		{
 			name:           "stable version with patch allows stable",
-			currentVersion: "0.23.1",
-			tag:            "v0.24.0",
+			currentVersion: v231,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "Stable version with patch number should allow stable tags",
 		},
 		{
 			name:           "tag with alpha substring in version number",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v1.0.0-alpha.1",
 			expectedFilter: true,
 			description:    "Tags with alpha in version string should be filtered on stable",
 		},
 		{
 			name:           "tag with beta substring in version number",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v1.0.0-beta.1",
 			expectedFilter: true,
 			description:    "Tags with beta in version string should be filtered on stable",
 		},
 		{
 			name:           "tag with rc substring in version number",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v1.0.0-rc.1",
 			expectedFilter: true,
 			description:    "Tags with rc in version string should be filtered on stable",
 		},
 		{
 			name:           "empty tag on stable version",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "",
 			expectedFilter: false,
 			description:    "Empty tags should not be filtered",
 		},
 		{
 			name:           "dev version allows all tags",
-			currentVersion: "0.23.0-dev",
-			tag:            "v0.24.0-alpha.1",
+			currentVersion: v23Dev,
+			tag:            v24Alpha1Tag,
 			expectedFilter: false,
 			description:    "Dev versions should not filter any tags (pre-release allows all)",
 		},
 		{
 			name:           "stable version filters dev tag",
-			currentVersion: "0.23.0",
+			currentVersion: v23,
 			tag:            "v0.24.0-dev",
 			expectedFilter: true,
 			description:    "When on stable release, dev tags should be filtered",
 		},
 		{
 			name:           "dev version allows dev tag",
-			currentVersion: "0.23.0-dev",
+			currentVersion: v23Dev,
 			tag:            "v0.24.0-dev.1",
 			expectedFilter: false,
 			description:    "When on dev release, dev tags should not be filtered",
 		},
 		{
 			name:           "dev version allows stable tag",
-			currentVersion: "0.23.0-dev",
-			tag:            "v0.24.0",
+			currentVersion: v23Dev,
+			tag:            v24Tag,
 			expectedFilter: false,
 			description:    "When on dev release, stable tags should not be filtered",
 		},
@@ -222,25 +235,25 @@ func TestIsPreReleaseVersion(t *testing.T) {
 	}{
 		{
 			name:        "stable version",
-			version:     "0.23.0",
+			version:     v23,
 			expected:    false,
 			description: "Stable version should not be pre-release",
 		},
 		{
 			name:        "alpha version",
-			version:     "0.23.0-alpha.1",
+			version:     v23Alpha1,
 			expected:    true,
 			description: "Alpha version should be pre-release",
 		},
 		{
 			name:        "beta version",
-			version:     "0.23.0-beta.1",
+			version:     v23Beta1,
 			expected:    true,
 			description: "Beta version should be pre-release",
 		},
 		{
 			name:        "rc version",
-			version:     "0.23.0-rc.1",
+			version:     v23RC1,
 			expected:    true,
 			description: "RC version should be pre-release",
 		},
@@ -258,7 +271,7 @@ func TestIsPreReleaseVersion(t *testing.T) {
 		},
 		{
 			name:        "dev version",
-			version:     "0.23.0-dev",
+			version:     v23Dev,
 			expected:    true,
 			description: "Dev version should be pre-release",
 		},
@@ -270,7 +283,7 @@ func TestIsPreReleaseVersion(t *testing.T) {
 		},
 		{
 			name:        "version with patch number",
-			version:     "0.23.1",
+			version:     v231,
 			expected:    false,
 			description: "Stable version with patch should not be pre-release",
 		},

cmd/headscale/cli/strings.go

@@ -0,0 +1,23 @@
+package cli
+
+// Shared CLI vocabulary used across multiple command definitions in this
+// package. Centralising the strings prevents goconst drift and ensures a
+// typo in a subcommand name fails to compile rather than silently
+// breaking the binding.
+const (
+	// Subcommand verbs (cobra Use field).
+	cmdList   = "list"
+	cmdShow   = "show"
+	cmdNew    = "new"
+	cmdDelete = "delete"
+	cmdExpire = "expire"
+
+	// Subcommand aliases.
+	aliasDel = "del"
+	aliasExp = "exp"
+
+	// Output table column headers and printOutput map keys.
+	colResult     = "Result"
+	colCreated    = "Created"
+	colExpiration = "Expiration"
+)

cmd/headscale/cli/users.go

@@ -70,7 +70,7 @@ var userCmd = &cobra.Command{
 var createUserCmd = &cobra.Command{
 	Use:     "create NAME",
 	Short:   "Creates a new user",
-	Aliases: []string{"c", "new"},
+	Aliases: []string{"c", cmdNew},
 	Args: func(cmd *cobra.Command, args []string) error {
 		if len(args) < 1 {
 			return errMissingParameter
@@ -115,7 +115,7 @@ var createUserCmd = &cobra.Command{
 var destroyUserCmd = &cobra.Command{
 	Use:     "destroy --identifier ID or --name NAME",
 	Short:   "Destroys a user",
-	Aliases: []string{"delete"},
+	Aliases: []string{cmdDelete},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		id, username, err := usernameAndIDFromFlag(cmd)
 		if err != nil {
@@ -142,7 +142,7 @@ var destroyUserCmd = &cobra.Command{
 			"Do you want to remove the user %q (%d) and any associated preauthkeys?",
 			user.GetName(), user.GetId(),
 		)) {
-			return printOutput(cmd, map[string]string{"Result": "User not destroyed"}, "User not destroyed")
+			return printOutput(cmd, map[string]string{colResult: "User not destroyed"}, "User not destroyed")
 		}
 
 		deleteRequest := &v1.DeleteUserRequest{Id: user.GetId()}
@@ -157,9 +157,9 @@ var destroyUserCmd = &cobra.Command{
 }
 
 var listUsersCmd = &cobra.Command{
-	Use:     "list",
+	Use:     cmdList,
 	Short:   "List all the users",
-	Aliases: []string{"ls", "show"},
+	Aliases: []string{"ls", cmdShow},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		request := &v1.ListUsersRequest{}
 
@@ -183,7 +183,9 @@ var listUsersCmd = &cobra.Command{
 		}
 
 		return printListOutput(cmd, response.GetUsers(), func() error {
-			tableData := pterm.TableData{{"ID", "Name", "Username", "Email", "Created"}}
+			tableData := make(pterm.TableData, 1, 1+len(response.GetUsers()))
+
+			tableData[0] = []string{"ID", "Name", "Username", "Email", colCreated}
 			for _, user := range response.GetUsers() {
 				tableData = append(
 					tableData,

cmd/headscale/cli/utils.go

@@ -67,9 +67,9 @@ func newHeadscaleServerWithConfig() (*hscontrol.Headscale, error) {
 	return app, nil
 }
 
-// grpcRunE wraps a cobra RunE func, injecting a ready gRPC client and
-// context. Connection lifecycle is managed by the wrapper — callers
-// never see the underlying conn or cancel func.
+// grpcRunE wraps a cobra [cobra.Command.RunE] func, injecting a ready
+// gRPC client and context. Connection lifecycle is managed by the
+// wrapper — callers never see the underlying conn or cancel func.
 func grpcRunE(
 	fn func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error,
 ) func(*cobra.Command, []string) error {
@@ -103,7 +103,7 @@ func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *g
 
 	address := cfg.CLI.Address
 
-	// If the address is not set, we assume that we are on the server hosting hscontrol.
+	// If the address is not set, we assume that we are on the server hosting [hscontrol].
 	if address == "" {
 		log.Debug().
 			Str("socket", cfg.UnixSocket).
@@ -112,9 +112,9 @@ func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *g
 		address = cfg.UnixSocket
 
 		// Try to give the user better feedback if we cannot write to the headscale
-		// socket.  Note: os.OpenFile on a Unix domain socket returns ENXIO on
+		// socket.  Note: [os.OpenFile] on a Unix domain socket returns ENXIO on
 		// Linux which is expected — only permission errors are actionable here.
-		// The actual gRPC connection uses net.Dial which handles sockets properly.
+		// The actual gRPC connection uses [net.Dial] which handles sockets properly.
 		socket, err := os.OpenFile(cfg.UnixSocket, os.O_WRONLY, SocketWritePermissions) //nolint
 		if err != nil {
 			if os.IsPermission(err) {
@@ -269,7 +269,7 @@ func printListOutput(
 
 // printError writes err to stderr, formatting it as JSON/YAML when the
 // --output flag requests machine-readable output.  Used exclusively by
-// Execute() so that every error surfaces in the format the caller asked for.
+// [Execute] so that every error surfaces in the format the caller asked for.
 func printError(err error, outputFormat string) {
 	type errOutput struct {
 		Error string `json:"error"`

cmd/headscale/headscale_test.go

@@ -73,5 +73,4 @@ func TestConfigLoading(t *testing.T) {
 	assert.Equal(t, "HTTP-01", viper.GetString("tls_letsencrypt_challenge_type"))
 	assert.Equal(t, fs.FileMode(0o770), util.GetFileMode("unix_socket_permission"))
 	assert.False(t, viper.GetBool("logtail.enabled"))
-	assert.False(t, viper.GetBool("randomize_client_port"))
 }

cmd/hi/docker.go

@@ -14,6 +14,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/cenkalti/backoff/v5"
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/api/types/image"
 	"github.com/docker/docker/api/types/mount"
@@ -522,9 +523,9 @@ func checkImageAvailableLocally(ctx context.Context, cli *client.Client, imageNa
 	return true, nil
 }
 
-// ensureImageAvailable checks if the image is available locally first, then pulls if needed.
+// ensureImageAvailable pulls imageName if missing, using Docker Hub
+// credentials and retrying transient errors.
 func ensureImageAvailable(ctx context.Context, cli *client.Client, imageName string, verbose bool) error {
-	// First check if image is available locally
 	available, err := checkImageAvailableLocally(ctx, cli, imageName)
 	if err != nil {
 		return fmt.Errorf("checking local image availability: %w", err)
@@ -538,34 +539,64 @@ func ensureImageAvailable(ctx context.Context, cli *client.Client, imageName str
 		return nil
 	}
 
-	// Image not available locally, try to pull it
 	if verbose {
 		log.Printf("Image %s not found locally, pulling...", imageName)
 	}
 
-	reader, err := cli.ImagePull(ctx, imageName, image.PullOptions{})
+	registryAuth, err := dockertestutil.RegistryAuth()
 	if err != nil {
-		return fmt.Errorf("pulling image %s: %w", imageName, err)
+		return fmt.Errorf("resolving registry auth: %w", err)
 	}
-	defer reader.Close()
 
-	if verbose {
-		_, err = io.Copy(os.Stdout, reader)
-		if err != nil {
-			return fmt.Errorf("reading pull output: %w", err)
-		}
-	} else {
-		_, err = io.Copy(io.Discard, reader)
-		if err != nil {
-			return fmt.Errorf("reading pull output: %w", err)
-		}
+	_, err = backoff.Retry(
+		ctx,
+		func() (struct{}, error) {
+			reader, pullErr := cli.ImagePull(ctx, imageName, image.PullOptions{RegistryAuth: registryAuth})
+			if pullErr != nil {
+				if isPermanentDockerPullError(pullErr) {
+					return struct{}{}, backoff.Permanent(pullErr)
+				}
 
+				return struct{}{}, fmt.Errorf("pulling image %s: %w", imageName, pullErr)
+			}
+			defer reader.Close()
+
+			sink := io.Discard
+			if verbose {
+				sink = os.Stdout
+			}
+
+			_, copyErr := io.Copy(sink, reader)
+			if copyErr != nil {
+				return struct{}{}, fmt.Errorf("reading pull output: %w", copyErr)
+			}
+
+			return struct{}{}, nil
+		},
+		backoff.WithBackOff(backoff.NewExponentialBackOff()),
+		backoff.WithMaxElapsedTime(60*time.Second),
+	)
+	if err != nil {
+		return err
+	}
+
+	if !verbose {
 		log.Printf("Image %s pulled successfully", imageName)
 	}
 
 	return nil
 }
 
+func isPermanentDockerPullError(err error) bool {
+	msg := strings.ToLower(err.Error())
+
+	return strings.Contains(msg, "manifest unknown") ||
+		strings.Contains(msg, "manifest not found") ||
+		strings.Contains(msg, "repository does not exist") ||
+		strings.Contains(msg, "name unknown") ||
+		strings.Contains(msg, "no such image")
+}
+
 // listControlFiles displays the headscale test artifacts created in the control logs directory.
 func listControlFiles(logsDir string) {
 	entries, err := os.ReadDir(logsDir)
@@ -799,7 +830,7 @@ func extractContainerLogs(ctx context.Context, cli *client.Client, containerID,
 
 // extractContainerFiles extracts database file and directories from headscale containers.
 // Note: The actual file extraction is now handled by the integration tests themselves
-// via SaveProfile, SaveMapResponses, and SaveDatabase functions in hsic.go.
+// via [SaveProfile], [SaveMapResponses], and [SaveDatabase] functions in hsic.go.
 func extractContainerFiles(ctx context.Context, cli *client.Client, containerID, containerName, logsDir string, verbose bool) error {
 	// Files are now extracted directly by the integration tests
 	// This function is kept for potential future use or other file types

cmd/hi/doctor.go

@@ -7,6 +7,20 @@ import (
 	"log"
 	"os/exec"
 	"strings"
+
+	"github.com/juanfont/headscale/integration/dockertestutil"
+)
+
+const (
+	statusPass = "PASS"
+	statusFail = "FAIL"
+	statusWarn = "WARN"
+
+	nameDockerDaemon  = "Docker Daemon"
+	nameDockerContext = "Docker Context"
+	nameDockerSocket  = "Docker Socket"
+	nameGolangImage   = "Golang Image"
+	nameGoInstall     = "Go Installation"
 )
 
 var ErrSystemChecksFailed = errors.New("system checks failed")
@@ -31,9 +45,10 @@ func runDoctorCheck(ctx context.Context) error {
 	results = append(results, dockerResult)
 
 	// If Docker is available, run additional checks
-	if dockerResult.Status == "PASS" {
+	if dockerResult.Status == statusPass {
 		results = append(results, checkDockerContext(ctx))
 		results = append(results, checkDockerSocket(ctx))
+		results = append(results, checkDockerHubCredentials())
 		results = append(results, checkGolangImage(ctx))
 	}
 
@@ -51,7 +66,7 @@ func runDoctorCheck(ctx context.Context) error {
 
 	// Return error if any critical checks failed
 	for _, result := range results {
-		if result.Status == "FAIL" {
+		if result.Status == statusFail {
 			return fmt.Errorf("%w - see details above", ErrSystemChecksFailed)
 		}
 	}
@@ -67,7 +82,7 @@ func checkDockerBinary() DoctorResult {
 	if err != nil {
 		return DoctorResult{
 			Name:    "Docker Binary",
-			Status:  "FAIL",
+			Status:  statusFail,
 			Message: "Docker binary not found in PATH",
 			Suggestions: []string{
 				"Install Docker: https://docs.docker.com/get-docker/",
@@ -79,7 +94,7 @@ func checkDockerBinary() DoctorResult {
 
 	return DoctorResult{
 		Name:    "Docker Binary",
-		Status:  "PASS",
+		Status:  statusPass,
 		Message: "Docker binary found",
 	}
 }
@@ -89,8 +104,8 @@ func checkDockerDaemon(ctx context.Context) DoctorResult {
 	cli, err := createDockerClient(ctx)
 	if err != nil {
 		return DoctorResult{
-			Name:    "Docker Daemon",
-			Status:  "FAIL",
+			Name:    nameDockerDaemon,
+			Status:  statusFail,
 			Message: fmt.Sprintf("Cannot create Docker client: %v", err),
 			Suggestions: []string{
 				"Start Docker daemon/service",
@@ -105,8 +120,8 @@ func checkDockerDaemon(ctx context.Context) DoctorResult {
 	_, err = cli.Ping(ctx)
 	if err != nil {
 		return DoctorResult{
-			Name:    "Docker Daemon",
-			Status:  "FAIL",
+			Name:    nameDockerDaemon,
+			Status:  statusFail,
 			Message: fmt.Sprintf("Cannot ping Docker daemon: %v", err),
 			Suggestions: []string{
 				"Ensure Docker daemon is running",
@@ -117,8 +132,8 @@ func checkDockerDaemon(ctx context.Context) DoctorResult {
 	}
 
 	return DoctorResult{
-		Name:    "Docker Daemon",
-		Status:  "PASS",
+		Name:    nameDockerDaemon,
+		Status:  statusPass,
 		Message: "Docker daemon is running and accessible",
 	}
 }
@@ -128,8 +143,8 @@ func checkDockerContext(ctx context.Context) DoctorResult {
 	contextInfo, err := getCurrentDockerContext(ctx)
 	if err != nil {
 		return DoctorResult{
-			Name:    "Docker Context",
-			Status:  "WARN",
+			Name:    nameDockerContext,
+			Status:  statusWarn,
 			Message: "Could not detect Docker context, using default settings",
 			Suggestions: []string{
 				"Check: docker context ls",
@@ -140,15 +155,15 @@ func checkDockerContext(ctx context.Context) DoctorResult {
 
 	if contextInfo == nil {
 		return DoctorResult{
-			Name:    "Docker Context",
-			Status:  "PASS",
+			Name:    nameDockerContext,
+			Status:  statusPass,
 			Message: "Using default Docker context",
 		}
 	}
 
 	return DoctorResult{
-		Name:    "Docker Context",
-		Status:  "PASS",
+		Name:    nameDockerContext,
+		Status:  statusPass,
 		Message: "Using Docker context: " + contextInfo.Name,
 	}
 }
@@ -158,8 +173,8 @@ func checkDockerSocket(ctx context.Context) DoctorResult {
 	cli, err := createDockerClient(ctx)
 	if err != nil {
 		return DoctorResult{
-			Name:    "Docker Socket",
-			Status:  "FAIL",
+			Name:    nameDockerSocket,
+			Status:  statusFail,
 			Message: fmt.Sprintf("Cannot access Docker socket: %v", err),
 			Suggestions: []string{
 				"Check Docker socket permissions",
@@ -173,8 +188,8 @@ func checkDockerSocket(ctx context.Context) DoctorResult {
 	info, err := cli.Info(ctx)
 	if err != nil {
 		return DoctorResult{
-			Name:    "Docker Socket",
-			Status:  "FAIL",
+			Name:    nameDockerSocket,
+			Status:  statusFail,
 			Message: fmt.Sprintf("Cannot get Docker info: %v", err),
 			Suggestions: []string{
 				"Check Docker daemon status",
@@ -184,19 +199,43 @@ func checkDockerSocket(ctx context.Context) DoctorResult {
 	}
 
 	return DoctorResult{
-		Name:    "Docker Socket",
-		Status:  "PASS",
+		Name:    nameDockerSocket,
+		Status:  statusPass,
 		Message: fmt.Sprintf("Docker socket accessible (Server: %s)", info.ServerVersion),
 	}
 }
 
+// checkDockerHubCredentials warns when pulls would be anonymous and
+// therefore rate-limited.
+func checkDockerHubCredentials() DoctorResult {
+	_, _, source := dockertestutil.Credentials()
+	if source == dockertestutil.CredentialSourceAnonymous {
+		return DoctorResult{
+			Name:    "Docker Hub Credentials",
+			Status:  "WARN",
+			Message: "No Docker Hub credentials found — pulls will be rate-limited (100/6h per IP)",
+			Suggestions: []string{
+				"Run: docker login",
+				"Or export DOCKERHUB_USERNAME and DOCKERHUB_TOKEN",
+				"In CI: ensure the docker/login-action step is configured with secrets",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Docker Hub Credentials",
+		Status:  "PASS",
+		Message: fmt.Sprintf("Credentials available (source: %s)", source),
+	}
+}
+
 // checkGolangImage verifies the golang Docker image is available locally or can be pulled.
 func checkGolangImage(ctx context.Context) DoctorResult {
 	cli, err := createDockerClient(ctx)
 	if err != nil {
 		return DoctorResult{
-			Name:    "Golang Image",
-			Status:  "FAIL",
+			Name:    nameGolangImage,
+			Status:  statusFail,
 			Message: "Cannot create Docker client for image check",
 		}
 	}
@@ -209,8 +248,8 @@ func checkGolangImage(ctx context.Context) DoctorResult {
 	available, err := checkImageAvailableLocally(ctx, cli, imageName)
 	if err != nil {
 		return DoctorResult{
-			Name:    "Golang Image",
-			Status:  "FAIL",
+			Name:    nameGolangImage,
+			Status:  statusFail,
 			Message: fmt.Sprintf("Cannot check golang image %s: %v", imageName, err),
 			Suggestions: []string{
 				"Check Docker daemon status",
@@ -221,8 +260,8 @@ func checkGolangImage(ctx context.Context) DoctorResult {
 
 	if available {
 		return DoctorResult{
-			Name:    "Golang Image",
-			Status:  "PASS",
+			Name:    nameGolangImage,
+			Status:  statusPass,
 			Message: fmt.Sprintf("Golang image %s is available locally", imageName),
 		}
 	}
@@ -231,8 +270,8 @@ func checkGolangImage(ctx context.Context) DoctorResult {
 	err = ensureImageAvailable(ctx, cli, imageName, false)
 	if err != nil {
 		return DoctorResult{
-			Name:    "Golang Image",
-			Status:  "FAIL",
+			Name:    nameGolangImage,
+			Status:  statusFail,
 			Message: fmt.Sprintf("Golang image %s not available locally and cannot pull: %v", imageName, err),
 			Suggestions: []string{
 				"Check internet connectivity",
@@ -244,8 +283,8 @@ func checkGolangImage(ctx context.Context) DoctorResult {
 	}
 
 	return DoctorResult{
-		Name:    "Golang Image",
-		Status:  "PASS",
+		Name:    nameGolangImage,
+		Status:  statusPass,
 		Message: fmt.Sprintf("Golang image %s is now available", imageName),
 	}
 }
@@ -255,8 +294,8 @@ func checkGoInstallation(ctx context.Context) DoctorResult {
 	_, err := exec.LookPath("go")
 	if err != nil {
 		return DoctorResult{
-			Name:    "Go Installation",
-			Status:  "FAIL",
+			Name:    nameGoInstall,
+			Status:  statusFail,
 			Message: "Go binary not found in PATH",
 			Suggestions: []string{
 				"Install Go: https://golang.org/dl/",
@@ -270,8 +309,8 @@ func checkGoInstallation(ctx context.Context) DoctorResult {
 	output, err := cmd.Output()
 	if err != nil {
 		return DoctorResult{
-			Name:    "Go Installation",
-			Status:  "FAIL",
+			Name:    nameGoInstall,
+			Status:  statusFail,
 			Message: fmt.Sprintf("Cannot get Go version: %v", err),
 		}
 	}
@@ -279,8 +318,8 @@ func checkGoInstallation(ctx context.Context) DoctorResult {
 	version := strings.TrimSpace(string(output))
 
 	return DoctorResult{
-		Name:    "Go Installation",
-		Status:  "PASS",
+		Name:    nameGoInstall,
+		Status:  statusPass,
 		Message: version,
 	}
 }
@@ -293,7 +332,7 @@ func checkGitRepository(ctx context.Context) DoctorResult {
 	if err != nil {
 		return DoctorResult{
 			Name:    "Git Repository",
-			Status:  "FAIL",
+			Status:  statusFail,
 			Message: "Not in a Git repository",
 			Suggestions: []string{
 				"Run from within the headscale git repository",
@@ -304,7 +343,7 @@ func checkGitRepository(ctx context.Context) DoctorResult {
 
 	return DoctorResult{
 		Name:    "Git Repository",
-		Status:  "PASS",
+		Status:  statusPass,
 		Message: "Running in Git repository",
 	}
 }
@@ -331,7 +370,7 @@ func checkRequiredFiles(ctx context.Context) DoctorResult {
 	if len(missingFiles) > 0 {
 		return DoctorResult{
 			Name:    "Required Files",
-			Status:  "FAIL",
+			Status:  statusFail,
 			Message: "Missing required files: " + strings.Join(missingFiles, ", "),
 			Suggestions: []string{
 				"Ensure you're in the headscale project root directory",
@@ -343,7 +382,7 @@ func checkRequiredFiles(ctx context.Context) DoctorResult {
 
 	return DoctorResult{
 		Name:    "Required Files",
-		Status:  "PASS",
+		Status:  statusPass,
 		Message: "All required files found",
 	}
 }
@@ -357,11 +396,11 @@ func displayDoctorResults(results []DoctorResult) {
 		var icon string
 
 		switch result.Status {
-		case "PASS":
+		case statusPass:
 			icon = "✅"
-		case "WARN":
+		case statusWarn:
 			icon = "⚠️"
-		case "FAIL":
+		case statusFail:
 			icon = "❌"
 		default:
 			icon = "❓"

cmd/hi/listversions.go

@@ -0,0 +1,89 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/creachadair/command"
+	"github.com/juanfont/headscale/hscontrol/capver"
+)
+
+var (
+	errUnknownSet    = errors.New("unknown --set value (want must|all)")
+	errUnknownFormat = errors.New("unknown --format value (want space|newline|json)")
+)
+
+// ListVersionsConfig holds flags for the list-versions subcommand.
+type ListVersionsConfig struct {
+	Set     string `flag:"set,default=must,Version set: must|all"`
+	Exclude string `flag:"exclude,Comma-separated versions to exclude (e.g. head,unstable)"`
+	Format  string `flag:"format,default=space,Output format: space|newline|json"`
+}
+
+var listVersionsConfig ListVersionsConfig
+
+// listVersions prints the Tailscale versions used by integration tests
+// in a format CI can shell out to. Mirrors integration/scenario.go
+// AllVersions and MustTestVersions: "head" and "unstable" are bare
+// tags, releases get a "v" prefix so each entry can be appended to
+// "ghcr.io/tailscale/tailscale:" directly.
+func listVersions(env *command.Env) error {
+	release := capver.TailscaleLatestMajorMinor(capver.SupportedMajorMinorVersions, true)
+	all := append([]string{"head", "unstable"}, release...)
+	must := append(append([]string{}, all[0:4]...), all[len(all)-2:]...)
+
+	var versions []string
+
+	switch listVersionsConfig.Set {
+	case "must":
+		versions = must
+	case "all":
+		versions = all
+	default:
+		return fmt.Errorf("%w: %q", errUnknownSet, listVersionsConfig.Set)
+	}
+
+	excluded := make(map[string]bool)
+
+	if listVersionsConfig.Exclude != "" {
+		for v := range strings.SplitSeq(listVersionsConfig.Exclude, ",") {
+			excluded[strings.TrimSpace(v)] = true
+		}
+	}
+
+	out := make([]string, 0, len(versions))
+
+	for _, v := range versions {
+		if excluded[v] {
+			continue
+		}
+
+		if v != "head" && v != "unstable" {
+			v = "v" + v
+		}
+
+		out = append(out, v)
+	}
+
+	switch listVersionsConfig.Format {
+	case "space":
+		fmt.Println(strings.Join(out, " "))
+	case "newline":
+		for _, v := range out {
+			fmt.Println(v)
+		}
+	case "json":
+		b, err := json.Marshal(out)
+		if err != nil {
+			return err
+		}
+
+		fmt.Println(string(b))
+	default:
+		return fmt.Errorf("%w: %q", errUnknownFormat, listVersionsConfig.Format)
+	}
+
+	return nil
+}

cmd/hi/main.go

@@ -29,6 +29,13 @@ func main() {
 					return runDoctorCheck(env.Context())
 				},
 			},
+			{
+				Name:     "list-versions",
+				Help:     "Print Tailscale versions used by integration tests",
+				Usage:    "list-versions [flags]",
+				SetFlags: command.Flags(flax.MustBind, &listVersionsConfig),
+				Run:      listVersions,
+			},
 			{
 				Name: "clean",
 				Help: "Clean Docker resources",

cmd/hi/run.go

@@ -94,7 +94,7 @@ func detectGoVersion() string {
 	return "1.26.1"
 }
 
-// splitLines splits a string into lines without using strings.Split.
+// splitLines splits a string into lines without using [strings.Split].
 func splitLines(s string) []string {
 	var (
 		lines   []string

cmd/hi/stats.go

@@ -160,7 +160,7 @@ func (sc *StatsCollector) monitorDockerEvents(ctx context.Context, runID string,
 					continue
 				}
 
-				// Convert to types.Container format for consistency
+				// Convert to [types.Container] format for consistency
 				cont := types.Container{ //nolint:staticcheck // SA1019: use container.Summary
 					ID:     containerInfo.ID,
 					Names:  []string{containerInfo.Name},
@@ -256,7 +256,7 @@ func (sc *StatsCollector) collectStatsForContainer(ctx context.Context, containe
 
 			err := decoder.Decode(&stats)
 			if err != nil {
-				// EOF is expected when container stops or stream ends
+				// [io.EOF] is expected when container stops or stream ends
 				if err.Error() != "EOF" && verbose {
 					log.Printf("Failed to decode stats for container %s: %v", containerID[:12], err)
 				}
@@ -312,7 +312,7 @@ func calculateCPUPercent(prevStats, stats *container.Stats) float64 { //nolint:s
 		// Calculate CPU percentage: (container CPU delta / system CPU delta) * number of CPUs * 100
 		numCPUs := float64(len(stats.CPUStats.CPUUsage.PercpuUsage))
 		if numCPUs == 0 {
-			// Fallback: if PercpuUsage is not available, assume 1 CPU
+			// Fallback: if [PercpuUsage] is not available, assume 1 CPU
 			numCPUs = 1.0
 		}
 

cmd/vendorhash/main.go

@@ -0,0 +1,221 @@
+// vendorhash maintains the Nix SRI hash for the Go module vendor tree
+// and stores it in flakehashes.json alongside a content fingerprint of
+// go.mod and go.sum.
+//
+// Each block records its input fingerprint (goModSum) so that re-runs
+// with no input change are essentially free: the fast path is just a
+// sha256 over two small files. The vendor tree is only re-walked when
+// the fingerprint actually drifts.
+//
+// Subcommands:
+//
+//	vendorhash check   exit non-zero if flakehashes.json is stale
+//	vendorhash update  recompute and rewrite flakehashes.json
+//
+// The JSON schema and [goModFingerprint] algorithm mirror upstream
+// tailscale's tool/updateflakes so a future shared library extraction
+// is straightforward.
+package main
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+
+	"tailscale.com/cmd/nardump/nardump"
+)
+
+const (
+	hashesFile = "flakehashes.json"
+	goModFile  = "go.mod"
+	goSumFile  = "go.sum"
+)
+
+type FlakeHashes struct {
+	Vendor VendorBlock `json:"vendor"`
+}
+
+type VendorBlock struct {
+	GoModSum string `json:"goModSum"`
+	SRI      string `json:"sri"`
+}
+
+func main() {
+	if len(os.Args) < 2 {
+		usage()
+		os.Exit(2)
+	}
+
+	ctx := context.Background()
+
+	var err error
+
+	switch os.Args[1] {
+	case "check":
+		err = cmdCheck(ctx)
+	case "update":
+		err = cmdUpdate(ctx)
+	case "-h", "--help", "help":
+		usage()
+		return
+	default:
+		usage()
+		os.Exit(2)
+	}
+
+	if err != nil {
+		if errors.Is(err, errStale) {
+			os.Exit(1)
+		}
+
+		fmt.Fprintln(os.Stderr, "vendorhash:", err)
+		os.Exit(1)
+	}
+}
+
+func usage() {
+	fmt.Fprintln(os.Stderr, "usage: vendorhash <check|update>")
+}
+
+// errStale signals to [main] that the check found a mismatch; it has
+// already printed a remediation message, so [main] should exit 1
+// silently.
+var errStale = errors.New("vendor hash stale")
+
+// cmdCheck verifies that flakehashes.json matches the current
+// go.mod/go.sum. The fast path (fingerprint unchanged) costs only
+// a sha256 over the two files. On mismatch, it computes the actual
+// SRI so the failure message gives the developer the value to paste
+// (or to run `vendorhash update`).
+func cmdCheck(ctx context.Context) error {
+	hashes, err := loadHashes()
+	if err != nil {
+		return err
+	}
+
+	curFP, err := goModFingerprint()
+	if err != nil {
+		return err
+	}
+
+	if curFP == hashes.Vendor.GoModSum {
+		return nil
+	}
+
+	curSRI, err := hashVendor(ctx)
+	if err != nil {
+		return err
+	}
+
+	fmt.Fprintln(os.Stderr, "vendor hash is stale.")
+	fmt.Fprintf(os.Stderr, "  expected goModSum: %s\n", hashes.Vendor.GoModSum)
+	fmt.Fprintf(os.Stderr, "    actual goModSum: %s\n", curFP)
+	fmt.Fprintf(os.Stderr, "       expected sri: %s\n", hashes.Vendor.SRI)
+	fmt.Fprintf(os.Stderr, "         actual sri: %s\n", curSRI)
+	fmt.Fprintln(os.Stderr, "run: go run ./cmd/vendorhash update")
+	// Also emit machine-parseable lines so CI can pick them up.
+	fmt.Printf("expected_sri=%s\n", hashes.Vendor.SRI)
+	fmt.Printf("actual_sri=%s\n", curSRI)
+
+	return errStale
+}
+
+func cmdUpdate(ctx context.Context) error {
+	fp, err := goModFingerprint()
+	if err != nil {
+		return err
+	}
+
+	sri, err := hashVendor(ctx)
+	if err != nil {
+		return err
+	}
+
+	return writeHashes(FlakeHashes{
+		Vendor: VendorBlock{
+			GoModSum: fp,
+			SRI:      sri,
+		},
+	})
+}
+
+// goModFingerprint returns a content fingerprint of go.mod and go.sum
+// that changes whenever either file changes. The byte layout matches
+// upstream tailscale's tool/updateflakes.
+func goModFingerprint() (string, error) {
+	h := sha256.New()
+
+	for _, f := range []string{goModFile, goSumFile} {
+		b, err := os.ReadFile(f)
+		if err != nil {
+			return "", err
+		}
+
+		fmt.Fprintf(h, "%s %d\n", f, len(b))
+		h.Write(b)
+	}
+
+	return "sha256-" + base64.StdEncoding.EncodeToString(h.Sum(nil)), nil
+}
+
+// hashVendor runs `go mod vendor` into a temporary directory and
+// returns the Nix SRI hash of the resulting tree.
+func hashVendor(ctx context.Context) (string, error) {
+	out, err := os.MkdirTemp("", "nar-vendor-")
+	if err != nil {
+		return "", err
+	}
+	// `go mod vendor -o` requires the destination to not already exist.
+	err = os.Remove(out)
+	if err != nil {
+		return "", err
+	}
+
+	defer os.RemoveAll(out)
+
+	cmd := exec.CommandContext(ctx, "go", "mod", "vendor", "-o", out)
+
+	cmd.Env = append(os.Environ(), "GOWORK=off")
+	cmd.Stderr = os.Stderr
+
+	err = cmd.Run()
+	if err != nil {
+		return "", fmt.Errorf("go mod vendor: %w", err)
+	}
+
+	return nardump.SRI(os.DirFS(out))
+}
+
+func loadHashes() (FlakeHashes, error) {
+	var h FlakeHashes
+
+	b, err := os.ReadFile(hashesFile)
+	if err != nil {
+		return h, err
+	}
+
+	err = json.Unmarshal(b, &h)
+	if err != nil {
+		return h, fmt.Errorf("%s: %w", hashesFile, err)
+	}
+
+	return h, nil
+}
+
+func writeHashes(h FlakeHashes) error {
+	b, err := json.MarshalIndent(h, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	b = append(b, '\n')
+
+	// flakehashes.json is committed source read by Nix during evaluation;
+	// world-readable matches every other tracked file in the repo.
+	return os.WriteFile(hashesFile, b, 0o644) //nolint:gosec
+}

config-example.yaml

@@ -20,7 +20,7 @@ listen_addr: 127.0.0.1:8080
 
 # Address to listen to /metrics and /debug, you may want
 # to keep this endpoint private to your internal network
-# Use an emty value to disable the metrics listener.
+# Use an empty value to disable the metrics listener.
 metrics_listen_addr: 127.0.0.1:9090
 
 # Address to listen for gRPC.
@@ -39,6 +39,13 @@ grpc_listen_addr: 127.0.0.1:50443
 # are doing.
 grpc_allow_insecure: false
 
+# CIDR(s) of reverse proxies (e.g. 127.0.0.1/32) whose
+# True-Client-IP, X-Real-IP and X-Forwarded-For headers should
+# be honoured. Empty (default) ignores those headers; setting
+# this without a proxy in front lets clients spoof their logged
+# source IP.
+trusted_proxies: []
+
 # The Noise section includes specific configuration for the
 # TS2021 Noise protocol
 noise:
@@ -80,8 +87,7 @@ prefixes:
 # connection cannot be established.
 # https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
 #
-# headscale needs a list of DERP servers that can be presented
-# to the clients.
+# Headscale needs a list of DERP servers that can be presented to the clients.
 derp:
   server:
     # If enabled, runs the embedded DERP server and merges it into the rest of the DERP config
@@ -126,9 +132,9 @@ derp:
 
   # Locally available DERP map files encoded in YAML
   #
-  # This option is mostly interesting for people hosting
-  # their own DERP servers:
-  # https://tailscale.com/kb/1118/custom-derp-servers/
+  # This option is mostly interesting for people hosting their own DERP servers:
+  # https://tailscale.com/docs/reference/derp-servers/custom-derp-servers
+  # https://headscale.net/stable/ref/derp/
   #
   # paths:
   #   - /etc/headscale/derp-example.yaml
@@ -165,6 +171,26 @@ node:
     # Time before an inactive ephemeral node is deleted.
     inactivity_timeout: 30m
 
+  # HA subnet router health probing.
+  #
+  # When HA routes exist (2+ nodes advertising the same prefix), headscale
+  # pings each HA node every probe_interval via the Noise channel. If a node
+  # fails to respond within probe_timeout it is marked unhealthy and the
+  # primary role moves to the next healthy node. A node that later responds
+  # is marked healthy again but does NOT reclaim primary (avoids flapping).
+  #
+  # Worst-case detection time is probe_interval + probe_timeout (15s default).
+  # No-op when no HA routes exist. Set probe_interval to 0 to disable.
+  routes:
+    ha:
+      # How often to ping HA subnet routers. Set to 0 to disable probing.
+      # Must be >= 2s when enabled.
+      probe_interval: 10s
+
+      # How long to wait for a ping response before marking a node unhealthy.
+      # Must be >= 1s and less than probe_interval.
+      probe_timeout: 5s
+
 database:
   # Database type. Available options: sqlite, postgres
   # Please note that using Postgres is highly discouraged as it is only supported for legacy reasons.
@@ -242,7 +268,7 @@ tls_letsencrypt_cache_dir: /var/lib/headscale/cache
 
 # Type of ACME challenge to use, currently supported types:
 # HTTP-01 or TLS-ALPN-01
-# See: docs/ref/tls.md for more information
+# See: https://headscale.net/stable/ref/tls/
 tls_letsencrypt_challenge_type: HTTP-01
 # When HTTP-01 challenge is chosen, letsencrypt must set up a
 # verification endpoint, and it will be listening on:
@@ -261,25 +287,24 @@ log:
   format: text
 
 ## Policy
-# headscale supports Tailscale's ACL policies.
-# Please have a look to their KB to better
-# understand the concepts: https://tailscale.com/kb/1018/acls/
+# Headscale supports a wide range of Tailscale policy features such as ACLs and
+# Grants. Please have a look at their docs to better understand the concepts:
+# ACLs: https://tailscale.com/docs/features/access-control/acls
+# Grants: https://tailscale.com/docs/features/access-control/grants
 policy:
   # The mode can be "file" or "database" that defines
-  # where the ACL policies are stored and read from.
+  # where the policies are stored and read from.
   mode: file
-  # If the mode is set to "file", the path to a
-  # HuJSON file containing ACL policies.
+  # If the mode is set to "file", the path to a HuJSON file containing policies.
   path: ""
 
 ## DNS
 #
 # headscale supports Tailscale's DNS configuration and MagicDNS.
-# Please have a look to their KB to better understand the concepts:
+# Please have a look to their docs to better understand the concepts:
 #
-# - https://tailscale.com/kb/1054/dns/
-# - https://tailscale.com/kb/1081/magicdns/
-# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
+# - https://tailscale.com/docs/features/magicdns
+# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns
 #
 # Please note that for the DNS configuration to have any effect,
 # clients must have the `--accept-dns=true` option enabled. This is the
@@ -289,12 +314,12 @@ policy:
 # Setting _any_ of the configuration and `--accept-dns=true` on the
 # clients will integrate with the DNS manager on the client or
 # overwrite /etc/resolv.conf.
-# https://tailscale.com/kb/1235/resolv-conf
+# https://tailscale.com/docs/reference/faq/dns-resolv-conf
 #
 # If you want stop Headscale from managing the DNS configuration
 # all the fields under `dns` should be set to empty values.
 dns:
-  # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
+  # Whether to use MagicDNS
   magic_dns: true
 
   # Defines the base domain to create the hostnames for MagicDNS.
@@ -316,11 +341,11 @@ dns:
       - 2606:4700:4700::1111
       - 2606:4700:4700::1001
 
-      # NextDNS (see https://tailscale.com/kb/1218/nextdns/).
+      # NextDNS (see https://tailscale.com/docs/integrations/nextdns).
       # "abc123" is example NextDNS ID, replace with yours.
       # - https://dns.nextdns.io/abc123
 
-    # Split DNS (see https://tailscale.com/kb/1054/dns/),
+    # Split DNS (see https://tailscale.com/docs/reference/dns-in-tailscale#restricted-nameservers),
     # a map of domains and which DNS server to use for each.
     split: {}
       # foo.bar.com:
@@ -335,7 +360,7 @@ dns:
 
   # Extra DNS records
   # so far only A and AAAA records are supported (on the tailscale side)
-  # See: docs/ref/dns.md
+  # See: https://headscale.net/stable/ref/dns/
   extra_records: []
   #   - name: "grafana.myvpn.example.com"
   #     type: "A"
@@ -354,6 +379,7 @@ unix_socket: /var/run/headscale/headscale.sock
 unix_socket_permission: "0770"
 
 # OpenID Connect
+# https://headscale.net/stable/ref/oidc/
 # oidc:
 #   # Block startup until the identity provider is available and healthy.
 #   only_start_if_oidc_is_available: true
@@ -425,26 +451,31 @@ unix_socket_permission: "0770"
 # Logtail is Tailscales logging and auditing infrastructure, it allows the
 # control panel to instruct tailscale nodes to log their activity to a remote
 # server. To disable logging on the client side, please refer to:
-# https://tailscale.com/kb/1011/log-mesh-traffic#opting-out-of-client-logging
+# https://tailscale.com/docs/features/logging#opt-out-of-client-logging
 logtail:
   # Enable logtail for tailscale nodes of this Headscale instance.
   # As there is currently no support for overriding the log server in Headscale, this is
   # disabled by default. Enabling this will make your clients send logs to Tailscale Inc.
   enabled: false
 
-# Enabling this option makes devices prefer a random port for WireGuard traffic over the
-# default static port 41641. This option is intended as a workaround for some buggy
-# firewall devices. See https://tailscale.com/kb/1181/firewalls/ for more information.
-randomize_client_port: false
-
 # Taildrop configuration
-# Taildrop is the file sharing feature of Tailscale, allowing nodes to send files to each other.
-# https://tailscale.com/kb/1106/taildrop/
+# Taildrop is the file sharing feature of Tailscale, allowing nodes to
+# send files to each other.
+# https://tailscale.com/docs/features/taildrop
 taildrop:
-  # Enable or disable Taildrop for all nodes.
-  # When enabled, nodes can send files to other nodes owned by the same user.
-  # Tagged devices and cross-user transfers are not permitted by Tailscale clients.
+  # Enable or disable Taildrop tailnet-wide. When disabled, headscale
+  # withholds `https://tailscale.com/cap/file-sharing` from every
+  # node's CapMap.
   enabled: true
+
+# Default node auto-update behaviour. When enabled, every node's
+# CapMap carries `default-auto-update: [true]` so clients that have
+# not made a local opt-in / opt-out choice run auto-updates by
+# default. Setting it back to false flips the default for future
+# clients; clients that already stored the value locally keep their
+# choice.
+auto_update:
+  enabled: false
 # Advanced performance tuning parameters.
 # The defaults are carefully chosen and should rarely need adjustment.
 # Only modify these if you have identified a specific performance issue.

derp-example.yaml

@@ -1,4 +1,5 @@
-# If you plan to somehow use headscale, please deploy your own DERP infra: https://tailscale.com/kb/1118/custom-derp-servers/
+# If you plan to somehow use headscale, please deploy your own DERP infra.
+# See: https://tailscale.com/docs/reference/derp-servers/custom-derp-servers
 regions:
   1: null # Disable DERP region with ID 1
   900:

docs/about/faq.md

@@ -134,7 +134,7 @@ help to the community.
 
 Running headscale on a machine that is also in the tailnet can cause problems with subnet routers, traffic relay nodes, and MagicDNS. It might work, but it is not supported.
 
-## Why do two nodes see each other in their status, even if an ACL allows traffic only in one direction?
+## Why do two nodes see each other in their status, even if a policy rule allows traffic only in one direction?
 
 A frequent use case is to allow traffic only from one node to another, but not the other way around. For example, the
 workstation of an administrator should be able to connect to all nodes but the nodes themselves shouldn't be able to
@@ -142,10 +142,10 @@ connect back to the administrator's node. Why do all nodes see the administrator
 `tailscale status`?
 
 This is essentially how Tailscale works. If traffic is allowed to flow in one direction, then both nodes see each other
-in their output of `tailscale status`. Traffic is still filtered according to the ACL, with the exception of
+in their output of `tailscale status`. Traffic is still filtered according to the policy, with the exception of
 `tailscale ping` which is always allowed in either direction.
 
-See also <https://tailscale.com/kb/1087/device-visibility>.
+See also <https://tailscale.com/docs/concepts/device-visibility>.
 
 ## My policy is stored in the database and Headscale refuses to start due to an invalid policy. How can I recover?
 
@@ -191,7 +191,7 @@ following steps can be used to migrate from unsupported IP prefixes back to the
     SET ipv4=concat('100.64.', id/256, '.', id%256),
         ipv6=concat('fd7a:115c:a1e0::', format('%x', id));
     ```
-- Update the [policy](../ref/acls.md) to reflect the IP address changes (if any)
+- Update the [policy](../ref/policy.md) to reflect the IP address changes (if any)
 - Start Headscale
 
 Nodes should reconnect within a few seconds and pickup their newly assigned IP addresses.
@@ -199,7 +199,7 @@ Nodes should reconnect within a few seconds and pickup their newly assigned IP a
 ## How can I avoid to send logs to Tailscale Inc?
 
 A Tailscale client [collects logs about its operation and connection attempts with other
-clients](https://tailscale.com/kb/1011/log-mesh-traffic#client-logs) and sends them to a central log service operated by
+clients](https://tailscale.com/docs/features/logging#client-logs) and sends them to a central log service operated by
 Tailscale Inc.
 
 Headscale, by default, instructs clients to disable log submission to the central log service. This configuration is
@@ -209,5 +209,5 @@ applied by a client once it successfully connected with Headscale. See the confi
 Alternatively, logging can also be disabled on the client side. This is independent of Headscale and opting out of
 client logging disables log submission early during client startup. The configuration is operating system specific and
 is usually achieved by setting the environment variable `TS_NO_LOGS_NO_SUPPORT=true` or by passing the flag
-`--no-logs-no-support` to `tailscaled`. See
-<https://tailscale.com/kb/1011/log-mesh-traffic#opting-out-of-client-logging> for details.
+`--no-logs-no-support` to `tailscaled`. See <https://tailscale.com/docs/features/logging#opt-out-of-client-logging> for
+details.

docs/about/features.md

@@ -9,30 +9,37 @@ provides on overview of Headscale's feature and compatibility with the Tailscale
     - [x] [Web authentication](../ref/registration.md#web-authentication)
     - [x] [Pre authenticated key](../ref/registration.md#pre-authenticated-key)
 - [x] [DNS](../ref/dns.md)
-    - [x] [MagicDNS](https://tailscale.com/kb/1081/magicdns)
-    - [x] [Global and restricted nameservers (split DNS)](https://tailscale.com/kb/1054/dns#nameservers)
-    - [x] [search domains](https://tailscale.com/kb/1054/dns#search-domains)
+    - [x] [MagicDNS](https://tailscale.com/docs/features/magicdns)
+    - [x] [Global and restricted nameservers (split DNS)](https://tailscale.com/docs/reference/dns-in-tailscale#nameservers)
+    - [x] [search domains](https://tailscale.com/docs/reference/dns-in-tailscale#search-domains)
     - [x] [Extra DNS records (Headscale only)](../ref/dns.md#setting-extra-dns-records)
-- [x] [Taildrop (File Sharing)](https://tailscale.com/kb/1106/taildrop)
+- [x] File sharing
+    - [x] [Taildrive](https://tailscale.com/docs/features/taildrive)
+    - [x] [Taildrop](https://tailscale.com/docs/features/taildrop)
 - [x] [Tags](../ref/tags.md)
 - [x] [Routes](../ref/routes.md)
     - [x] [Subnet routers](../ref/routes.md#subnet-router)
     - [x] [Exit nodes](../ref/routes.md#exit-node)
+    - [x] [Route filtering with Via](https://tailscale.com/docs/features/access-control/grants/grants-via)
 - [x] Dual stack (IPv4 and IPv6)
 - [x] Ephemeral nodes
 - [x] Embedded [DERP server](../ref/derp.md)
-- [x] Access control lists ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D))
-    - [x] ACL management via API
-    - [x] Some [Autogroups](https://tailscale.com/kb/1396/targets#autogroups), currently: `autogroup:internet`,
-      `autogroup:nonroot`, `autogroup:member`, `autogroup:tagged`, `autogroup:self`
-    - [x] [Auto approvers](https://tailscale.com/kb/1337/acl-syntax#auto-approvers) for [subnet
+- [x] [Peer relays](https://tailscale.com/docs/features/peer-relay)
+- [x] [Policy](../ref/policy.md) ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D))
+    - [x] ACLs
+    - [x] Grants
+    - [x] Some [Autogroups](../ref/policy.md#autogroups)
+    - [x] [Auto approvers](https://tailscale.com/docs/reference/syntax/policy-file#auto-approvers) for [subnet
       routers](../ref/routes.md#automatically-approve-routes-of-a-subnet-router) and [exit
       nodes](../ref/routes.md#automatically-approve-an-exit-node-with-auto-approvers)
-    - [x] [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh)
+    - [x] [Tailscale SSH](https://tailscale.com/docs/features/tailscale-ssh)
+    - [x] [Node attributes](../ref/policy.md#node-attributes)
+    - [x] [Tests](https://tailscale.com/docs/reference/syntax/policy-file#tests) and
+      [sshTests](https://tailscale.com/docs/reference/syntax/policy-file#ssh-tests)
 - [x] [Node registration using Single-Sign-On (OpenID Connect)](../ref/oidc.md) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
     - [x] Basic registration
     - [x] Update user profile from identity provider
     - [ ] OIDC groups cannot be used in ACLs
-- [ ] [Funnel](https://tailscale.com/kb/1223/funnel) ([#1040](https://github.com/juanfont/headscale/issues/1040))
-- [ ] [Serve](https://tailscale.com/kb/1312/serve) ([#1234](https://github.com/juanfont/headscale/issues/1921))
-- [ ] [Network flow logs](https://tailscale.com/kb/1219/network-flow-logs) ([#1687](https://github.com/juanfont/headscale/issues/1687))
+- [ ] [Funnel](https://tailscale.com/docs/features/tailscale-funnel) ([#1040](https://github.com/juanfont/headscale/issues/1040))
+- [ ] [Serve](https://tailscale.com/docs/features/tailscale-serve) ([#1234](https://github.com/juanfont/headscale/issues/1921))
+- [ ] [Network flow logs](https://tailscale.com/docs/features/logging/network-flow-logs) ([#1687](https://github.com/juanfont/headscale/issues/1687))

docs/index.md

@@ -8,7 +8,7 @@ hide:
 
 Headscale is an open source, self-hosted implementation of the Tailscale control server.
 
-This page contains the documentation for the latest version of headscale. Please also check our [FAQ](./about/faq.md).
+This page contains the documentation for the latest version of headscale. Please also check our [FAQ](about/faq.md).
 
 Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat and community support.
 

docs/ref/acls.md

@@ -1,288 +0,0 @@
-Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-hosted environment.
-
-For instance, instead of referring to users when defining groups you must
-use users (which are the equivalent to user/logins in Tailscale.com).
-
-Please check https://tailscale.com/kb/1018/acls/ for further information.
-
-When using ACL's the User borders are no longer applied. All machines
-whichever the User have the ability to communicate with other hosts as
-long as the ACL's permits this exchange.
-
-## ACL Setup
-
-To enable and configure ACLs in Headscale, you need to specify the path to your ACL policy file in the `policy.path` key in `config.yaml`.
-
-Your ACL policy file must be formatted using [huJSON](https://github.com/tailscale/hujson).
-
-Info on how these policies are written can be found
-[here](https://tailscale.com/kb/1018/acls/).
-
-Please reload or restart Headscale after updating the ACL file. Headscale may be reloaded either via its systemd service
-(`sudo systemctl reload headscale`) or by sending a SIGHUP signal (`sudo kill -HUP $(pidof headscale)`) to the main
-process. Headscale logs the result of ACL policy processing after each reload.
-
-## Simple Examples
-
-- [**Allow All**](https://tailscale.com/kb/1192/acl-samples#allow-all-default-acl): If you define an ACL file but completely omit the `"acls"` field from its content, Headscale will default to an "allow all" policy. This means all devices connected to your tailnet will be able to communicate freely with each other.
-
-    ```json
-    {}
-    ```
-
-- [**Deny All**](https://tailscale.com/kb/1192/acl-samples#deny-all): To prevent all communication within your tailnet, you can include an empty array for the `"acls"` field in your policy file.
-
-    ```json
-    {
-      "acls": []
-    }
-    ```
-
-## Complex Example
-
-Let's build a more complex example use case for a small business (It may be the place where
-ACL's are the most useful).
-
-We have a small company with a boss, an admin, two developers and an intern.
-
-The boss should have access to all servers but not to the user's hosts. Admin
-should also have access to all hosts except that their permissions should be
-limited to maintaining the hosts (for example purposes). The developers can do
-anything they want on dev hosts but only watch on productions hosts. Intern
-can only interact with the development servers.
-
-There's an additional server that acts as a router, connecting the VPN users
-to an internal network `10.20.0.0/16`. Developers must have access to those
-internal resources.
-
-Each user have at least a device connected to the network and we have some
-servers.
-
-- database.prod
-- database.dev
-- app-server1.prod
-- app-server1.dev
-- billing.internal
-- router.internal
-
-![ACL implementation example](../assets/images/headscale-acl-network.png)
-
-When [registering the servers](../usage/getting-started.md#register-a-node) we
-will need to add the flag `--advertise-tags=tag:<tag1>,tag:<tag2>`, and the user
-that is registering the server should be allowed to do it. Since anyone can add
-tags to a server they can register, the check of the tags is done on headscale
-server and only valid tags are applied. A tag is valid if the user that is
-registering it is allowed to do it.
-
-Here are the ACL's to implement the same permissions as above:
-
-```json title="acl.json"
-{
-  // groups are collections of users having a common scope. A user can be in multiple groups
-  // groups cannot be composed of groups
-  "groups": {
-    "group:boss": ["boss@"],
-    "group:dev": ["dev1@", "dev2@"],
-    "group:admin": ["admin1@"],
-    "group:intern": ["intern1@"]
-  },
-  // tagOwners in tailscale is an association between a TAG and the people allowed to set this TAG on a server.
-  // This is documented [here](https://tailscale.com/kb/1068/acl-tags#defining-a-tag)
-  // and explained [here](https://tailscale.com/blog/rbac-like-it-was-meant-to-be/)
-  "tagOwners": {
-    // the administrators can add servers in production
-    "tag:prod-databases": ["group:admin"],
-    "tag:prod-app-servers": ["group:admin"],
-
-    // the boss can tag any server as internal
-    "tag:internal": ["group:boss"],
-
-    // dev can add servers for dev purposes as well as admins
-    "tag:dev-databases": ["group:admin", "group:dev"],
-    "tag:dev-app-servers": ["group:admin", "group:dev"]
-
-    // interns cannot add servers
-  },
-  // hosts should be defined using its IP addresses and a subnet mask.
-  // to define a single host, use a /32 mask. You cannot use DNS entries here,
-  // as they're prone to be hijacked by replacing their IP addresses.
-  // see https://github.com/tailscale/tailscale/issues/3800 for more information.
-  "hosts": {
-    "postgresql.internal": "10.20.0.2/32",
-    "webservers.internal": "10.20.10.1/29"
-  },
-  "acls": [
-    // boss have access to all servers
-    {
-      "action": "accept",
-      "src": ["group:boss"],
-      "dst": [
-        "tag:prod-databases:*",
-        "tag:prod-app-servers:*",
-        "tag:internal:*",
-        "tag:dev-databases:*",
-        "tag:dev-app-servers:*"
-      ]
-    },
-
-    // admin have only access to administrative ports of the servers, in tcp/22
-    {
-      "action": "accept",
-      "src": ["group:admin"],
-      "proto": "tcp",
-      "dst": [
-        "tag:prod-databases:22",
-        "tag:prod-app-servers:22",
-        "tag:internal:22",
-        "tag:dev-databases:22",
-        "tag:dev-app-servers:22"
-      ]
-    },
-
-    // we also allow admin to ping the servers
-    {
-      "action": "accept",
-      "src": ["group:admin"],
-      "proto": "icmp",
-      "dst": [
-        "tag:prod-databases:*",
-        "tag:prod-app-servers:*",
-        "tag:internal:*",
-        "tag:dev-databases:*",
-        "tag:dev-app-servers:*"
-      ]
-    },
-
-    // developers have access to databases servers and application servers on all ports
-    // they can only view the applications servers in prod and have no access to databases servers in production
-    {
-      "action": "accept",
-      "src": ["group:dev"],
-      "dst": [
-        "tag:dev-databases:*",
-        "tag:dev-app-servers:*",
-        "tag:prod-app-servers:80,443"
-      ]
-    },
-    // developers have access to the internal network through the router.
-    // the internal network is composed of HTTPS endpoints and Postgresql
-    // database servers.
-    {
-      "action": "accept",
-      "src": ["group:dev"],
-      "dst": ["10.20.0.0/16:443,5432"]
-    },
-
-    // servers should be able to talk to database in tcp/5432. Database should not be able to initiate connections to
-    // applications servers
-    {
-      "action": "accept",
-      "src": ["tag:dev-app-servers"],
-      "proto": "tcp",
-      "dst": ["tag:dev-databases:5432"]
-    },
-    {
-      "action": "accept",
-      "src": ["tag:prod-app-servers"],
-      "dst": ["tag:prod-databases:5432"]
-    },
-
-    // interns have access to dev-app-servers only in reading mode
-    {
-      "action": "accept",
-      "src": ["group:intern"],
-      "dst": ["tag:dev-app-servers:80,443"]
-    },
-
-    // Allow users to access their own devices using autogroup:self (see below for more details about performance impact)
-    {
-      "action": "accept",
-      "src": ["autogroup:member"],
-      "dst": ["autogroup:self:*"]
-    }
-  ]
-}
-```
-
-## Autogroups
-
-Headscale supports several autogroups that automatically include users, destinations, or devices with specific properties. Autogroups provide a convenient way to write ACL rules without manually listing individual users or devices.
-
-### `autogroup:internet`
-
-Allows access to the internet through [exit nodes](routes.md#exit-node). Can only be used in ACL destinations.
-
-```json
-{
-  "action": "accept",
-  "src": ["group:users"],
-  "dst": ["autogroup:internet:*"]
-}
-```
-
-### `autogroup:member`
-
-Includes all [personal (untagged) devices](registration.md/#identity-model).
-
-```json
-{
-  "action": "accept",
-  "src": ["autogroup:member"],
-  "dst": ["tag:prod-app-servers:80,443"]
-}
-```
-
-### `autogroup:tagged`
-
-Includes all devices that [have at least one tag](registration.md/#identity-model).
-
-```json
-{
-  "action": "accept",
-  "src": ["autogroup:tagged"],
-  "dst": ["tag:monitoring:9090"]
-}
-```
-
-### `autogroup:self`
-
-!!! warning "The current implementation of `autogroup:self` is inefficient"
-
-Includes devices where the same user is authenticated on both the source and destination. Does not include tagged devices. Can only be used in ACL destinations.
-
-```json
-{
-  "action": "accept",
-  "src": ["autogroup:member"],
-  "dst": ["autogroup:self:*"]
-}
-```
-
-*Using `autogroup:self` may cause performance degradation on the Headscale coordinator server in large deployments, as filter rules must be compiled per-node rather than globally and the current implementation is not very efficient.*
-
-If you experience performance issues, consider using more specific ACL rules or limiting the use of `autogroup:self`.
-
-```json
-{
-  // The following rules allow internal users to communicate with their
-  // own nodes in case autogroup:self is causing performance issues.
-  { "action": "accept", "src": ["boss@"], "dst": ["boss@:*"] },
-  { "action": "accept", "src": ["dev1@"], "dst": ["dev1@:*"] },
-  { "action": "accept", "src": ["dev2@"], "dst": ["dev2@:*"] },
-  { "action": "accept", "src": ["admin1@"], "dst": ["admin1@:*"] },
-  { "action": "accept", "src": ["intern1@"], "dst": ["intern1@:*"] }
-}
-```
-
-### `autogroup:nonroot`
-
-Used in Tailscale SSH rules to allow access to any user except root. Can only be used in the `users` field of SSH rules.
-
-```json
-{
-  "action": "accept",
-  "src": ["autogroup:member"],
-  "dst": ["autogroup:self"],
-  "users": ["autogroup:nonroot"]
-}
-```

docs/ref/debug.md

@@ -3,16 +3,16 @@
 Headscale and Tailscale provide debug and introspection capabilities that can be helpful when things don't work as
 expected. This page explains some debugging techniques to help pinpoint problems.
 
-Please also have a look at [Tailscale's Troubleshooting guide](https://tailscale.com/kb/1023/troubleshooting). It offers
-a many tips and suggestions to troubleshoot common issues.
+Please also have a look at [Tailscale's Troubleshooting guide](https://tailscale.com/docs/reference/troubleshooting). It
+offers a many tips and suggestions to troubleshoot common issues.
 
 ## Tailscale
 
 The Tailscale client itself offers many commands to introspect its state as well as the state of the network:
 
-- [Check local network conditions](https://tailscale.com/kb/1080/cli#netcheck): `tailscale netcheck`
-- [Get the client status](https://tailscale.com/kb/1080/cli#status): `tailscale status --json`
-- [Get DNS status](https://tailscale.com/kb/1080/cli#dns): `tailscale dns status --all`
+- [Check local network conditions](https://tailscale.com/docs/reference/tailscale-cli#netcheck): `tailscale netcheck`
+- [Get the client status](https://tailscale.com/docs/reference/tailscale-cli#status): `tailscale status --json`
+- [Get DNS status](https://tailscale.com/docs/reference/tailscale-cli#dns): `tailscale dns status --all`
 - Client logs: `tailscale debug daemon-logs`
 - Client netmap: `tailscale debug netmap`
 - Test DERP connection: `tailscale debug derp headscale`
@@ -53,19 +53,19 @@ Headscale provides a metrics and debug endpoint. It allows to introspect differe
 
 - Information about the Go runtime, memory usage and statistics
 - Connected nodes and pending registrations
-- Active ACLs, filters and SSH policy
+- Active policy, filters and SSH policy
 - Current DERPMap
 - Prometheus metrics
 
 !!! warning "Keep the metrics and debug endpoint private"
 
     The listen address and port can be configured with the `metrics_listen_addr` variable in the [configuration
-    file](./configuration.md). By default it listens on localhost, port 9090.
+    file](configuration.md). By default it listens on localhost, port 9090.
 
     Keep the metrics and debug endpoint private to your internal network and don't expose it to the Internet.
 
     The metrics and debug interface can be disabled completely by setting `metrics_listen_addr: null` in the
-    [configuration file](./configuration.md).
+    [configuration file](configuration.md).
 
 Query metrics via <http://localhost:9090/metrics> and get an overview of available debug information via
 <http://localhost:9090/debug/>. Metrics may be queried from outside localhost but the debug interface is subject to

docs/ref/derp.md

@@ -1,13 +1,13 @@
 # DERP
 
-A [DERP (Designated Encrypted Relay for Packets) server](https://tailscale.com/kb/1232/derp-servers) is mainly used to
-relay traffic between two nodes in case a direct connection can't be established. Headscale provides an embedded DERP
-server to ensure seamless connectivity between nodes.
+A [DERP (Designated Encrypted Relay for Packets) server](https://tailscale.com/docs/reference/derp-servers) is mainly
+used to relay traffic between two nodes in case a direct connection can't be established. Headscale provides an embedded
+DERP server to ensure seamless connectivity between nodes.
 
 ## Configuration
 
-DERP related settings are configured within the `derp` section of the [configuration file](./configuration.md). The
-following sections only use a few of the available settings, check the [example configuration](./configuration.md) for
+DERP related settings are configured within the `derp` section of the [configuration file](configuration.md). The
+following sections only use a few of the available settings, check the [example configuration](configuration.md) for
 all available configuration options.
 
 ### Enable embedded DERP
@@ -31,8 +31,8 @@ traversal. [Check DERP server connectivity](#check-derp-server-connectivity) to
 ### Remove Tailscale's DERP servers
 
 Once enabled, Headscale's embedded DERP is added to the list of free-to-use [DERP
-servers](https://tailscale.com/kb/1232/derp-servers) offered by Tailscale Inc. To only use Headscale's embedded DERP
-server, disable the loading of the default DERP map:
+servers](https://tailscale.com/docs/reference/derp-servers) offered by Tailscale Inc. To only use Headscale's embedded
+DERP server, disable the loading of the default DERP map:
 
 ```yaml title="config.yaml" hl_lines="6"
 derp:
@@ -59,8 +59,8 @@ maps fetched via URL or to offer your own, custom DERP servers to nodes.
 
 === "Remove specific DERP regions"
 
-    The free-to-use [DERP servers](https://tailscale.com/kb/1232/derp-servers) are organized into regions via a region
-    ID. You can explicitly disable a specific region by setting its region ID to `null`. The following sample
+    The free-to-use [DERP servers](https://tailscale.com/docs/reference/derp-servers) are organized into regions via a
+    region ID. You can explicitly disable a specific region by setting its region ID to `null`. The following sample
     `derp.yaml` disables the New York DERP region (which has the region ID 1):
 
     ```yaml title="derp.yaml"
@@ -163,7 +163,7 @@ Any Tailscale client may be used to introspect the DERP map and to check for con
 - Check connectivity with the embedded DERP[^1]:`tailscale debug derp headscale`
 
 Additional DERP related metrics and information is available via the [metrics and debug
-endpoint](./debug.md#metrics-and-debug-endpoint).
+endpoint](debug.md#metrics-and-debug-endpoint).
 
 ## Limitations
 
@@ -171,4 +171,4 @@ endpoint](./debug.md#metrics-and-debug-endpoint).
   endpoint via HTTP on port tcp/80.
 - There are no speed or throughput optimisations, the main purpose is to assist in node connectivity.
 
-[^1]: This assumes that the default region code of the [configuration file](./configuration.md) is used.
+[^1]: This assumes that the default region code of the [configuration file](configuration.md) is used.

docs/ref/dns.md

@@ -1,19 +1,19 @@
 # DNS
 
 Headscale supports [most DNS features](../about/features.md) from Tailscale. DNS related settings can be configured
-within the `dns` section of the [configuration file](./configuration.md).
+within the `dns` section of the [configuration file](configuration.md).
 
 ## Setting extra DNS records
 
 Headscale allows to set extra DNS records which are made available via
-[MagicDNS](https://tailscale.com/kb/1081/magicdns). Extra DNS records can be configured either via static entries in the
-[configuration file](./configuration.md) or from a JSON file that Headscale continuously watches for changes:
+[MagicDNS](https://tailscale.com/docs/features/magicdns). Extra DNS records can be configured either via static entries
+in the [configuration file](configuration.md) or from a JSON file that Headscale continuously watches for changes:
 
-- Use the `dns.extra_records` option in the [configuration file](./configuration.md) for entries that are static and
+- Use the `dns.extra_records` option in the [configuration file](configuration.md) for entries that are static and
   don't change while Headscale is running. Those entries are processed when Headscale is starting up and changes to the
   configuration require a restart of Headscale.
 - For dynamic DNS records that may be added, updated or removed while Headscale is running or DNS records that are
-  generated by scripts the option `dns.extra_records_path` in the [configuration file](./configuration.md) is useful.
+  generated by scripts the option `dns.extra_records_path` in the [configuration file](configuration.md) is useful.
   Set it to the absolute path of the JSON file containing DNS records and Headscale processes this file as it detects
   changes.
 
@@ -66,7 +66,7 @@ hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:30
 
         !!! tip "Good to know"
 
-            - The `dns.extra_records_path` option in the [configuration file](./configuration.md) needs to reference the
+            - The `dns.extra_records_path` option in the [configuration file](configuration.md) needs to reference the
               JSON file containing extra DNS records.
             - Be sure to "sort keys" and produce a stable output in case you generate the JSON file with a script.
               Headscale uses a checksum to detect changes to the file and a stable output avoids unnecessary processing.

docs/ref/integration/reverse-proxy.md

@@ -1,90 +1,186 @@
-# Running headscale behind a reverse proxy
+# Running Headscale behind a reverse proxy
 
 !!! warning "Community documentation"
 
-    This page is not actively maintained by the headscale authors and is
-    written by community members. It is _not_ verified by headscale developers.
+    This page is not actively maintained by the Headscale authors and is
+    written by community members. It is _not_ verified by Headscale developers.
 
     **It might be outdated and it might miss necessary steps**.
 
-Running headscale behind a reverse proxy is useful when running multiple applications on the same server, and you want to reuse the same external IP and port - usually tcp/443 for HTTPS.
+Running Headscale behind a reverse proxy is useful when running multiple applications on the same server, and you want
+to reuse the same external IP and port - usually tcp/443 for HTTPS.
 
-### WebSockets
+Please see [limitations](#limitations) for known issues and limitations.
 
-The reverse proxy MUST be configured to support WebSockets to communicate with Tailscale clients.
+## Configuration
 
-WebSockets support is also required when using the Headscale [embedded DERP server](../derp.md). In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml).
+The configuration depends on the set of Headscale features you intend to use. Please have a look at the
+[requirements](../../setup/requirements.md) and especially the [ports in use](../../setup/requirements.md#ports-in-use)
+section to learn what a Tailscale clients expects.
 
-### Cloudflare
+The configuration examples in this documentation are basic and cover only HTTP and HTTPS traffic. Other features such as
+STUN for Headscale's [embedded DERP server](../derp.md) are expected to be exposed directly or to be only available on
+localhost.
 
-Running headscale behind a cloudflare proxy or cloudflare tunnel is not supported and will not work as Cloudflare does not support WebSocket POSTs as required by the Tailscale protocol. See [this issue](https://github.com/juanfont/headscale/issues/1468)
+### WebSocket
+
+Tailscale clients are using a custom protocol (Tailscale Control Protocol) to communicate with a control server such as
+Headscale. The reverse proxy **must** be configured to support WebSockets in order to communicate with Tailscale clients
+and it needs to handle two peculiarities of the Tailscale Control Protocol:
+
+- The POST method is used to upgrade the WebSocket connection.
+- The value for the `Upgrade` header is `tailscale-control-protocol`.
 
 ### TLS
 
-Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration values to your headscale config file.
+Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration
+values to your Headscale [configuration file](../configuration.md):
 
-```yaml title="config.yaml"
-server_url: https://<YOUR_SERVER_NAME> # This should be the FQDN at which headscale will be served
-listen_addr: 0.0.0.0:8080
-metrics_listen_addr: 0.0.0.0:9090
+```yaml title="config.yaml" hl_lines="1"
+server_url: https://<SERVER_NAME>
 tls_cert_path: ""
 tls_key_path: ""
 ```
 
-## nginx
+Headscale logs `WRN listening without TLS but ServerURL does not start with http://` during startup. This is expected
+and indicates that the reverse proxy is in charge of terminating TLS.
 
-The following example configuration can be used in your nginx setup, substituting values as necessary. `<IP:PORT>` should be the IP address and port where headscale is running. In most cases, this will be `http://localhost:8080`.
+### Trusted proxies
 
-```nginx title="nginx.conf"
-map $http_upgrade $connection_upgrade {
-    default      upgrade;
-    ''           close;
+Headscale ignores `True-Client-IP`, `X-Real-IP` and `X-Forwarded-For` headers unless the request's TCP peer matches the
+`trusted_proxies` configuration option. Set this to the CIDR(s) your reverse proxy connects from so the real client IP
+appears in access logs.
+
+```yaml title="config.yaml"
+trusted_proxies:
+  - 127.0.0.1/32
+  - ::1/128
+```
+
+The reverse proxy is responsible to replace any client-supplied `True-Client-IP`, `X-Real-IP`, `X-Forwarded-For` headers
+on inbound requests with sanitized values. Headscale picks the first valid IP address supplied by headers in this order:
+
+- `True-Client-IP`
+- `X-Real-IP`
+- `X-Forwarded-For`
+
+## Limitations
+
+- A reverse proxy adds another layer of complexity that needs to be able to handle the [Tailscale Control
+  Protocol](#websocket) properly. Be sure to test your setup without a reverse proxy before raising an issue.
+- STUN (used along with the [embedded DERP server](../derp.md)) requires udp/3478 to be served publicly.
+- [gRPC](../api.md#grpc) (used to remote control Headscale) may not be proxied.
+
+## Reverse proxy specific configuration
+
+!!! warning "Third-party software and services"
+
+    This section of the documentation is specific for third-party software and services. We recommend users read the
+    third-party documentation for a secure configuration.
+
+This following Headscale configuration may be used as base for the various reverse proxy examples below. The following
+is [assumed](../../setup/requirements.md):
+
+- Service for Tailscale clients is served via HTTPS on port 443.
+- The reverse proxy redirects HTTP to HTTPS and is terminating TLS.
+- Both Headscale and the reverse proxy are running on the same host.
+- [Metrics](../debug.md#metrics-and-debug-endpoint) and [gRPC](../api.md#grpc) are not proxied, those are available via
+  localhost.
+
+```yaml title="config.yaml" hl_lines="1"
+server_url: https://<SERVER_NAME>
+listen_addr: 127.0.0.1:8080
+metrics_listen_addr: 127.0.0.1:9090
+grpc_listen_addr: 127.0.0.1:50443
+trusted_proxies:
+  - 127.0.0.1/32
+  - ::1/128
+tls_cert_path: ""
+tls_key_path: ""
+```
+
+### Apache
+
+The following basic Apache configuration works with the Headscale configuration [as shown
+above](#reverse-proxy-specific-configuration). Substitute placeholders and adjust the configuration as needed:
+
+- `<SERVER_NAME>`: The server name for your instance, e.g. `headscale.example.com`
+- `<PATH_TO_TLS_CERT>`: Absolute path to your TLS certificate
+- `<PATH_TO_TLS_KEY>`: Absolute path to your TLS private key
+
+```apache title="apache.conf" hl_lines="2 7 11 14-15"
+<VirtualHost *:80>
+  ServerName <SERVER_NAME>
+
+  # Tailscale captive portal detection
+  RedirectMatch 204 ^/generate_204$
+
+  RedirectMatch permanent "^/(.*)$" "https://<SERVER_NAME>/$1"
+</VirtualHost>
+
+<VirtualHost *:443>
+  ServerName <SERVER_NAME>
+
+  SSLEngine On
+  SSLCertificateFile <PATH_TO_TLS_CERT>
+  SSLCertificateKeyFile <PATH_TO_TLS_KEY>
+
+  RequestHeader set True-Client-IP "%{REMOTE_ADDR}s"
+  RequestHeader set X-Real-IP "%{REMOTE_ADDR}s"
+
+  ProxyPreserveHost On
+  ProxyPass / http://127.0.0.1:8080/ upgrade=any
+</VirtualHost>
+```
+
+Note that `upgrade=any` is required as a parameter for `ProxyPass` so that WebSocket traffic whose `Upgrade` header
+value is not equal to `WebSocket` (i. e. Tailscale Control Protocol) is forwarded correctly. See the [Apache
+docs](https://httpd.apache.org/docs/current/mod/mod_proxy.html#upgrade) for more information on this.
+
+### Caddy
+
+The following basic Caddyfile works with the Headscale configuration [as shown
+above](#reverse-proxy-specific-configuration). Substitute placeholders and adjust the configuration as needed:
+
+- `<SERVER_NAME>`: The server name for your instance, e.g. `headscale.example.com`
+
+```none title="Caddyfile" hl_lines="1 12"
+http://<SERVER_NAME> {
+	# Tailscale captive portal detection
+	handle /generate_204 {
+		respond 204
+	}
+
+	handle * {
+		redir https://{host}{uri}
+	}
 }
 
-server {
-    listen 80;
-	listen [::]:80;
-
-	listen 443      ssl http2;
-	listen [::]:443 ssl http2;
-
-    server_name <YOUR_SERVER_NAME>;
-
-    ssl_certificate <PATH_TO_CERT>;
-    ssl_certificate_key <PATH_CERT_KEY>;
-    ssl_protocols TLSv1.2 TLSv1.3;
-
-    location / {
-        proxy_pass http://<IP:PORT>;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection $connection_upgrade;
-        proxy_set_header Host $server_name;
-        proxy_redirect http:// https://;
-        proxy_buffering off;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
-    }
+<SERVER_NAME> {
+	reverse_proxy 127.0.0.1:8080 {
+		header_up True-Client-IP {remote_host}
+		header_up X-Real-IP {remote_host}
+	}
 }
 ```
 
-## istio/envoy
+Caddy will [automatically](https://caddyserver.com/docs/automatic-https) provision a certificate for your
+domain/subdomain, force HTTPS, and proxy WebSocket connections.
 
-If you using [Istio](https://istio.io/) ingressgateway or [Envoy](https://www.envoyproxy.io/) as reverse proxy, there are some tips for you. If not set, you may see some debug log in proxy as below:
+### Cloudflare
 
-```log
-Sending local reply with details upgrade_failed
-```
+Running Headscale behind a Cloudflare Proxy or Cloudflare Tunnel is not supported and will not work as Cloudflare does
+not support [WebSocket POSTs as required by the Tailscale protocol](#websocket). See [issue
+1468](https://github.com/juanfont/headscale/issues/1468) for more information.
 
 ### Envoy
 
-You need to add a new upgrade_type named `tailscale-control-protocol`. [see details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig)
+You need to add a new upgrade_type named `tailscale-control-protocol`. [See
+details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig).
 
 ### Istio
 
-Same as envoy, we can use `EnvoyFilter` to add upgrade_type.
+Same as [envoy](#envoy), we can use `EnvoyFilter` to add a new upgrade_type named `tailscale-control-protocol`.
 
 ```yaml
 apiVersion: networking.istio.io/v1alpha3
@@ -109,33 +205,68 @@ spec:
               - upgrade_type: tailscale-control-protocol
 ```
 
-## Caddy
+### Nginx
 
-The following Caddyfile is all that is necessary to use Caddy as a reverse proxy for headscale, in combination with the `config.yaml` specifications above to disable headscale's built in TLS. Replace values as necessary - `<YOUR_SERVER_NAME>` should be the FQDN at which headscale will be served, and `<IP:PORT>` should be the IP address and port where headscale is running. In most cases, this will be `localhost:8080`.
+The following basic Nginx configuration works with the Headscale configuration [as shown
+above](#reverse-proxy-specific-configuration). Substitute placeholders and adjust the configuration as needed:
 
-```none title="Caddyfile"
-<YOUR_SERVER_NAME> {
-    reverse_proxy <IP:PORT>
+- `<SERVER_NAME>`: The server name for your instance, e.g. `headscale.example.com`
+- `<PATH_TO_TLS_CERT>`: Absolute path to your TLS certificate
+- `<PATH_TO_TLS_KEY>`: Absolute path to your TLS private key
+
+```nginx title="nginx.conf" hl_lines="19 37 39-40"
+# headscale
+upstream headscale {
+  zone upstreams 64K;
+  server 127.0.0.1:8080 max_fails=1 fail_timeout=5s;
+  keepalive 2;
+}
+
+# websocket
+map $http_upgrade $connection_upgrade {
+  default keep-alive;
+  ''      close;
+}
+
+# http
+server {
+  listen 80;
+  listen [::]:80;
+
+  server_name <SERVER_NAME>;
+
+  # Tailscale captive portal detection
+  location = /generate_204 {
+    return 204;
+  }
+
+  location / {
+    return 301 https://$server_name$request_uri;
+  }
+}
+
+# https
+server {
+  listen 443 ssl;
+  listen [::]:443 ssl;
+  http2 on;
+
+  server_name <SERVER_NAME>;
+
+  ssl_certificate <PATH_TO_TLS_CERT>;
+  ssl_certificate_key <PATH_TO_TLS_KEY>;
+
+  location / {
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_set_header Host $host;
+    proxy_set_header True-Client-IP $remote_addr;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_buffering off;
+    proxy_pass http://headscale;
+  }
 }
 ```
-
-Caddy v2 will [automatically](https://caddyserver.com/docs/automatic-https) provision a certificate for your domain/subdomain, force HTTPS, and proxy websockets - no further configuration is necessary.
-
-For a slightly more complex configuration which utilizes Docker containers to manage Caddy, headscale, and Headscale-UI, [Guru Computing's guide](https://blog.gurucomputing.com.au/smart-vpns-with-headscale/) is an excellent reference.
-
-## Apache
-
-The following minimal Apache config will proxy traffic to the headscale instance on `<IP:PORT>`. Note that `upgrade=any` is required as a parameter for `ProxyPass` so that WebSockets traffic whose `Upgrade` header value is not equal to `WebSocket` (i. e. Tailscale Control Protocol) is forwarded correctly. See the [Apache docs](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) for more information on this.
-
-```apache title="apache.conf"
-<VirtualHost *:443>
-	ServerName <YOUR_SERVER_NAME>
-
-	ProxyPreserveHost On
-	ProxyPass / http://<IP:PORT>/ upgrade=any
-
-	SSLEngine On
-	SSLCertificateFile <PATH_TO_CERT>
-	SSLCertificateKeyFile <PATH_CERT_KEY>
-</VirtualHost>
-```

docs/ref/integration/web-ui.md

@@ -19,8 +19,9 @@ Headscale doesn't provide a built-in web interface but users may pick one from t
   it offers Local (`docker exec`) and API Mode
 - [headscale-console](https://github.com/rickli-cloud/headscale-console) - WebAssembly-based client supporting SSH, VNC
   and RDP with optional self-service capabilities
-- [headscale-piying](https://github.com/wszgrcy/headscale-piying) - headscale web ui,support visual ACL configuration
+- [headscale-piying](https://github.com/wszgrcy/headscale-piying) - headscale web ui, support visual ACL configuration
 - [HeadControl](https://github.com/ahmadzip/HeadControl) - Minimal Headscale admin dashboard, built with Go and HTMX
 - [Headscale Manager](https://github.com/hkdone/headscalemanager) - Headscale UI for Android
+- [Headscale UI](https://github.com/MunMunMiao/headscale-ui) - Headscale UI online and Self-hosting
 
 You can ask for support on our [Discord server](https://discord.gg/c84AZQhmpx) in the "web-interfaces" channel.

docs/ref/oidc.md

@@ -214,14 +214,14 @@ You may refer to users in the Headscale policy via:
     {
       "groups": {
         "group:alice": [
-          "https://soo.example.com/oauth2/openid/59ac9125-c31b-46c5-814e-06242908cf57@"
+          "https://sso.example.com/oauth2/openid/59ac9125-c31b-46c5-814e-06242908cf57@"
         ]
       },
-      "acls": [
+      "grants": [
         {
-          "action": "accept",
           "src": ["group:alice"],
-          "dst": ["*:*"]
+          "dst": ["*"],
+          "ip": ["*"]
         }
       ]
     }
@@ -246,7 +246,7 @@ endpoint.
 
 - Support for OpenID Connect aims to be generic and vendor independent. It offers only limited support for quirks of
   specific identity providers.
-- OIDC groups cannot be used in ACLs.
+- OIDC groups cannot be used in policy rules.
 - The username provided by the identity provider needs to adhere to this pattern:
     - The username must be at least two characters long.
     - It must only contain letters, digits, hyphens, dots, underscores, and up to a single `@`.
@@ -283,9 +283,9 @@ Authelia is fully supported by Headscale.
 
 ### Google OAuth
 
-!!! warning "No username due to missing preferred_username"
+!!! warning "No username due to missing preferred_username claim"
 
-    Google OAuth does not send the `preferred_username` claim when the scope `profile` is requested. The username in
+    Google OAuth does not send the `preferred_username` claim when the `profile` scope is requested. The username in
     Headscale will be blank/not set.
 
 In order to integrate Headscale with Google, you'll need to have a [Google Cloud

docs/ref/policy.md

@@ -0,0 +1,249 @@
+# Policy
+
+Headscale implements a large portion of Tailscale's [policy
+features](https://tailscale.com/docs/features/tailnet-policy-file), most notably access control based on
+[ACLs](https://tailscale.com/docs/features/access-control/acls) and
+[Grants](https://tailscale.com/docs/features/access-control/grants) or [Tailscale
+SSH](https://tailscale.com/docs/features/tailscale-ssh). See [limitations](#limitations) to learn about missing features
+and notable implementation differences between Headscale and Tailscale.
+
+Headscale uses the same [huJSON](https://github.com/tailscale/hujson) based file format as Tailscale. By default, no
+policy is loaded which means that Headscale allows all traffic between nodes. To start using a policy file[^1], specify
+its path in the `policy.path` key in the [configuration file](configuration.md).
+
+Headscale needs to be reloaded to pick up changes to the policy file. Either reload Headscale via its systemd service
+(`sudo systemctl reload headscale`) or by sending a SIGHUP signal (`sudo kill -HUP $(pidof headscale)`) to the main
+process. Headscale logs the result of policy processing after each reload.
+
+Please have a look at Tailscale's policy related documentation to learn more:
+
+- [Tailscale policy file](https://tailscale.com/docs/features/tailnet-policy-file): A description of supported sections
+  within the policy file along with links to syntax references for each section.
+- [ACLs](https://tailscale.com/docs/features/access-control/acls): How to configure access control using ACLs.
+- [Grants](https://tailscale.com/docs/features/access-control/grants): Introduction to Grants with links to [syntax
+  reference](https://tailscale.com/docs/reference/syntax/grants),
+  [examples](https://tailscale.com/docs/reference/examples/grants) and a [migration guide from ACLs to
+  Grants](https://tailscale.com/docs/reference/migrate-acls-grants).
+
+## Getting started
+
+Headscale supports both [ACLs](https://tailscale.com/docs/features/access-control/acls) and
+[Grants](https://tailscale.com/docs/features/access-control/grants) to write an access control policy. We recommend the
+use of Grants since ACLs are considered legacy and will not receive new features by Tailscale.
+
+### Allow All
+
+If you define a policy file but completely omit the `"acls"` or `"grants"` section, Headscale will default to an [allow
+all](https://tailscale.com/docs/reference/examples/acls#allow-all-default-acl) policy. This means all devices connected
+to your tailnet will be able to communicate freely with each other.
+
+```json title="policy.json"
+{}
+```
+
+### Deny All
+
+To [prevent all communication within your tailnet](https://tailscale.com/docs/reference/examples/acls#deny-all), you can
+include an empty array for the `"grants"` section in your policy file.
+
+```json title="policy.json"
+{
+  "grants": []
+}
+```
+
+### More examples
+
+- See our documentation on [subnet routers](routes.md#subnet-router) and [exit nodes](routes.md#exit-node) to learn how
+  to restrict their use or how to automatically approve them.
+- The Tailscale documentation provides a large collection of configuration examples:
+    - [ACL examples](https://tailscale.com/docs/reference/examples/acls)
+    - [Grants examples](https://tailscale.com/docs/reference/examples/grants)
+    - [SSH configuration](https://tailscale.com/docs/features/tailscale-ssh#configure-tailscale-ssh)
+    - [Define a tag](https://tailscale.com/docs/features/tags#define-a-tag)
+
+______________________________________________________________________
+
+## Limitations
+
+- [Device postures](https://tailscale.com/docs/features/device-posture) and the related sections such as `postures` or
+  `srcPosture` aren't supported.
+- [IP sets](https://tailscale.com/docs/features/tailnet-policy-file/ip-sets) aren't supported.
+- A subset of [Autogroups](#autogroups) are available.
+
+## Autogroups
+
+Headscale supports several [Autogroups](https://tailscale.com/docs/reference/targets-and-selectors#autogroups) that
+automatically include users, destinations, or devices with specific properties. Autogroups provide a convenient way to
+write policy rules without manually listing individual users or devices.
+
+### [`autogroup:internet`](https://tailscale.com/docs/reference/targets-and-selectors#autogroupinternet)
+
+Allows access to the internet through [exit nodes](routes.md#exit-node). Can only be used in policy destinations.
+
+```json title="policy.json"
+{
+  "grants": [
+    {
+      "src": ["alice@"],
+      "dst": ["autogroup:internet"],
+      "ip": ["*"]
+    }
+  ]
+}
+```
+
+### [`autogroup:member`](https://tailscale.com/docs/reference/targets-and-selectors#autogrouprole)
+
+Includes all [personal (untagged) devices](registration.md/#identity-model).
+
+```json title="policy.json"
+{
+  "grants": [
+    {
+      "src": ["autogroup:member"],
+      "dst": ["tag:prod-app-servers"],
+      "ip": ["80,443"]
+    }
+  ]
+}
+```
+
+### [`autogroup:tagged`](https://tailscale.com/docs/reference/targets-and-selectors#autogrouptagged)
+
+Includes all devices that [have at least one tag](registration.md/#identity-model).
+
+```json title="policy.json"
+{
+  "grants": [
+    {
+      "src": ["autogroup:tagged"],
+      "dst": ["tag:monitoring"],
+      "ip": ["9090"]
+    }
+  ]
+}
+```
+
+### [`autogroup:self`](https://tailscale.com/docs/reference/targets-and-selectors#autogroupself)
+
+Includes devices where the same user is authenticated on both the source and destination. Does not include tagged
+devices. Can only be used in policy destinations.
+
+```json title="policy.json"
+{
+  "grants": [
+    {
+      "src": ["autogroup:member"],
+      "dst": ["autogroup:self"],
+      "ip": ["*"]
+    }
+  ]
+}
+```
+
+!!! warning "The current implementation of `autogroup:self` is inefficient"
+
+    Using `autogroup:self` may cause performance degradation on the Headscale coordinator server in large deployments,
+    as filter rules must be compiled per-node rather than globally and the current implementation is not very efficient.
+
+    If you experience performance issues, consider using more specific policy rules or limiting the use of
+    `autogroup:self`.
+
+    ```json title="policy.json"
+    {
+      "grants": [
+        // The following rules allow internal users to communicate with their
+        // own nodes in case autogroup:self is causing performance issues.
+        {
+          "src": ["boss@"],
+          "dst": ["boss@"],
+          "ip": ["*"]
+        },
+        {
+          "src": ["dev1@"],
+          "dst": ["dev1@"],
+          "ip": ["*"]
+        },
+        {
+          "src": ["intern1@"],
+          "dst": ["intern1@"],
+          "ip": ["*"]
+        }
+      ]
+    }
+    ```
+
+### [`autogroup:nonroot`](https://tailscale.com/docs/reference/targets-and-selectors#other-built-in-targets)
+
+Used in Tailscale SSH rules to allow access to any user except root. Can only be used in the `users` field of SSH rules.
+
+```json title="policy.json"
+{
+  "ssh": [
+    {
+      "action": "accept",
+      "src": ["autogroup:member"],
+      "dst": ["autogroup:self"],
+      "users": ["autogroup:nonroot"]
+    }
+  ]
+}
+```
+
+### [`autogroup:danger-all`](https://tailscale.com/docs/reference/targets-and-selectors#autogroupdanger-all)
+
+This autogroup resolves to all IP addresses (`0.0.0.0/0` and `::/0`) which also includes all IP addresses outside the
+standard Tailscale IP ranges. This autogroup can only be used as source.
+
+## Node Attributes
+
+[Node attributes](https://tailscale.com/docs/reference/syntax/policy-file#node-attributes) allow for device-specific
+configuration and attributes. At least the following node attributes are currently supported by Headscale[^2]:
+
+- `drive:access`, `drive:share`: [Taildrive support](https://tailscale.com/docs/features/taildrive).
+- `nextdns:<profile>`, `nextdns:no-device-info`: [NextDNS integration](https://tailscale.com/docs/integrations/nextdns).
+  Be sure to set NextDNS as global resolver in the [configuration](configuration.md).
+- `magicdns-aaaa`: Respond to AAAA queries on the local [MagicDNS](https://tailscale.com/docs/features/magicdns)
+  resolver at 100.100.100.100.
+- `disable-ipv4`: Selectively disable IPv4 for specfic nodes. This is may be useful to workaround [CGNat
+  conflicts](https://tailscale.com/docs/reference/troubleshooting/network-configuration/cgnat-conflicts).
+- `randomize-client-port`: Allocate a [random port for WireGuard
+  traffic](https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport) instead of the static default
+  port 41641.
+- `disable-captive-portal-detection`: [Disable automatic captive portal
+  detection](https://tailscale.com/docs/integrations/captive-portals#disable-captive-portal-detection).
+
+```json title="policy.json"
+{
+  "nodeAttrs": [
+    {
+      // Enable MagicDNS AAAA records for all nodes
+      "target": ["*"]
+      "attr": ["magicdns-aaaa"]
+    }
+  ]
+}
+```
+
+## Network-wide policy options
+
+The following options are applied for the entire tailnet. Consider [node attributes](#node-attributes) for a more
+fine-grained configuration instead.
+
+- `randomizeClientPort`: Allocate a [random port for WireGuard
+  traffic](https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport) instead of the static default
+  port 41641.
+
+```json title="policy.json"
+{
+  // Use a random WireGuard port for the entire tailnet
+  "randomizeClientPort": true
+}
+```
+
+[^1]: Headscale also allows to store the policy in the database. This is typically only required in case a [web
+    interface](integration/web-ui.md) is used.
+
+[^2]: Other key-only node attributes can be used as well. Find them in the client source code with `grep -E '^\s+NodeAttr\w+' tailcfg/tailcfg.go` or by using [GitHub code search (requires
+    login)](https://github.com/search?q=repo%3Atailscale%2Ftailscale%20language%3Ago%20path%3Atailcfg%2Ftailcfg.go%20symbol%3A%2FNodeAttr%5Cw%2B%2F&type=code).

docs/ref/registration.md

@@ -11,8 +11,8 @@ Tailscale's identity model distinguishes between personal and tagged nodes:
   workstations or mobile phones. End-user devices are managed by a single user.
 - A tagged node (or service-based node or non-human node) provides services to the network. Common examples include web-
   and database servers. Those nodes are typically managed by a team of users. Some additional restrictions apply for
-  tagged nodes, e.g. a tagged node is not allowed to [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh) into a
-  personal node.
+  tagged nodes, e.g. a tagged node is not allowed to [Tailscale SSH](https://tailscale.com/docs/features/tailscale-ssh)
+  into a personal node.
 
 Headscale implements Tailscale's identity model and distinguishes between personal and tagged nodes where a personal
 node is owned by a Headscale user and a tagged node is owned by a tag. Tagged devices are grouped under the special user
@@ -61,8 +61,8 @@ headscale users create <USER>
 === "Tagged devices"
 
     Your Headscale user needs to be authorized to register tagged devices. This authorization is specified in the
-    [`tagOwners`](https://tailscale.com/kb/1337/policy-syntax#tag-owners) section of the [ACL](acls.md). A simple
-    example looks like this:
+    [`tagOwners`](https://tailscale.com/docs/reference/syntax/policy-file#tag-owners) section of the
+    [policy](policy.md). A simple example looks like this:
 
     ```json title="The user alice can register nodes tagged with tag:server"
     {

docs/ref/routes.md

@@ -1,7 +1,8 @@
 # Routes
 
-Headscale supports route advertising and can be used to manage [subnet routers](https://tailscale.com/kb/1019/subnets)
-and [exit nodes](https://tailscale.com/kb/1103/exit-nodes) for a tailnet.
+Headscale supports route advertising and can be used to manage [subnet
+routers](https://tailscale.com/docs/features/subnet-routers) and [exit
+nodes](https://tailscale.com/docs/features/exit-nodes) for a tailnet.
 
 - [Subnet routers](#subnet-router) may be used to connect an existing network such as a virtual
   private cloud or an on-premise network with your tailnet. Use a subnet router to access devices where Tailscale can't
@@ -72,32 +73,32 @@ $ sudo tailscale set --accept-routes
 ```
 
 Please refer to the official [Tailscale
-documentation](https://tailscale.com/kb/1019/subnets#use-your-subnet-routes-from-other-devices) for how to use a subnet
-router on different operating systems.
+documentation](https://tailscale.com/docs/features/subnet-routers#use-your-subnet-routes-from-other-devices) for how to
+use a subnet router on different operating systems.
 
-### Restrict the use of a subnet router with ACL
+### Restrict the use of a subnet router with a policy
 
-The routes announced by subnet routers are available to the nodes in a tailnet. By default, without an ACL enabled, all
-nodes can accept and use such routes. Configure an ACL to explicitly manage who can use routes.
+The routes announced by subnet routers are available to the nodes in a tailnet. By default, without a policy enabled,
+all nodes can accept and use such routes. Configure a policy to explicitly manage who can use routes.
 
-The ACL snippet below defines three hosts, a subnet router `router`, a regular node `node` and `service.example.net` as
-internal service that can be reached via a route on the subnet router `router`. It allows the node `node` to access
+The policy snippet below defines three hosts, a subnet router `router`, a regular node `node` and `service.example.net`
+as internal service that can be reached via a route on the subnet router `router`. It allows the node `node` to access
 `service.example.net` on port 80 and 443 which is reachable via the subnet router. Access to the subnet router itself is
 denied.
 
 ```json title="Access the routes of a subnet router without the subnet router itself"
 {
   "hosts": {
-    // the router is not referenced but announces 192.168.0.0/24"
+    // the router is not referenced but announces 192.168.0.0/24
     "router": "100.64.0.1/32",
     "node": "100.64.0.2/32",
     "service.example.net": "192.168.0.1/32"
   },
-  "acls": [
+  "grants": [
     {
-      "action": "accept",
       "src": ["node"],
-      "dst": ["service.example.net:80,443"]
+      "dst": ["service.example.net"],
+      "ip": ["80,443"]
     }
   ]
 }
@@ -106,10 +107,10 @@ denied.
 ### Automatically approve routes of a subnet router
 
 The initial setup of a subnet router usually requires manual approval of their announced routes on the control server
-before they can be used by a node in a tailnet. Headscale supports the `autoApprovers` section of an ACL to automate the
-approval of routes served with a subnet router.
+before they can be used by a node in a tailnet. Headscale supports the `autoApprovers` section in a policy to automate
+the approval of routes served with a subnet router.
 
-The ACL snippet below defines the tag `tag:router` owned by the user `alice`. This tag is used for `routes` in the
+The policy snippet below defines the tag `tag:router` owned by the user `alice`. This tag is used for `routes` in the
 `autoApprovers` section. The IPv4 route `192.168.0.0/24` is automatically approved once announced by a subnet router
 that advertises the tag `tag:router`.
 
@@ -123,7 +124,7 @@ that advertises the tag `tag:router`.
       "192.168.0.0/24": ["tag:router"]
     }
   },
-  "acls": [
+  "grants": [
     // more rules
   ]
 }
@@ -135,8 +136,9 @@ Advertise the route `192.168.0.0/24` from a subnet router that also advertises t
 $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:router --advertise-routes 192.168.0.0/24
 ```
 
-Please see the [official Tailscale documentation](https://tailscale.com/kb/1337/acl-syntax#autoapprovers) for more
-information on auto approvers.
+Please see the [official Tailscale
+documentation](https://tailscale.com/docs/reference/syntax/policy-file#auto-approvers) for more information on auto
+approvers.
 
 ## Exit node
 
@@ -199,22 +201,22 @@ The exit node can now be used on a node with:
 $ sudo tailscale set --exit-node myexit
 ```
 
-Please refer to the official [Tailscale documentation](https://tailscale.com/kb/1103/exit-nodes#use-the-exit-node) for
-how to use an exit node on different operating systems.
+Please refer to the official [Tailscale documentation](https://tailscale.com/docs/features/exit-nodes#use-the-exit-node)
+for how to use an exit node on different operating systems.
 
-### Restrict the use of an exit node with ACL
+### Restrict the use of an exit node with a policy
 
-An exit node is offered to all nodes in a tailnet. By default, without an ACL enabled, all nodes in a tailnet can select
-and use an exit node. Configure `autogroup:internet` in an ACL rule to restrict who can use _any_ of the available exit
-nodes.
+An exit node is offered to all nodes in a tailnet. By default, without a policy enabled, all nodes in a tailnet can
+select and use an exit node. Configure `autogroup:internet` in a policy rule to restrict who can use _any_ of the
+available exit nodes.
 
 ```json title="Example use of autogroup:internet"
 {
-  "acls": [
+  "grants": [
     {
-      "action": "accept",
       "src": ["..."],
-      "dst": ["autogroup:internet:*"]
+      "dst": ["autogroup:internet"],
+      "ip": ["*"]
     }
   ]
 }
@@ -222,45 +224,41 @@ nodes.
 
 ### Restrict access to exit nodes per user or group
 
-A user can use _any_ of the available exit nodes with `autogroup:internet`. Alternatively, the ACL snippet below assigns
-each user a specific exit node while hiding all other exit nodes. The user `alice` can only use exit node `exit1` while
-user `bob` can only use exit node `exit2`.
+A user can use _any_ of the available exit nodes with `autogroup:internet`. Alternatively, the policy snippet below
+assigns each user a specific exit node while hiding all other exit nodes. The user `alice` can only use an exit node
+tagged with `tag:exit1` while user `bob` can only use an exit node tagged with `tag:exit2`.
 
 ```json title="Assign each user a dedicated exit node"
 {
-  "hosts": {
-    "exit1": "100.64.0.1/32",
-    "exit2": "100.64.0.2/32"
+  "tagOwners": {
+    "tag:exit1": ["alice@"],
+    "tag:exit2": ["bob@"]
   },
-  "acls": [
+  "grants": [
     {
-      "action": "accept",
       "src": ["alice@"],
-      "dst": ["exit1:*"]
+      "dst": ["autogroup:internet"],
+      "via": ["tag:exit1"],
+      "ip": ["*"]
     },
     {
-      "action": "accept",
       "src": ["bob@"],
-      "dst": ["exit2:*"]
+      "dst": ["autogroup:internet"],
+      "via": ["tag:exit2"],
+      "ip": ["*"]
     }
   ]
 }
 ```
 
-!!! warning
-
-    - The above implementation is Headscale specific and will likely be removed once [support for
-      `via`](https://github.com/juanfont/headscale/issues/2409) is available.
-    - Beware that a user can also connect to any port of the exit node itself.
-
 ### Automatically approve an exit node with auto approvers
 
 The initial setup of an exit node usually requires manual approval on the control server before it can be used by a node
-in a tailnet. Headscale supports the `autoApprovers` section of an ACL to automate the approval of a new exit node as
+in a tailnet. Headscale supports the `autoApprovers` section in a policy to automate the approval of a new exit node as
 soon as it joins the tailnet.
 
-The ACL snippet below defines the tag `tag:exit` owned by the user `alice`. This tag is used for `exitNode` in the
-`autoApprovers` section. A new exit node that advertises the tag `tag:exit` is automatically approved:
+The policy snippet below defines the tag `tag:exit` owned by the user `alice`. This tag is used for the `exitNode` entry
+in the `autoApprovers` section. A new exit node that advertises the tag `tag:exit` is automatically approved:
 
 ```json title="Exit nodes tagged with tag:exit are automatically approved"
 {
@@ -270,7 +268,7 @@ The ACL snippet below defines the tag `tag:exit` owned by the user `alice`. This
   "autoApprovers": {
     "exitNode": ["tag:exit"]
   },
-  "acls": [
+  "grants": [
     // more rules
   ]
 }
@@ -282,26 +280,23 @@ Advertise a node as exit node and also advertise the tag `tag:exit` when joining
 $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:exit --advertise-exit-node
 ```
 
-Please see the [official Tailscale documentation](https://tailscale.com/kb/1337/acl-syntax#autoapprovers) for more
-information on auto approvers.
+Please see the [official Tailscale documentation](https://tailscale.com/docs/reference/syntax/policy-file#autoapprovers)
+for more information on auto approvers.
 
 ## High availability
 
-Headscale has limited support for high availability routing. Multiple subnet routers with overlapping routes or multiple
-exit nodes can be used to provide high availability for users. If one router node goes offline, another one can serve
-the same routes to clients. Please see the official [Tailscale documentation on high
-availability](https://tailscale.com/kb/1115/high-availability#subnet-router-high-availability) for details.
+Headscale supports high availability routing. Multiple subnet routers with overlapping routes or multiple exit nodes can
+be used to provide high availability for users. If one router node goes offline, another one can serve the same routes
+to clients. Please see the official [Tailscale documentation on high
+availability](https://tailscale.com/docs/how-to/set-up-high-availability#subnet-router-high-availability) for details.
 
-!!! bug
-
-    In certain situations it might take up to 16 minutes for Headscale to detect a node as offline. A failover node
-    might not be selected fast enough, if such a node is used as subnet router or exit node causing service
-    interruptions for clients. See [issue 2129](https://github.com/juanfont/headscale/issues/2129) for more information.
+This feature is enabled by default when at least two nodes advertise the same prefix. See the configuration options
+`node.routes.ha` in the [configuration file](configuration.md) for details.
 
 ## Troubleshooting
 
 ### Enable IP forwarding
 
 A subnet router or exit node is routing traffic on behalf of other nodes and thus requires IP forwarding. Check the
-official [Tailscale documentation](https://tailscale.com/kb/1019/subnets/?tab=linux#enable-ip-forwarding) for how to
+official [Tailscale documentation](https://tailscale.com/docs/features/subnet-routers#enable-ip-forwarding) for how to
 enable IP forwarding.

docs/ref/tags.md

@@ -1,7 +1,7 @@
 # Tags
 
-Headscale supports Tailscale tags. Please read [Tailscale's tag documentation](https://tailscale.com/kb/1068/tags) to
-learn how tags work and how to use them.
+Headscale supports Tailscale tags. Please read [Tailscale's tag documentation](https://tailscale.com/docs/features/tags)
+to learn how tags work and how to use them.
 
 Tags can be applied during [node registration](registration.md):
 

docs/setup/install/community.md

@@ -1,7 +1,7 @@
 # Community packages
 
 Several Linux distributions and community members provide packages for headscale. Those packages may be used instead of
-the [official releases](./official.md) provided by the headscale maintainers. Such packages offer improved integration
+the [official releases](official.md) provided by the headscale maintainers. Such packages offer improved integration
 for their targeted operating system and usually:
 
 - setup a dedicated local user account to run headscale
@@ -10,8 +10,8 @@ for their targeted operating system and usually:
 
 !!! warning "Community packages might be outdated"
 
-    The packages mentioned on this page might be outdated or unmaintained. Use the [official releases](./official.md) to
-    get the current stable version or to test pre-releases.
+    The packages mentioned on this page might be outdated or unmaintained. Use the [official releases](official.md) to
+    get the current stable version or to [test pre-releases](main.md).
 
     [![Packaging status](https://repology.org/badge/vertical-allrepos/headscale.svg)](https://repology.org/project/headscale/versions)
 
@@ -23,9 +23,6 @@ Arch Linux offers a package for headscale, install via:
 pacman -S headscale
 ```
 
-The [AUR package `headscale-git`](https://aur.archlinux.org/packages/headscale-git) can be used to build the current
-development version.
-
 ## Fedora, RHEL, CentOS
 
 A third-party repository for various RPM based distributions is available at:

docs/setup/install/container.md

@@ -7,9 +7,8 @@
 
     **It might be outdated and it might miss necessary steps**.
 
-This documentation has the goal of showing a user how-to set up and run headscale in a container. A container runtime
-such as [Docker](https://www.docker.com) or [Podman](https://podman.io) is required. The container image can be found on
-[Docker Hub](https://hub.docker.com/r/headscale/headscale) and [GitHub Container
+A container runtime such as [Docker](https://www.docker.com) or [Podman](https://podman.io) is required. The container
+image can be found on [Docker Hub](https://hub.docker.com/r/headscale/headscale) and [GitHub Container
 Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The container image URLs are:
 
 - [Docker Hub](https://hub.docker.com/r/headscale/headscale): `docker.io/headscale/headscale:<VERSION>`
@@ -18,7 +17,7 @@ Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The c
 
 ## Configure and run headscale
 
-1. Create a directory on the container host to store headscale's [configuration](../../ref/configuration.md) and the [SQLite](https://www.sqlite.org/) database:
+1. Create a directory on the container host to store headscale's [configuration](../../ref/configuration.md) and the SQLite database:
 
     ```shell
     mkdir -p ./headscale/{config,lib}
@@ -98,7 +97,7 @@ Continue on the [getting started page](../../usage/getting-started.md) to regist
 
 ## Debugging headscale running in Docker
 
-The Headscale container image is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug headscale running in the Docker container, you can use the `-debug` variant, for example `docker.io/headscale/headscale:x.x.x-debug`.
+The Headscale container image is based on a distroless image that does not contain a shell or any other debug tools. If you need to debug headscale running in the Docker container, you can use the `-debug` variant, for example `docker.io/headscale/headscale:x.x.x-debug`.
 
 ### Running the debug Docker container
 

docs/setup/install/main.md

@@ -39,7 +39,7 @@ docker run \
   serve
 ```
 
-See [Running headscale in a container](./container.md) for full container setup instructions.
+See [Running headscale in a container](container.md) for full container setup instructions.
 
 ## Binaries
 
@@ -54,5 +54,5 @@ via [nightly.link](https://nightly.link/juanfont/headscale/workflows/container-m
 | macOS | arm64 | [headscale-darwin-arm64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-darwin-arm64.zip) |
 
 After downloading and extracting the archive, make the binary executable and follow the
-[standalone binary installation](./official.md#using-standalone-binaries-advanced)
+[standalone binary installation](official.md#using-standalone-binaries-advanced)
 instructions for setting up the service.

docs/setup/install/official.md

@@ -24,16 +24,17 @@ distributions are Ubuntu 22.04 or newer, Debian 12 or newer.
     sudo apt install ./headscale.deb
     ```
 
-1. [Configure headscale by editing the configuration file](../../ref/configuration.md):
+1. [Configure headscale by editing the configuration file](../../ref/configuration.md). An up-to date example
+   configuration file is also available in `/usr/share/doc/headscale/examples/config-example.yaml`:
 
     ```shell
     sudo nano /etc/headscale/config.yaml
     ```
 
-1. Enable and start the headscale service:
+1. Restart headscale to pick up configuration changes:
 
     ```shell
-    sudo systemctl enable --now headscale
+    sudo systemctl restart headscale
     ```
 
 1. Verify that headscale is running as intended:
@@ -50,7 +51,7 @@ Continue on the [getting started page](../../usage/getting-started.md) to regist
 
     This installation method is considered advanced as one needs to take care of the local user and the systemd
     service themselves. If possible, use the [DEB packages](#using-packages-for-debianubuntu-recommended) or a
-    [community package](./community.md) instead.
+    [community package](community.md) instead.
 
 This section describes the installation of headscale according to the [Requirements and
 assumptions](../requirements.md#assumptions). Headscale is run by a dedicated local user and the service itself is

docs/setup/requirements.md

@@ -17,7 +17,7 @@ The ports in use vary with the intended scenario and enabled features. Some of t
 - tcp/80
     - Expose publicly: yes
     - HTTP, used by Let's Encrypt to verify ownership via the HTTP-01 challenge.
-    - Only required if the built-in Let's Enrypt client with the HTTP-01 challenge is used. See [TLS](../ref/tls.md) for
+    - Only required if the built-in Let's Encrypt client with the HTTP-01 challenge is used. See [TLS](../ref/tls.md) for
       details.
 - tcp/443
     - Expose publicly: yes
@@ -40,7 +40,7 @@ The headscale documentation and the provided examples are written with a few ass
 - Headscale is running as system service via a dedicated local user `headscale`.
 - The [configuration](../ref/configuration.md) is loaded from `/etc/headscale/config.yaml`.
 - SQLite is used as database.
-- The data directory for headscale (used for private keys, ACLs, SQLite database, …) is located in `/var/lib/headscale`.
+- The data directory for headscale (used for private keys, policy, SQLite database, …) is located in `/var/lib/headscale`.
 - URLs and values that need to be replaced by the user are either denoted as `<VALUE_TO_CHANGE>` or use placeholder
   values such as `headscale.example.com`.
 

docs/usage/connect/apple.md

@@ -25,7 +25,8 @@ Install the official Tailscale iOS client from the [App Store](https://apps.appl
 
 ### Installation
 
-Choose one of the available [Tailscale clients for macOS](https://tailscale.com/kb/1065/macos-variants) and install it.
+Choose one of the available [Tailscale clients for macOS](https://tailscale.com/docs/concepts/macos-variants) and
+install it.
 
 ### Configuring the headscale URL
 

docs/usage/connect/windows.md

@@ -33,7 +33,8 @@ all the time, please enable "Unattended mode":
 - Enable `Run unattended`
 - Confirm the "Unattended mode" message
 
-See also [Keep Tailscale running when I'm not logged in to my computer](https://tailscale.com/kb/1088/run-unattended)
+See also [Keep Tailscale running when I'm not logged in to my
+computer](https://tailscale.com/docs/how-to/run-unattended).
 
 ### Failing node registration
 

flake.lock

@@ -20,16 +20,16 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1775701739,
-        "narHash": "sha256-2FWWY1rr/+pGUJK1npcVcsWNEblzmKs6VxD3VEvwJSs=",
+        "lastModified": 1781153106,
+        "narHash": "sha256-yzsroLCcuRG4KdGMxWt0eXKOrRSgQT8/xjYngeq9ujU=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "0f7663154ff2fec150f9dbf5f81ec2785dc1e0db",
+        "rev": "9ee75f111a06d7ab2b2f729698a8eff53d54e070",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixpkgs-unstable",
+        "ref": "staging-next-26.05",
         "repo": "nixpkgs",
         "type": "github"
       }

flake.nix

@@ -2,7 +2,12 @@
   description = "headscale - Open Source Tailscale Control server";
 
   inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+    # Pinned to staging-next-26.05 for Go 1.26.4 (security fix GO-2026-5037/5039):
+    # nixpkgs-unstable still ships 1.26.3 — the bump is merged to nixpkgs staging
+    # but the large-rebuild staging->unstable pipeline lags. The 26.05 line is
+    # otherwise current (dev tools match unstable). Switch back to nixpkgs-unstable
+    # once it ships go_1_26 >= 1.26.4.
+    nixpkgs.url = "github:NixOS/nixpkgs/staging-next-26.05";
     flake-utils.url = "github:numtide/flake-utils";
   };
 
@@ -26,8 +31,9 @@
       overlays.default = _: prev:
         let
           pkgs = nixpkgs.legacyPackages.${prev.stdenv.hostPlatform.system};
+          # Go 1.26 builder; resolves to Go 1.26.4 from the pinned nixpkgs.
           buildGo = pkgs.buildGo126Module;
-          vendorHash = "sha256-x0xXxa7sjyDwWLq8fO0Z/pbPefctzctK3TAdBea7FtY=";
+          vendorHash = (builtins.fromJSON (builtins.readFile ./flakehashes.json)).vendor.sri;
         in
         {
           headscale = buildGo {
@@ -38,8 +44,8 @@
             # Only run unit tests when testing a build
             checkFlags = [ "-short" ];
 
-            # When updating go.mod or go.sum, a new sha will need to be calculated,
-            # update this if you have a mismatch after doing a change to those files.
+            # vendorHash is read from flakehashes.json; refresh via:
+            #   go run ./cmd/vendorhash update
             inherit vendorHash;
 
             subPackages = [ "cmd/headscale" ];
@@ -62,16 +68,16 @@
 
           protoc-gen-grpc-gateway = buildGo rec {
             pname = "grpc-gateway";
-            version = "2.28.0";
+            version = "2.29.0";
 
             src = pkgs.fetchFromGitHub {
               owner = "grpc-ecosystem";
               repo = "grpc-gateway";
               rev = "v${version}";
-              sha256 = "sha256-93omvHb+b+S0w4D+FGEEwYYDjgumJFDAruc1P4elfvA=";
+              sha256 = "sha256-d9OIIGttyMBSNgpS6mbR5JEIm13qGu2gFHJazJAexdw=";
             };
 
-            vendorHash = "sha256-jVP5zfFPfHeAEApKNJzZwuZLA+DjKgkL7m2DFG72UNs=";
+            vendorHash = "sha256-p51yD+v8+rPs+ztlX7r0VQ4XlwUkxu+PxgknKEvH00k=";
 
             nativeBuildInputs = [ pkgs.installShellFiles ];
 
@@ -94,19 +100,20 @@
             subPackages = [ "." ];
           };
 
-          # Build golangci-lint with Go 1.26 (upstream uses hardcoded Go version)
+          # Build golangci-lint with stock Go 1.26 (upstream uses hardcoded Go
+          # version); it does not build against the pinned 1.26.4.
           golangci-lint = buildGo rec {
             pname = "golangci-lint";
-            version = "2.11.4";
+            version = "2.12.2";
 
             src = pkgs.fetchFromGitHub {
               owner = "golangci";
               repo = "golangci-lint";
               rev = "v${version}";
-              hash = "sha256-B19aLvfNRY9TOYw/71f2vpNUuSIz8OI4dL0ijGezsas=";
+              hash = "sha256-qR7fp1x2S+EwEAcplRHTvA3jWwLr/XSiYKSZtAwkrNU=";
             };
 
-            vendorHash = "sha256-xuoj4+U4tB5gpABKq4Dbp2cxnljxdYoBbO8A7DqPM5E=";
+            vendorHash = "sha256-AG5wtLwWLz55bdp1oi3cW+9O3yj1W1P7MV9zxym7Pb4=";
 
             subPackages = [ "cmd/golangci-lint" ];
 
@@ -198,7 +205,7 @@
             clang-tools # clang-format
             protobuf-language-server
           ]
-          ++ lib.optional pkgs.stdenv.isLinux [ traceroute ];
+          ++ lib.optionals pkgs.stdenv.isLinux [ traceroute ];
 
         # Add entry to build a docker image with headscale
         # caveat: only works on Linux
@@ -223,19 +230,13 @@
                 "nix-vendor-sri"
                 ''
                   set -eu
-
-                  OUT=$(mktemp -d -t nar-hash-XXXXXX)
-                  rm -rf "$OUT"
-
-                  go mod vendor -o "$OUT"
-                  go run tailscale.com/cmd/nardump --sri "$OUT"
-                  rm -rf "$OUT"
+                  exec go run ./cmd/vendorhash update "$@"
                 '')
 
               (pkgs.writeShellScriptBin
                 "go-mod-update-all"
                 ''
-                  cat go.mod | ${pkgs.silver-searcher}/bin/ag "\t" | ${pkgs.silver-searcher}/bin/ag -v indirect | ${pkgs.gawk}/bin/awk '{print $1}' | ${pkgs.findutils}/bin/xargs go get -u
+                  cat go.mod | ${pkgs.ripgrep}/bin/rg "\t" | ${pkgs.ripgrep}/bin/rg -v indirect | ${pkgs.gawk}/bin/awk '{print $1}' | ${pkgs.findutils}/bin/xargs go get -u
                   go mod tidy
                 '')
             ];

flakehashes.json

@@ -0,0 +1,6 @@
+{
+  "vendor": {
+    "goModSum": "sha256-csVm5v6HZ49PBp/FCX+yK1sjV8/nuUQz3GKN21Ne1mg=",
+    "sri": "sha256-fzKyXNMw/2yAEhaTZu0n1NXatPO2IP0HFA2ey1vZIYM="
+  }
+}

gen/go/headscale/v1/headscale.pb.go

@@ -109,7 +109,7 @@ const file_headscale_v1_headscale_proto_rawDesc = "" +
 	"\x1cheadscale/v1/headscale.proto\x12\fheadscale.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x17headscale/v1/user.proto\x1a\x1dheadscale/v1/preauthkey.proto\x1a\x17headscale/v1/node.proto\x1a\x19headscale/v1/apikey.proto\x1a\x17headscale/v1/auth.proto\x1a\x19headscale/v1/policy.proto\"\x0f\n" +
 	"\rHealthRequest\"E\n" +
 	"\x0eHealthResponse\x123\n" +
-	"\x15database_connectivity\x18\x01 \x01(\bR\x14databaseConnectivity2\xeb\x19\n" +
+	"\x15database_connectivity\x18\x01 \x01(\bR\x14databaseConnectivity2\xe0\x1a\n" +
 	"\x10HeadscaleService\x12h\n" +
 	"\n" +
 	"CreateUser\x12\x1f.headscale.v1.CreateUserRequest\x1a .headscale.v1.CreateUserResponse\"\x17\x82\xd3\xe4\x93\x02\x11:\x01*\"\f/api/v1/user\x12\x80\x01\n" +
@@ -144,7 +144,8 @@ const file_headscale_v1_headscale_proto_rawDesc = "" +
 	"\vListApiKeys\x12 .headscale.v1.ListApiKeysRequest\x1a!.headscale.v1.ListApiKeysResponse\"\x16\x82\xd3\xe4\x93\x02\x10\x12\x0e/api/v1/apikey\x12v\n" +
 	"\fDeleteApiKey\x12!.headscale.v1.DeleteApiKeyRequest\x1a\".headscale.v1.DeleteApiKeyResponse\"\x1f\x82\xd3\xe4\x93\x02\x19*\x17/api/v1/apikey/{prefix}\x12d\n" +
 	"\tGetPolicy\x12\x1e.headscale.v1.GetPolicyRequest\x1a\x1f.headscale.v1.GetPolicyResponse\"\x16\x82\xd3\xe4\x93\x02\x10\x12\x0e/api/v1/policy\x12g\n" +
-	"\tSetPolicy\x12\x1e.headscale.v1.SetPolicyRequest\x1a\x1f.headscale.v1.SetPolicyResponse\"\x19\x82\xd3\xe4\x93\x02\x13:\x01*\x1a\x0e/api/v1/policy\x12[\n" +
+	"\tSetPolicy\x12\x1e.headscale.v1.SetPolicyRequest\x1a\x1f.headscale.v1.SetPolicyResponse\"\x19\x82\xd3\xe4\x93\x02\x13:\x01*\x1a\x0e/api/v1/policy\x12s\n" +
+	"\vCheckPolicy\x12 .headscale.v1.CheckPolicyRequest\x1a!.headscale.v1.CheckPolicyResponse\"\x1f\x82\xd3\xe4\x93\x02\x19:\x01*\"\x14/api/v1/policy/check\x12[\n" +
 	"\x06Health\x12\x1b.headscale.v1.HealthRequest\x1a\x1c.headscale.v1.HealthResponse\"\x16\x82\xd3\xe4\x93\x02\x10\x12\x0e/api/v1/healthB)Z'github.com/juanfont/headscale/gen/go/v1b\x06proto3"
 
 var (
@@ -190,33 +191,35 @@ var file_headscale_v1_headscale_proto_goTypes = []any{
 	(*DeleteApiKeyRequest)(nil),       // 26: headscale.v1.DeleteApiKeyRequest
 	(*GetPolicyRequest)(nil),          // 27: headscale.v1.GetPolicyRequest
 	(*SetPolicyRequest)(nil),          // 28: headscale.v1.SetPolicyRequest
-	(*CreateUserResponse)(nil),        // 29: headscale.v1.CreateUserResponse
-	(*RenameUserResponse)(nil),        // 30: headscale.v1.RenameUserResponse
-	(*DeleteUserResponse)(nil),        // 31: headscale.v1.DeleteUserResponse
-	(*ListUsersResponse)(nil),         // 32: headscale.v1.ListUsersResponse
-	(*CreatePreAuthKeyResponse)(nil),  // 33: headscale.v1.CreatePreAuthKeyResponse
-	(*ExpirePreAuthKeyResponse)(nil),  // 34: headscale.v1.ExpirePreAuthKeyResponse
-	(*DeletePreAuthKeyResponse)(nil),  // 35: headscale.v1.DeletePreAuthKeyResponse
-	(*ListPreAuthKeysResponse)(nil),   // 36: headscale.v1.ListPreAuthKeysResponse
-	(*DebugCreateNodeResponse)(nil),   // 37: headscale.v1.DebugCreateNodeResponse
-	(*GetNodeResponse)(nil),           // 38: headscale.v1.GetNodeResponse
-	(*SetTagsResponse)(nil),           // 39: headscale.v1.SetTagsResponse
-	(*SetApprovedRoutesResponse)(nil), // 40: headscale.v1.SetApprovedRoutesResponse
-	(*RegisterNodeResponse)(nil),      // 41: headscale.v1.RegisterNodeResponse
-	(*DeleteNodeResponse)(nil),        // 42: headscale.v1.DeleteNodeResponse
-	(*ExpireNodeResponse)(nil),        // 43: headscale.v1.ExpireNodeResponse
-	(*RenameNodeResponse)(nil),        // 44: headscale.v1.RenameNodeResponse
-	(*ListNodesResponse)(nil),         // 45: headscale.v1.ListNodesResponse
-	(*BackfillNodeIPsResponse)(nil),   // 46: headscale.v1.BackfillNodeIPsResponse
-	(*AuthRegisterResponse)(nil),      // 47: headscale.v1.AuthRegisterResponse
-	(*AuthApproveResponse)(nil),       // 48: headscale.v1.AuthApproveResponse
-	(*AuthRejectResponse)(nil),        // 49: headscale.v1.AuthRejectResponse
-	(*CreateApiKeyResponse)(nil),      // 50: headscale.v1.CreateApiKeyResponse
-	(*ExpireApiKeyResponse)(nil),      // 51: headscale.v1.ExpireApiKeyResponse
-	(*ListApiKeysResponse)(nil),       // 52: headscale.v1.ListApiKeysResponse
-	(*DeleteApiKeyResponse)(nil),      // 53: headscale.v1.DeleteApiKeyResponse
-	(*GetPolicyResponse)(nil),         // 54: headscale.v1.GetPolicyResponse
-	(*SetPolicyResponse)(nil),         // 55: headscale.v1.SetPolicyResponse
+	(*CheckPolicyRequest)(nil),        // 29: headscale.v1.CheckPolicyRequest
+	(*CreateUserResponse)(nil),        // 30: headscale.v1.CreateUserResponse
+	(*RenameUserResponse)(nil),        // 31: headscale.v1.RenameUserResponse
+	(*DeleteUserResponse)(nil),        // 32: headscale.v1.DeleteUserResponse
+	(*ListUsersResponse)(nil),         // 33: headscale.v1.ListUsersResponse
+	(*CreatePreAuthKeyResponse)(nil),  // 34: headscale.v1.CreatePreAuthKeyResponse
+	(*ExpirePreAuthKeyResponse)(nil),  // 35: headscale.v1.ExpirePreAuthKeyResponse
+	(*DeletePreAuthKeyResponse)(nil),  // 36: headscale.v1.DeletePreAuthKeyResponse
+	(*ListPreAuthKeysResponse)(nil),   // 37: headscale.v1.ListPreAuthKeysResponse
+	(*DebugCreateNodeResponse)(nil),   // 38: headscale.v1.DebugCreateNodeResponse
+	(*GetNodeResponse)(nil),           // 39: headscale.v1.GetNodeResponse
+	(*SetTagsResponse)(nil),           // 40: headscale.v1.SetTagsResponse
+	(*SetApprovedRoutesResponse)(nil), // 41: headscale.v1.SetApprovedRoutesResponse
+	(*RegisterNodeResponse)(nil),      // 42: headscale.v1.RegisterNodeResponse
+	(*DeleteNodeResponse)(nil),        // 43: headscale.v1.DeleteNodeResponse
+	(*ExpireNodeResponse)(nil),        // 44: headscale.v1.ExpireNodeResponse
+	(*RenameNodeResponse)(nil),        // 45: headscale.v1.RenameNodeResponse
+	(*ListNodesResponse)(nil),         // 46: headscale.v1.ListNodesResponse
+	(*BackfillNodeIPsResponse)(nil),   // 47: headscale.v1.BackfillNodeIPsResponse
+	(*AuthRegisterResponse)(nil),      // 48: headscale.v1.AuthRegisterResponse
+	(*AuthApproveResponse)(nil),       // 49: headscale.v1.AuthApproveResponse
+	(*AuthRejectResponse)(nil),        // 50: headscale.v1.AuthRejectResponse
+	(*CreateApiKeyResponse)(nil),      // 51: headscale.v1.CreateApiKeyResponse
+	(*ExpireApiKeyResponse)(nil),      // 52: headscale.v1.ExpireApiKeyResponse
+	(*ListApiKeysResponse)(nil),       // 53: headscale.v1.ListApiKeysResponse
+	(*DeleteApiKeyResponse)(nil),      // 54: headscale.v1.DeleteApiKeyResponse
+	(*GetPolicyResponse)(nil),         // 55: headscale.v1.GetPolicyResponse
+	(*SetPolicyResponse)(nil),         // 56: headscale.v1.SetPolicyResponse
+	(*CheckPolicyResponse)(nil),       // 57: headscale.v1.CheckPolicyResponse
 }
 var file_headscale_v1_headscale_proto_depIdxs = []int32{
 	2,  // 0: headscale.v1.HeadscaleService.CreateUser:input_type -> headscale.v1.CreateUserRequest
@@ -246,37 +249,39 @@ var file_headscale_v1_headscale_proto_depIdxs = []int32{
 	26, // 24: headscale.v1.HeadscaleService.DeleteApiKey:input_type -> headscale.v1.DeleteApiKeyRequest
 	27, // 25: headscale.v1.HeadscaleService.GetPolicy:input_type -> headscale.v1.GetPolicyRequest
 	28, // 26: headscale.v1.HeadscaleService.SetPolicy:input_type -> headscale.v1.SetPolicyRequest
-	0,  // 27: headscale.v1.HeadscaleService.Health:input_type -> headscale.v1.HealthRequest
-	29, // 28: headscale.v1.HeadscaleService.CreateUser:output_type -> headscale.v1.CreateUserResponse
-	30, // 29: headscale.v1.HeadscaleService.RenameUser:output_type -> headscale.v1.RenameUserResponse
-	31, // 30: headscale.v1.HeadscaleService.DeleteUser:output_type -> headscale.v1.DeleteUserResponse
-	32, // 31: headscale.v1.HeadscaleService.ListUsers:output_type -> headscale.v1.ListUsersResponse
-	33, // 32: headscale.v1.HeadscaleService.CreatePreAuthKey:output_type -> headscale.v1.CreatePreAuthKeyResponse
-	34, // 33: headscale.v1.HeadscaleService.ExpirePreAuthKey:output_type -> headscale.v1.ExpirePreAuthKeyResponse
-	35, // 34: headscale.v1.HeadscaleService.DeletePreAuthKey:output_type -> headscale.v1.DeletePreAuthKeyResponse
-	36, // 35: headscale.v1.HeadscaleService.ListPreAuthKeys:output_type -> headscale.v1.ListPreAuthKeysResponse
-	37, // 36: headscale.v1.HeadscaleService.DebugCreateNode:output_type -> headscale.v1.DebugCreateNodeResponse
-	38, // 37: headscale.v1.HeadscaleService.GetNode:output_type -> headscale.v1.GetNodeResponse
-	39, // 38: headscale.v1.HeadscaleService.SetTags:output_type -> headscale.v1.SetTagsResponse
-	40, // 39: headscale.v1.HeadscaleService.SetApprovedRoutes:output_type -> headscale.v1.SetApprovedRoutesResponse
-	41, // 40: headscale.v1.HeadscaleService.RegisterNode:output_type -> headscale.v1.RegisterNodeResponse
-	42, // 41: headscale.v1.HeadscaleService.DeleteNode:output_type -> headscale.v1.DeleteNodeResponse
-	43, // 42: headscale.v1.HeadscaleService.ExpireNode:output_type -> headscale.v1.ExpireNodeResponse
-	44, // 43: headscale.v1.HeadscaleService.RenameNode:output_type -> headscale.v1.RenameNodeResponse
-	45, // 44: headscale.v1.HeadscaleService.ListNodes:output_type -> headscale.v1.ListNodesResponse
-	46, // 45: headscale.v1.HeadscaleService.BackfillNodeIPs:output_type -> headscale.v1.BackfillNodeIPsResponse
-	47, // 46: headscale.v1.HeadscaleService.AuthRegister:output_type -> headscale.v1.AuthRegisterResponse
-	48, // 47: headscale.v1.HeadscaleService.AuthApprove:output_type -> headscale.v1.AuthApproveResponse
-	49, // 48: headscale.v1.HeadscaleService.AuthReject:output_type -> headscale.v1.AuthRejectResponse
-	50, // 49: headscale.v1.HeadscaleService.CreateApiKey:output_type -> headscale.v1.CreateApiKeyResponse
-	51, // 50: headscale.v1.HeadscaleService.ExpireApiKey:output_type -> headscale.v1.ExpireApiKeyResponse
-	52, // 51: headscale.v1.HeadscaleService.ListApiKeys:output_type -> headscale.v1.ListApiKeysResponse
-	53, // 52: headscale.v1.HeadscaleService.DeleteApiKey:output_type -> headscale.v1.DeleteApiKeyResponse
-	54, // 53: headscale.v1.HeadscaleService.GetPolicy:output_type -> headscale.v1.GetPolicyResponse
-	55, // 54: headscale.v1.HeadscaleService.SetPolicy:output_type -> headscale.v1.SetPolicyResponse
-	1,  // 55: headscale.v1.HeadscaleService.Health:output_type -> headscale.v1.HealthResponse
-	28, // [28:56] is the sub-list for method output_type
-	0,  // [0:28] is the sub-list for method input_type
+	29, // 27: headscale.v1.HeadscaleService.CheckPolicy:input_type -> headscale.v1.CheckPolicyRequest
+	0,  // 28: headscale.v1.HeadscaleService.Health:input_type -> headscale.v1.HealthRequest
+	30, // 29: headscale.v1.HeadscaleService.CreateUser:output_type -> headscale.v1.CreateUserResponse
+	31, // 30: headscale.v1.HeadscaleService.RenameUser:output_type -> headscale.v1.RenameUserResponse
+	32, // 31: headscale.v1.HeadscaleService.DeleteUser:output_type -> headscale.v1.DeleteUserResponse
+	33, // 32: headscale.v1.HeadscaleService.ListUsers:output_type -> headscale.v1.ListUsersResponse
+	34, // 33: headscale.v1.HeadscaleService.CreatePreAuthKey:output_type -> headscale.v1.CreatePreAuthKeyResponse
+	35, // 34: headscale.v1.HeadscaleService.ExpirePreAuthKey:output_type -> headscale.v1.ExpirePreAuthKeyResponse
+	36, // 35: headscale.v1.HeadscaleService.DeletePreAuthKey:output_type -> headscale.v1.DeletePreAuthKeyResponse
+	37, // 36: headscale.v1.HeadscaleService.ListPreAuthKeys:output_type -> headscale.v1.ListPreAuthKeysResponse
+	38, // 37: headscale.v1.HeadscaleService.DebugCreateNode:output_type -> headscale.v1.DebugCreateNodeResponse
+	39, // 38: headscale.v1.HeadscaleService.GetNode:output_type -> headscale.v1.GetNodeResponse
+	40, // 39: headscale.v1.HeadscaleService.SetTags:output_type -> headscale.v1.SetTagsResponse
+	41, // 40: headscale.v1.HeadscaleService.SetApprovedRoutes:output_type -> headscale.v1.SetApprovedRoutesResponse
+	42, // 41: headscale.v1.HeadscaleService.RegisterNode:output_type -> headscale.v1.RegisterNodeResponse
+	43, // 42: headscale.v1.HeadscaleService.DeleteNode:output_type -> headscale.v1.DeleteNodeResponse
+	44, // 43: headscale.v1.HeadscaleService.ExpireNode:output_type -> headscale.v1.ExpireNodeResponse
+	45, // 44: headscale.v1.HeadscaleService.RenameNode:output_type -> headscale.v1.RenameNodeResponse
+	46, // 45: headscale.v1.HeadscaleService.ListNodes:output_type -> headscale.v1.ListNodesResponse
+	47, // 46: headscale.v1.HeadscaleService.BackfillNodeIPs:output_type -> headscale.v1.BackfillNodeIPsResponse
+	48, // 47: headscale.v1.HeadscaleService.AuthRegister:output_type -> headscale.v1.AuthRegisterResponse
+	49, // 48: headscale.v1.HeadscaleService.AuthApprove:output_type -> headscale.v1.AuthApproveResponse
+	50, // 49: headscale.v1.HeadscaleService.AuthReject:output_type -> headscale.v1.AuthRejectResponse
+	51, // 50: headscale.v1.HeadscaleService.CreateApiKey:output_type -> headscale.v1.CreateApiKeyResponse
+	52, // 51: headscale.v1.HeadscaleService.ExpireApiKey:output_type -> headscale.v1.ExpireApiKeyResponse
+	53, // 52: headscale.v1.HeadscaleService.ListApiKeys:output_type -> headscale.v1.ListApiKeysResponse
+	54, // 53: headscale.v1.HeadscaleService.DeleteApiKey:output_type -> headscale.v1.DeleteApiKeyResponse
+	55, // 54: headscale.v1.HeadscaleService.GetPolicy:output_type -> headscale.v1.GetPolicyResponse
+	56, // 55: headscale.v1.HeadscaleService.SetPolicy:output_type -> headscale.v1.SetPolicyResponse
+	57, // 56: headscale.v1.HeadscaleService.CheckPolicy:output_type -> headscale.v1.CheckPolicyResponse
+	1,  // 57: headscale.v1.HeadscaleService.Health:output_type -> headscale.v1.HealthResponse
+	29, // [29:58] is the sub-list for method output_type
+	0,  // [0:29] is the sub-list for method input_type
 	0,  // [0:0] is the sub-list for extension type_name
 	0,  // [0:0] is the sub-list for extension extendee
 	0,  // [0:0] is the sub-list for field type_name

gen/go/headscale/v1/headscale.pb.gw.go

@@ -966,6 +966,33 @@ func local_request_HeadscaleService_SetPolicy_0(ctx context.Context, marshaler r
 	return msg, metadata, err
 }
 
+func request_HeadscaleService_CheckPolicy_0(ctx context.Context, marshaler runtime.Marshaler, client HeadscaleServiceClient, req *http.Request, pathParams map[string]string) (proto.Message, runtime.ServerMetadata, error) {
+	var (
+		protoReq CheckPolicyRequest
+		metadata runtime.ServerMetadata
+	)
+	if err := marshaler.NewDecoder(req.Body).Decode(&protoReq); err != nil && !errors.Is(err, io.EOF) {
+		return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", err)
+	}
+	if req.Body != nil {
+		_, _ = io.Copy(io.Discard, req.Body)
+	}
+	msg, err := client.CheckPolicy(ctx, &protoReq, grpc.Header(&metadata.HeaderMD), grpc.Trailer(&metadata.TrailerMD))
+	return msg, metadata, err
+}
+
+func local_request_HeadscaleService_CheckPolicy_0(ctx context.Context, marshaler runtime.Marshaler, server HeadscaleServiceServer, req *http.Request, pathParams map[string]string) (proto.Message, runtime.ServerMetadata, error) {
+	var (
+		protoReq CheckPolicyRequest
+		metadata runtime.ServerMetadata
+	)
+	if err := marshaler.NewDecoder(req.Body).Decode(&protoReq); err != nil && !errors.Is(err, io.EOF) {
+		return nil, metadata, status.Errorf(codes.InvalidArgument, "%v", err)
+	}
+	msg, err := server.CheckPolicy(ctx, &protoReq)
+	return msg, metadata, err
+}
+
 func request_HeadscaleService_Health_0(ctx context.Context, marshaler runtime.Marshaler, client HeadscaleServiceClient, req *http.Request, pathParams map[string]string) (proto.Message, runtime.ServerMetadata, error) {
 	var (
 		protoReq HealthRequest
@@ -1533,6 +1560,26 @@ func RegisterHeadscaleServiceHandlerServer(ctx context.Context, mux *runtime.Ser
 		}
 		forward_HeadscaleService_SetPolicy_0(annotatedContext, mux, outboundMarshaler, w, req, resp, mux.GetForwardResponseOptions()...)
 	})
+	mux.Handle(http.MethodPost, pattern_HeadscaleService_CheckPolicy_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) {
+		ctx, cancel := context.WithCancel(req.Context())
+		defer cancel()
+		var stream runtime.ServerTransportStream
+		ctx = grpc.NewContextWithServerTransportStream(ctx, &stream)
+		inboundMarshaler, outboundMarshaler := runtime.MarshalerForRequest(mux, req)
+		annotatedContext, err := runtime.AnnotateIncomingContext(ctx, mux, req, "/headscale.v1.HeadscaleService/CheckPolicy", runtime.WithHTTPPathPattern("/api/v1/policy/check"))
+		if err != nil {
+			runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err)
+			return
+		}
+		resp, md, err := local_request_HeadscaleService_CheckPolicy_0(annotatedContext, inboundMarshaler, server, req, pathParams)
+		md.HeaderMD, md.TrailerMD = metadata.Join(md.HeaderMD, stream.Header()), metadata.Join(md.TrailerMD, stream.Trailer())
+		annotatedContext = runtime.NewServerMetadataContext(annotatedContext, md)
+		if err != nil {
+			runtime.HTTPError(annotatedContext, mux, outboundMarshaler, w, req, err)
+			return
+		}
+		forward_HeadscaleService_CheckPolicy_0(annotatedContext, mux, outboundMarshaler, w, req, resp, mux.GetForwardResponseOptions()...)
+	})
 	mux.Handle(http.MethodGet, pattern_HeadscaleService_Health_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) {
 		ctx, cancel := context.WithCancel(req.Context())
 		defer cancel()
@@ -2052,6 +2099,23 @@ func RegisterHeadscaleServiceHandlerClient(ctx context.Context, mux *runtime.Ser
 		}
 		forward_HeadscaleService_SetPolicy_0(annotatedContext, mux, outboundMarshaler, w, req, resp, mux.GetForwardResponseOptions()...)
 	})
+	mux.Handle(http.MethodPost, pattern_HeadscaleService_CheckPolicy_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) {
+		ctx, cancel := context.WithCancel(req.Context())
+		defer cancel()
+		inboundMarshaler, outboundMarshaler := runtime.MarshalerForRequest(mux, req)
+		annotatedContext, err := runtime.AnnotateContext(ctx, mux, req, "/headscale.v1.HeadscaleService/CheckPolicy", runtime.WithHTTPPathPattern("/api/v1/policy/check"))
+		if err != nil {
+			runtime.HTTPError(ctx, mux, outboundMarshaler, w, req, err)
+			return
+		}
+		resp, md, err := request_HeadscaleService_CheckPolicy_0(annotatedContext, inboundMarshaler, client, req, pathParams)
+		annotatedContext = runtime.NewServerMetadataContext(annotatedContext, md)
+		if err != nil {
+			runtime.HTTPError(annotatedContext, mux, outboundMarshaler, w, req, err)
+			return
+		}
+		forward_HeadscaleService_CheckPolicy_0(annotatedContext, mux, outboundMarshaler, w, req, resp, mux.GetForwardResponseOptions()...)
+	})
 	mux.Handle(http.MethodGet, pattern_HeadscaleService_Health_0, func(w http.ResponseWriter, req *http.Request, pathParams map[string]string) {
 		ctx, cancel := context.WithCancel(req.Context())
 		defer cancel()
@@ -2100,6 +2164,7 @@ var (
 	pattern_HeadscaleService_DeleteApiKey_0      = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2, 1, 0, 4, 1, 5, 3}, []string{"api", "v1", "apikey", "prefix"}, ""))
 	pattern_HeadscaleService_GetPolicy_0         = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2}, []string{"api", "v1", "policy"}, ""))
 	pattern_HeadscaleService_SetPolicy_0         = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2}, []string{"api", "v1", "policy"}, ""))
+	pattern_HeadscaleService_CheckPolicy_0       = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2, 2, 3}, []string{"api", "v1", "policy", "check"}, ""))
 	pattern_HeadscaleService_Health_0            = runtime.MustPattern(runtime.NewPattern(1, []int{2, 0, 2, 1, 2, 2}, []string{"api", "v1", "health"}, ""))
 )
 
@@ -2131,5 +2196,6 @@ var (
 	forward_HeadscaleService_DeleteApiKey_0      = runtime.ForwardResponseMessage
 	forward_HeadscaleService_GetPolicy_0         = runtime.ForwardResponseMessage
 	forward_HeadscaleService_SetPolicy_0         = runtime.ForwardResponseMessage
+	forward_HeadscaleService_CheckPolicy_0       = runtime.ForwardResponseMessage
 	forward_HeadscaleService_Health_0            = runtime.ForwardResponseMessage
 )

gen/go/headscale/v1/headscale_grpc.pb.go

@@ -1,6 +1,6 @@
 // Code generated by protoc-gen-go-grpc. DO NOT EDIT.
 // versions:
-// - protoc-gen-go-grpc v1.6.1
+// - protoc-gen-go-grpc v1.6.2
 // - protoc             (unknown)
 // source: headscale/v1/headscale.proto
 
@@ -46,6 +46,7 @@ const (
 	HeadscaleService_DeleteApiKey_FullMethodName      = "/headscale.v1.HeadscaleService/DeleteApiKey"
 	HeadscaleService_GetPolicy_FullMethodName         = "/headscale.v1.HeadscaleService/GetPolicy"
 	HeadscaleService_SetPolicy_FullMethodName         = "/headscale.v1.HeadscaleService/SetPolicy"
+	HeadscaleService_CheckPolicy_FullMethodName       = "/headscale.v1.HeadscaleService/CheckPolicy"
 	HeadscaleService_Health_FullMethodName            = "/headscale.v1.HeadscaleService/Health"
 )
 
@@ -86,6 +87,7 @@ type HeadscaleServiceClient interface {
 	// --- Policy start ---
 	GetPolicy(ctx context.Context, in *GetPolicyRequest, opts ...grpc.CallOption) (*GetPolicyResponse, error)
 	SetPolicy(ctx context.Context, in *SetPolicyRequest, opts ...grpc.CallOption) (*SetPolicyResponse, error)
+	CheckPolicy(ctx context.Context, in *CheckPolicyRequest, opts ...grpc.CallOption) (*CheckPolicyResponse, error)
 	// --- Health start ---
 	Health(ctx context.Context, in *HealthRequest, opts ...grpc.CallOption) (*HealthResponse, error)
 }
@@ -368,6 +370,16 @@ func (c *headscaleServiceClient) SetPolicy(ctx context.Context, in *SetPolicyReq
 	return out, nil
 }
 
+func (c *headscaleServiceClient) CheckPolicy(ctx context.Context, in *CheckPolicyRequest, opts ...grpc.CallOption) (*CheckPolicyResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(CheckPolicyResponse)
+	err := c.cc.Invoke(ctx, HeadscaleService_CheckPolicy_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 func (c *headscaleServiceClient) Health(ctx context.Context, in *HealthRequest, opts ...grpc.CallOption) (*HealthResponse, error) {
 	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
 	out := new(HealthResponse)
@@ -415,6 +427,7 @@ type HeadscaleServiceServer interface {
 	// --- Policy start ---
 	GetPolicy(context.Context, *GetPolicyRequest) (*GetPolicyResponse, error)
 	SetPolicy(context.Context, *SetPolicyRequest) (*SetPolicyResponse, error)
+	CheckPolicy(context.Context, *CheckPolicyRequest) (*CheckPolicyResponse, error)
 	// --- Health start ---
 	Health(context.Context, *HealthRequest) (*HealthResponse, error)
 	mustEmbedUnimplementedHeadscaleServiceServer()
@@ -508,6 +521,9 @@ func (UnimplementedHeadscaleServiceServer) GetPolicy(context.Context, *GetPolicy
 func (UnimplementedHeadscaleServiceServer) SetPolicy(context.Context, *SetPolicyRequest) (*SetPolicyResponse, error) {
 	return nil, status.Error(codes.Unimplemented, "method SetPolicy not implemented")
 }
+func (UnimplementedHeadscaleServiceServer) CheckPolicy(context.Context, *CheckPolicyRequest) (*CheckPolicyResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method CheckPolicy not implemented")
+}
 func (UnimplementedHeadscaleServiceServer) Health(context.Context, *HealthRequest) (*HealthResponse, error) {
 	return nil, status.Error(codes.Unimplemented, "method Health not implemented")
 }
@@ -1018,6 +1034,24 @@ func _HeadscaleService_SetPolicy_Handler(srv interface{}, ctx context.Context, d
 	return interceptor(ctx, in, info, handler)
 }
 
+func _HeadscaleService_CheckPolicy_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(CheckPolicyRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(HeadscaleServiceServer).CheckPolicy(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: HeadscaleService_CheckPolicy_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(HeadscaleServiceServer).CheckPolicy(ctx, req.(*CheckPolicyRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 func _HeadscaleService_Health_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
 	in := new(HealthRequest)
 	if err := dec(in); err != nil {
@@ -1151,6 +1185,10 @@ var HeadscaleService_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "SetPolicy",
 			Handler:    _HeadscaleService_SetPolicy_Handler,
 		},
+		{
+			MethodName: "CheckPolicy",
+			Handler:    _HeadscaleService_CheckPolicy_Handler,
+		},
 		{
 			MethodName: "Health",
 			Handler:    _HeadscaleService_Health_Handler,

gen/go/headscale/v1/policy.pb.go

@@ -206,6 +206,86 @@ func (x *GetPolicyResponse) GetUpdatedAt() *timestamppb.Timestamp {
 	return nil
 }
 
+type CheckPolicyRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Policy        string                 `protobuf:"bytes,1,opt,name=policy,proto3" json:"policy,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *CheckPolicyRequest) Reset() {
+	*x = CheckPolicyRequest{}
+	mi := &file_headscale_v1_policy_proto_msgTypes[4]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *CheckPolicyRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*CheckPolicyRequest) ProtoMessage() {}
+
+func (x *CheckPolicyRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_headscale_v1_policy_proto_msgTypes[4]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use CheckPolicyRequest.ProtoReflect.Descriptor instead.
+func (*CheckPolicyRequest) Descriptor() ([]byte, []int) {
+	return file_headscale_v1_policy_proto_rawDescGZIP(), []int{4}
+}
+
+func (x *CheckPolicyRequest) GetPolicy() string {
+	if x != nil {
+		return x.Policy
+	}
+	return ""
+}
+
+type CheckPolicyResponse struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *CheckPolicyResponse) Reset() {
+	*x = CheckPolicyResponse{}
+	mi := &file_headscale_v1_policy_proto_msgTypes[5]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *CheckPolicyResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*CheckPolicyResponse) ProtoMessage() {}
+
+func (x *CheckPolicyResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_headscale_v1_policy_proto_msgTypes[5]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use CheckPolicyResponse.ProtoReflect.Descriptor instead.
+func (*CheckPolicyResponse) Descriptor() ([]byte, []int) {
+	return file_headscale_v1_policy_proto_rawDescGZIP(), []int{5}
+}
+
 var File_headscale_v1_policy_proto protoreflect.FileDescriptor
 
 const file_headscale_v1_policy_proto_rawDesc = "" +
@@ -221,7 +301,10 @@ const file_headscale_v1_policy_proto_rawDesc = "" +
 	"\x11GetPolicyResponse\x12\x16\n" +
 	"\x06policy\x18\x01 \x01(\tR\x06policy\x129\n" +
 	"\n" +
-	"updated_at\x18\x02 \x01(\v2\x1a.google.protobuf.TimestampR\tupdatedAtB)Z'github.com/juanfont/headscale/gen/go/v1b\x06proto3"
+	"updated_at\x18\x02 \x01(\v2\x1a.google.protobuf.TimestampR\tupdatedAt\",\n" +
+	"\x12CheckPolicyRequest\x12\x16\n" +
+	"\x06policy\x18\x01 \x01(\tR\x06policy\"\x15\n" +
+	"\x13CheckPolicyResponseB)Z'github.com/juanfont/headscale/gen/go/v1b\x06proto3"
 
 var (
 	file_headscale_v1_policy_proto_rawDescOnce sync.Once
@@ -235,17 +318,19 @@ func file_headscale_v1_policy_proto_rawDescGZIP() []byte {
 	return file_headscale_v1_policy_proto_rawDescData
 }
 
-var file_headscale_v1_policy_proto_msgTypes = make([]protoimpl.MessageInfo, 4)
+var file_headscale_v1_policy_proto_msgTypes = make([]protoimpl.MessageInfo, 6)
 var file_headscale_v1_policy_proto_goTypes = []any{
 	(*SetPolicyRequest)(nil),      // 0: headscale.v1.SetPolicyRequest
 	(*SetPolicyResponse)(nil),     // 1: headscale.v1.SetPolicyResponse
 	(*GetPolicyRequest)(nil),      // 2: headscale.v1.GetPolicyRequest
 	(*GetPolicyResponse)(nil),     // 3: headscale.v1.GetPolicyResponse
-	(*timestamppb.Timestamp)(nil), // 4: google.protobuf.Timestamp
+	(*CheckPolicyRequest)(nil),    // 4: headscale.v1.CheckPolicyRequest
+	(*CheckPolicyResponse)(nil),   // 5: headscale.v1.CheckPolicyResponse
+	(*timestamppb.Timestamp)(nil), // 6: google.protobuf.Timestamp
 }
 var file_headscale_v1_policy_proto_depIdxs = []int32{
-	4, // 0: headscale.v1.SetPolicyResponse.updated_at:type_name -> google.protobuf.Timestamp
-	4, // 1: headscale.v1.GetPolicyResponse.updated_at:type_name -> google.protobuf.Timestamp
+	6, // 0: headscale.v1.SetPolicyResponse.updated_at:type_name -> google.protobuf.Timestamp
+	6, // 1: headscale.v1.GetPolicyResponse.updated_at:type_name -> google.protobuf.Timestamp
 	2, // [2:2] is the sub-list for method output_type
 	2, // [2:2] is the sub-list for method input_type
 	2, // [2:2] is the sub-list for extension type_name
@@ -264,7 +349,7 @@ func file_headscale_v1_policy_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_headscale_v1_policy_proto_rawDesc), len(file_headscale_v1_policy_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   4,
+			NumMessages:   6,
 			NumExtensions: 0,
 			NumServices:   0,
 		},

gen/openapiv2/headscale/v1/headscale.swagger.json

@@ -660,6 +660,38 @@
         ]
       }
     },
+    "/api/v1/policy/check": {
+      "post": {
+        "operationId": "HeadscaleService_CheckPolicy",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/v1CheckPolicyResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "body",
+            "in": "body",
+            "required": true,
+            "schema": {
+              "$ref": "#/definitions/v1CheckPolicyRequest"
+            }
+          }
+        ],
+        "tags": [
+          "HeadscaleService"
+        ]
+      }
+    },
     "/api/v1/preauthkey": {
       "get": {
         "operationId": "HeadscaleService_ListPreAuthKeys",
@@ -1044,6 +1076,17 @@
         }
       }
     },
+    "v1CheckPolicyRequest": {
+      "type": "object",
+      "properties": {
+        "policy": {
+          "type": "string"
+        }
+      }
+    },
+    "v1CheckPolicyResponse": {
+      "type": "object"
+    },
     "v1CreateApiKeyRequest": {
       "type": "object",
       "properties": {

go.mod

@@ -1,6 +1,6 @@
 module github.com/juanfont/headscale
 
-go 1.26.1
+go 1.26.4
 
 require (
 	github.com/arl/statsviz v0.8.0
@@ -8,20 +8,19 @@ require (
 	github.com/chasefleming/elem-go v0.31.0
 	github.com/coder/websocket v1.8.14
 	github.com/coreos/go-oidc/v3 v3.18.0
-	github.com/creachadair/command v0.2.2
-	github.com/creachadair/flax v0.0.5
+	github.com/creachadair/command v0.2.6
+	github.com/creachadair/flax v0.0.6
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc
 	github.com/docker/docker v28.5.2+incompatible
-	github.com/fsnotify/fsnotify v1.9.0
+	github.com/fsnotify/fsnotify v1.10.1
 	github.com/glebarez/sqlite v1.11.0
-	github.com/go-chi/chi/v5 v5.2.5
+	github.com/go-chi/chi/v5 v5.3.0
 	github.com/go-chi/metrics v0.1.1
-	github.com/go-gormigrate/gormigrate/v2 v2.1.5
-	github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433
+	github.com/go-gormigrate/gormigrate/v2 v2.1.6
+	github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6
 	github.com/gofrs/uuid/v5 v5.4.0
 	github.com/google/go-cmp v0.7.0
-	github.com/gorilla/mux v1.8.1
-	github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0
 	github.com/hashicorp/golang-lru/v2 v2.0.7
 	github.com/jagottsicher/termcolor v1.0.2
 	github.com/oauth2-proxy/mockoidc v0.0.0-20240214162133-caebfff84d25
@@ -29,32 +28,34 @@ require (
 	github.com/philip-bui/grpc-zerolog v1.0.1
 	github.com/pkg/profile v1.7.0
 	github.com/prometheus/client_golang v1.23.2
-	github.com/prometheus/common v0.67.5
+	github.com/prometheus/common v0.68.1
 	github.com/pterm/pterm v0.12.83
-	github.com/puzpuzpuz/xsync/v4 v4.4.0
-	github.com/rs/zerolog v1.35.0
+	github.com/puzpuzpuz/xsync/v4 v4.5.0
+	github.com/realclientip/realclientip-go v1.0.0
+	github.com/rs/zerolog v1.35.1
 	github.com/samber/lo v1.53.0
 	github.com/sasha-s/go-deadlock v0.3.9
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	github.com/stretchr/testify v1.11.1
 	github.com/tailscale/hujson v0.0.0-20260302212456-ecc657c15afd
-	github.com/tailscale/squibble v0.0.0-20260303070345-3ac5157f405e
-	github.com/tailscale/tailsql v0.0.0-20260322172246-3ab0c1744d9c
+	github.com/tailscale/squibble v0.0.0-20260411062017-141f5d618bc4
+	github.com/tailscale/tailsql v0.0.0-20260522170732-77aec5aabc76
 	github.com/tcnksm/go-latest v0.0.0-20170313132115-e3007ae9052e
 	go4.org/netipx v0.0.0-20231129151722-fdeea329fbba
-	golang.org/x/crypto v0.49.0
-	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90
-	golang.org/x/net v0.52.0
+	golang.org/x/crypto v0.53.0
+	golang.org/x/exp v0.0.0-20260603202125-055de637280b
+	golang.org/x/net v0.56.0
 	golang.org/x/oauth2 v0.36.0
-	golang.org/x/sync v0.20.0
-	google.golang.org/genproto/googleapis/api v0.0.0-20260406210006-6f92a3bedf2d
-	google.golang.org/grpc v1.80.0
+	golang.org/x/sync v0.21.0
+	google.golang.org/genproto/googleapis/api v0.0.0-20260610212136-7ab31c22f7ad
+	google.golang.org/grpc v1.81.1
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v3 v3.0.1
 	gorm.io/driver/postgres v1.6.0
 	gorm.io/gorm v1.31.1
-	tailscale.com v1.96.5
+	pgregory.net/rapid v1.3.0
+	tailscale.com v1.101.0-pre
 	zombiezen.com/go/postgrestest v1.0.1
 )
 
@@ -76,10 +77,10 @@ require (
 // together, e.g:
 // go get modernc.org/libc@v1.55.3 modernc.org/sqlite@v1.33.1
 require (
-	modernc.org/libc v1.70.0 // indirect
+	modernc.org/libc v1.72.3 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
-	modernc.org/sqlite v1.48.2
+	modernc.org/sqlite v1.52.0
 )
 
 // NOTE: gvisor must be updated in lockstep with
@@ -92,15 +93,18 @@ require gvisor.dev/gvisor v0.0.0-20260224225140-573d5e7127a8 // indirect
 
 require (
 	atomicgo.dev/cursor v0.2.0 // indirect
-	atomicgo.dev/keyboard v0.2.9 // indirect
+	atomicgo.dev/keyboard v0.2.10 // indirect
 	atomicgo.dev/schedule v0.1.0 // indirect
 	dario.cat/mergo v1.0.2 // indirect
 	filippo.io/edwards25519 v1.2.0 // indirect
+	fyne.io/systray v1.11.1-0.20250812065214-4856ac3adc3c // indirect
 	github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
+	github.com/Kodeworks/golang-image-ico v0.0.0-20141118225523-73f0f4cfade9 // indirect
 	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/Nvveen/Gotty v0.0.0-20120604004816-cd527374f1e5 // indirect
 	github.com/akutz/memconn v0.1.0 // indirect
 	github.com/alexbrainman/sspi v0.0.0-20250919150558-7d374ff0d59e // indirect
+	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aws/aws-sdk-go-v2 v1.41.1 // indirect
 	github.com/aws/aws-sdk-go-v2/config v1.32.7 // indirect
 	github.com/aws/aws-sdk-go-v2/credentials v1.19.7 // indirect
@@ -111,6 +115,7 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.4 // indirect
 	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.17 // indirect
 	github.com/aws/aws-sdk-go-v2/service/signin v1.0.5 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssm v1.45.0 // indirect
 	github.com/aws/aws-sdk-go-v2/service/sso v1.30.9 // indirect
 	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.13 // indirect
 	github.com/aws/aws-sdk-go-v2/service/sts v1.41.6 // indirect
@@ -121,64 +126,69 @@ require (
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
 	github.com/containerd/console v1.0.5 // indirect
-	github.com/containerd/continuity v0.4.5 // indirect
+	github.com/containerd/continuity v0.5.0 // indirect
 	github.com/containerd/errdefs v1.0.0 // indirect
 	github.com/containerd/errdefs/pkg v0.3.0 // indirect
-	github.com/creachadair/mds v0.26.2 // indirect
+	github.com/creachadair/mds v0.29.0 // indirect
 	github.com/creachadair/msync v0.8.2 // indirect
 	github.com/dblohm7/wingoes v0.0.0-20250822163801-6d8e6105c62d // indirect
 	github.com/dgryski/go-metro v0.0.0-20250106013310-edb8663e5e33 // indirect
 	github.com/distribution/reference v0.6.0 // indirect
-	github.com/docker/cli v29.2.1+incompatible // indirect
-	github.com/docker/go-connections v0.6.0 // indirect
+	github.com/docker/cli v29.5.3+incompatible // indirect
+	github.com/docker/go-connections v0.7.0 // indirect
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/felixge/fgprof v0.9.5 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/fogleman/gg v1.3.0 // indirect
 	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
 	github.com/gaissmai/bart v0.26.1 // indirect
 	github.com/glebarez/go-sqlite v1.22.0 // indirect
-	github.com/go-jose/go-jose/v3 v3.0.4 // indirect
+	github.com/go-jose/go-jose/v3 v3.0.5 // indirect
 	github.com/go-jose/go-jose/v4 v4.1.4 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
+	github.com/go4org/hashtriemap v0.0.0-20251130024219-545ba229f689 // indirect
 	github.com/godbus/dbus/v5 v5.2.2 // indirect
 	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
+	github.com/golang/freetype v0.0.0-20170609003504-e2365dfdc4a0 // indirect
 	github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/google/btree v1.1.3 // indirect
 	github.com/google/go-github v17.0.0+incompatible // indirect
 	github.com/google/go-querystring v1.2.0 // indirect
-	github.com/google/pprof v0.0.0-20260202012954-cb029daf43ef // indirect
+	github.com/google/pprof v0.0.0-20260604005048-7023385849c0 // indirect
 	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
 	github.com/google/uuid v1.6.0 // indirect
-	github.com/gookit/color v1.6.0 // indirect
+	github.com/gookit/color v1.6.1 // indirect
 	github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 // indirect
-	github.com/hashicorp/go-version v1.8.0 // indirect
+	github.com/hashicorp/go-version v1.9.0 // indirect
 	github.com/hdevalence/ed25519consensus v0.2.0 // indirect
 	github.com/huin/goupnp v1.3.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
-	github.com/jackc/pgx/v5 v5.8.0 // indirect
+	github.com/jackc/pgx/v5 v5.10.0 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/jmespath/go-jmespath v0.4.0 // indirect
 	github.com/jsimonetti/rtnetlink v1.4.2 // indirect
 	github.com/kamstrup/intmap v0.5.2 // indirect
-	github.com/klauspost/compress v1.18.3 // indirect
-	github.com/lib/pq v1.11.1 // indirect
+	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 // indirect
+	github.com/klauspost/compress v1.18.6 // indirect
+	github.com/lib/pq v1.12.3 // indirect
 	github.com/lithammer/fuzzysearch v1.1.8 // indirect
-	github.com/mattn/go-colorable v0.1.14 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
-	github.com/mattn/go-runewidth v0.0.20 // indirect
+	github.com/mattn/go-colorable v0.1.15 // indirect
+	github.com/mattn/go-isatty v0.0.22 // indirect
+	github.com/mattn/go-runewidth v0.0.24 // indirect
 	github.com/mdlayher/netlink v1.8.0 // indirect
 	github.com/mdlayher/socket v0.5.1 // indirect
 	github.com/mitchellh/go-ps v1.0.0 // indirect
 	github.com/moby/docker-image-spec v1.3.1 // indirect
-	github.com/moby/moby/api v1.53.0 // indirect
-	github.com/moby/moby/client v0.2.2 // indirect
+	github.com/moby/moby/api v1.54.2 // indirect
+	github.com/moby/moby/client v0.4.1 // indirect
 	github.com/moby/sys/atomicwriter v0.1.0 // indirect
 	github.com/moby/sys/user v0.4.0 // indirect
 	github.com/moby/term v0.5.2 // indirect
@@ -188,55 +198,64 @@ require (
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.1 // indirect
 	github.com/opencontainers/runc v1.3.2 // indirect
-	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
-	github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741 // indirect
+	github.com/pelletier/go-toml/v2 v2.3.1 // indirect
+	github.com/peterbourgon/ff/v3 v3.4.0 // indirect
+	github.com/petermattis/goid v0.0.0-20260330135022-df67b199bc81 // indirect
 	github.com/pires/go-proxyproto v0.9.2 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
-	github.com/prometheus-community/pro-bing v0.7.0 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
-	github.com/prometheus/procfs v0.19.2 // indirect
+	github.com/prometheus/procfs v0.20.1 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/safchain/ethtool v0.7.0 // indirect
 	github.com/sagikazarmark/locafero v0.12.0 // indirect
 	github.com/sirupsen/logrus v1.9.4 // indirect
+	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
-	github.com/tailscale/certstore v0.1.1-0.20231202035212-d3fa0460f47e // indirect
+	github.com/tailscale/certstore v0.1.1-0.20260409135935-3638fb84b77d // indirect
 	github.com/tailscale/go-winio v0.0.0-20231025203758-c4f33415bf55 // indirect
 	github.com/tailscale/peercred v0.0.0-20250107143737-35a0c7bd7edc // indirect
-	github.com/tailscale/setec v0.0.0-20260115174028-19d190c5556d // indirect
+	github.com/tailscale/setec v0.0.0-20260310221408-dcd97e42f251 // indirect
 	github.com/tailscale/web-client-prebuilt v0.0.0-20251127225136-f19339b67368 // indirect
-	github.com/tailscale/wireguard-go v0.0.0-20250716170648-1d0488a3d7da // indirect
+	github.com/tailscale/wireguard-go v0.0.0-20260527010701-b48af7099cad // indirect
+	github.com/toqueteos/webbrowser v1.2.0 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb // indirect
 	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 // indirect
-	go.opentelemetry.io/otel v1.40.0 // indirect
-	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.40.0 // indirect
-	go.opentelemetry.io/otel/metric v1.40.0 // indirect
-	go.opentelemetry.io/otel/trace v1.40.0 // indirect
-	go.yaml.in/yaml/v2 v2.4.3 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 // indirect
+	go.opentelemetry.io/otel v1.44.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.44.0 // indirect
+	go.opentelemetry.io/otel/trace v1.44.0 // indirect
+	go.yaml.in/yaml/v2 v2.4.4 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	go4.org/mem v0.0.0-20240501181205-ae6ca9944745 // indirect
-	golang.org/x/mod v0.35.0 // indirect
-	golang.org/x/sys v0.43.0 // indirect
-	golang.org/x/term v0.42.0 // indirect
-	golang.org/x/text v0.36.0 // indirect
+	golang.org/x/exp/typeparams v0.0.0-20260603202125-055de637280b // indirect
+	golang.org/x/image v0.41.0 // indirect
+	golang.org/x/mod v0.36.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/term v0.44.0 // indirect
+	golang.org/x/text v0.38.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
-	golang.org/x/tools v0.43.0 // indirect
+	golang.org/x/tools v0.45.0 // indirect
 	golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 // indirect
 	golang.zx2c4.com/wireguard/windows v0.5.3 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa // indirect
+	k8s.io/client-go v0.34.0 // indirect
+	sigs.k8s.io/yaml v1.6.0 // indirect
+	software.sslmate.com/src/go-pkcs12 v0.4.0 // indirect
 )
 
 tool (
 	golang.org/x/tools/cmd/stress
 	golang.org/x/tools/cmd/stringer
+	tailscale.com/cmd/tailscale
 	tailscale.com/cmd/viewer
+	tailscale.com/tstest/mts
 )

go.sum

@@ -4,8 +4,8 @@ atomicgo.dev/assert v0.0.2 h1:FiKeMiZSgRrZsPo9qn/7vmr7mCsh5SZyXY4YGYiYwrg=
 atomicgo.dev/assert v0.0.2/go.mod h1:ut4NcI3QDdJtlmAxQULOmA13Gz6e2DWbSAS8RUOmNYQ=
 atomicgo.dev/cursor v0.2.0 h1:H6XN5alUJ52FZZUkI7AlJbUc1aW38GWZalpYRPpoPOw=
 atomicgo.dev/cursor v0.2.0/go.mod h1:Lr4ZJB3U7DfPPOkbH7/6TOtJ4vFGHlgj1nc+n900IpU=
-atomicgo.dev/keyboard v0.2.9 h1:tOsIid3nlPLZ3lwgG8KZMp/SFmr7P0ssEN5JUsm78K8=
-atomicgo.dev/keyboard v0.2.9/go.mod h1:BC4w9g00XkxH/f1HXhW2sXmJFOCWbKn9xrOunSFtExQ=
+atomicgo.dev/keyboard v0.2.10 h1:v7mvUKUZLHIggxULEIuWbT+WkkyQSgdbA201EziAhHU=
+atomicgo.dev/keyboard v0.2.10/go.mod h1:ap/z5ilnhLqYq852m6kPeTq5Z6aESGWu5mzRpJlC6aI=
 atomicgo.dev/schedule v0.1.0 h1:nTthAbhZS5YZmgYbb2+DH8uQIZcTlIrd4eYr3UQxEjs=
 atomicgo.dev/schedule v0.1.0/go.mod h1:xeUa3oAkiuHYh8bKiQBRojqAMq3PXXbJujjb0hw8pEU=
 dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
@@ -14,17 +14,14 @@ filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
 filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
 filippo.io/mkcert v1.4.4 h1:8eVbbwfVlaqUM7OwuftKc2nuYOoTDQWqsoXmzoXZdbc=
 filippo.io/mkcert v1.4.4/go.mod h1:VyvOchVuAye3BoUsPUOOofKygVwLV2KQMVFJNRq+1dA=
+fyne.io/systray v1.11.1-0.20250812065214-4856ac3adc3c h1:km4PIleGtbbF1oxmFQuO93CyNCldwuRTPB8WlzNWNZs=
+fyne.io/systray v1.11.1-0.20250812065214-4856ac3adc3c/go.mod h1:RVwqP9nYMo7h5zViCBHri2FgjXF7H2cub7MAq4NSoLs=
 github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c h1:udKWzYgxTojEKWjV8V+WSxDXJ4NFATAsZjh8iIbsQIg=
 github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
 github.com/BurntSushi/toml v1.5.0 h1:W5quZX/G/csjUnuI8SUYlsHs9M38FC7znL0lIO+DvMg=
 github.com/BurntSushi/toml v1.5.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
-github.com/MarvinJWendt/testza v0.1.0/go.mod h1:7AxNvlfeHP7Z/hDQ5JtE3OKYT3XFUeLCDE2DQninSqs=
-github.com/MarvinJWendt/testza v0.2.1/go.mod h1:God7bhG8n6uQxwdScay+gjm9/LnO4D3kkcZX4hv9Rp8=
-github.com/MarvinJWendt/testza v0.2.8/go.mod h1:nwIcjmr0Zz+Rcwfh3/4UhBp7ePKVhuBExvZqnKYWlII=
-github.com/MarvinJWendt/testza v0.2.10/go.mod h1:pd+VWsoGUiFtq+hRKSU1Bktnn+DMCSrDrXDpX2bG66k=
-github.com/MarvinJWendt/testza v0.2.12/go.mod h1:JOIegYyV7rX+7VZ9r77L/eH6CfJHHzXjB69adAhzZkI=
-github.com/MarvinJWendt/testza v0.3.0/go.mod h1:eFcL4I0idjtIx8P9C6KkAuLgATNKpX4/2oUqKc6bF2c=
-github.com/MarvinJWendt/testza v0.4.2/go.mod h1:mSdhXiKH8sg/gQehJ63bINcCKp7RtYewEjXsvsVUPbE=
+github.com/Kodeworks/golang-image-ico v0.0.0-20141118225523-73f0f4cfade9 h1:1ltqoej5GtaWF8jaiA49HwsZD459jqm9YFz9ZtMFpQA=
+github.com/Kodeworks/golang-image-ico v0.0.0-20141118225523-73f0f4cfade9/go.mod h1:7uhhqiBaR4CpN0k9rMjOtjpcfGd6DG2m04zQxKnWQ0I=
 github.com/MarvinJWendt/testza v0.5.2 h1:53KDo64C1z/h/d/stCYCPY69bt/OSwjq5KpFNwi+zB4=
 github.com/MarvinJWendt/testza v0.5.2/go.mod h1:xu53QFE5sCdjtMCKk8YMQ2MnymimEctc4n3EjyIYvEY=
 github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
@@ -39,7 +36,8 @@ github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be h1:9AeTilPcZAjCFI
 github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be/go.mod h1:ySMOLuWl6zY27l47sB3qLNK6tF2fkHG55UZxx8oIVo4=
 github.com/arl/statsviz v0.8.0 h1:O6GjjVxEDxcByAucOSl29HaGYLXsuwA3ujJw8H9E7/U=
 github.com/arl/statsviz v0.8.0/go.mod h1:XlrbiT7xYT03xaW9JMMfD8KFUhBOESJwfyNJu83PbB0=
-github.com/atomicgo/cursor v0.0.1/go.mod h1:cBON2QmmrysudxNBFthvMtN32r3jxVRIvzkUiF/RuIk=
+github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
+github.com/atotto/clipboard v0.1.4/go.mod h1:ZY9tmq7sm5xIbd9bOK4onWV4S6X0u6GY7Vn0Yu86PYI=
 github.com/aws/aws-sdk-go-v2 v1.41.1 h1:ABlyEARCDLN034NhxlRUSZr4l71mh+T5KAeGh6cerhU=
 github.com/aws/aws-sdk-go-v2 v1.41.1/go.mod h1:MayyLB8y+buD9hZqkCW3kX1AKq07Y5pXxtgB+rRFhz0=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.4 h1:489krEF9xIGkOaaX3CE/Be2uWjiXrkCH6gUX+bZA/BU=
@@ -107,11 +105,10 @@ github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJ
 github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
 github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
-github.com/containerd/console v1.0.3/go.mod h1:7LqA/THxQ86k76b8c/EMSiaJ3h1eZkMkXar0TQ1gf3U=
 github.com/containerd/console v1.0.5 h1:R0ymNeydRqH2DmakFNdmjR2k0t7UPuiOV/N/27/qqsc=
 github.com/containerd/console v1.0.5/go.mod h1:YynlIjWYF8myEu6sdkwKIvGQq+cOckRm6So2avqoYAk=
-github.com/containerd/continuity v0.4.5 h1:ZRoN1sXq9u7V6QoHMcVWGhOwDFqZ4B9i5H6un1Wh0x4=
-github.com/containerd/continuity v0.4.5/go.mod h1:/lNJvtJKUQStBzpVQ1+rasXO1LAWtUQssk28EZvJ3nE=
+github.com/containerd/continuity v0.5.0 h1:7a85HZpCSs+1Zps0Ee3DPSuAWY+0SJM1JNM51nlEVDg=
+github.com/containerd/continuity v0.5.0/go.mod h1:/lNJvtJKUQStBzpVQ1+rasXO1LAWtUQssk28EZvJ3nE=
 github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
 github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
 github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
@@ -123,12 +120,12 @@ github.com/coreos/go-iptables v0.7.1-0.20240112124308-65c67c9f46e6/go.mod h1:Qe8
 github.com/coreos/go-oidc/v3 v3.18.0 h1:V9orjXynvu5wiC9SemFTWnG4F45v403aIcjWo0d41+A=
 github.com/coreos/go-oidc/v3 v3.18.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
-github.com/creachadair/command v0.2.2 h1:4RGsUhqFf1imFC+vMWOOCiQdncThCdcdMJp0JNCjxxc=
-github.com/creachadair/command v0.2.2/go.mod h1:Z6Zp6CSJcnaWWR4wHgdqzODnFdxFJAaa/DrcVkeUu3E=
-github.com/creachadair/flax v0.0.5 h1:zt+CRuXQASxwQ68e9GHAOnEgAU29nF0zYMHOCrL5wzE=
-github.com/creachadair/flax v0.0.5/go.mod h1:F1PML0JZLXSNDMNiRGK2yjm5f+L9QCHchyHBldFymj8=
-github.com/creachadair/mds v0.26.2 h1:rCtvEV/bCRY0hGfwvvMg0p3yzKgBE8l/9OV4fjF9QQ8=
-github.com/creachadair/mds v0.26.2/go.mod h1:dMBTCSy3iS3dwh4Rb1zxeZz2d7K8+N24GCTsayWtQRI=
+github.com/creachadair/command v0.2.6 h1:+d4xUSZza5nqRVVsVRf5jDbix/0uKxVqFrc30F4uyRI=
+github.com/creachadair/command v0.2.6/go.mod h1:HWvS3zEpVakKlNXxT/j1U8tNoDaY7By7ORYQ+m1ha2U=
+github.com/creachadair/flax v0.0.6 h1:IFUdRdfKynNTyR5SRlrHMUGnxxMZZen8RVpwcDq/ftk=
+github.com/creachadair/flax v0.0.6/go.mod h1:F1PML0JZLXSNDMNiRGK2yjm5f+L9QCHchyHBldFymj8=
+github.com/creachadair/mds v0.29.0 h1:LyR8pWAj2ofsrdJ9s2YoIqN8b6a1djHmPQULD2fTSCA=
+github.com/creachadair/mds v0.29.0/go.mod h1:dMBTCSy3iS3dwh4Rb1zxeZz2d7K8+N24GCTsayWtQRI=
 github.com/creachadair/msync v0.8.2 h1:ujvc/SVJPn+bFwmjUHucXNTTn3opVe2YbQ46mBCnP08=
 github.com/creachadair/msync v0.8.2/go.mod h1:LzxqD9kfIl/O3DczkwOgJplLPqwrTbIhINlf9bHIsEY=
 github.com/creachadair/taskgroup v0.13.2 h1:3KyqakBuFsm3KkXi/9XIb0QcA8tEzLHLgaoidf0MdVc=
@@ -149,12 +146,12 @@ github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5Qvfr
 github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
 github.com/djherbis/times v1.6.0 h1:w2ctJ92J8fBvWPxugmXIv7Nz7Q3iDMKNx9v5ocVH20c=
 github.com/djherbis/times v1.6.0/go.mod h1:gOHeRAz2h+VJNZ5Gmc/o7iD9k4wW7NMVqieYCY99oc0=
-github.com/docker/cli v29.2.1+incompatible h1:n3Jt0QVCN65eiVBoUTZQM9mcQICCJt3akW4pKAbKdJg=
-github.com/docker/cli v29.2.1+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
+github.com/docker/cli v29.5.3+incompatible h1:nbEFfz774vBwQ5KRYv7c/AghjReqnGISvrRhzjV0evs=
+github.com/docker/cli v29.5.3+incompatible/go.mod h1:JLrzqnKDaYBop7H2jaqPtU4hHvMKP+vjCwu2uszcLI8=
 github.com/docker/docker v28.5.2+incompatible h1:DBX0Y0zAjZbSrm1uzOkdr1onVghKaftjlSWt4AFexzM=
 github.com/docker/docker v28.5.2+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
-github.com/docker/go-connections v0.6.0 h1:LlMG9azAe1TqfR7sO+NJttz1gy6KO7VJBh+pMmjSD94=
-github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
+github.com/docker/go-connections v0.7.0 h1:6SsRfJddP22WMrCkj19x9WKjEDTB+ahsdiGYf0mN39c=
+github.com/docker/go-connections v0.7.0/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q=
 github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
 github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
@@ -164,10 +161,12 @@ github.com/felixge/fgprof v0.9.5 h1:8+vR6yu2vvSKn08urWyEuxx75NWPEvybbkBirEpsbVY=
 github.com/felixge/fgprof v0.9.5/go.mod h1:yKl+ERSa++RYOs32d8K6WEXCB4uXdLls4ZaZPpayhMM=
 github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
 github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/fogleman/gg v1.3.0 h1:/7zJX8F6AaYQc57WQCyN9cAIz+4bCJGO9B+dyW29am8=
+github.com/fogleman/gg v1.3.0/go.mod h1:R/bRT+9gY/C5z7JzPU0zXsXHKM4/ayA+zqcVNZzPa1k=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
-github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
-github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
+github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
 github.com/fxamacker/cbor/v2 v2.9.0 h1:NpKPmjDBgUfBms6tr6JZkTHtfFGcMKsw3eGcmD/sapM=
 github.com/fxamacker/cbor/v2 v2.9.0/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=
 github.com/gaissmai/bart v0.26.1 h1:+w4rnLGNlA2GDVn382Tfe3jOsK5vOr5n4KmigJ9lbTo=
@@ -178,18 +177,18 @@ github.com/glebarez/go-sqlite v1.22.0 h1:uAcMJhaA6r3LHMTFgP0SifzgXg46yJkgxqyuyec
 github.com/glebarez/go-sqlite v1.22.0/go.mod h1:PlBIdHe0+aUEFn+r2/uthrWq4FxbzugL0L8Li6yQJbc=
 github.com/glebarez/sqlite v1.11.0 h1:wSG0irqzP6VurnMEpFGer5Li19RpIRi2qvQz++w0GMw=
 github.com/glebarez/sqlite v1.11.0/go.mod h1:h8/o8j5wiAsqSPoWELDUdJXhjAhsVliSn7bWZjOhrgQ=
-github.com/go-chi/chi/v5 v5.2.5 h1:Eg4myHZBjyvJmAFjFvWgrqDTXFyOzjj7YIm3L3mu6Ug=
-github.com/go-chi/chi/v5 v5.2.5/go.mod h1:X7Gx4mteadT3eDOMTsXzmI4/rwUpOwBHLpAfupzFJP0=
+github.com/go-chi/chi/v5 v5.3.0 h1:halUjDxhshgXHMrao5bB8eNBXo/rnzwr8m5m36glehM=
+github.com/go-chi/chi/v5 v5.3.0/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
 github.com/go-chi/metrics v0.1.1 h1:CXhbnkAVVjb0k73EBRQ6Z2YdWFnbXZgNtg1Mboguibk=
 github.com/go-chi/metrics v0.1.1/go.mod h1:mcGTM1pPalP7WCtb+akNYFO/lwNwBBLCuedepqjoPn4=
-github.com/go-gormigrate/gormigrate/v2 v2.1.5 h1:1OyorA5LtdQw12cyJDEHuTrEV3GiXiIhS4/QTTa/SM8=
-github.com/go-gormigrate/gormigrate/v2 v2.1.5/go.mod h1:mj9ekk/7CPF3VjopaFvWKN2v7fN3D9d3eEOAXRhi/+M=
-github.com/go-jose/go-jose/v3 v3.0.4 h1:Wp5HA7bLQcKnf6YYao/4kpRpVMp/yf6+pJKV8WFSaNY=
-github.com/go-jose/go-jose/v3 v3.0.4/go.mod h1:5b+7YgP7ZICgJDBdfjZaIt+H/9L9T/YQrVfLAMboGkQ=
+github.com/go-gormigrate/gormigrate/v2 v2.1.6 h1:VtX+l1Stj2v5RGubVQk0LS/8EPGXR+ldcOyCmlmKoyg=
+github.com/go-gormigrate/gormigrate/v2 v2.1.6/go.mod h1:PZpedQc4tWaxn6kvXicwhinh3L0seLpMc5ReKRX5id4=
+github.com/go-jose/go-jose/v3 v3.0.5 h1:BLLJWbC4nMZOfuPVxoZIxeYsn6Nl2r1fITaJ78UQlVQ=
+github.com/go-jose/go-jose/v3 v3.0.5/go.mod h1:5b+7YgP7ZICgJDBdfjZaIt+H/9L9T/YQrVfLAMboGkQ=
 github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
 github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6 h1:nxP4pPoyqOAgX8lYDFCfl3DyKeXErCvSvhcyzwGV9CE=
+github.com/go-json-experiment/json v0.0.0-20260601182631-00ed12fed2a6/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
@@ -201,6 +200,8 @@ github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpv
 github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
 github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
 github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/go4org/hashtriemap v0.0.0-20251130024219-545ba229f689 h1:0psnKZ+N2IP43/SZC8SKx6OpFJwLmQb9m9QyV9BC2f8=
+github.com/go4org/hashtriemap v0.0.0-20251130024219-545ba229f689/go.mod h1:OGmRfY/9QEK2P5zCRtmqfbCF283xPkU2dvVA4MvbvpI=
 github.com/go4org/plan9netshell v0.0.0-20250324183649-788daa080737 h1:cf60tHxREO3g1nroKr2osU3JWZsJzkfi7rEg+oAB0Lo=
 github.com/go4org/plan9netshell v0.0.0-20250324183649-788daa080737/go.mod h1:MIS0jDzbU/vuM9MC4YnBITCv+RYuTRq8dJzmCrFsK9g=
 github.com/gobwas/httphead v0.1.0/go.mod h1:O/RXo79gxV8G+RqlR/otEwx4Q36zl9rqC5u12GKvMCM=
@@ -212,6 +213,8 @@ github.com/gofrs/uuid/v5 v5.4.0 h1:EfbpCTjqMuGyq5ZJwxqzn3Cbr2d0rUZU7v5ycAk/e/0=
 github.com/gofrs/uuid/v5 v5.4.0/go.mod h1:CDOjlDMVAtN56jqyRUZh58JT31Tiw7/oQyEXZV+9bD8=
 github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
 github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/golang/freetype v0.0.0-20170609003504-e2365dfdc4a0 h1:DACJavvAHhabrF08vX0COfcOBJRhZ8lUbR+ZWIs0Y5g=
+github.com/golang/freetype v0.0.0-20170609003504-e2365dfdc4a0/go.mod h1:E/TSTwGwJL78qG/PmXZO1EjYhfJinVAhrmmHX6Z8B9k=
 github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 h1:f+oWsMOmNPc8JmEHVZIycC7hBoQxHH9pNKQORJNozsQ=
 github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8/go.mod h1:wcDNUvekVysuuOpQKo3191zZyTpiI6se1N1ULghS0sw=
 github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
@@ -232,26 +235,22 @@ github.com/google/nftables v0.2.1-0.20240414091927-5e242ec57806 h1:wG8RYIyctLhdF
 github.com/google/nftables v0.2.1-0.20240414091927-5e242ec57806/go.mod h1:Beg6V6zZ3oEn0JuiUQ4wqwuyqqzasOltcoXPtgLbFp4=
 github.com/google/pprof v0.0.0-20211214055906-6f57359322fd/go.mod h1:KgnwoLYCZ8IQu3XUZ8Nc/bM9CCZFOyjUNOSygVozoDg=
 github.com/google/pprof v0.0.0-20240227163752-401108e1b7e7/go.mod h1:czg5+yv1E0ZGTi6S6vVK1mke0fV+FaUhNGcd6VRS9Ik=
-github.com/google/pprof v0.0.0-20260202012954-cb029daf43ef h1:xpF9fUHpoIrrjX24DURVKiwHcFpw19ndIs+FwTSMbno=
-github.com/google/pprof v0.0.0-20260202012954-cb029daf43ef/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
+github.com/google/pprof v0.0.0-20260604005048-7023385849c0 h1:h1QTMDl6q9wDvDCJVpKQSjgleGFYnd2fOxmg2K+6BGE=
+github.com/google/pprof v0.0.0-20260604005048-7023385849c0/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
 github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 h1:El6M4kTTCOh6aBiKaUGG7oYTSPP8MxqL4YI3kZKwcP4=
 github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510/go.mod h1:pupxD2MaaD3pAXIBCelhxNneeOaAeabZDe5s4K6zSpQ=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gookit/assert v0.1.1 h1:lh3GcawXe/p+cU7ESTZ5Ui3Sm/x8JWpIis4/1aF0mY0=
 github.com/gookit/assert v0.1.1/go.mod h1:jS5bmIVQZTIwk42uXl4lyj4iaaxx32tqH16CFj0VX2E=
-github.com/gookit/color v1.4.2/go.mod h1:fqRyamkC1W8uxl+lxCQxOT09l/vYfZ+QeiX3rKQHCoQ=
-github.com/gookit/color v1.5.0/go.mod h1:43aQb+Zerm/BWh2GnrgOQm7ffz7tvQXEKV6BFMl7wAo=
-github.com/gookit/color v1.6.0 h1:JjJXBTk1ETNyqyilJhkTXJYYigHG24TM9Xa2M1xAhRA=
-github.com/gookit/color v1.6.0/go.mod h1:9ACFc7/1IpHGBW8RwuDm/0YEnhg3dwwXpoMsmtyHfjs=
-github.com/gorilla/mux v1.8.1 h1:TuBL49tXwgrFYWhqrNgrUNEY92u81SPhu7sTdzQEiWY=
-github.com/gorilla/mux v1.8.1/go.mod h1:AKf9I4AEqPTmMytcMc0KkNouC66V3BtZ4qD5fmWSiMQ=
+github.com/gookit/color v1.6.1 h1:KoTnDxJPRgrL0SoX0f8rCFg2zI0t4E3GZZBMo2nN8LU=
+github.com/gookit/color v1.6.1/go.mod h1:9ACFc7/1IpHGBW8RwuDm/0YEnhg3dwwXpoMsmtyHfjs=
 github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674 h1:JeSE6pjso5THxAzdVpqr6/geYxZytqFMBCOtn/ujyeo=
 github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674/go.mod h1:r4w70xmWCQKmi1ONH4KIaBptdivuRPyosB9RmPlGEwA=
-github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 h1:HWRh5R2+9EifMyIHV7ZV+MIZqgz+PMpZ14Jynv3O2Zs=
-github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0/go.mod h1:JfhWUomR1baixubs02l85lZYYOm7LV6om4ceouMv45c=
-github.com/hashicorp/go-version v1.8.0 h1:KAkNb1HAiZd1ukkxDFGmokVZe1Xy9HG6NUp+bPle2i4=
-github.com/hashicorp/go-version v1.8.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 h1:5VipnvEpbqr2gA2VbM+nYVbkIF28c5ZQfqCBQ5g2xfk=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0/go.mod h1:Hyl3n6Twe1hvtd9XUXDec4pTvgMSEixRuQKPTMH2bNs=
+github.com/hashicorp/go-version v1.9.0 h1:CeOIz6k+LoN3qX9Z0tyQrPtiB1DFYRPfCIBtaXPSCnA=
+github.com/hashicorp/go-version v1.9.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
 github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/hdevalence/ed25519consensus v0.2.0 h1:37ICyZqdyj0lAZ8P4D1d1id3HqbbG1N3iBb1Tb4rdcU=
@@ -270,8 +269,8 @@ github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsI
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
-github.com/jackc/pgx/v5 v5.8.0 h1:TYPDoleBBme0xGSAX3/+NujXXtpZn9HBONkQC7IEZSo=
-github.com/jackc/pgx/v5 v5.8.0/go.mod h1:QVeDInX2m9VyzvNeiCJVjCkNFqzsNb43204HshNSZKw=
+github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
+github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/jagottsicher/termcolor v1.0.2 h1:fo0c51pQSuLBN1+yVX2ZE+hE+P7ULb/TY8eRowJnrsM=
@@ -284,45 +283,42 @@ github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
 github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
 github.com/jmespath/go-jmespath v0.4.0 h1:BEgLn5cpjn8UN1mAw4NjwDrS35OdebyEtFe+9YPoQUg=
 github.com/jmespath/go-jmespath v0.4.0/go.mod h1:T8mJZnbsbmF+m6zOOFylbeCJqk5+pHWvzYPziyZiYoo=
+github.com/jmespath/go-jmespath/internal/testify v1.5.1 h1:shLQSRRSCCPj3f2gpwzGwWFoC7ycTf1rcQZHOlsJ6N8=
+github.com/jmespath/go-jmespath/internal/testify v1.5.1/go.mod h1:L3OGu8Wl2/fWfCI6z80xFu9LTZmf1ZRjMHUOPmWr69U=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/jsimonetti/rtnetlink v1.4.2 h1:Df9w9TZ3npHTyDn0Ev9e1uzmN2odmXd0QX+J5GTEn90=
 github.com/jsimonetti/rtnetlink v1.4.2/go.mod h1:92s6LJdE+1iOrw+F2/RO7LYI2Qd8pPpFNNUYW06gcoM=
 github.com/kamstrup/intmap v0.5.2 h1:qnwBm1mh4XAnW9W9Ue9tZtTff8pS6+s6iKF6JRIV2Dk=
 github.com/kamstrup/intmap v0.5.2/go.mod h1:gWUVWHKzWj8xpJVFf5GC0O26bWmv3GqdnIX/LMT6Aq4=
-github.com/klauspost/compress v1.18.3 h1:9PJRvfbmTabkOX8moIpXPbMMbYN60bWImDDU7L+/6zw=
-github.com/klauspost/compress v1.18.3/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
-github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
-github.com/klauspost/cpuid/v2 v2.0.10/go.mod h1:g2LTdtYhdyuGPqyWyv7qRAmj1WBqxuObKfj5c0PQa7c=
-github.com/klauspost/cpuid/v2 v2.0.12/go.mod h1:g2LTdtYhdyuGPqyWyv7qRAmj1WBqxuObKfj5c0PQa7c=
-github.com/klauspost/cpuid/v2 v2.2.3 h1:sxCkb+qR91z4vsqw4vGGZlDgPz3G7gjaLyK3V8y70BU=
-github.com/klauspost/cpuid/v2 v2.2.3/go.mod h1:RVVoqg1df56z8g3pUjL/3lE5UfnlrJX8tyFgg4nqhuY=
+github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 h1:Z9n2FFNUXsshfwJMBgNA0RU6/i7WVaAegv3PtuIHPMs=
+github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51/go.mod h1:CzGEWj7cYgsdH8dAjBGEr58BoE7ScuLd+fwFZ44+/x8=
+github.com/klauspost/compress v1.18.6 h1:2jupLlAwFm95+YDR+NwD2MEfFO9d4z4Prjl1XXDjuao=
+github.com/klauspost/compress v1.18.6/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
+github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
+github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
 github.com/kortschak/wol v0.0.0-20200729010619-da482cc4850a h1:+RR6SqnTkDLWyICxS1xpjCi/3dhyV+TgZwA6Ww3KncQ=
 github.com/kortschak/wol v0.0.0-20200729010619-da482cc4850a/go.mod h1:YTtCCM3ryyfiu4F7t8HQ1mxvp1UBdWM2r6Xa+nGWvDk=
 github.com/kr/fs v0.1.0 h1:Jskdu9ieNAYnjxsi0LbQp1ulIKZV1LAFgK1tWhpZgl8=
 github.com/kr/fs v0.1.0/go.mod h1:FFnZGqtBN9Gxj7eW1uZ42v5BccTP0vu6NEaFoC2HwRg=
-github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
-github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
-github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80/go.mod h1:imJHygn/1yfhB7XSJJKlFZKl/J+dCPAknuiaGOshXAs=
 github.com/lib/pq v1.8.0/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
-github.com/lib/pq v1.11.1 h1:wuChtj2hfsGmmx3nf1m7xC2XpK6OtelS2shMY+bGMtI=
-github.com/lib/pq v1.11.1/go.mod h1:/p+8NSbOcwzAEI7wiMXFlgydTwcgTr3OSKMsD2BitpA=
+github.com/lib/pq v1.12.3 h1:tTWxr2YLKwIvK90ZXEw8GP7UFHtcbTtty8zsI+YjrfQ=
+github.com/lib/pq v1.12.3/go.mod h1:/p+8NSbOcwzAEI7wiMXFlgydTwcgTr3OSKMsD2BitpA=
 github.com/lithammer/fuzzysearch v1.1.8 h1:/HIuJnjHuXS8bKaiTMeeDlW2/AyIWk2brx1V8LFgLN4=
 github.com/lithammer/fuzzysearch v1.1.8/go.mod h1:IdqeyBClc3FFqSzYq/MXESsS4S0FsZ5ajtkr5xPLts4=
 github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
-github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
-github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
-github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
-github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
-github.com/mattn/go-runewidth v0.0.13/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
-github.com/mattn/go-runewidth v0.0.20 h1:WcT52H91ZUAwy8+HUkdM3THM6gXqXuLJi9O3rjcQQaQ=
-github.com/mattn/go-runewidth v0.0.20/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/mattn/go-colorable v0.1.15 h1:+u9SLTRGnXv73cEsnsmoZBom+dMU88B2M0aDcWy0/jY=
+github.com/mattn/go-colorable v0.1.15/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.22 h1:j8l17JJ9i6VGPUFUYoTUKPSgKe/83EYU2zBC7YNKMw4=
+github.com/mattn/go-isatty v0.0.22/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
+github.com/mattn/go-runewidth v0.0.24 h1:cpokDiIn0MGnhdHwuWnJBITySJ20QyNGnY2kR/ay2DU=
+github.com/mattn/go-runewidth v0.0.24/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/mdlayher/genetlink v1.3.2 h1:KdrNKe+CTu+IbZnm/GVUMXSqBBLqcGpRDa0xkQy56gw=
 github.com/mdlayher/genetlink v1.3.2/go.mod h1:tcC3pkCrPUGIKKsCsp0B3AdaaKuHtaxoJRz3cc+528o=
 github.com/mdlayher/netlink v1.8.0 h1:e7XNIYJKD7hUct3Px04RuIGJbBxy1/c4nX7D5YyvvlM=
@@ -337,10 +333,10 @@ github.com/mitchellh/go-ps v1.0.0 h1:i6ampVEEF4wQFF+bkYfwYgY+F/uYJDktmvLPf7qIgjc
 github.com/mitchellh/go-ps v1.0.0/go.mod h1:J4lOc8z8yJs6vUwklHw2XEIiT4z4C40KtWVN3nvg8Pg=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
-github.com/moby/moby/api v1.53.0 h1:PihqG1ncw4W+8mZs69jlwGXdaYBeb5brF6BL7mPIS/w=
-github.com/moby/moby/api v1.53.0/go.mod h1:8mb+ReTlisw4pS6BRzCMts5M49W5M7bKt1cJy/YbAqc=
-github.com/moby/moby/client v0.2.2 h1:Pt4hRMCAIlyjL3cr8M5TrXCwKzguebPAc2do2ur7dEM=
-github.com/moby/moby/client v0.2.2/go.mod h1:2EkIPVNCqR05CMIzL1mfA07t0HvVUUOl85pasRz/GmQ=
+github.com/moby/moby/api v1.54.2 h1:wiat9QAhnDQjA7wk1kh/TqHz2I1uUA7M7t9SAl/JNXg=
+github.com/moby/moby/api v1.54.2/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs=
+github.com/moby/moby/client v0.4.1 h1:DMQgisVoMkmMs7fp3ROSdiBnoAu8+vo3GggFl06M/wY=
+github.com/moby/moby/client v0.4.1/go.mod h1:z52C9O2POPOsnxZAy//WtKcQ32P+jT/NGeXu/7nfjGQ=
 github.com/moby/sys/atomicwriter v0.1.0 h1:kw5D/EqkBwsBFi0ss9v1VG3wIkVhzGvLklJ+w3A14Sw=
 github.com/moby/sys/atomicwriter v0.1.0/go.mod h1:Ul8oqv2ZMNHOceF643P6FKPXeCmYtlQMvpizfsSoaWs=
 github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
@@ -368,11 +364,13 @@ github.com/opencontainers/runc v1.3.2/go.mod h1:F7UQQEsxcjUNnFpT1qPLHZBKYP7yWwk6
 github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde/go.mod h1:nZgzbfBr3hhjoZnS66nKrHmduYNpc34ny7RK4z5/HM0=
 github.com/ory/dockertest/v3 v3.12.0 h1:3oV9d0sDzlSQfHtIaB5k6ghUCVMVLpAY8hwrqoCyRCw=
 github.com/ory/dockertest/v3 v3.12.0/go.mod h1:aKNDTva3cp8dwOWwb9cWuX84aH5akkxXRvO7KCwWVjE=
-github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
-github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pelletier/go-toml/v2 v2.3.1 h1:MYEvvGnQjeNkRF1qUuGolNtNExTDwct51yp7olPtrEc=
+github.com/pelletier/go-toml/v2 v2.3.1/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/peterbourgon/ff/v3 v3.4.0 h1:QBvM/rizZM1cB0p0lGMdmR7HxZeI/ZrBWB4DqLkMUBc=
+github.com/peterbourgon/ff/v3 v3.4.0/go.mod h1:zjJVUhx+twciwfDl0zBcFzl4dW8axCRyXE/eKY9RztQ=
 github.com/petermattis/goid v0.0.0-20250813065127-a731cc31b4fe/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
-github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741 h1:KPpdlQLZcHfTMQRi6bFQ7ogNO0ltFT4PmtwTLW4W+14=
-github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
+github.com/petermattis/goid v0.0.0-20260330135022-df67b199bc81 h1:WDsQxOJDy0N1VRAjXLpi8sCEZRSGarLWQevDxpTBRrM=
+github.com/petermattis/goid v0.0.0-20260330135022-df67b199bc81/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
 github.com/philip-bui/grpc-zerolog v1.0.1 h1:EMacvLRUd2O1K0eWod27ZP5CY1iTNkhBDLSN+Q4JEvA=
 github.com/philip-bui/grpc-zerolog v1.0.1/go.mod h1:qXbiq/2X4ZUMMshsqlWyTHOcw7ns+GZmlqZZN05ZHcQ=
 github.com/pierrec/lz4/v4 v4.1.25 h1:kocOqRffaIbU5djlIBr7Wh+cx82C0vtFb0fOurZHqD0=
@@ -388,34 +386,26 @@ github.com/pkg/sftp v1.13.6/go.mod h1:tz1ryNURKu77RL+GuCzmoJYxQczL3wLNNpPWagdg4Q
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/prometheus-community/pro-bing v0.7.0 h1:KFYFbxC2f2Fp6c+TyxbCOEarf7rbnzr9Gw8eIb0RfZA=
-github.com/prometheus-community/pro-bing v0.7.0/go.mod h1:Moob9dvlY50Bfq6i88xIwfyw7xLFHH69LUgx9n5zqCE=
 github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
 github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
 github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
-github.com/prometheus/common v0.67.5 h1:pIgK94WWlQt1WLwAC5j2ynLaBRDiinoAb86HZHTUGI4=
-github.com/prometheus/common v0.67.5/go.mod h1:SjE/0MzDEEAyrdr5Gqc6G+sXI67maCxzaT3A2+HqjUw=
-github.com/prometheus/procfs v0.19.2 h1:zUMhqEW66Ex7OXIiDkll3tl9a1ZdilUOd/F6ZXw4Vws=
-github.com/prometheus/procfs v0.19.2/go.mod h1:M0aotyiemPhBCM0z5w87kL22CxfcH05ZpYlu+b4J7mw=
-github.com/pterm/pterm v0.12.27/go.mod h1:PhQ89w4i95rhgE+xedAoqous6K9X+r6aSOI2eFF7DZI=
-github.com/pterm/pterm v0.12.29/go.mod h1:WI3qxgvoQFFGKGjGnJR849gU0TsEOvKn5Q8LlY1U7lg=
-github.com/pterm/pterm v0.12.30/go.mod h1:MOqLIyMOgmTDz9yorcYbcw+HsgoZo3BQfg2wtl3HEFE=
-github.com/pterm/pterm v0.12.31/go.mod h1:32ZAWZVXD7ZfG0s8qqHXePte42kdz8ECtRyEejaWgXU=
-github.com/pterm/pterm v0.12.33/go.mod h1:x+h2uL+n7CP/rel9+bImHD5lF3nM9vJj80k9ybiiTTE=
-github.com/pterm/pterm v0.12.36/go.mod h1:NjiL09hFhT/vWjQHSj1athJpx6H8cjpHXNAK5bUw8T8=
-github.com/pterm/pterm v0.12.40/go.mod h1:ffwPLwlbXxP+rxT0GsgDTzS3y3rmpAO1NMjUkGTYf8s=
+github.com/prometheus/common v0.68.1 h1:omjRRl4QP4komogpXuhfeOiisQg7xdy8VM1UY+pStaY=
+github.com/prometheus/common v0.68.1/go.mod h1:ZzL3f6u94qUxh9p+tJTrF+FvBS1XXbbRAZCQkytAL0Y=
+github.com/prometheus/procfs v0.20.1 h1:XwbrGOIplXW/AU3YhIhLODXMJYyC1isLFfYCsTEycfc=
+github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4UlK79eF5TGGo=
 github.com/pterm/pterm v0.12.83 h1:ie+YmGmA727VuhxBlyGr74Ks+7McV6kT99IB8EU80aA=
 github.com/pterm/pterm v0.12.83/go.mod h1:xlgc6bFWyJIMtmLJvGim+L7jhSReilOlOnodeIYe4Tk=
-github.com/puzpuzpuz/xsync/v4 v4.4.0 h1:vlSN6/CkEY0pY8KaB0yqo/pCLZvp9nhdbBdjipT4gWo=
-github.com/puzpuzpuz/xsync/v4 v4.4.0/go.mod h1:VJDmTCJMBt8igNxnkQd86r+8KUeN1quSfNKu5bLYFQo=
+github.com/puzpuzpuz/xsync/v4 v4.5.0 h1:vOSWu6b57/emh+L/Cw0BeQfvxa/cogFywXHeGUxQxAg=
+github.com/puzpuzpuz/xsync/v4 v4.5.0/go.mod h1:VJDmTCJMBt8igNxnkQd86r+8KUeN1quSfNKu5bLYFQo=
+github.com/realclientip/realclientip-go v1.0.0 h1:+yPxeC0mEaJzq1BfCt2h4BxlyrvIIBzR6suDc3BEF1U=
+github.com/realclientip/realclientip-go v1.0.0/go.mod h1:CXnUdVwFRcXFJIRb/dTYqbT7ud48+Pi2pFm80bxDmcI=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
-github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
-github.com/rs/zerolog v1.35.0 h1:VD0ykx7HMiMJytqINBsKcbLS+BJ4WYjz+05us+LRTdI=
-github.com/rs/zerolog v1.35.0/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
+github.com/rs/zerolog v1.35.1 h1:m7xQeoiLIiV0BCEY4Hs+j2NG4Gp2o2KPKmhnnLiazKI=
+github.com/rs/zerolog v1.35.1/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/safchain/ethtool v0.7.0 h1:rlJzfDetsVvT61uz8x1YIcFn12akMfuPulHtZjtb7Is=
 github.com/safchain/ethtool v0.7.0/go.mod h1:MenQKEjXdfkjD3mp2QdCk8B/hwvkrlOTm/FD4gTpFxQ=
@@ -425,11 +415,12 @@ github.com/samber/lo v1.53.0 h1:t975lj2py4kJPQ6haz1QMgtId2gtmfktACxIXArw3HM=
 github.com/samber/lo v1.53.0/go.mod h1:4+MXEGsJzbKGaUEQFKBq2xtfuznW9oz/WrgyzMzRoM0=
 github.com/sasha-s/go-deadlock v0.3.9 h1:fiaT9rB7g5sr5ddNZvlwheclN9IP86eFW9WgqlEQV+w=
 github.com/sasha-s/go-deadlock v0.3.9/go.mod h1:KuZj51ZFmx42q/mPaYbRk0P1xcwe697zsJKE03vD4/Y=
-github.com/sergi/go-diff v1.2.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=
-github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 h1:n661drycOFuPLCN3Uc8sB6B/s6Z4t2xvBgU1htSHuq8=
-github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
+github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw=
+github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
 github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
 github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
+github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e h1:MRM5ITcdelLK2j1vwZ3Je0FKVCfqOLp5zO6trqMLYs0=
+github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e/go.mod h1:XV66xRDqSt+GTGFMVlhk3ULuV0y9ZmzeVGR4mloJI3M=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
 github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
 github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
@@ -446,8 +437,6 @@ github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSS
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
-github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
-github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
@@ -455,8 +444,10 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
-github.com/tailscale/certstore v0.1.1-0.20231202035212-d3fa0460f47e h1:PtWT87weP5LWHEY//SWsYkSO3RWRZo4OSWagh3YD2vQ=
-github.com/tailscale/certstore v0.1.1-0.20231202035212-d3fa0460f47e/go.mod h1:XrBNfAFN+pwoWuksbFS9Ccxnopa15zJGgXRFN90l3K4=
+github.com/tailscale/certstore v0.1.1-0.20260409135935-3638fb84b77d h1:JcGKBZAL7ePLwOhUdN8qGQZlP5GueEiIZwY7R62pejE=
+github.com/tailscale/certstore v0.1.1-0.20260409135935-3638fb84b77d/go.mod h1:XrBNfAFN+pwoWuksbFS9Ccxnopa15zJGgXRFN90l3K4=
+github.com/tailscale/gliderssh v0.3.4-0.20260330083525-c1389c70ff89 h1:glgVc1ZYMjwN1Q/ITWeuSQyl029uayagaR2sjsifehc=
+github.com/tailscale/gliderssh v0.3.4-0.20260330083525-c1389c70ff89/go.mod h1:wn16Km1EZOX4UEAyaZa3dBwfFGOJ7neck40NcwosJUw=
 github.com/tailscale/go-winio v0.0.0-20231025203758-c4f33415bf55 h1:Gzfnfk2TWrk8Jj4P4c1a3CtQyMaTVCznlkLZI++hok4=
 github.com/tailscale/go-winio v0.0.0-20231025203758-c4f33415bf55/go.mod h1:4k4QO+dQ3R5FofL+SanAUZe+/QfeK0+OIuwDIRu2vSg=
 github.com/tailscale/golang-x-crypto v0.0.0-20250404221719-a5573b049869 h1:SRL6irQkKGQKKLzvQP/ke/2ZuB7Py5+XuqtOgSj+iMM=
@@ -467,18 +458,18 @@ github.com/tailscale/netlink v1.1.1-0.20240822203006-4d49adab4de7 h1:uFsXVBE9Qr4
 github.com/tailscale/netlink v1.1.1-0.20240822203006-4d49adab4de7/go.mod h1:NzVQi3Mleb+qzq8VmcWpSkcSYxXIg0DkI6XDzpVkhJ0=
 github.com/tailscale/peercred v0.0.0-20250107143737-35a0c7bd7edc h1:24heQPtnFR+yfntqhI3oAu9i27nEojcQ4NuBQOo5ZFA=
 github.com/tailscale/peercred v0.0.0-20250107143737-35a0c7bd7edc/go.mod h1:f93CXfllFsO9ZQVq+Zocb1Gp4G5Fz0b0rXHLOzt/Djc=
-github.com/tailscale/setec v0.0.0-20260115174028-19d190c5556d h1:N+TtzIaGYREbLbKZB0WU0vVnMSfaqUkSf3qMEi03hwE=
-github.com/tailscale/setec v0.0.0-20260115174028-19d190c5556d/go.mod h1:6NU8H/GLPVX2TnXAY1duyy9ylLaHwFpr0X93UPiYmNI=
-github.com/tailscale/squibble v0.0.0-20260303070345-3ac5157f405e h1:4yfp5/YDr+TzbUME/PalYJVXAsp7zA2Gv2xQMZ9Qors=
-github.com/tailscale/squibble v0.0.0-20260303070345-3ac5157f405e/go.mod h1:xJkMmR3t+thnUQhA3Q4m2VSlS5pcOq+CIjmU/xfKKx4=
-github.com/tailscale/tailsql v0.0.0-20260322172246-3ab0c1744d9c h1:7lJQ/zycbk1E9e0nUiMuwIDYprFTLpWXUwiPdi+tRlI=
-github.com/tailscale/tailsql v0.0.0-20260322172246-3ab0c1744d9c/go.mod h1:bpNmZdvZKmBstrZunT+NXL6hmrFw5AsuT7MGiYS8sRc=
+github.com/tailscale/setec v0.0.0-20260310221408-dcd97e42f251 h1:kNnJlwxSzue+VRJuDdZ/yebcMM2q9KqFmK9xQqH1YRc=
+github.com/tailscale/setec v0.0.0-20260310221408-dcd97e42f251/go.mod h1:6NU8H/GLPVX2TnXAY1duyy9ylLaHwFpr0X93UPiYmNI=
+github.com/tailscale/squibble v0.0.0-20260411062017-141f5d618bc4 h1:1ghkd9YIC4J7umZuu9jZz8afWJSj1hCRSzfvdI2Q3Vo=
+github.com/tailscale/squibble v0.0.0-20260411062017-141f5d618bc4/go.mod h1:EVp9PDh7v69Do6aNzFfLvL0fdCph3XskGMi+WcS/uOM=
+github.com/tailscale/tailsql v0.0.0-20260522170732-77aec5aabc76 h1:o7mEEIci+U0H3Ddo0JRMOxm2VGcCKaVPro/F+f3qFbg=
+github.com/tailscale/tailsql v0.0.0-20260522170732-77aec5aabc76/go.mod h1:N2Dm+UzRWz01zPMDl5XHkSVq91kNPWU13uUUibcOm+c=
 github.com/tailscale/web-client-prebuilt v0.0.0-20251127225136-f19339b67368 h1:0tpDdAj9sSfSZg4gMwNTdqMP592sBrq2Sm0w6ipnh7k=
 github.com/tailscale/web-client-prebuilt v0.0.0-20251127225136-f19339b67368/go.mod h1:agQPE6y6ldqCOui2gkIh7ZMztTkIQKH049tv8siLuNQ=
 github.com/tailscale/wf v0.0.0-20240214030419-6fbb0a674ee6 h1:l10Gi6w9jxvinoiq15g8OToDdASBni4CyJOdHY1Hr8M=
 github.com/tailscale/wf v0.0.0-20240214030419-6fbb0a674ee6/go.mod h1:ZXRML051h7o4OcI0d3AaILDIad/Xw0IkXaHM17dic1Y=
-github.com/tailscale/wireguard-go v0.0.0-20250716170648-1d0488a3d7da h1:jVRUZPRs9sqyKlYHHzHjAqKN+6e/Vog6NpHYeNPJqOw=
-github.com/tailscale/wireguard-go v0.0.0-20250716170648-1d0488a3d7da/go.mod h1:BOm5fXUBFM+m9woLNBoxI9TaBXXhGNP50LX/TGIvGb4=
+github.com/tailscale/wireguard-go v0.0.0-20260527010701-b48af7099cad h1:Ky26FR5yZ5IKEB0xtm5A8xSTb06ImY7kxBFrvgOmJSg=
+github.com/tailscale/wireguard-go v0.0.0-20260527010701-b48af7099cad/go.mod h1:6SerzcvHWQchKO2BfNdmquA77CHSECZuFl+D9fp4RnI=
 github.com/tailscale/xnet v0.0.0-20240729143630-8497ac4dab2e h1:zOGKqN5D5hHhiYUp091JqK7DPCqSARyUfduhGUY8Bek=
 github.com/tailscale/xnet v0.0.0-20240729143630-8497ac4dab2e/go.mod h1:orPd6JZXXRyuDusYilywte7k094d7dycXXU5YnWsrwg=
 github.com/tc-hib/winres v0.2.1 h1:YDE0FiP0VmtRaDn7+aaChp1KiF4owBiJa5l964l5ujA=
@@ -487,6 +478,8 @@ github.com/tcnksm/go-latest v0.0.0-20170313132115-e3007ae9052e h1:IWllFTiDjjLIf2
 github.com/tcnksm/go-latest v0.0.0-20170313132115-e3007ae9052e/go.mod h1:d7u6HkTYKSv5m6MCKkOQlHwaShTMl3HjqSGW3XtVhXM=
 github.com/tink-crypto/tink-go/v2 v2.6.0 h1:+KHNBHhWH33Vn+igZWcsgdEPUxKwBMEe0QC60t388v4=
 github.com/tink-crypto/tink-go/v2 v2.6.0/go.mod h1:2WbBA6pfNsAfBwDCggboaHeB2X29wkU8XHtGwh2YIk8=
+github.com/toqueteos/webbrowser v1.2.0 h1:tVP/gpK69Fx+qMJKsLE7TD8LuGWPnEV71wBN9rrstGQ=
+github.com/toqueteos/webbrowser v1.2.0/go.mod h1:XWoZq4cyp9WeUeak7w7LXRUQf1F1ATJMir8RTqb4ayM=
 github.com/u-root/u-root v0.14.0 h1:Ka4T10EEML7dQ5XDvO9c3MBN8z4nuSnGjcd1jmU2ivg=
 github.com/u-root/u-root v0.14.0/go.mod h1:hAyZorapJe4qzbLWlAkmSVCJGbfoU9Pu4jpJ1WMluqE=
 github.com/u-root/uio v0.0.0-20240224005618-d2acac8f3701 h1:pyC9PaHYZFgEKFdlp3G8RaCKgVpHZnecvArXvPXcFkM=
@@ -502,34 +495,33 @@ github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHo
 github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415/go.mod h1:GwrjFmJcFw6At/Gs6z4yjiIwzuJ1/+UwLxMQDVQXShQ=
 github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74=
 github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQluxsYJ78Id3Y=
-github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778/go.mod h1:2MuV+tbUrU1zIOPMxZ5EncGwgmMJsa+9ucAQZXxsObs=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 h1:7iP2uCb7sGddAr30RRS6xjKy7AZ2JtTOPA3oolgVSw8=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0/go.mod h1:c7hN3ddxs/z6q9xwvfLPk+UHlWRQyaeR1LdgfL/66l0=
-go.opentelemetry.io/otel v1.40.0 h1:oA5YeOcpRTXq6NN7frwmwFR0Cn3RhTVZvXsP4duvCms=
-go.opentelemetry.io/otel v1.40.0/go.mod h1:IMb+uXZUKkMXdPddhwAHm6UfOwJyh4ct1ybIlV14J0g=
-go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0 h1:QKdN8ly8zEMrByybbQgv8cWBcdAarwmIPZ6FThrWXJs=
-go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0/go.mod h1:bTdK1nhqF76qiPoCCdyFIV+N/sRHYXYCTQc+3VCi3MI=
-go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.40.0 h1:wVZXIWjQSeSmMoxF74LzAnpVQOAFDo3pPji9Y4SOFKc=
-go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.40.0/go.mod h1:khvBS2IggMFNwZK/6lEeHg/W57h/IX6J4URh57fuI40=
-go.opentelemetry.io/otel/metric v1.40.0 h1:rcZe317KPftE2rstWIBitCdVp89A2HqjkxR3c11+p9g=
-go.opentelemetry.io/otel/metric v1.40.0/go.mod h1:ib/crwQH7N3r5kfiBZQbwrTge743UDc7DTFVZrrXnqc=
-go.opentelemetry.io/otel/sdk v1.40.0 h1:KHW/jUzgo6wsPh9At46+h4upjtccTmuZCFAc9OJ71f8=
-go.opentelemetry.io/otel/sdk v1.40.0/go.mod h1:Ph7EFdYvxq72Y8Li9q8KebuYUr2KoeyHx0DRMKrYBUE=
-go.opentelemetry.io/otel/sdk/metric v1.40.0 h1:mtmdVqgQkeRxHgRv4qhyJduP3fYJRMX4AtAlbuWdCYw=
-go.opentelemetry.io/otel/sdk/metric v1.40.0/go.mod h1:4Z2bGMf0KSK3uRjlczMOeMhKU2rhUqdWNoKcYrtcBPg=
-go.opentelemetry.io/otel/trace v1.40.0 h1:WA4etStDttCSYuhwvEa8OP8I5EWu24lkOzp+ZYblVjw=
-go.opentelemetry.io/otel/trace v1.40.0/go.mod h1:zeAhriXecNGP/s2SEG3+Y8X9ujcJOTqQ5RgdEJcawiA=
-go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A=
-go.opentelemetry.io/proto/otlp v1.9.0/go.mod h1:xE+Cx5E/eEHw+ISFkwPLwCZefwVjY+pqKg1qcK03+/4=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 h1:8tvICD4vSTOOsNrsI4Ljf6C+6UKvpTEH5XY3JMoyPoo=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0/go.mod h1:z9+yiacE0IHRqM4qFfkbt/JYlmYXgss8GY/jXoNuPJI=
+go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU=
+go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0 h1:88Y4s2C8oTui1LGM6bTWkw0ICGcOLCAI5l6zsD1j20k=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0/go.mod h1:Vl1/iaggsuRlrHf/hfPJPvVag77kKyvrLeD10kpMl+A=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0 h1:3iZJKlCZufyRzPzlQhUIWVmfltrXuGyfjREgGP3UUjc=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0/go.mod h1:/G+nUPfhq2e+qiXMGxMwumDrP5jtzU+mWN7/sjT2rak=
+go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc=
+go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo=
+go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58=
+go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0=
+go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI=
+go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA=
+go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk=
+go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE=
+go.opentelemetry.io/proto/otlp v1.10.0 h1:IQRWgT5srOCYfiWnpqUYz9CVmbO8bFmKcwYxpuCSL2g=
+go.opentelemetry.io/proto/otlp v1.10.0/go.mod h1:/CV4QoCR/S9yaPj8utp3lvQPoqMtxXdzn7ozvvozVqk=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
-go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=
-go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8=
+go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
+go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
 go4.org/mem v0.0.0-20240501181205-ae6ca9944745 h1:Tl++JLUCe4sxGu8cTpDzRLd3tN7US4hOxG5YpKCzkek=
@@ -539,43 +531,39 @@ go4.org/netipx v0.0.0-20231129151722-fdeea329fbba/go.mod h1:PLyyIXexvUFg3Owu6p/W
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
-golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
-golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
-golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 h1:jiDhWWeC7jfWqR9c/uplMOqJ0sbNlNWv0UkzE0vX1MA=
-golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90/go.mod h1:xE1HEv6b+1SCZ5/uscMRjUBKtIxworgEcEi+/n9NQDQ=
-golang.org/x/exp/typeparams v0.0.0-20240314144324-c7f7c6466f7f h1:phY1HzDcf18Aq9A8KkmRtY9WvOFIxN8wgfvy6Zm1DV8=
-golang.org/x/exp/typeparams v0.0.0-20240314144324-c7f7c6466f7f/go.mod h1:AbB0pIl9nAr9wVwH+Z2ZpaocVmF5I4GyWCDIsVjR0bk=
-golang.org/x/image v0.27.0 h1:C8gA4oWU/tKkdCfYT6T2u4faJu3MeNS5O8UPWlPF61w=
-golang.org/x/image v0.27.0/go.mod h1:xbdrClrAUway1MUTEZDq9mz/UpRwYAkFFNUslZtcB+g=
+golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
+golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
+golang.org/x/exp v0.0.0-20260603202125-055de637280b h1:v1uXiEBHo8QA0LiGCo7UgHMzHT4Kdfpl2zmtH5vaP1Q=
+golang.org/x/exp v0.0.0-20260603202125-055de637280b/go.mod h1:d2fgXJLVs4dYDHUk5lwMIfzRzSrWCfGZb0ZqeLa/Vcw=
+golang.org/x/exp/typeparams v0.0.0-20260603202125-055de637280b h1:E7MAoHE/7prIY6tu29UATfH3hVHv6IWqOchjE48pTAU=
+golang.org/x/exp/typeparams v0.0.0-20260603202125-055de637280b/go.mod h1:PqrXSW65cXDZH0k4IeUbhmg/bcAZDbzNz3byBpKCsXo=
+golang.org/x/image v0.41.0 h1:8wS72eGJMJaBxK6okTzd4WaXumUlTVlb753MlsSvTCo=
+golang.org/x/image v0.41.0/go.mod h1:uIc348UZMSvS5Z65CVZ7iDPaNobNFEPeJ4kbqTOszmA=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
-golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
-golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
+golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4=
+golang.org/x/mod v0.36.0/go.mod h1:moc6ELqsWcOw5Ef3xVprK5ul/MvtVvkIXLziUOICjUQ=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
 golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
 golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
-golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
-golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20211007075335-d3039528d8ac/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20211013075003-97ac67df715c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20220319134239-a9b59b0215f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
@@ -583,33 +571,31 @@ golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
-golang.org/x/term v0.0.0-20210220032956-6a3ed077a48d/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
-golang.org/x/term v0.0.0-20210615171337-6886f2dfbf5b/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
 golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
 golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
-golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY=
-golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
+golang.org/x/term v0.44.0 h1:0rLvDRCtNj0gZkyIXhCyOb2OAzEhLVqc4B+hrsBhrmc=
+golang.org/x/term v0.44.0/go.mod h1:7ze4MdzUzLXpSAoFP1H0bOI9aXDqveSvatT5vKcFh2Y=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
 golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
-golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
-golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
+golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
-golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
-golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
+golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8=
+golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 h1:B82qJJgjvYKsXS9jeunTOisW56dUokqW/FOteYJJ/yg=
 golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2/go.mod h1:deeaetjYA+DHMHg+sMSMI58GrEteJUUzzw7en6TJQcI=
@@ -617,22 +603,21 @@ golang.zx2c4.com/wireguard/windows v0.5.3 h1:On6j2Rpn3OEMXqBq00QEDC7bWSZrPIHKIus
 golang.zx2c4.com/wireguard/windows v0.5.3/go.mod h1:9TEe8TJmtwyQebdFwAkEWOPr3prrtqm+REGFifP60hI=
 gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
 gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
-google.golang.org/genproto/googleapis/api v0.0.0-20260406210006-6f92a3bedf2d h1:/aDRtSZJjyLQzm75d+a1wOJaqyKBMvIAfeQmoa3ORiI=
-google.golang.org/genproto/googleapis/api v0.0.0-20260406210006-6f92a3bedf2d/go.mod h1:etfGUgejTiadZAUaEP14NP97xi1RGeawqkjDARA/UOs=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 h1:m8qni9SQFH0tJc1X0vmnpw/0t+AImlSvp30sEupozUg=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
-google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
+google.golang.org/genproto/googleapis/api v0.0.0-20260610212136-7ab31c22f7ad h1:3iLyITS/sySRwbUKoC7ogfj2Yr1Cjs0pfaRKj5U5HEw=
+google.golang.org/genproto/googleapis/api v0.0.0-20260610212136-7ab31c22f7ad/go.mod h1:KdNqO+rCIWgFumrNBSEDlDNrkrQnpkax7Tv1WxNY8V4=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa h1:mZHHdPZl0dbGHCflZgAq/Q468DWVFcU2whhB2KAo8fk=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.81.1 h1:VnnIIZ88UzOOKLukQi+ImGz8O1Wdp8nAGGnvOfEIWQQ=
+google.golang.org/grpc v1.81.1/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
-gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
-gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gorm.io/driver/postgres v1.6.0 h1:2dxzU8xJ+ivvqTRph34QX+WrRaJlmfyPqXmoGVjMBa4=
@@ -647,10 +632,12 @@ honnef.co/go/tools v0.7.0 h1:w6WUp1VbkqPEgLz4rkBzH/CSU6HkoqNLp6GstyTx3lU=
 honnef.co/go/tools v0.7.0/go.mod h1:pm29oPxeP3P82ISxZDgIYeOaf9ta6Pi0EWvCFoLG2vc=
 howett.net/plist v1.0.0 h1:7CrbWYbPPO/PyNy38b2EB/+gYbjCe2DXBxgtOOZbSQM=
 howett.net/plist v1.0.0/go.mod h1:lqaXoTrLY4hg8tnEzNru53gicrbv7rrk+2xJA/7hw9g=
-modernc.org/cc/v4 v4.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=
-modernc.org/cc/v4 v4.27.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
-modernc.org/ccgo/v4 v4.32.0 h1:hjG66bI/kqIPX1b2yT6fr/jt+QedtP2fqojG2VrFuVw=
-modernc.org/ccgo/v4 v4.32.0/go.mod h1:6F08EBCx5uQc38kMGl+0Nm0oWczoo1c7cgpzEry7Uc0=
+k8s.io/client-go v0.34.0 h1:YoWv5r7bsBfb0Hs2jh8SOvFbKzzxyNo0nSb0zC19KZo=
+k8s.io/client-go v0.34.0/go.mod h1:ozgMnEKXkRjeMvBZdV1AijMHLTh3pbACPvK7zFR+QQY=
+modernc.org/cc/v4 v4.28.2 h1:3tQ0lf2ADtoby2EtSP+J7IE2SHwEJdP8ioR59wx7XpY=
+modernc.org/cc/v4 v4.28.2/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/ccgo/v4 v4.34.0 h1:yRLPFZieg532OT4rp4JFNIVcquwalMX26G95WQDqwCQ=
+modernc.org/ccgo/v4 v4.34.0/go.mod h1:AS5WYMyBakQ+fhsHhtP8mWB82KTGPkNNJDGfGQCe0/A=
 modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
 modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
 modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
@@ -659,27 +646,29 @@ modernc.org/gc/v3 v3.1.2 h1:ZtDCnhonXSZexk/AYsegNRV1lJGgaNZJuKjJSWKyEqo=
 modernc.org/gc/v3 v3.1.2/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
 modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
 modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
-modernc.org/libc v1.70.0 h1:U58NawXqXbgpZ/dcdS9kMshu08aiA6b7gusEusqzNkw=
-modernc.org/libc v1.70.0/go.mod h1:OVmxFGP1CI/Z4L3E0Q3Mf1PDE0BucwMkcXjjLntvHJo=
+modernc.org/libc v1.72.3 h1:ZnDF4tXn4NBXFutMMQC4vtbTFSXhhKzR73fv0beZEAU=
+modernc.org/libc v1.72.3/go.mod h1:dn0dZNnnn1clLyvRxLxYExxiKRZIRENOfqQ8XEeg4Qs=
 modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
 modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
 modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
 modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
-modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
-modernc.org/opt v0.1.4/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
 modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
 modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
-modernc.org/sqlite v1.48.2 h1:5CnW4uP8joZtA0LedVqLbZV5GD7F/0x91AXeSyjoh5c=
-modernc.org/sqlite v1.48.2/go.mod h1:hWjRO6Tj/5Ik8ieqxQybiEOUXy0NJFNp2tpvVpKlvig=
+modernc.org/sqlite v1.52.0 h1:p4dhYh2tXZCiyaqHwRVJDjIGKWyXayiQpThxgDzJaxo=
+modernc.org/sqlite v1.52.0/go.mod h1:tcNzv5p84E0skkmJn038y+hWJbLQXQqEnQfeh5r2JLM=
 modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
 modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
 modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
 modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
-pgregory.net/rapid v1.2.0 h1:keKAYRcjm+e1F0oAuU5F5+YPAWcyxNNRK2wud503Gnk=
-pgregory.net/rapid v1.2.0/go.mod h1:PY5XlDGj0+V1FCq0o192FdRhpKHGTRIWBgqjDBTrq04=
+pgregory.net/rapid v1.3.0 h1:vBvO0VSqti75J1jjYqpgPNBLKMd1+gxa9fYo7vk/Exc=
+pgregory.net/rapid v1.3.0/go.mod h1:dPlE4OBBxgXPqkP79flB6sJL1dx5azpI7HQ9MY9Z7uk=
+sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=
+sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=
 software.sslmate.com/src/go-pkcs12 v0.4.0 h1:H2g08FrTvSFKUj+D309j1DPfk5APnIdAQAB8aEykJ5k=
 software.sslmate.com/src/go-pkcs12 v0.4.0/go.mod h1:Qiz0EyvDRJjjxGyUQa2cCNZn/wMyzrRJ/qcDXOQazLI=
-tailscale.com v1.96.5 h1:gNkfA/KSZAl6jCH9cj8urq00HRWItDDTtGsyATI89jA=
-tailscale.com v1.96.5/go.mod h1:/3lnZBYb2UEwnN0MNu2SDXUtT06AGd5k0s+OWx3WmcY=
+tailscale.com v1.101.0-pre h1:q1eBWxryj7Lz5fMvi7npSbN/fJ3q6/crvbbfMkx89F8=
+tailscale.com v1.101.0-pre/go.mod h1:DQ9YBy85DpNlSyeU2XRIWzbAu3RsGp/frv+Khg57meE=
 zombiezen.com/go/postgrestest v1.0.1 h1:aXoADQAJmZDU3+xilYVut0pHhgc0sF8ZspPW9gFNwP4=
 zombiezen.com/go/postgrestest v1.0.1/go.mod h1:marlZezr+k2oSJrvXHnZUs1olHqpE9czlz8ZYkVxliQ=

hscontrol/app.go

@@ -99,6 +99,10 @@ type Headscale struct {
 
 	DERPServer *derpServer.DERPServer
 
+	// realIPMiddleware is nil when cfg.TrustedProxies is empty; the
+	// router skips the mount and r.RemoteAddr stays as the TCP peer.
+	realIPMiddleware func(http.Handler) http.Handler
+
 	// Things that generate changes
 	extraRecordMan *dns.ExtraRecordsMan
 	authProvider   AuthProvider
@@ -140,6 +144,13 @@ func NewHeadscale(cfg *types.Config) (*Headscale, error) {
 		state:             s,
 	}
 
+	if len(cfg.TrustedProxies) > 0 {
+		app.realIPMiddleware, err = trustedProxyRealIP(cfg.TrustedProxies)
+		if err != nil {
+			return nil, fmt.Errorf("building trusted_proxies middleware: %w", err)
+		}
+	}
+
 	// Initialize ephemeral garbage collector
 	ephemeralGC := db.NewEphemeralGarbageCollector(func(ni types.NodeID) {
 		node, ok := app.state.GetNodeByID(ni)
@@ -208,7 +219,19 @@ func NewHeadscale(cfg *types.Config) (*Headscale, error) {
 		}
 
 		for _, d := range magicDNSDomains {
-			app.cfg.TailcfgDNSConfig.Routes[d.WithoutTrailingDot()] = nil
+			// Empty non-nil slice rather than nil: tailcfg.DNSConfig.Clone
+			// and dns.Config.Clone in tailscale drop map entries whose
+			// value is nil (see tailscale.com/tailcfg/tailcfg_clone.go and
+			// tailscale.com/net/dns/dns_clone.go: `if sv == nil { continue }`).
+			// Sending nil here caused the client's wgengine LinkChange:major
+			// handler to clobber /etc/resolv.conf on every tunnel-IP rebind
+			// — the handler reapplies a Clone of lastDNSConfig and the magic
+			// DNS routes vanish, taking the resolver with them for ~6 min
+			// until the next route-changing netmap. Empty slice survives
+			// Clone and carries the same "resolve locally" semantics
+			// (tailscale.com/ipn/ipnlocal/node_backend.go:869 documents the
+			// empty-resolver Routes form for Issue 2706).
+			app.cfg.TailcfgDNSConfig.Routes[d.WithoutTrailingDot()] = []*dnstype.Resolver{}
 		}
 	}
 
@@ -251,7 +274,7 @@ func NewHeadscale(cfg *types.Config) (*Headscale, error) {
 // Redirect to our TLS url.
 func (h *Headscale) redirect(w http.ResponseWriter, req *http.Request) {
 	target := h.cfg.ServerURL + req.URL.RequestURI()
-	http.Redirect(w, req, target, http.StatusFound)
+	http.Redirect(w, req, target, http.StatusFound) //nolint:gosec // G710: target prefixed by trusted ServerURL
 }
 
 func (h *Headscale) scheduledTasks(ctx context.Context) {
@@ -276,6 +299,31 @@ func (h *Headscale) scheduledTasks(ctx context.Context) {
 		extraRecordsUpdate = make(chan []tailcfg.DNSRecord)
 	}
 
+	var (
+		haProber     *state.HAHealthProber
+		haHealthChan <-chan time.Time
+	)
+	if h.cfg.Node.Routes.HA.ProbeInterval > 0 {
+		haProber = state.NewHAHealthProber(
+			h.state,
+			h.cfg.Node.Routes.HA,
+			h.cfg.ServerURL,
+			h.mapBatcher.IsConnected,
+		)
+
+		haTicker := time.NewTicker(h.cfg.Node.Routes.HA.ProbeInterval)
+		defer haTicker.Stop()
+
+		haHealthChan = haTicker.C
+
+		log.Info().
+			Dur("interval", h.cfg.Node.Routes.HA.ProbeInterval).
+			Dur("timeout", h.cfg.Node.Routes.HA.ProbeTimeout).
+			Msg("HA subnet router health probing enabled")
+	} else {
+		haHealthChan = make(<-chan time.Time)
+	}
+
 	for {
 		select {
 		case <-ctx.Done():
@@ -329,9 +377,12 @@ func (h *Headscale) scheduledTasks(ctx context.Context) {
 				continue
 			}
 
-			h.cfg.TailcfgDNSConfig.ExtraRecords = records
+			h.cfg.SetExtraRecords(records)
 
 			h.Change(change.ExtraRecords())
+
+		case <-haHealthChan:
+			haProber.ProbeOnce(ctx, h.Change)
 		}
 	}
 }
@@ -460,6 +511,20 @@ func (h *Headscale) ensureUnixSocketIsAbsent() error {
 	return os.Remove(h.cfg.UnixSocket)
 }
 
+// securityHeaders sets baseline response headers on every HTTP response:
+// deny framing (clickjacking), forbid MIME-type sniffing, drop the Referer
+// header on outbound navigation. Cheap defense-in-depth for HTML surfaces.
+func securityHeaders(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		h := w.Header()
+		h.Set("X-Frame-Options", "DENY")
+		h.Set("Content-Security-Policy", "frame-ancestors 'none'")
+		h.Set("X-Content-Type-Options", "nosniff")
+		h.Set("Referrer-Policy", "no-referrer")
+		next.ServeHTTP(w, r)
+	})
+}
+
 func (h *Headscale) createRouter(grpcMux *grpcRuntime.ServeMux) *chi.Mux {
 	r := chi.NewRouter()
 	r.Use(metrics.Collector(metrics.CollectorOpts{
@@ -470,10 +535,20 @@ func (h *Headscale) createRouter(grpcMux *grpcRuntime.ServeMux) *chi.Mux {
 		},
 	}))
 	r.Use(middleware.RequestID)
-	r.Use(middleware.RealIP)
+
+	if h.realIPMiddleware != nil {
+		r.Use(h.realIPMiddleware)
+	}
+
 	r.Use(middleware.RequestLogger(&zerologRequestLogger{}))
 	r.Use(middleware.Recoverer)
+	r.Use(securityHeaders)
 
+	// TS2021 accepts both the native client's HTTP POST upgrade and the
+	// browser/WASM client's WebSocket GET upgrade; NoiseUpgradeHandler
+	// dispatches on the Upgrade header, not the method. Registering GET as
+	// well keeps the router from rejecting the WebSocket handshake with 405.
+	r.Get(ts2021UpgradePath, h.NoiseUpgradeHandler)
 	r.Post(ts2021UpgradePath, h.NoiseUpgradeHandler)
 
 	r.Get("/robots.txt", h.RobotsHandler)
@@ -509,6 +584,10 @@ func (h *Headscale) createRouter(grpcMux *grpcRuntime.ServeMux) *chi.Mux {
 		r.Use(h.httpAuthenticationMiddleware)
 		r.HandleFunc("/v1/*", grpcMux.ServeHTTP)
 	})
+	// Ping response endpoint: receives HEAD from clients responding
+	// to a [tailcfg.PingRequest]. The unguessable ping ID serves as authentication.
+	r.Head("/machine/ping-response", h.PingResponseHandler)
+
 	r.Get("/favicon.ico", FaviconHandler)
 	r.Get("/", BlankHandler)
 
@@ -593,7 +672,7 @@ func (h *Headscale) Serve() error {
 			return fmt.Errorf("setting up extrarecord manager: %w", err)
 		}
 
-		h.cfg.TailcfgDNSConfig.ExtraRecords = h.extraRecordMan.Records()
+		h.cfg.SetExtraRecords(h.extraRecordMan.Records())
 
 		go h.extraRecordMan.Run()
 		defer h.extraRecordMan.Close()
@@ -1070,7 +1149,7 @@ func (h *Headscale) Change(cs ...change.Change) {
 	h.mapBatcher.AddWork(cs...)
 }
 
-// HTTPHandler returns an http.Handler for the Headscale control server.
+// HTTPHandler returns an [http.Handler] for the [Headscale] control server.
 // The handler serves the Tailscale control protocol including the /key
 // endpoint and /ts2021 Noise upgrade path.
 func (h *Headscale) HTTPHandler() http.Handler {
@@ -1109,6 +1188,11 @@ func (h *Headscale) StartBatcherForTest(tb testing.TB) {
 	tb.Cleanup(func() { h.mapBatcher.Close() })
 }
 
+// MapBatcher returns the map response batcher (for test use).
+func (h *Headscale) MapBatcher() *mapper.Batcher {
+	return h.mapBatcher
+}
+
 // StartEphemeralGCForTest starts the ephemeral node garbage collector.
 // It registers a cleanup function on tb to stop the collector.
 // It panics when called outside of tests.
@@ -1145,7 +1229,7 @@ func (l *acmeLogger) RoundTrip(req *http.Request) (*http.Response, error) {
 	return resp, nil
 }
 
-// zerologRequestLogger implements chi's middleware.LogFormatter
+// [zerologRequestLogger] implements chi's [middleware.LogFormatter]
 // to route HTTP request logs through zerolog.
 type zerologRequestLogger struct{}
 

hscontrol/app_test.go

@@ -0,0 +1,26 @@
+package hscontrol
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestSecurityHeaders(t *testing.T) {
+	handler := securityHeaders(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/", nil)
+	handler.ServeHTTP(rec, req)
+
+	h := rec.Result().Header
+	assert.Equal(t, "DENY", h.Get("X-Frame-Options"))
+	assert.Equal(t, "frame-ancestors 'none'", h.Get("Content-Security-Policy"))
+	assert.Equal(t, "nosniff", h.Get("X-Content-Type-Options"))
+	assert.Equal(t, "no-referrer", h.Get("Referrer-Policy"))
+}

hscontrol/assets/style.css

@@ -11,11 +11,46 @@
   --md-typeset-a-color: var(--md-primary-fg-color);
   --md-text-font: "Roboto", -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif;
   --md-code-font: "Roboto Mono", "SF Mono", Monaco, "Cascadia Code", Consolas, "Courier New", monospace;
+  --hs-success: #059669;
+  --hs-success-bg: #d1fae5;
+  --hs-error: #dc2626;
+  --hs-error-bg: #fee2e2;
+  --hs-warning-text: #92400e;
+  --hs-warning-bg: #fef3c7;
+  --hs-warning-border: #f59e0b;
+  --hs-border: #e5e7eb;
+  --hs-bg: #ffffff;
+  --hs-focus-ring: #4051b5;
 }
 
-/* Base Typography */
+/* Dark mode */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --md-default-fg-color: rgba(255, 255, 255, 0.87);
+    --md-default-fg-color--light: rgba(255, 255, 255, 0.6);
+    --md-default-fg-color--lighter: rgba(255, 255, 255, 0.38);
+    --md-default-fg-color--lightest: rgba(255, 255, 255, 0.07);
+    --md-code-fg-color: #c9d1d9;
+    --md-code-bg-color: #1e1e1e;
+    --md-primary-fg-color: #7b8fdb;
+    --md-accent-fg-color: #8fa4ff;
+    --md-typeset-a-color: var(--md-primary-fg-color);
+    --hs-success: #34d399;
+    --hs-success-bg: #064e3b;
+    --hs-error: #f87171;
+    --hs-error-bg: #450a0a;
+    --hs-warning-text: #fbbf24;
+    --hs-warning-bg: #451a03;
+    --hs-warning-border: #d97706;
+    --hs-border: #374151;
+    --hs-bg: #111827;
+    --hs-focus-ring: #7b8fdb;
+  }
+}
+
+/* Base Typography - 1rem (16px) avoids iOS auto-zoom on inputs */
 .md-typeset {
-  font-size: 0.8rem;
+  font-size: 1rem;
   line-height: 1.6;
   color: var(--md-default-fg-color);
   font-family: var(--md-text-font);
@@ -76,16 +111,33 @@
   padding-left: 2em;
 }
 
-/* Links */
+.md-typeset li {
+  margin-bottom: 0.25em;
+}
+
+/* Links - underline for accessibility (don't rely on color alone) */
 .md-typeset a {
   color: var(--md-typeset-a-color);
-  text-decoration: none;
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 2px;
   word-break: break-word;
+  cursor: pointer;
 }
 
 .md-typeset a:hover,
 .md-typeset a:focus {
   color: var(--md-accent-fg-color);
+  text-decoration-thickness: 2px;
+}
+
+/* Focus styles - visible ring for keyboard navigation */
+.md-typeset a:focus-visible,
+button:focus-visible,
+input:focus-visible {
+  outline: 2px solid var(--hs-focus-ring);
+  outline-offset: 2px;
+  border-radius: 2px;
 }
 
 /* Code (inline) */
@@ -118,6 +170,7 @@
   overflow-wrap: break-word;
   word-wrap: break-word;
   white-space: pre-wrap;
+  border-radius: 0.25rem;
 }
 
 /* Links in code */
@@ -125,6 +178,36 @@
   color: currentcolor;
 }
 
+/* Buttons - styled via CSS for hover/active/focus pseudo-classes */
+.md-typeset button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.75rem 1.5rem;
+  font-size: 1rem;
+  font-weight: 500;
+  font-family: var(--md-text-font);
+  line-height: 1;
+  color: #ffffff;
+  background-color: var(--md-primary-fg-color);
+  border: none;
+  border-radius: 0.375rem;
+  cursor: pointer;
+  min-height: 44px;
+  transition:
+    background-color 150ms ease-out,
+    box-shadow 150ms ease-out;
+}
+
+.md-typeset button:hover {
+  background-color: var(--md-accent-fg-color);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12);
+}
+
+.md-typeset button:active {
+  transform: translateY(1px);
+}
+
 /* Logo */
 .headscale-logo {
   display: block;
@@ -138,6 +221,17 @@
 @media (max-width: 768px) {
   .headscale-logo {
     width: 200px;
-    margin-left: 0;
+  }
+}
+
+/* Reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
   }
 }

hscontrol/auth.go

@@ -10,7 +10,6 @@ import (
 	"time"
 
 	"github.com/juanfont/headscale/hscontrol/types"
-	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/rs/zerolog/log"
 	"gorm.io/gorm"
 	"tailscale.com/tailcfg"
@@ -74,8 +73,8 @@ func (h *Headscale) handleRegister(
 			// the Noise session's machine key matches the cached node.
 			// Without this check anyone holding a target's NodeKey could
 			// open a Noise session with a throwaway machine key and read
-			// the owner's User/Login back through nodeToRegisterResponse.
-			// handleLogout enforces the same check on its own path.
+			// the owner's User/Login back through [nodeToRegisterResponse].
+			// [Headscale.handleLogout] enforces the same check on its own path.
 			if node.MachineKey() != machineKey {
 				return nil, NewHTTPError(
 					http.StatusUnauthorized,
@@ -84,10 +83,9 @@ func (h *Headscale) handleRegister(
 				)
 			}
 
-			// When tailscaled restarts, it sends RegisterRequest with Auth=nil and Expiry=zero.
+			// When tailscaled restarts, it sends [tailcfg.RegisterRequest] with Auth=nil and Expiry=zero.
 			// Return the current node state without modification.
-			// See: https://github.com/juanfont/headscale/issues/2862
-			if req.Expiry.IsZero() && node.Expiry().Valid() && !node.IsExpired() {
+			if req.Expiry.IsZero() && !node.IsExpired() {
 				return nodeToRegisterResponse(node), nil
 			}
 
@@ -193,7 +191,7 @@ func (h *Headscale) handleLogout(
 	}
 
 	// If the request expiry is in the past, we consider it a logout.
-	// Zero expiry is handled in handleRegister() before calling this function.
+	// Zero expiry is handled in [Headscale.handleRegister] before calling this function.
 	if req.Expiry.Before(time.Now()) {
 		log.Debug().
 			EmbedObject(node).
@@ -227,7 +225,16 @@ func (h *Headscale) handleLogout(
 
 	// Update the internal state with the nodes new expiry, meaning it is
 	// logged out.
+	//
+	// Clamp the client-supplied value to now: Tailscale sends the
+	// sentinel time.Unix(123, 0) on logout (controlclient/direct.go),
+	// and storing it verbatim propagates a 1970 KeyExpiry to every
+	// peer's netmap. Semantically identical (expired as of now), but
+	// sane in logs, debug dumps, and peer netmaps.
 	expiry := req.Expiry
+	if now := time.Now(); expiry.Before(now) {
+		expiry = now
+	}
 
 	updatedNode, c, err := h.state.SetNodeExpiry(node.ID(), &expiry)
 	if err != nil {
@@ -255,7 +262,7 @@ func nodeToRegisterResponse(node types.NodeView) *tailcfg.RegisterResponse {
 		MachineAuthorized: true,
 	}
 
-	// For tagged nodes, use the TaggedDevices special user
+	// For tagged nodes, use the [types.TaggedDevices] special user
 	// For user-owned nodes, include User and Login information from the actual user
 	if node.IsTagged() {
 		resp.User = types.TaggedDevices.View().TailscaleUser()
@@ -304,8 +311,8 @@ func (h *Headscale) waitForFollowup(
 }
 
 // reqToNewRegisterResponse refreshes the registration flow by creating a new
-// registration ID and returning the corresponding AuthURL so the client can
-// restart the authentication process.
+// registration ID and returning the corresponding [tailcfg.RegisterResponse.AuthURL]
+// so the client can restart the authentication process.
 func (h *Headscale) reqToNewRegisterResponse(
 	req tailcfg.RegisterRequest,
 	machineKey key.MachinePublic,
@@ -327,8 +334,8 @@ func (h *Headscale) reqToNewRegisterResponse(
 	}, nil
 }
 
-// registrationDataFromRequest builds the RegistrationData payload stored
-// in the auth cache for a pending registration. The original Hostinfo is
+// registrationDataFromRequest builds the [types.RegistrationData] payload stored
+// in the auth cache for a pending registration. The original [tailcfg.Hostinfo] is
 // retained so that consumers (auth callback, observability) see the
 // fields the client originally announced; the bounded-LRU cap on the
 // cache is what bounds the unauthenticated cache-fill DoS surface.
@@ -336,11 +343,10 @@ func registrationDataFromRequest(
 	req tailcfg.RegisterRequest,
 	machineKey key.MachinePublic,
 ) *types.RegistrationData {
-	hostname := util.EnsureHostname(
-		req.Hostinfo.View(),
-		machineKey.String(),
-		req.NodeKey.String(),
-	)
+	var hostname string
+	if req.Hostinfo != nil {
+		hostname = req.Hostinfo.Hostname
+	}
 
 	regData := &types.RegistrationData{
 		MachineKey: machineKey,

hscontrol/auth_tags_test.go

@@ -1,6 +1,7 @@
 package hscontrol
 
 import (
+	"context"
 	"testing"
 	"time"
 
@@ -59,7 +60,7 @@ func createTestAppWithNodeExpiry(t *testing.T, nodeExpiry time.Duration) *Headsc
 // a tagged node with:
 // - Tags from the PreAuthKey
 // - Nil UserID (tagged nodes are owned by tags, not a user)
-// - IsTagged() returns true.
+// - [types.Node.IsTagged] returns true.
 func TestTaggedPreAuthKeyCreatesTaggedNode(t *testing.T) {
 	app := createTestApp(t)
 
@@ -112,7 +113,7 @@ func TestTaggedPreAuthKeyCreatesTaggedNode(t *testing.T) {
 // authentication. This is critical for the container restart scenario (#2830).
 //
 // NOTE: This test verifies that re-authentication preserves the node's current tags
-// without testing tag modification via SetNodeTags (which requires ACL policy setup).
+// without testing tag modification via [state.State.SetNodeTags] (which requires ACL policy setup).
 func TestReAuthDoesNotReapplyTags(t *testing.T) {
 	app := createTestApp(t)
 
@@ -179,7 +180,7 @@ func TestReAuthDoesNotReapplyTags(t *testing.T) {
 }
 
 // NOTE: TestSetTagsOnUserOwnedNode functionality is covered by gRPC tests in grpcv1_test.go
-// which properly handle ACL policy setup. The test verifies that SetTags can convert
+// which properly handle ACL policy setup. The test verifies that [headscaleV1APIServer.SetTags] can convert
 // user-owned nodes to tagged nodes while preserving UserID.
 
 // TestCannotRemoveAllTags tests that attempting to remove all tags from a
@@ -669,10 +670,151 @@ func TestTaggedNodeReauthPreservesDisabledExpiry(t *testing.T) {
 		"Tagged node should have expiry PRESERVED as disabled after re-auth")
 }
 
+// TestTaggedNodeRestartPreservesNilExpiry tests that a tagged node whose
+// tailscaled restarts (sending Auth=nil, Expiry=zero) keeps its nil expiry.
+//
+// The handleRegister guard required node.Expiry().Valid(), false for the
+// nil expiry tagged nodes are created with. The request fell through to
+// handleLogout, which wrote &time.Time{} over the original nil and flipped
+// the API representation from null to "0001-01-01T00:00:00Z".
+func TestTaggedNodeRestartPreservesNilExpiry(t *testing.T) {
+	app := createTestApp(t)
+
+	user := app.state.CreateUserForTest("tag-restart")
+	tags := []string{"tag:agent"}
+
+	pak, err := app.state.CreatePreAuthKey(user.TypedID(), true, false, nil, tags)
+	require.NoError(t, err)
+
+	machineKey := key.NewMachine()
+	nodeKey := key.NewNode()
+
+	regReq := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pak.Key,
+		},
+		NodeKey: nodeKey.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "tagged-restart-test",
+		},
+	}
+
+	resp, err := app.handleRegisterWithAuthKey(regReq, machineKey.Public())
+	require.NoError(t, err)
+	require.True(t, resp.MachineAuthorized)
+
+	node, found := app.state.GetNodeByNodeKey(nodeKey.Public())
+	require.True(t, found)
+	require.True(t, node.IsTagged())
+	require.False(t, node.Expiry().Valid(), "tagged node should have nil expiry after registration")
+	require.False(t, node.IsExpired(), "tagged node with nil expiry should not be expired")
+
+	// tailscaled restart: RegisterRequest with Auth=nil and Expiry=time.Time{}
+	// (the Go zero value) is what the client sends when it restarts with
+	// persisted state.
+	restartReq := tailcfg.RegisterRequest{
+		Auth:    nil,
+		NodeKey: nodeKey.Public(),
+		Expiry:  time.Time{},
+	}
+
+	restartResp, err := app.handleRegister(context.Background(), restartReq, machineKey.Public())
+	require.NoError(t, err)
+
+	require.True(t, restartResp.MachineAuthorized,
+		"restart should not require re-authorization")
+	require.False(t, restartResp.NodeKeyExpired,
+		"restart should not mark node key as expired")
+	require.Equal(t, types.TaggedDevices.View().TailscaleUser(), restartResp.User,
+		"response should identify node as tagged device")
+
+	nodeAfterRestart, found := app.state.GetNodeByNodeKey(nodeKey.Public())
+	require.True(t, found)
+
+	assert.True(t, nodeAfterRestart.IsTagged(), "node should still be tagged")
+	assert.False(t, nodeAfterRestart.IsExpired(), "node should not be expired after restart")
+	assert.False(t, nodeAfterRestart.Expiry().Valid(),
+		"tagged node expiry must remain nil (not zero-time) after restart")
+
+	var dbNode types.Node
+	require.NoError(t,
+		app.state.DB().DB.First(&dbNode, nodeAfterRestart.ID().Uint64()).Error)
+	assert.Nil(t, dbNode.Expiry,
+		"database expiry column must be NULL after restart, not a pointer to zero-time")
+}
+
+// TestUntaggedNodeRestartPreservesNilExpiry tests that an untagged node
+// registered against a preauth key with no default node.expiry keeps its
+// nil expiry when tailscaled restarts. Same root cause as the tagged
+// variant: the dropped node.Expiry().Valid() check covers any nil-expiry
+// node, regardless of ownership.
+func TestUntaggedNodeRestartPreservesNilExpiry(t *testing.T) {
+	app := createTestAppWithNodeExpiry(t, 0)
+
+	user := app.state.CreateUserForTest("untagged-restart")
+
+	pak, err := app.state.CreatePreAuthKey(user.TypedID(), true, false, nil, nil)
+	require.NoError(t, err)
+
+	machineKey := key.NewMachine()
+	nodeKey := key.NewNode()
+
+	regReq := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pak.Key,
+		},
+		NodeKey: nodeKey.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "untagged-restart-test",
+		},
+		Expiry: time.Time{},
+	}
+
+	resp, err := app.handleRegisterWithAuthKey(regReq, machineKey.Public())
+	require.NoError(t, err)
+	require.True(t, resp.MachineAuthorized)
+
+	node, found := app.state.GetNodeByNodeKey(nodeKey.Public())
+	require.True(t, found)
+	require.False(t, node.IsTagged(), "node should be user-owned, not tagged")
+	require.False(t, node.Expiry().Valid(),
+		"untagged node with no default expiry should have nil expiry after registration")
+	require.False(t, node.IsExpired())
+
+	restartReq := tailcfg.RegisterRequest{
+		Auth:    nil,
+		NodeKey: nodeKey.Public(),
+		Expiry:  time.Time{},
+	}
+
+	restartResp, err := app.handleRegister(context.Background(), restartReq, machineKey.Public())
+	require.NoError(t, err)
+
+	require.True(t, restartResp.MachineAuthorized,
+		"restart should not require re-authorization")
+	require.False(t, restartResp.NodeKeyExpired,
+		"restart should not mark node key as expired")
+
+	nodeAfterRestart, found := app.state.GetNodeByNodeKey(nodeKey.Public())
+	require.True(t, found)
+
+	assert.False(t, nodeAfterRestart.IsTagged(), "node should still be user-owned")
+	assert.False(t, nodeAfterRestart.IsExpired(), "node should not be expired after restart")
+	assert.False(t, nodeAfterRestart.Expiry().Valid(),
+		"untagged node expiry must remain nil (not zero-time) after restart")
+
+	var dbNode types.Node
+	require.NoError(t,
+		app.state.DB().DB.First(&dbNode, nodeAfterRestart.ID().Uint64()).Error)
+	assert.Nil(t, dbNode.Expiry,
+		"database expiry column must be NULL after restart, not a pointer to zero-time "+
+			"(this is what `sqlite3 ... 'select expiry from nodes'` sees)")
+}
+
 // TestExpiryDuringPersonalToTaggedConversion tests that when a personal node
 // is converted to tagged via reauth with RequestTags, the expiry is cleared to nil.
-// BUG #3048: Previously expiry was NOT cleared because expiry handling ran
-// BEFORE processReauthTags.
+// Previously expiry was NOT cleared because expiry handling ran
+// BEFORE [state.State.processReauthTags].
 func TestExpiryDuringPersonalToTaggedConversion(t *testing.T) {
 	app := createTestApp(t)
 	user := app.state.CreateUserForTest("expiry-test-user")
@@ -744,8 +886,8 @@ func TestExpiryDuringPersonalToTaggedConversion(t *testing.T) {
 // TestExpiryDuringTaggedToPersonalConversion tests that when a tagged node
 // is converted to personal via reauth with empty RequestTags, expiry is set
 // from the client request.
-// BUG #3048: Previously expiry was NOT set because expiry handling ran
-// BEFORE processReauthTags (node was still tagged at check time).
+// Previously expiry was NOT set because expiry handling ran
+// BEFORE [state.State.processReauthTags] (node was still tagged at check time).
 func TestExpiryDuringTaggedToPersonalConversion(t *testing.T) {
 	app := createTestApp(t)
 	user := app.state.CreateUserForTest("expiry-test-user2")
@@ -866,16 +1008,24 @@ func TestReAuthWithDifferentMachineKey(t *testing.T) {
 		Expiry: time.Now().Add(24 * time.Hour),
 	}
 
-	resp2, err := app.handleRegisterWithAuthKey(regReq2, machineKey2.Public())
-	require.NoError(t, err)
-	require.True(t, resp2.MachineAuthorized)
+	// A NodeKey is bound 1:1 to a MachineKey (getAndValidateNode enforces
+	// this at poll time). A different machine claiming an existing NodeKey is
+	// a hijack: it would poison the NodeStore NodeKey index so the original
+	// node fails the poll-time MachineKey check and is denied service.
+	// Registration now rejects it (see f8f08cf7). Real Tailscale clients
+	// never reuse a NodeKey across machine keys, so no legitimate flow is
+	// affected.
+	_, err = app.handleRegisterWithAuthKey(regReq2, machineKey2.Public())
+	require.Error(t, err,
+		"a different machine claiming an existing NodeKey must be rejected")
 
-	// Verify the node still exists and has tags
-	// Note: Depending on implementation, this might be the same node or a new node
+	// The original node is unaffected: still present, tagged, same identity.
 	node2, found := app.state.GetNodeByNodeKey(nodeKey.Public())
 	require.True(t, found)
 	assert.True(t, node2.IsTagged())
 	assert.ElementsMatch(t, tags, node2.Tags().AsSlice())
+	assert.Equal(t, node1.ID(), node2.ID(),
+		"original node must survive; the hijacking registration was rejected")
 }
 
 // TestUntaggedAuthKeyZeroExpiryGetsDefault tests that when node.expiry is configured
@@ -1003,7 +1153,7 @@ func TestNodeExpiryZeroDisablesDefault(t *testing.T) {
 	assert.False(t, node.IsExpired(), "node should not be expired")
 
 	// With node.expiry=0 and zero client expiry, the node gets a zero expiry
-	// which IsExpired() treats as "never expires" — backwards compatible.
+	// which [types.Node.IsExpired] treats as "never expires" — backwards compatible.
 	if node.Expiry().Valid() {
 		assert.True(t, node.Expiry().Get().IsZero(),
 			"with node.expiry=0 and zero client expiry, expiry should be zero time")
@@ -1119,3 +1269,72 @@ func TestReregistrationAppliesDefaultExpiry(t *testing.T) {
 	assert.True(t, node2.Expiry().Get().After(firstExpiry),
 		"re-registration expiry should be later than initial registration expiry")
 }
+
+// TestReregistrationZeroExpiryStaysNil tests that when a user-owned node
+// re-registers with zero client expiry and node.expiry is disabled (0),
+// the node's expiry stays nil rather than being set to a pointer to zero
+// time. Regression test for the else branch introduced in commit 6337a3db
+// which assigned `&regReq.Expiry` (pointer to [time.Time]{}) instead of nil,
+// causing the database row to hold `0001-01-01 00:00:00` instead of NULL.
+//
+// The same !regReq.Expiry.IsZero() gate at state.go:2221-2228 is shared by
+// the tags-only PreAuthKey path ([state.State.createAndSaveNewNode] also receives nil
+// when the client sends zero expiry), so this regression is covered for
+// tagged nodes by inspection.
+func TestReregistrationZeroExpiryStaysNil(t *testing.T) {
+	t.Parallel()
+
+	// node.expiry = 0 means "no default expiry"
+	app := createTestAppWithNodeExpiry(t, 0)
+
+	user := app.state.CreateUserForTest("node-owner")
+
+	pak, err := app.state.CreatePreAuthKey(user.TypedID(), true, false, nil, nil)
+	require.NoError(t, err)
+
+	machineKey := key.NewMachine()
+	nodeKey := key.NewNode()
+
+	// Initial registration with zero client expiry
+	regReq := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pak.Key,
+		},
+		NodeKey: nodeKey.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "reregister-zero-expiry",
+		},
+		Expiry: time.Time{},
+	}
+
+	resp, err := app.handleRegisterWithAuthKey(regReq, machineKey.Public())
+	require.NoError(t, err)
+	require.True(t, resp.MachineAuthorized)
+
+	node, found := app.state.GetNodeByNodeKey(nodeKey.Public())
+	require.True(t, found)
+	assert.False(t, node.Expiry().Valid(),
+		"initial registration with zero expiry and no default should leave expiry nil")
+
+	// Re-register with a new node key but same machine key + user
+	nodeKey2 := key.NewNode()
+	regReq2 := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pak.Key,
+		},
+		NodeKey: nodeKey2.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "reregister-zero-expiry",
+		},
+		Expiry: time.Time{}, // still zero
+	}
+
+	resp2, err := app.handleRegisterWithAuthKey(regReq2, machineKey.Public())
+	require.NoError(t, err)
+	require.True(t, resp2.MachineAuthorized)
+
+	node2, found := app.state.GetNodeByNodeKey(nodeKey2.Public())
+	require.True(t, found)
+	assert.False(t, node2.Expiry().Valid(),
+		"re-registration with zero client expiry and no default should leave expiry nil, not pointer to zero time")
+}

hscontrol/auth_test.go

@@ -31,7 +31,7 @@ type interactiveStep struct {
 	stepType         string // stepTypeInitialRequest, stepTypeAuthCompletion, or stepTypeFollowupRequest
 	expectAuthURL    bool
 	expectCacheEntry bool
-	callAuthPath     bool // Real call to HandleNodeFromAuthPath, not mocked
+	callAuthPath     bool // Real call to [state.State.HandleNodeFromAuthPath], not mocked
 }
 
 //nolint:gocyclo // comprehensive test function with many scenarios
@@ -140,7 +140,7 @@ func TestAuthenticationFlows(t *testing.T) {
 					return "", err
 				}
 
-				// Wait for node to be available in NodeStore
+				// Wait for node to be available in [state.NodeStore]
 				require.EventuallyWithT(t, func(c *assert.CollectT) {
 					_, found := app.state.GetNodeByNodeKey(nodeKey1.Public())
 					assert.True(c, found, "node should be available in NodeStore")
@@ -209,7 +209,7 @@ func TestAuthenticationFlows(t *testing.T) {
 					return "", err
 				}
 
-				// Wait for node to be available in NodeStore
+				// Wait for node to be available in [state.NodeStore]
 				require.EventuallyWithT(t, func(c *assert.CollectT) {
 					_, found := app.state.GetNodeByNodeKey(nodeKey1.Public())
 					assert.True(c, found, "node should be available in NodeStore")
@@ -409,7 +409,7 @@ func TestAuthenticationFlows(t *testing.T) {
 
 				t.Logf("Setup registered node: %+v", resp)
 
-				// Wait for node to be available in NodeStore with debug info
+				// Wait for node to be available in [state.NodeStore] with debug info
 				var attemptCount int
 
 				require.EventuallyWithT(t, func(c *assert.CollectT) {
@@ -470,7 +470,7 @@ func TestAuthenticationFlows(t *testing.T) {
 					return "", err
 				}
 
-				// Wait for node to be available in NodeStore
+				// Wait for node to be available in [state.NodeStore]
 				require.EventuallyWithT(t, func(c *assert.CollectT) {
 					_, found := app.state.GetNodeByNodeKey(nodeKey1.Public())
 					assert.True(c, found, "node should be available in NodeStore")
@@ -520,7 +520,7 @@ func TestAuthenticationFlows(t *testing.T) {
 					return "", err
 				}
 
-				// Wait for node to be available in NodeStore
+				// Wait for node to be available in [state.NodeStore]
 				require.EventuallyWithT(t, func(c *assert.CollectT) {
 					_, found := app.state.GetNodeByNodeKey(nodeKey1.Public())
 					assert.True(c, found, "node should be available in NodeStore")
@@ -637,7 +637,7 @@ func TestAuthenticationFlows(t *testing.T) {
 					return "", err
 				}
 
-				// Wait for node to be available in NodeStore
+				// Wait for node to be available in [state.NodeStore]
 				require.EventuallyWithT(t, func(c *assert.CollectT) {
 					_, found := app.state.GetNodeByNodeKey(nodeKey1.Public())
 					assert.True(c, found, "node should be available in NodeStore")
@@ -687,7 +687,7 @@ func TestAuthenticationFlows(t *testing.T) {
 				app.state.SetAuthCacheEntry(regID, nodeToRegister)
 
 				// Simulate successful registration
-				// handleRegister will receive the value when it starts waiting
+				// [Headscale.handleRegister] will receive the value when it starts waiting
 				go func() {
 					user := app.state.CreateUserForTest("followup-user")
 
@@ -816,15 +816,17 @@ func TestAuthenticationFlows(t *testing.T) {
 			validate: func(t *testing.T, resp *tailcfg.RegisterResponse, app *Headscale) { //nolint:thelper //nolint:thelper
 				assert.True(t, resp.MachineAuthorized)
 
-				// Node should be created with generated hostname
+				// Raw hostname is preserved (empty in, empty stored), and
+				// GivenName falls back to the literal "node" per SaaS.
 				node, found := app.state.GetNodeByNodeKey(nodeKey1.Public())
 				assert.True(t, found)
-				assert.NotEmpty(t, node.Hostname())
+				assert.Empty(t, node.Hostname())
+				assert.Equal(t, "node", node.GivenName())
 			},
 		},
 		// TEST: Nil hostinfo is handled with defensive code
 		// WHAT: Tests that nil hostinfo in register request is handled gracefully
-		// INPUT: Register request with Hostinfo field set to nil
+		// INPUT: Register request with [tailcfg.Hostinfo] field set to nil
 		// EXPECTED: Node registers successfully with generated hostname starting with "node-"
 		// WHY: Defensive code prevents nil pointer panics; creates valid default hostinfo
 		{
@@ -854,12 +856,12 @@ func TestAuthenticationFlows(t *testing.T) {
 			validate: func(t *testing.T, resp *tailcfg.RegisterResponse, app *Headscale) { //nolint:thelper //nolint:thelper
 				assert.True(t, resp.MachineAuthorized)
 
-				// Node should be created with generated hostname from defensive code
+				// With nil [tailcfg.Hostinfo] the raw hostname stays empty and GivenName
+				// falls back to the literal "node" per the SaaS spec.
 				node, found := app.state.GetNodeByNodeKey(nodeKey1.Public())
 				assert.True(t, found)
-				assert.NotEmpty(t, node.Hostname())
-				// Hostname should start with "node-" (generated from machine key)
-				assert.True(t, strings.HasPrefix(node.Hostname(), "node-"))
+				assert.Empty(t, node.Hostname())
+				assert.Equal(t, "node", node.GivenName())
 			},
 		},
 
@@ -952,7 +954,7 @@ func TestAuthenticationFlows(t *testing.T) {
 
 		// TEST: PreAuthKey registration rejects client-provided RequestTags
 		// WHAT: Tests that PreAuthKey registrations cannot use client-provided tags
-		// INPUT: PreAuthKey registration with RequestTags in Hostinfo
+		// INPUT: PreAuthKey registration with [tailcfg.Hostinfo.RequestTags] set
 		// EXPECTED: Registration fails with "requested tags [...] are invalid or not permitted" error
 		// WHY: PreAuthKey nodes get their tags from the key itself, not from client requests
 		{
@@ -1238,7 +1240,7 @@ func TestAuthenticationFlows(t *testing.T) {
 
 		// TEST: Zero-time expiry is handled correctly
 		// WHAT: Tests registration with expiry set to zero time value
-		// INPUT: Register request with Expiry set to time.Time{} (zero value)
+		// INPUT: Register request with Expiry set to [time.Time]{} (zero value)
 		// EXPECTED: Node registers successfully; zero time treated as no expiry
 		// WHY: Zero time is valid Go default; should be handled gracefully
 		{
@@ -1278,7 +1280,7 @@ func TestAuthenticationFlows(t *testing.T) {
 		},
 		// TEST: Malformed hostinfo with very long hostname is truncated
 		// WHAT: Tests that excessively long hostname is truncated to DNS label limit
-		// INPUT: Hostinfo with 110-character hostname (exceeds 63-char DNS limit)
+		// INPUT: [tailcfg.Hostinfo] with 110-character hostname (exceeds 63-char DNS limit)
 		// EXPECTED: Node registers successfully; hostname truncated to 63 characters
 		// WHY: Defensive code enforces DNS label limit (RFC 1123); prevents errors
 		{
@@ -1697,7 +1699,7 @@ func TestAuthenticationFlows(t *testing.T) {
 				assert.False(t, resp.NodeKeyExpired)
 
 				// Verify NEW node was created for user2
-				node2, found := app.state.GetNodeByMachineKey(machineKey1.Public(), types.UserID(2))
+				node2, found := app.state.GetNodesByMachineKeyAllUsers(machineKey1.Public())[types.UserID(2)]
 				require.True(t, found, "new node should exist for user2")
 				assert.Equal(t, uint(2), node2.UserID().Get(), "new node should belong to user2")
 
@@ -1705,7 +1707,7 @@ func TestAuthenticationFlows(t *testing.T) {
 				assert.Equal(t, "user2-context", user.Name(), "new node should show user2 username")
 
 				// Verify original node still exists for user1
-				node1, found := app.state.GetNodeByMachineKey(machineKey1.Public(), types.UserID(1))
+				node1, found := app.state.GetNodesByMachineKeyAllUsers(machineKey1.Public())[types.UserID(1)]
 				require.True(t, found, "original node should still exist for user1")
 				assert.Equal(t, uint(1), node1.UserID().Get(), "original node should still belong to user1")
 
@@ -1773,13 +1775,13 @@ func TestAuthenticationFlows(t *testing.T) {
 			validateCompleteResponse: true,
 			validate: func(t *testing.T, resp *tailcfg.RegisterResponse, app *Headscale) { //nolint:thelper
 				// User1's original node should STILL exist (not transferred)
-				node1, found1 := app.state.GetNodeByMachineKey(machineKey1.Public(), types.UserID(1))
+				node1, found1 := app.state.GetNodesByMachineKeyAllUsers(machineKey1.Public())[types.UserID(1)]
 				require.True(t, found1, "user1's original node should still exist")
 				assert.Equal(t, uint(1), node1.UserID().Get(), "user1's node should still belong to user1")
 				assert.Equal(t, nodeKey1.Public(), node1.NodeKey(), "user1's node should have original node key")
 
 				// User2 should have a NEW node created
-				node2, found2 := app.state.GetNodeByMachineKey(machineKey1.Public(), types.UserID(2))
+				node2, found2 := app.state.GetNodesByMachineKeyAllUsers(machineKey1.Public())[types.UserID(2)]
 				require.True(t, found2, "user2 should have new node created")
 				assert.Equal(t, uint(2), node2.UserID().Get(), "user2's node should belong to user2")
 
@@ -1843,7 +1845,7 @@ func TestAuthenticationFlows(t *testing.T) {
 		},
 		// TEST: Logout with expiry exactly at current time
 		// WHAT: Tests logout when expiry is set to exact current time (boundary case)
-		// INPUT: Existing node sends request with expiry=time.Now() (not past, not future)
+		// INPUT: Existing node sends request with expiry=[time.Now]() (not past, not future)
 		// EXPECTED: Node is logged out (treated as expired)
 		// WHY: Edge case: current time should be treated as expired
 		{
@@ -2223,7 +2225,7 @@ func TestAuthenticationFlows(t *testing.T) {
 		},
 		// TEST: Interactive workflow with nil hostinfo
 		// WHAT: Tests interactive registration when request has nil hostinfo
-		// INPUT: Interactive registration request with Hostinfo=nil
+		// INPUT: Interactive registration request with [tailcfg.Hostinfo]=nil
 		// EXPECTED: Node registers successfully with generated default hostname
 		// WHY: Defensive code handles nil hostinfo in interactive flow
 		{
@@ -2251,9 +2253,9 @@ func TestAuthenticationFlows(t *testing.T) {
 				assert.True(t, found, "node should be registered despite nil hostinfo")
 
 				if found {
-					// Should have some default hostname or handle nil gracefully
-					hostname := node.Hostname()
-					assert.NotEmpty(t, hostname, "should have some hostname even with nil hostinfo")
+					// Raw hostname stays empty; GivenName falls back to "node".
+					assert.Empty(t, node.Hostname())
+					assert.Equal(t, "node", node.GivenName())
 				}
 			},
 		},
@@ -2759,7 +2761,7 @@ func TestNodeStoreLookup(t *testing.T) {
 
 	t.Logf("Registered node successfully: %+v", resp)
 
-	// Wait for node to be available in NodeStore
+	// Wait for node to be available in [state.NodeStore]
 	var node types.NodeView
 
 	require.EventuallyWithT(t, func(c *assert.CollectT) {
@@ -2912,7 +2914,7 @@ func TestPreAuthKeyLogoutAndReloginDifferentUser(t *testing.T) {
 	for i := range 2 {
 		node := nodes[i]
 		// User1's original nodes should still be owned by user1
-		registeredNode, found := app.state.GetNodeByMachineKey(node.machineKey.Public(), types.UserID(user1.ID))
+		registeredNode, found := app.state.GetNodesByMachineKeyAllUsers(node.machineKey.Public())[types.UserID(user1.ID)]
 		require.True(t, found, "User1's original node %s should still exist", node.hostname)
 		require.Equal(t, user1.ID, registeredNode.UserID().Get(), "Node %s should still belong to user1", node.hostname)
 		t.Logf("✓ User1's original node %s (ID=%d) still owned by user1", node.hostname, registeredNode.ID().Uint64())
@@ -2921,7 +2923,7 @@ func TestPreAuthKeyLogoutAndReloginDifferentUser(t *testing.T) {
 	for i := 2; i < 4; i++ {
 		node := nodes[i]
 		// User2's original nodes should still be owned by user2
-		registeredNode, found := app.state.GetNodeByMachineKey(node.machineKey.Public(), types.UserID(user2.ID))
+		registeredNode, found := app.state.GetNodesByMachineKeyAllUsers(node.machineKey.Public())[types.UserID(user2.ID)]
 		require.True(t, found, "User2's original node %s should still exist", node.hostname)
 		require.Equal(t, user2.ID, registeredNode.UserID().Get(), "Node %s should still belong to user2", node.hostname)
 		t.Logf("✓ User2's original node %s (ID=%d) still owned by user2", node.hostname, registeredNode.ID().Uint64())
@@ -2933,7 +2935,7 @@ func TestPreAuthKeyLogoutAndReloginDifferentUser(t *testing.T) {
 	for i := 2; i < 4; i++ {
 		node := nodes[i]
 		// Should be able to find a node with user1 and this machine key (the new one)
-		newNode, found := app.state.GetNodeByMachineKey(node.machineKey.Public(), types.UserID(user1.ID))
+		newNode, found := app.state.GetNodesByMachineKeyAllUsers(node.machineKey.Public())[types.UserID(user1.ID)]
 		require.True(t, found, "Should have created new node for user1 with machine key from %s", node.hostname)
 		require.Equal(t, user1.ID, newNode.UserID().Get(), "New node should belong to user1")
 		t.Logf("✓ New node created for user1 with machine key from %s (ID=%d)", node.hostname, newNode.ID().Uint64())
@@ -2982,7 +2984,7 @@ func TestWebFlowReauthDifferentUser(t *testing.T) {
 	require.True(t, resp1.MachineAuthorized, "Should be authorized via pre-auth key")
 
 	// Verify node exists for user1
-	user1Node, found := app.state.GetNodeByMachineKey(machineKey.Public(), types.UserID(user1.ID))
+	user1Node, found := app.state.GetNodesByMachineKeyAllUsers(machineKey.Public())[types.UserID(user1.ID)]
 	require.True(t, found, "Node should exist for user1")
 	require.Equal(t, user1.ID, user1Node.UserID().Get(), "Node should belong to user1")
 	user1NodeID := user1Node.ID()
@@ -2998,7 +3000,7 @@ func TestWebFlowReauthDifferentUser(t *testing.T) {
 	require.NoError(t, err)
 
 	// Verify node is expired
-	user1Node, found = app.state.GetNodeByMachineKey(machineKey.Public(), types.UserID(user1.ID))
+	user1Node, found = app.state.GetNodesByMachineKeyAllUsers(machineKey.Public())[types.UserID(user1.ID)]
 	require.True(t, found, "Node should still exist after logout")
 	require.True(t, user1Node.IsExpired(), "Node should be expired after logout")
 	t.Logf("✓ User1 node expired (logged out)")
@@ -3039,7 +3041,7 @@ func TestWebFlowReauthDifferentUser(t *testing.T) {
 
 	t.Run("user1_original_node_still_exists", func(t *testing.T) {
 		// User1's original node should STILL exist (not transferred to user2)
-		user1NodeAfter, found1 := app.state.GetNodeByMachineKey(machineKey.Public(), types.UserID(user1.ID))
+		user1NodeAfter, found1 := app.state.GetNodesByMachineKeyAllUsers(machineKey.Public())[types.UserID(user1.ID)]
 		assert.True(t, found1, "User1's original node should still exist (not transferred)")
 
 		if !found1 {
@@ -3054,7 +3056,7 @@ func TestWebFlowReauthDifferentUser(t *testing.T) {
 
 	t.Run("user2_has_new_node_created", func(t *testing.T) {
 		// User2 should have a NEW node created (not transfer from user1)
-		user2Node, found2 := app.state.GetNodeByMachineKey(machineKey.Public(), types.UserID(user2.ID))
+		user2Node, found2 := app.state.GetNodesByMachineKeyAllUsers(machineKey.Public())[types.UserID(user2.ID)]
 		assert.True(t, found2, "User2 should have a new node created")
 
 		if !found2 {
@@ -3070,7 +3072,7 @@ func TestWebFlowReauthDifferentUser(t *testing.T) {
 	})
 
 	t.Run("returned_node_is_user2_new_node", func(t *testing.T) {
-		// The node returned from HandleNodeFromAuthPath should be user2's NEW node
+		// The node returned from [state.State.HandleNodeFromAuthPath] should be user2's NEW node
 		assert.Equal(t, user2.ID, node.UserID().Get(), "Returned node should belong to user2")
 		assert.NotEqual(t, user1NodeID, node.ID(), "Returned node should be NEW, not transferred from user1")
 		t.Logf("✓ HandleNodeFromAuthPath returned user2's new node (ID: %d)", node.ID())
@@ -3078,8 +3080,8 @@ func TestWebFlowReauthDifferentUser(t *testing.T) {
 
 	t.Run("both_nodes_share_machine_key", func(t *testing.T) {
 		// Both nodes should have the same machine key (same physical device)
-		user1NodeFinal, found1 := app.state.GetNodeByMachineKey(machineKey.Public(), types.UserID(user1.ID))
-		user2NodeFinal, found2 := app.state.GetNodeByMachineKey(machineKey.Public(), types.UserID(user2.ID))
+		user1NodeFinal, found1 := app.state.GetNodesByMachineKeyAllUsers(machineKey.Public())[types.UserID(user1.ID)]
+		user2NodeFinal, found2 := app.state.GetNodesByMachineKeyAllUsers(machineKey.Public())[types.UserID(user2.ID)]
 
 		require.True(t, found1, "User1 node should exist")
 		require.True(t, found2, "User2 node should exist")
@@ -3164,7 +3166,7 @@ func createTestApp(t *testing.T) *Headscale {
 // 1. Node registers successfully with a single-use pre-auth key
 // 2. Node is running fine
 // 3. Node restarts (e.g., after headscale upgrade or tailscale container restart)
-// 4. Node sends RegisterRequest with the same pre-auth key
+// 4. Node sends [tailcfg.RegisterRequest] with the same pre-auth key
 // 5. BUG: Headscale rejects the request with "authkey expired" or "authkey already used"
 //
 // Expected behavior:
@@ -3221,7 +3223,7 @@ func TestGitHubIssue2830_NodeRestartWithUsedPreAuthKey(t *testing.T) {
 	require.NoError(t, err)
 	assert.True(t, usedPak.Used, "pre-auth key should be marked as used after initial registration")
 
-	// STEP 2: Simulate node restart - node sends RegisterRequest again with same pre-auth key
+	// STEP 2: Simulate node restart - node sends [tailcfg.RegisterRequest] again with same pre-auth key
 	// This happens when:
 	// - Tailscale container restarts
 	// - Tailscaled service restarts
@@ -3506,7 +3508,7 @@ func TestGitHubIssue2830_ExistingNodeCanReregisterWithUsedPreAuthKey(t *testing.
 	// WITHOUT THE FIX: This would fail with "authkey already used" error
 	// WITH THE FIX: This succeeds because it's the same node re-registering with its own key
 
-	// Simulate sending the same RegisterRequest again (same MachineKey, same AuthKey)
+	// Simulate sending the same [tailcfg.RegisterRequest] again (same MachineKey, same AuthKey)
 	// This is exactly what happens when a container restarts
 	reregisterReq := tailcfg.RegisterRequest{
 		Auth: &tailcfg.RegisterResponseAuth{
@@ -3785,15 +3787,15 @@ func TestAuthKeyTaggedToUserOwnedViaReauth(t *testing.T) {
 		nodeAfterReauth.IsTagged(), nodeAfterReauth.UserID().Get())
 }
 
-// TestDeletedPreAuthKeyNotRecreatedOnNodeUpdate tests that when a PreAuthKey is deleted,
-// subsequent node updates (like those triggered by MapRequests) do not recreate the key.
+// TestDeletedPreAuthKeyNotRecreatedOnNodeUpdate tests that when a [types.PreAuthKey] is deleted,
+// subsequent node updates (like those triggered by [tailcfg.MapRequest]s) do not recreate the key.
 //
 // This reproduces the bug where:
 //  1. Create a tagged preauthkey and register a node
 //  2. Delete the preauthkey (confirmed gone from pre_auth_keys DB table)
-//  3. Node sends MapRequest (e.g., after tailscaled restart)
+//  3. Node sends [tailcfg.MapRequest] (e.g., after tailscaled restart)
 //  4. BUG: The preauthkey reappears because GORM's Updates() upserts the stale AuthKey
-//     data that still exists in the NodeStore's in-memory cache.
+//     data that still exists in the [state.NodeStore]'s in-memory cache.
 //
 // The fix is to use Omit("AuthKey") on all node Updates() calls to prevent GORM
 // from touching the AuthKey association.
@@ -3862,11 +3864,11 @@ func TestDeletedPreAuthKeyNotRecreatedOnNodeUpdate(t *testing.T) {
 	require.Nil(t, dbNode.AuthKeyID, "node's AuthKeyID should be NULL after PreAuthKey deletion")
 	t.Log("Node's AuthKeyID is NULL in database")
 
-	// The NodeStore may still have stale AuthKey data in memory.
-	// Now simulate what happens when the node sends a MapRequest after a tailscaled restart.
-	// This triggers persistNodeToDB which calls GORM's Updates().
+	// The [state.NodeStore] may still have stale AuthKey data in memory.
+	// Now simulate what happens when the node sends a [tailcfg.MapRequest] after a tailscaled restart.
+	// This triggers [state.State.persistNodeToDB] which calls GORM's Updates().
 
-	// Simulate a MapRequest by updating the node through the state layer
+	// Simulate a [tailcfg.MapRequest] by updating the node through the state layer
 	// This mimics what poll.go does when processing MapRequests
 	mapReq := tailcfg.MapRequest{
 		NodeKey:  nodeKey.Public(),
@@ -3877,8 +3879,8 @@ func TestDeletedPreAuthKeyNotRecreatedOnNodeUpdate(t *testing.T) {
 		},
 	}
 
-	// Process the MapRequest-like update
-	// This calls UpdateNodeFromMapRequest which eventually calls persistNodeToDB
+	// Process the [tailcfg.MapRequest]-like update
+	// This calls [state.State.UpdateNodeFromMapRequest] which eventually calls [state.State.persistNodeToDB]
 	_, err = app.state.UpdateNodeFromMapRequest(node.ID(), mapReq)
 	require.NoError(t, err, "UpdateNodeFromMapRequest should succeed")
 	t.Log("Simulated MapRequest update completed")
@@ -3941,7 +3943,7 @@ func TestTaggedNodeWithoutUserToDifferentUser(t *testing.T) {
 	alice := app.state.CreateUserForTest("alice")
 	require.NotNil(t, alice, "Alice user should be created")
 
-	// Step 4: Re-register the node to alice via HandleNodeFromAuthPath
+	// Step 4: Re-register the node to alice via [state.State.HandleNodeFromAuthPath]
 	// This is what happens when running: headscale auth register --auth-id <id> --user alice
 	nodeKey2 := key.NewNode()
 	registrationID := types.MustAuthID()
@@ -3958,7 +3960,7 @@ func TestTaggedNodeWithoutUserToDifferentUser(t *testing.T) {
 
 	// This should NOT panic - before the fix, this would panic with:
 	// panic: runtime error: invalid memory address or nil pointer dereference
-	// at UserView.Name() because the existing node has no User
+	// at [types.UserView.Name] because the existing node has no User
 	nodeAfterReauth, _, err := app.state.HandleNodeFromAuthPath(
 		registrationID,
 		types.UserID(alice.ID),
@@ -3975,8 +3977,8 @@ func TestTaggedNodeWithoutUserToDifferentUser(t *testing.T) {
 	require.False(t, nodeAfterReauth.IsTagged(), "Node should no longer be tagged")
 	require.Empty(t, nodeAfterReauth.Tags().AsSlice(), "Node should have no tags")
 
-	// Verify Owner() works without panicking - this is what the mapper's
-	// generateUserProfiles calls, and it would panic with a nil pointer
+	// Verify [types.NodeView.Owner] works without panicking - this is what the mapper's
+	// [generateUserProfiles] calls, and it would panic with a nil pointer
 	// dereference if node.User was not set during the tag→user conversion.
 	owner := nodeAfterReauth.Owner()
 	require.True(t, owner.Valid(), "Owner should be valid after conversion (mapper would panic if nil)")
@@ -3986,3 +3988,116 @@ func TestTaggedNodeWithoutUserToDifferentUser(t *testing.T) {
 		nodeAfterReauth.ID().Uint64(), nodeAfterReauth.Tags().AsSlice(),
 		nodeAfterReauth.IsTagged(), nodeAfterReauth.UserID().Get())
 }
+
+// TestHandleNodeFromPreAuthKey_OldUserNil_NoPanic asserts that
+// HandleNodeFromPreAuthKey does not panic when the in-memory NodeStore
+// holds a non-tagged node whose UserID points at a user but whose User
+// pointer is nil (orphan snapshot, e.g. a Preload("User") join missed
+// the row). Re-registering the same machine key under a different user
+// enters the "different user" branch and would otherwise crash at
+// oldUser.Name() in UserView.Name when the backing pointer is nil.
+func TestHandleNodeFromPreAuthKey_OldUserNil_NoPanic(t *testing.T) {
+	app := createTestApp(t)
+
+	userA := app.state.CreateUserForTest("preauth-orphan-old")
+	userB := app.state.CreateUserForTest("preauth-orphan-new")
+
+	machineKey := key.NewMachine()
+	orphanNodeKey := key.NewNode()
+
+	userIDA := userA.ID
+	orphan := types.Node{
+		ID:             99001,
+		MachineKey:     machineKey.Public(),
+		NodeKey:        orphanNodeKey.Public(),
+		Hostname:       "preauth-orphan",
+		GivenName:      "preauth-orphan",
+		UserID:         &userIDA,
+		User:           nil,
+		RegisterMethod: "authkey",
+	}
+	app.state.PutNodeInStoreForTest(orphan)
+
+	pakB, err := app.state.CreatePreAuthKey(userB.TypedID(), true, false, nil, nil)
+	require.NoError(t, err)
+
+	newNodeKey := key.NewNode()
+	regReq := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pakB.Key,
+		},
+		NodeKey: newNodeKey.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "preauth-orphan-newuser",
+		},
+		Expiry: time.Now().Add(24 * time.Hour),
+	}
+
+	resp, err := app.handleRegisterWithAuthKey(regReq, machineKey.Public())
+	require.NoError(t, err, "registration must not panic when old user is nil")
+	require.NotNil(t, resp)
+	require.True(t, resp.MachineAuthorized)
+
+	var registered types.NodeView
+
+	require.EventuallyWithT(t, func(c *assert.CollectT) {
+		var found bool
+
+		registered, found = app.state.GetNodeByNodeKey(newNodeKey.Public())
+		assert.True(c, found, "new node should be available in NodeStore")
+	}, 1*time.Second, 50*time.Millisecond, "waiting for new node")
+
+	assert.NotEqual(t, types.NodeID(99001), registered.ID(), "new node, not orphan")
+	assert.Equal(t, userB.ID, registered.UserID().Get(), "new node belongs to userB")
+}
+
+// TestHandleNodeFromAuthPath_OldUserNil_NoPanic is the parallel guard
+// for the gRPC/OIDC entry point. Same orphan shape as
+// TestHandleNodeFromPreAuthKey_OldUserNil_NoPanic; HandleNodeFromAuthPath
+// has its own oldUser.Name() log line in the existingNodeOwnedByOtherUser
+// branch and panics independently of the noise registration path.
+func TestHandleNodeFromAuthPath_OldUserNil_NoPanic(t *testing.T) {
+	app := createTestApp(t)
+
+	userA := app.state.CreateUserForTest("authpath-orphan-old")
+	userB := app.state.CreateUserForTest("authpath-orphan-new")
+
+	machineKey := key.NewMachine()
+	orphanNodeKey := key.NewNode()
+
+	userIDA := userA.ID
+	orphan := types.Node{
+		ID:             99002,
+		MachineKey:     machineKey.Public(),
+		NodeKey:        orphanNodeKey.Public(),
+		Hostname:       "authpath-orphan",
+		GivenName:      "authpath-orphan",
+		UserID:         &userIDA,
+		User:           nil,
+		RegisterMethod: "oidc",
+	}
+	app.state.PutNodeInStoreForTest(orphan)
+
+	newNodeKey := key.NewNode()
+	authID := types.MustAuthID()
+	regEntry := types.NewRegisterAuthRequest(&types.RegistrationData{
+		MachineKey: machineKey.Public(),
+		NodeKey:    newNodeKey.Public(),
+		Hostname:   "authpath-orphan-newuser",
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "authpath-orphan-newuser",
+		},
+	})
+	app.state.SetAuthCacheEntry(authID, regEntry)
+
+	node, _, err := app.state.HandleNodeFromAuthPath(
+		authID,
+		types.UserID(userB.ID),
+		nil,
+		"oidc",
+	)
+	require.NoError(t, err, "auth-path registration must not panic on nil old user")
+	require.True(t, node.Valid())
+	assert.NotEqual(t, types.NodeID(99002), node.ID(), "new node, not orphan")
+	assert.Equal(t, userB.ID, node.UserID().Get(), "new node belongs to userB")
+}

hscontrol/capver/capver.go

@@ -12,24 +12,17 @@ import (
 	"tailscale.com/util/set"
 )
 
-const (
-	// minVersionParts is the minimum number of version parts needed for major.minor.
-	minVersionParts = 2
+// minVersionParts is the minimum number of version parts needed for major.minor.
+const minVersionParts = 2
 
-	// legacyDERPCapVer is the capability version when LegacyDERP can be cleaned up.
-	legacyDERPCapVer = 111
-)
-
-// CanOldCodeBeCleanedUp is intended to be called on startup to see if
-// there are old code that can ble cleaned up, entries should contain
-// a CapVer where something can be cleaned up and a panic if it can.
-// This is only intended to catch things in tests.
+// CanOldCodeBeCleanedUp is called at server startup to panic when
+// [MinSupportedCapabilityVersion] has crossed a threshold at which a
+// backwards-compat emit path can be deleted. Each entry pairs a
+// [tailcfg.CapabilityVersion] threshold with the message identifying
+// the code to remove; today there are none.
 //
-// All uses of Capability version checks should be listed here.
+// All capability-version-gated cleanups should be registered here.
 func CanOldCodeBeCleanedUp() {
-	if MinSupportedCapabilityVersion >= legacyDERPCapVer {
-		panic("LegacyDERP can be cleaned up in tail.go")
-	}
 }
 
 func tailscaleVersSorted() []string {
@@ -46,12 +39,12 @@ func capVersSorted() []tailcfg.CapabilityVersion {
 	return capVers
 }
 
-// TailscaleVersion returns the Tailscale version for the given CapabilityVersion.
+// TailscaleVersion returns the Tailscale version for the given [tailcfg.CapabilityVersion].
 func TailscaleVersion(ver tailcfg.CapabilityVersion) string {
 	return capVerToTailscaleVer[ver]
 }
 
-// CapabilityVersion returns the CapabilityVersion for the given Tailscale version.
+// CapabilityVersion returns the [tailcfg.CapabilityVersion] for the given Tailscale version.
 // It accepts both full versions (v1.90.1) and minor versions (v1.90).
 func CapabilityVersion(ver string) tailcfg.CapabilityVersion {
 	if !strings.HasPrefix(ver, "v") {
@@ -115,7 +108,7 @@ func TailscaleLatestMajorMinor(n int, stripV bool) []string {
 	return majorSl[len(majorSl)-n:]
 }
 
-// CapVerLatest returns the n latest CapabilityVersions.
+// CapVerLatest returns the n latest [tailcfg.CapabilityVersion] values.
 func CapVerLatest(n int) []tailcfg.CapabilityVersion {
 	if n <= 0 {
 		return nil

hscontrol/capver/capver_generated.go

@@ -42,6 +42,7 @@ var tailscaleToCapVer = map[string]tailcfg.CapabilityVersion{
 	"v1.92": 131,
 	"v1.94": 131,
 	"v1.96": 133,
+	"v1.98": 138,
 }
 
 var capVerToTailscaleVer = map[tailcfg.CapabilityVersion]string{
@@ -77,6 +78,7 @@ var capVerToTailscaleVer = map[tailcfg.CapabilityVersion]string{
 	130: "v1.90",
 	131: "v1.92",
 	133: "v1.96",
+	138: "v1.98",
 }
 
 // SupportedMajorMinorVersions is the number of major.minor Tailscale versions supported.
@@ -84,4 +86,4 @@ const SupportedMajorMinorVersions = 10
 
 // MinSupportedCapabilityVersion represents the minimum capability version
 // supported by this Headscale instance (latest 10 minor versions)
-const MinSupportedCapabilityVersion tailcfg.CapabilityVersion = 109
+const MinSupportedCapabilityVersion tailcfg.CapabilityVersion = 113

hscontrol/capver/capver_test_data.go

@@ -9,10 +9,9 @@ var tailscaleLatestMajorMinorTests = []struct {
 	stripV   bool
 	expected []string
 }{
-	{3, false, []string{"v1.92", "v1.94", "v1.96"}},
-	{2, true, []string{"1.94", "1.96"}},
+	{3, false, []string{"v1.94", "v1.96", "v1.98"}},
+	{2, true, []string{"1.96", "1.98"}},
 	{10, true, []string{
-		"1.78",
 		"1.80",
 		"1.82",
 		"1.84",
@@ -22,6 +21,7 @@ var tailscaleLatestMajorMinorTests = []struct {
 		"1.92",
 		"1.94",
 		"1.96",
+		"1.98",
 	}},
 	{0, false, nil},
 }
@@ -30,7 +30,7 @@ var capVerMinimumTailscaleVersionTests = []struct {
 	input    tailcfg.CapabilityVersion
 	expected string
 }{
-	{109, "v1.78"},
+	{113, "v1.80"},
 	{32, "v1.24"},
 	{41, "v1.30"},
 	{46, "v1.32"},

hscontrol/db/api_key.go

@@ -28,7 +28,7 @@ var (
 	ErrAPIKeyInvalidGeneration = errors.New("generated API key failed validation")
 )
 
-// CreateAPIKey creates a new ApiKey in a user, and returns it.
+// CreateAPIKey creates a new [types.APIKey] in a user, and returns it.
 func (hsdb *HSDatabase) CreateAPIKey(
 	expiration *time.Time,
 ) (string, *types.APIKey, error) {
@@ -84,7 +84,7 @@ func (hsdb *HSDatabase) CreateAPIKey(
 	return keyStr, &key, nil
 }
 
-// ListAPIKeys returns the list of ApiKeys for a user.
+// ListAPIKeys returns the list of [types.APIKey] values for a user.
 func (hsdb *HSDatabase) ListAPIKeys() ([]types.APIKey, error) {
 	keys := []types.APIKey{}
 
@@ -96,7 +96,7 @@ func (hsdb *HSDatabase) ListAPIKeys() ([]types.APIKey, error) {
 	return keys, nil
 }
 
-// GetAPIKey returns a ApiKey for a given key.
+// GetAPIKey returns a [types.APIKey] for a given key.
 func (hsdb *HSDatabase) GetAPIKey(prefix string) (*types.APIKey, error) {
 	key := types.APIKey{}
 	if result := hsdb.DB.First(&key, "prefix = ?", prefix); result.Error != nil {
@@ -106,17 +106,20 @@ func (hsdb *HSDatabase) GetAPIKey(prefix string) (*types.APIKey, error) {
 	return &key, nil
 }
 
-// GetAPIKeyByID returns a ApiKey for a given id.
+// GetAPIKeyByID returns a [types.APIKey] for a given id.
 func (hsdb *HSDatabase) GetAPIKeyByID(id uint64) (*types.APIKey, error) {
 	key := types.APIKey{}
-	if result := hsdb.DB.Find(&types.APIKey{ID: id}).First(&key); result.Error != nil {
+	// Query on an explicit primary-key clause: a struct condition would drop a
+	// zero-valued ID, making the lookup unconditional and returning the first
+	// row instead of not-found.
+	if result := hsdb.DB.First(&key, "id = ?", id); result.Error != nil {
 		return nil, result.Error
 	}
 
 	return &key, nil
 }
 
-// DestroyAPIKey destroys a ApiKey. Returns error if the ApiKey
+// DestroyAPIKey destroys a [types.APIKey]. Returns error if the [types.APIKey]
 // does not exist.
 func (hsdb *HSDatabase) DestroyAPIKey(key types.APIKey) error {
 	if result := hsdb.DB.Unscoped().Delete(key); result.Error != nil {
@@ -126,7 +129,7 @@ func (hsdb *HSDatabase) DestroyAPIKey(key types.APIKey) error {
 	return nil
 }
 
-// ExpireAPIKey marks a ApiKey as expired.
+// ExpireAPIKey marks a [types.APIKey] as expired.
 func (hsdb *HSDatabase) ExpireAPIKey(key *types.APIKey) error {
 	err := hsdb.DB.Model(&key).Update("Expiration", time.Now()).Error
 	if err != nil {

hscontrol/db/api_key_byid_test.go

@@ -0,0 +1,28 @@
+package db
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestGetAPIKeyByIDZeroReturnsError ensures GetAPIKeyByID(0) reports not-found
+// rather than returning the lowest-ID key. GORM drops a zero-valued primary key
+// from a struct condition, which would otherwise make the lookup unconditional.
+func TestGetAPIKeyByIDZeroReturnsError(t *testing.T) {
+	db, err := newSQLiteTestDB()
+	require.NoError(t, err)
+
+	_, key1, err := db.CreateAPIKey(nil)
+	require.NoError(t, err)
+	require.NotNil(t, key1)
+
+	_, key2, err := db.CreateAPIKey(nil)
+	require.NoError(t, err)
+	require.NotNil(t, key2)
+
+	key, err := db.GetAPIKeyByID(0)
+	require.Error(t, err, "GetAPIKeyByID(0) should be not-found, got key=%+v", key)
+	assert.Nil(t, key)
+}

hscontrol/db/db.go

@@ -706,13 +706,20 @@ AND auth_key_id NOT IN (
 				// but this prevents deleting users whose nodes have been
 				// tagged, and the ON DELETE CASCADE FK would destroy the
 				// tagged nodes if the user were deleted.
+				//
+				// A nil tags slice marshals to the JSON literal 'null', so
+				// untagged nodes can carry tags='null'. That spelling must be
+				// excluded alongside '[]' and '' or untagged nodes lose their
+				// user. Nodes already detached by the earlier version of this
+				// migration are repaired by the recovery migration below.
 				// Fixes: https://github.com/juanfont/headscale/issues/3077
+				// Fixes: https://github.com/juanfont/headscale/issues/3323
 				ID: "202602201200-clear-tagged-node-user-id",
 				Migrate: func(tx *gorm.DB) error {
 					err := tx.Exec(`
 UPDATE nodes
 SET user_id = NULL
-WHERE tags IS NOT NULL AND tags != '[]' AND tags != '';
+WHERE tags IS NOT NULL AND tags != '[]' AND tags != '' AND tags != 'null';
 						`).Error
 					if err != nil {
 						return fmt.Errorf("clearing user_id on tagged nodes: %w", err)
@@ -722,6 +729,58 @@ WHERE tags IS NOT NULL AND tags != '[]' AND tags != '';
 				},
 				Rollback: func(db *gorm.DB) error { return nil },
 			},
+			{
+				// Clear zero-time node expiry values to NULL.
+				// Versions before 0.28 persisted a pointer to a zero
+				// time.Time as '0001-01-01 00:00:00+00:00' rather than
+				// NULL, which 0.29 reports as an expired node. This
+				// normalises the existing rows so the column once
+				// again means "no expiry" when unset.
+				ID: "202605221435-clear-zero-time-node-expiry",
+				Migrate: func(tx *gorm.DB) error {
+					err := tx.Exec(`
+UPDATE nodes
+SET expiry = NULL
+WHERE expiry IS NOT NULL AND expiry < '1900-01-01';
+						`).Error
+					if err != nil {
+						return fmt.Errorf("clearing zero-time node expiry: %w", err)
+					}
+
+					return nil
+				},
+				Rollback: func(db *gorm.DB) error { return nil },
+			},
+			{
+				// Recover user_id on untagged nodes detached by the earlier
+				// version of 202602201200-clear-tagged-node-user-id, which
+				// treated tags='null' as tagged and cleared the user. This
+				// repairs databases that already upgraded to 0.29.0; fresh
+				// upgrades are protected by the fixed migration above and find
+				// nothing to repair. Recovery is best-effort: the owner is
+				// re-derived from the node's pre-auth key, so nodes registered
+				// via CLI/OIDC (no pre-auth key) cannot be recovered and must
+				// be reassigned manually.
+				// Fixes: https://github.com/juanfont/headscale/issues/3323
+				ID: "202606181200-recover-null-tags-node-user-id",
+				Migrate: func(tx *gorm.DB) error {
+					err := tx.Exec(`
+UPDATE nodes
+SET user_id = (
+	SELECT pak.user_id FROM pre_auth_keys pak WHERE pak.id = nodes.auth_key_id
+)
+WHERE user_id IS NULL
+	AND auth_key_id IS NOT NULL
+	AND (tags IS NULL OR tags = '' OR tags = '[]' OR tags = 'null');
+						`).Error
+					if err != nil {
+						return fmt.Errorf("recovering user_id on untagged nodes: %w", err)
+					}
+
+					return nil
+				},
+				Rollback: func(db *gorm.DB) error { return nil },
+			},
 		},
 	)
 

hscontrol/db/db_test.go

@@ -122,7 +122,7 @@ func TestSQLiteMigrationAndDataValidation(t *testing.T) {
 				// Expected: tags = ["tag:server"] (no duplicates)
 				node4 := findNode("node4")
 				require.NotNil(t, node4, "node4 should exist")
-				assert.Equal(t, []string{"tag:server"}, node4.Tags, "node4 should have tag:server without duplicates")
+				assert.Equal(t, []string{"tag:server"}, node4.Tags.List(), "node4 should have tag:server without duplicates") //nolint:goconst // descriptive test assertions read better with the literal inline
 
 				// Node 5: user2 has no RequestTags
 				// Expected: tags = [] (unchanged)
@@ -144,6 +144,157 @@ func TestSQLiteMigrationAndDataValidation(t *testing.T) {
 				assert.NotContains(t, node7.Tags, "tag:forbidden", "node7 should NOT have tag:forbidden (unauthorized)")
 			},
 		},
+		// Test for the zero-time node expiry migration
+		// (202605221435-clear-zero-time-node-expiry). Pre-0.28 versions
+		// stored a zero time.Time as '0001-01-01 00:00:00+00:00' rather
+		// than NULL, which caused 0.29 to report those nodes as expired.
+		// Fixes: https://github.com/juanfont/headscale/issues/3284
+		{
+			dbPath: "testdata/sqlite/zero_time_expiry_migration_test.sql",
+			wantFunc: func(t *testing.T, hsdb *HSDatabase) {
+				t.Helper()
+
+				nodes, err := Read(hsdb.DB, func(rx *gorm.DB) (types.Nodes, error) {
+					return ListNodes(rx)
+				})
+				require.NoError(t, err)
+				require.Len(t, nodes, 5, "should have all 5 nodes")
+
+				byHostname := make(map[string]*types.Node, len(nodes))
+				for _, n := range nodes {
+					byHostname[n.Hostname] = n
+				}
+
+				// Node 1 had a zero-time expiry; should be cleared.
+				node1 := byHostname["node1"]
+				require.NotNil(t, node1, "node1 should exist")
+				assert.Nil(t, node1.Expiry, "node1 zero-time expiry should be cleared to NULL")
+				assert.False(t, node1.IsExpired(), "node1 should not be reported as expired")
+
+				// Node 2 already had NULL expiry; should still be NULL.
+				node2 := byHostname["node2"]
+				require.NotNil(t, node2, "node2 should exist")
+				assert.Nil(t, node2.Expiry, "node2 NULL expiry should be preserved")
+				assert.False(t, node2.IsExpired(), "node2 should not be reported as expired")
+
+				// Node 3 had a real future expiry; should be preserved.
+				node3 := byHostname["node3"]
+				require.NotNil(t, node3, "node3 should exist")
+				require.NotNil(t, node3.Expiry, "node3 future expiry should be preserved")
+				assert.Equal(t, 2099, node3.Expiry.UTC().Year(), "node3 expiry year should be 2099")
+				assert.False(t, node3.IsExpired(), "node3 with future expiry should not be expired")
+
+				// Node 4 had a real past expiry; should be preserved.
+				node4 := byHostname["node4"]
+				require.NotNil(t, node4, "node4 should exist")
+				require.NotNil(t, node4.Expiry, "node4 past expiry should be preserved")
+				assert.Equal(t, 2020, node4.Expiry.UTC().Year(), "node4 expiry year should be 2020")
+				assert.True(t, node4.IsExpired(), "node4 with past expiry should still be expired")
+
+				// Node 5 also had a zero-time expiry; should be cleared.
+				node5 := byHostname["node5"]
+				require.NotNil(t, node5, "node5 should exist")
+				assert.Nil(t, node5.Expiry, "node5 zero-time expiry should be cleared to NULL")
+				assert.False(t, node5.IsExpired(), "node5 should not be reported as expired")
+			},
+		},
+		// Test for the clear-tagged-node-user-id migration
+		// (202602201200-clear-tagged-node-user-id). A nil tags slice
+		// marshals to the JSON literal 'null', so untagged nodes can carry
+		// tags='null' in the database. The migration must only clear
+		// user_id on genuinely tagged nodes, not on these untagged ones.
+		// Fixes: https://github.com/juanfont/headscale/issues/3323
+		{
+			dbPath: "testdata/sqlite/null_tags_user_id_migration_test.sql",
+			wantFunc: func(t *testing.T, hsdb *HSDatabase) {
+				t.Helper()
+
+				nodes, err := Read(hsdb.DB, func(rx *gorm.DB) (types.Nodes, error) {
+					return ListNodes(rx)
+				})
+				require.NoError(t, err)
+				require.Len(t, nodes, 4, "should have all 4 nodes")
+
+				byHostname := make(map[string]*types.Node, len(nodes))
+				for _, n := range nodes {
+					byHostname[n.Hostname] = n
+				}
+
+				// Node 1 had tags='null' (untagged) and belonged to user2.
+				// The migration must NOT clear its user_id.
+				node1 := byHostname["node1"]
+				require.NotNil(t, node1, "node1 should exist")
+				assert.False(t, node1.IsTagged(), "node1 with tags='null' should be untagged")
+				require.NotNil(t, node1.UserID, "node1 should keep its user assigned")
+				assert.Equal(t, uint(2), *node1.UserID, "node1 should still belong to user2")
+
+				// Node 2 is genuinely tagged; user_id must be cleared.
+				node2 := byHostname["node2"]
+				require.NotNil(t, node2, "node2 should exist")
+				assert.True(t, node2.IsTagged(), "node2 should be tagged")
+				assert.Nil(t, node2.UserID, "node2 (tagged) should have user_id cleared")
+
+				// Node 3 had tags='[]' (untagged); user_id preserved.
+				node3 := byHostname["node3"]
+				require.NotNil(t, node3, "node3 should exist")
+				assert.False(t, node3.IsTagged(), "node3 with tags='[]' should be untagged")
+				require.NotNil(t, node3.UserID, "node3 should keep its user assigned")
+				assert.Equal(t, uint(1), *node3.UserID, "node3 should still belong to user1")
+
+				// Node 4 had tags='' (untagged); user_id preserved.
+				node4 := byHostname["node4"]
+				require.NotNil(t, node4, "node4 should exist")
+				assert.False(t, node4.IsTagged(), "node4 with tags='' should be untagged")
+				require.NotNil(t, node4.UserID, "node4 should keep its user assigned")
+				assert.Equal(t, uint(1), *node4.UserID, "node4 should still belong to user1")
+			},
+		},
+		// Test for the null-tags user_id recovery migration. Databases that
+		// already upgraded to 0.29.0 had user_id wrongly cleared on untagged
+		// nodes with tags='null'. The recovery migration re-derives user_id
+		// from the node's pre-auth key where one exists.
+		// Fixes: https://github.com/juanfont/headscale/issues/3323
+		{
+			dbPath: "testdata/sqlite/recover_null_tags_user_id_migration_test.sql",
+			wantFunc: func(t *testing.T, hsdb *HSDatabase) {
+				t.Helper()
+
+				nodes, err := Read(hsdb.DB, func(rx *gorm.DB) (types.Nodes, error) {
+					return ListNodes(rx)
+				})
+				require.NoError(t, err)
+				require.Len(t, nodes, 4, "should have all 4 nodes")
+
+				byHostname := make(map[string]*types.Node, len(nodes))
+				for _, n := range nodes {
+					byHostname[n.Hostname] = n
+				}
+
+				// Node 1: authkey-registered, orphaned by the bug. The recovery
+				// migration restores user_id from its pre-auth key (user2).
+				node1 := byHostname["node1"]
+				require.NotNil(t, node1, "node1 should exist")
+				require.NotNil(t, node1.UserID, "node1 user_id should be recovered")
+				assert.Equal(t, uint(2), *node1.UserID, "node1 should be recovered to user2")
+
+				// Node 2: genuinely tagged, correctly cleared. Must stay cleared.
+				node2 := byHostname["node2"]
+				require.NotNil(t, node2, "node2 should exist")
+				assert.True(t, node2.IsTagged(), "node2 should be tagged")
+				assert.Nil(t, node2.UserID, "node2 (tagged) must remain cleared")
+
+				// Node 3: CLI-registered, no pre-auth key. Unrecoverable.
+				node3 := byHostname["node3"]
+				require.NotNil(t, node3, "node3 should exist")
+				assert.Nil(t, node3.UserID, "node3 has no pre-auth key to recover from")
+
+				// Node 4: never orphaned; user_id must be untouched.
+				node4 := byHostname["node4"]
+				require.NotNil(t, node4, "node4 should exist")
+				require.NotNil(t, node4.UserID, "node4 user_id should be untouched")
+				assert.Equal(t, uint(1), *node4.UserID, "node4 should still belong to user1")
+			},
+		},
 	}
 
 	for _, tt := range tests {

hscontrol/db/ephemeral_garbage_collector_test.go

@@ -2,6 +2,7 @@ package db
 
 import (
 	"runtime"
+	"slices"
 	"sync"
 	"sync/atomic"
 	"testing"
@@ -9,6 +10,7 @@ import (
 
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 const (
@@ -17,8 +19,8 @@ const (
 	fifty       = 50 * time.Millisecond
 )
 
-// TestEphemeralGarbageCollectorGoRoutineLeak is a test for a goroutine leak in EphemeralGarbageCollector().
-// It creates a new EphemeralGarbageCollector, schedules several nodes for deletion with a short expiry,
+// TestEphemeralGarbageCollectorGoRoutineLeak is a test for a goroutine leak in [EphemeralGarbageCollector].
+// It creates a new [EphemeralGarbageCollector], schedules several nodes for deletion with a short expiry,
 // and verifies that the nodes are deleted when the expiry time passes, and then
 // for any leaked goroutines after the garbage collector is closed.
 func TestEphemeralGarbageCollectorGoRoutineLeak(t *testing.T) {
@@ -89,8 +91,84 @@ func TestEphemeralGarbageCollectorGoRoutineLeak(t *testing.T) {
 	t.Logf("Final number of goroutines: %d", runtime.NumGoroutine())
 }
 
-// TestEphemeralGarbageCollectorReschedule is a test for the rescheduling of nodes in EphemeralGarbageCollector().
-// It creates a new EphemeralGarbageCollector, schedules a node for deletion with a longer expiry,
+// TestEphemeralGarbageCollectorCancelReapsGoroutine verifies that Cancel (and
+// reschedule) reaps the per-node watcher goroutine while the collector is still
+// running, rather than leaking it until Close. The production churn path is an
+// ephemeral node disconnecting (Schedule) then reconnecting (Cancel) before the
+// long expiry timer fires; a stopped timer never fires, so a watcher parked
+// only on <-timer.C would otherwise leak on every cycle.
+func TestEphemeralGarbageCollectorCancelReapsGoroutine(t *testing.T) {
+	gc := NewEphemeralGarbageCollector(func(types.NodeID) {})
+
+	go gc.Start()
+	defer gc.Close()
+
+	baseline := runtime.NumGoroutine()
+
+	const (
+		iterations = 1000
+		nodeID     = types.NodeID(42)
+	)
+
+	for range iterations {
+		gc.Schedule(nodeID, time.Hour) // disconnect: long timer, will not fire
+		gc.Cancel(nodeID)              // reconnect: must reap the watcher
+	}
+
+	assert.EventuallyWithT(t, func(c *assert.CollectT) {
+		assert.LessOrEqual(c, runtime.NumGoroutine(), baseline+10,
+			"per-node goroutines leaked on Cancel/reschedule")
+	}, 2*time.Second, 20*time.Millisecond, "watcher goroutines should be reaped")
+}
+
+// TestEphemeralGarbageCollectorCancelBeatsQueuedDeletion verifies that a node
+// reconnecting (Cancel) after its deletion has already been queued on the
+// internal channel is not deleted. The timer fires and enqueues the deletion;
+// Cancel then runs before Start drains it. Start must drop the now-superseded
+// deletion rather than removing the freshly reconnected node.
+func TestEphemeralGarbageCollectorCancelBeatsQueuedDeletion(t *testing.T) {
+	const targetNode types.NodeID = 42
+
+	var (
+		mu      sync.Mutex
+		deleted []types.NodeID
+	)
+
+	e := NewEphemeralGarbageCollector(func(ni types.NodeID) {
+		mu.Lock()
+		defer mu.Unlock()
+
+		deleted = append(deleted, ni)
+	})
+
+	// Schedule with a tiny expiry but do not drain yet: the watcher fires and
+	// enqueues the deletion onto the buffered channel.
+	e.Schedule(targetNode, time.Millisecond)
+	require.Eventually(t, func() bool {
+		return len(e.deleteCh) == 1
+	}, time.Second, time.Millisecond, "deletion should be queued")
+
+	// Node reconnects before the queue is drained.
+	e.Cancel(targetNode)
+
+	go e.Start()
+	defer e.Close()
+
+	require.Eventually(t, func() bool {
+		return len(e.deleteCh) == 0
+	}, time.Second, time.Millisecond, "Start should drain the queued deletion")
+
+	assert.Never(t, func() bool {
+		mu.Lock()
+		defer mu.Unlock()
+
+		return slices.Contains(deleted, targetNode)
+	}, 200*time.Millisecond, 10*time.Millisecond,
+		"cancelled node must not be deleted")
+}
+
+// TestEphemeralGarbageCollectorReschedule is a test for the rescheduling of nodes in [EphemeralGarbageCollector].
+// It creates a new [EphemeralGarbageCollector], schedules a node for deletion with a longer expiry,
 // and then reschedules it with a shorter expiry, and verifies that the node is deleted only once.
 func TestEphemeralGarbageCollectorReschedule(t *testing.T) {
 	// Deletion tracking mechanism
@@ -145,8 +223,8 @@ func TestEphemeralGarbageCollectorReschedule(t *testing.T) {
 	deleteMutex.Unlock()
 }
 
-// TestEphemeralGarbageCollectorCancelAndReschedule is a test for the cancellation and rescheduling of nodes in EphemeralGarbageCollector().
-// It creates a new EphemeralGarbageCollector, schedules a node for deletion, cancels it, and then reschedules it,
+// TestEphemeralGarbageCollectorCancelAndReschedule is a test for the cancellation and rescheduling of nodes in [EphemeralGarbageCollector].
+// It creates a new [EphemeralGarbageCollector], schedules a node for deletion, cancels it, and then reschedules it,
 // and verifies that the node is deleted only once.
 func TestEphemeralGarbageCollectorCancelAndReschedule(t *testing.T) {
 	// Deletion tracking mechanism
@@ -214,8 +292,8 @@ func TestEphemeralGarbageCollectorCancelAndReschedule(t *testing.T) {
 	deleteMutex.Unlock()
 }
 
-// TestEphemeralGarbageCollectorCloseBeforeTimerFires is a test for the closing of the EphemeralGarbageCollector before the timer fires.
-// It creates a new EphemeralGarbageCollector, schedules a node for deletion, closes the GC, and verifies that the node is not deleted.
+// TestEphemeralGarbageCollectorCloseBeforeTimerFires is a test for the closing of the [EphemeralGarbageCollector] before the timer fires.
+// It creates a new [EphemeralGarbageCollector], schedules a node for deletion, closes the GC, and verifies that the node is not deleted.
 func TestEphemeralGarbageCollectorCloseBeforeTimerFires(t *testing.T) {
 	// Deletion tracking
 	var (
@@ -264,7 +342,7 @@ func TestEphemeralGarbageCollectorCloseBeforeTimerFires(t *testing.T) {
 	deleteMutex.Unlock()
 }
 
-// TestEphemeralGarbageCollectorScheduleAfterClose verifies that calling Schedule after Close
+// TestEphemeralGarbageCollectorScheduleAfterClose verifies that calling [EphemeralGarbageCollector.Schedule] after [EphemeralGarbageCollector.Close]
 // is a no-op and doesn't cause any panics, goroutine leaks, or other issues.
 func TestEphemeralGarbageCollectorScheduleAfterClose(t *testing.T) {
 	// Count initial goroutines to check for leaks
@@ -339,7 +417,7 @@ func TestEphemeralGarbageCollectorScheduleAfterClose(t *testing.T) {
 }
 
 // TestEphemeralGarbageCollectorConcurrentScheduleAndClose tests the behavior of the garbage collector
-// when Schedule and Close are called concurrently from multiple goroutines.
+// when [EphemeralGarbageCollector.Schedule] and [EphemeralGarbageCollector.Close] are called concurrently from multiple goroutines.
 func TestEphemeralGarbageCollectorConcurrentScheduleAndClose(t *testing.T) {
 	// Count initial goroutines
 	initialGoroutines := runtime.NumGoroutine()
@@ -379,7 +457,7 @@ func TestEphemeralGarbageCollectorConcurrentScheduleAndClose(t *testing.T) {
 	stopScheduling := make(chan struct{})
 
 	// Track how many nodes have been scheduled
-	var scheduledCount int64
+	var scheduledCount atomic.Int64
 
 	// Launch goroutines that continuously schedule nodes
 	for schedulerIndex := range numSchedulers {
@@ -396,7 +474,7 @@ func TestEphemeralGarbageCollectorConcurrentScheduleAndClose(t *testing.T) {
 				default:
 					nodeID := types.NodeID(baseNodeID + j + 1) //nolint:gosec // safe conversion in test
 					gc.Schedule(nodeID, 1*time.Hour)           // Long expiry to ensure it doesn't trigger during test
-					atomic.AddInt64(&scheduledCount, 1)
+					scheduledCount.Add(1)
 
 					// Yield to other goroutines to introduce variability
 					runtime.Gosched()
@@ -410,7 +488,7 @@ func TestEphemeralGarbageCollectorConcurrentScheduleAndClose(t *testing.T) {
 		defer wg.Done()
 
 		// Wait until enough nodes have been scheduled
-		for atomic.LoadInt64(&scheduledCount) < int64(numSchedulers*closeAfterNodes) {
+		for scheduledCount.Load() < int64(numSchedulers*closeAfterNodes) {
 			runtime.Gosched()
 		}
 

hscontrol/db/ip.go

@@ -49,7 +49,7 @@ type IPAllocator struct {
 	usedIPs netipx.IPSetBuilder
 }
 
-// NewIPAllocator returns a new IPAllocator singleton which
+// NewIPAllocator returns a new [IPAllocator] singleton which
 // can be used to hand out unique IP addresses within the
 // provided IPv4 and IPv6 prefix. It needs to be created
 // when headscale starts and needs to finish its read
@@ -170,11 +170,36 @@ func (i *IPAllocator) Next() (*netip.Addr, *netip.Addr, error) {
 
 var ErrCouldNotAllocateIP = errors.New("failed to allocate IP")
 
-func (i *IPAllocator) nextLocked(prev netip.Addr, prefix *netip.Prefix) (*netip.Addr, error) {
+// allocateNext4 allocates the next IPv4 under i.mu, advancing prev4 so a run of
+// allocations (e.g. BackfillNodeIPs) does not rescan already-issued addresses,
+// and so prev4 is read under the lock rather than in the caller's frame.
+func (i *IPAllocator) allocateNext4() (*netip.Addr, error) {
 	i.mu.Lock()
 	defer i.mu.Unlock()
 
-	return i.next(prev, prefix)
+	ret, err := i.next(i.prev4, i.prefix4)
+	if err != nil {
+		return nil, err
+	}
+
+	i.prev4 = *ret
+
+	return ret, nil
+}
+
+// allocateNext6 mirrors allocateNext4 for the IPv6 prefix.
+func (i *IPAllocator) allocateNext6() (*netip.Addr, error) {
+	i.mu.Lock()
+	defer i.mu.Unlock()
+
+	ret, err := i.next(i.prev6, i.prefix6)
+	if err != nil {
+		return nil, err
+	}
+
+	i.prev6 = *ret
+
+	return ret, nil
 }
 
 func (i *IPAllocator) next(prev netip.Addr, prefix *netip.Prefix) (*netip.Addr, error) {
@@ -200,30 +225,40 @@ func (i *IPAllocator) next(prev netip.Addr, prefix *netip.Prefix) (*netip.Addr,
 		return nil, err
 	}
 
+	// Walk forward from the starting address until a free, non-reserved
+	// address inside the prefix is found. The random strategy only picks the
+	// starting point at random and then scans deterministically: this keeps
+	// the loop finite, so an exhausted prefix returns ErrCouldNotAllocateIP
+	// instead of re-drawing in-prefix addresses forever under i.mu.
+	start := ip
 	for {
-		if !prefix.Contains(ip) {
-			return nil, ErrCouldNotAllocateIP
+		if prefix.Contains(ip) && !set.Contains(ip) && !isTailscaleReservedIP(ip) {
+			i.usedIPs.Add(ip)
+
+			return &ip, nil
 		}
 
-		// Check if the IP has already been allocated
-		// or if it is a IP reserved by Tailscale.
-		if set.Contains(ip) || isTailscaleReservedIP(ip) {
-			switch i.strategy {
-			case types.IPAllocationStrategySequential:
-				ip = ip.Next()
-			case types.IPAllocationStrategyRandom:
-				ip, err = randomNext(*prefix)
-				if err != nil {
-					return nil, fmt.Errorf("getting random IP: %w", err)
-				}
+		ip = ip.Next()
+
+		switch i.strategy {
+		case types.IPAllocationStrategySequential:
+			// Sequential allocation never wraps: walking past the end of
+			// the prefix means the pool is exhausted.
+			if !prefix.Contains(ip) {
+				return nil, ErrCouldNotAllocateIP
+			}
+		case types.IPAllocationStrategyRandom:
+			// Random allocation wraps within the prefix so every address is
+			// examined exactly once; returning to the start means the prefix
+			// is exhausted.
+			if !prefix.Contains(ip) {
+				ip = prefix.Masked().Addr()
 			}
 
-			continue
+			if ip == start {
+				return nil, ErrCouldNotAllocateIP
+			}
 		}
-
-		i.usedIPs.Add(ip)
-
-		return &ip, nil
 	}
 }
 
@@ -241,6 +276,12 @@ func randomNext(pfx netip.Prefix) (netip.Addr, error) {
 	// after.
 	tempMax := big.NewInt(0).Sub(&to, &from)
 
+	// A single-address prefix (/32 or /128) has from == to, so tempMax is 0 and
+	// rand.Int would panic on a non-positive bound. Return the sole address.
+	if tempMax.Sign() <= 0 {
+		return fromIP, nil
+	}
+
 	out, err := rand.Int(rand.Reader, tempMax)
 	if err != nil {
 		return netip.Addr{}, fmt.Errorf("generating random IP: %w", err)
@@ -248,7 +289,10 @@ func randomNext(pfx netip.Prefix) (netip.Addr, error) {
 
 	valInRange := big.NewInt(0).Add(&from, out)
 
-	ip, ok := netip.AddrFromSlice(valInRange.Bytes())
+	// big.Int.Bytes() strips leading zero bytes, so a value with a zero high
+	// byte yields a too-short slice that AddrFromSlice rejects. Pad to the
+	// prefix's address width.
+	ip, ok := netip.AddrFromSlice(valInRange.FillBytes(make([]byte, len(fromIP.AsSlice()))))
 	if !ok {
 		return netip.Addr{}, errGeneratedIPBytesInvalid
 	}
@@ -272,7 +316,7 @@ func isTailscaleReservedIP(ip netip.Addr) bool {
 }
 
 // BackfillNodeIPs will take a database transaction, and
-// iterate through all of the current nodes in headscale
+// iterate through all of the current nodes ([types.Node]) in headscale
 // and ensure it has IP addresses according to the current
 // configuration.
 // This means that if both IPv4 and IPv6 is set in the
@@ -304,7 +348,7 @@ func (db *HSDatabase) BackfillNodeIPs(i *IPAllocator) ([]string, error) {
 			changed := false
 			// IPv4 prefix is set, but node ip is missing, alloc
 			if i.prefix4 != nil && node.IPv4 == nil {
-				ret4, err := i.nextLocked(i.prev4, i.prefix4)
+				ret4, err := i.allocateNext4()
 				if err != nil {
 					return fmt.Errorf("allocating IPv4 for node(%d): %w", node.ID, err)
 				}
@@ -317,7 +361,7 @@ func (db *HSDatabase) BackfillNodeIPs(i *IPAllocator) ([]string, error) {
 
 			// IPv6 prefix is set, but node ip is missing, alloc
 			if i.prefix6 != nil && node.IPv6 == nil {
-				ret6, err := i.nextLocked(i.prev6, i.prefix6)
+				ret6, err := i.allocateNext6()
 				if err != nil {
 					return fmt.Errorf("allocating IPv6 for node(%d): %w", node.ID, err)
 				}
@@ -346,7 +390,6 @@ func (db *HSDatabase) BackfillNodeIPs(i *IPAllocator) ([]string, error) {
 				// Use Updates() with Select() to only update IP fields, avoiding overwriting
 				// other fields like Expiry. We need Select() because Updates() alone skips
 				// zero values, but we DO want to update IPv4/IPv6 to nil when removing them.
-				// See issue #2862.
 				err := tx.Model(node).Select("ipv4", "ipv6").Updates(node).Error
 				if err != nil {
 					return fmt.Errorf("saving node(%d) after adding IPs: %w", node.ID, err)

hscontrol/db/ip_backfill_race_test.go

@@ -0,0 +1,52 @@
+package db
+
+import (
+	"net/netip"
+	"sync"
+	"testing"
+
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/stretchr/testify/require"
+)
+
+// TestAllocatorConcurrentNextAndBackfillNoRace exercises the registration path
+// (Next) concurrently with the backfill allocation path (allocateNext4/6) on
+// the same allocator. Backfill used to read prev4/prev6 in the caller's frame
+// without the lock, racing Next's writes; both must now take i.mu. Run with
+// -race.
+func TestAllocatorConcurrentNextAndBackfillNoRace(t *testing.T) {
+	p4 := netip.MustParsePrefix("100.64.0.0/10")
+	p6 := netip.MustParsePrefix("fd7a:115c:a1e0::/48")
+
+	alloc, err := NewIPAllocator(nil, &p4, &p6, types.IPAllocationStrategySequential)
+	require.NoError(t, err)
+
+	const iterations = 2000
+
+	var wg sync.WaitGroup
+
+	wg.Go(func() {
+		for range iterations {
+			_, _, err := alloc.Next()
+			if err != nil {
+				return
+			}
+		}
+	})
+
+	wg.Go(func() {
+		for range iterations {
+			_, err := alloc.allocateNext4()
+			if err != nil {
+				return
+			}
+
+			_, err = alloc.allocateNext6()
+			if err != nil {
+				return
+			}
+		}
+	})
+
+	wg.Wait()
+}

hscontrol/db/ip_random_exhaustion_test.go

@@ -0,0 +1,52 @@
+package db
+
+import (
+	"errors"
+	"net/netip"
+	"testing"
+	"time"
+
+	"github.com/juanfont/headscale/hscontrol/types"
+)
+
+// TestIPAllocatorRandomExhaustionReturnsError ensures the random allocation
+// strategy terminates when its prefix is exhausted. randomNext only ever
+// returns in-prefix addresses, so the allocation loop's exhaustion exit must
+// not depend on producing an out-of-prefix candidate; otherwise Next() spins
+// forever under the allocator mutex, wedging all registration and IP release.
+//
+// 100.64.0.0/30 has four addresses: .0 (network) and .3 (broadcast) are
+// reserved, leaving .1 and .2. After two allocations the pool is exhausted and
+// the third Next() must return ErrCouldNotAllocateIP promptly.
+func TestIPAllocatorRandomExhaustionReturnsError(t *testing.T) {
+	prefix4 := netip.MustParsePrefix("100.64.0.0/30")
+
+	alloc, err := NewIPAllocator(nil, &prefix4, nil, types.IPAllocationStrategyRandom)
+	if err != nil {
+		t.Fatalf("NewIPAllocator: %v", err)
+	}
+
+	for i := range 2 {
+		_, _, err := alloc.Next()
+		if err != nil {
+			t.Fatalf("Next() #%d unexpectedly failed: %v", i+1, err)
+		}
+	}
+
+	done := make(chan error, 1)
+
+	go func() {
+		_, _, err := alloc.Next()
+		done <- err
+	}()
+
+	select {
+	case err := <-done:
+		if !errors.Is(err, ErrCouldNotAllocateIP) {
+			t.Fatalf("expected ErrCouldNotAllocateIP on exhausted prefix, got: %v", err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("Next() on an exhausted random-strategy prefix did not return " +
+			"within 2s; it is spinning forever under the allocator mutex")
+	}
+}

hscontrol/db/node.go

@@ -1,15 +1,11 @@
 package db
 
 import (
-	"encoding/json"
 	"errors"
 	"fmt"
 	"net/netip"
-	"regexp"
-	"slices"
 	"sort"
 	"strconv"
-	"strings"
 	"sync"
 	"testing"
 	"time"
@@ -19,8 +15,8 @@ import (
 	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
 	"github.com/rs/zerolog/log"
 	"gorm.io/gorm"
-	"tailscale.com/net/tsaddr"
 	"tailscale.com/types/key"
+	"tailscale.com/util/dnsname"
 )
 
 const (
@@ -34,8 +30,6 @@ const (
 // ErrNodeNameNotUnique is returned when a node name is not unique.
 var ErrNodeNameNotUnique = errors.New("node name is not unique")
 
-var invalidDNSRegex = regexp.MustCompile("[^a-z0-9-.]+")
-
 var (
 	ErrNodeNotFound                  = errors.New("node not found")
 	ErrNodeRouteIsNotAvailable       = errors.New("route is not available on node")
@@ -115,7 +109,7 @@ func (hsdb *HSDatabase) getNode(uid types.UserID, name string) (*types.Node, err
 	})
 }
 
-// getNode finds a Node by name and user and returns the Node struct.
+// getNode finds a [types.Node] by name and user and returns the [types.Node] struct.
 func getNode(tx *gorm.DB, uid types.UserID, name string) (*types.Node, error) {
 	nodes, err := ListNodesByUser(tx, uid)
 	if err != nil {
@@ -135,7 +129,7 @@ func (hsdb *HSDatabase) GetNodeByID(id types.NodeID) (*types.Node, error) {
 	return GetNodeByID(hsdb.DB, id)
 }
 
-// GetNodeByID finds a Node by ID and returns the Node struct.
+// GetNodeByID finds a [types.Node] by ID and returns the [types.Node] struct.
 func GetNodeByID(tx *gorm.DB, id types.NodeID) (*types.Node, error) {
 	mach := types.Node{}
 	if result := tx.
@@ -149,32 +143,11 @@ func GetNodeByID(tx *gorm.DB, id types.NodeID) (*types.Node, error) {
 	return &mach, nil
 }
 
-func (hsdb *HSDatabase) GetNodeByMachineKey(machineKey key.MachinePublic) (*types.Node, error) {
-	return GetNodeByMachineKey(hsdb.DB, machineKey)
-}
-
-// GetNodeByMachineKey finds a Node by its MachineKey and returns the Node struct.
-func GetNodeByMachineKey(
-	tx *gorm.DB,
-	machineKey key.MachinePublic,
-) (*types.Node, error) {
-	mach := types.Node{}
-	if result := tx.
-		Preload("AuthKey").
-		Preload("AuthKey.User").
-		Preload("User").
-		First(&mach, "machine_key = ?", machineKey.String()); result.Error != nil {
-		return nil, result.Error
-	}
-
-	return &mach, nil
-}
-
 func (hsdb *HSDatabase) GetNodeByNodeKey(nodeKey key.NodePublic) (*types.Node, error) {
 	return GetNodeByNodeKey(hsdb.DB, nodeKey)
 }
 
-// GetNodeByNodeKey finds a Node by its NodeKey and returns the Node struct.
+// GetNodeByNodeKey finds a [types.Node] by its [key.NodePublic] and returns the [types.Node] struct.
 func GetNodeByNodeKey(
 	tx *gorm.DB,
 	nodeKey key.NodePublic,
@@ -191,87 +164,6 @@ func GetNodeByNodeKey(
 	return &mach, nil
 }
 
-func (hsdb *HSDatabase) SetTags(
-	nodeID types.NodeID,
-	tags []string,
-) error {
-	return hsdb.Write(func(tx *gorm.DB) error {
-		return SetTags(tx, nodeID, tags)
-	})
-}
-
-// SetTags takes a NodeID and update the forced tags.
-// It will overwrite any tags with the new list.
-func SetTags(
-	tx *gorm.DB,
-	nodeID types.NodeID,
-	tags []string,
-) error {
-	if len(tags) == 0 {
-		// if no tags are provided, we remove all tags
-		err := tx.Model(&types.Node{}).Where("id = ?", nodeID).Update("tags", "[]").Error
-		if err != nil {
-			return fmt.Errorf("removing tags: %w", err)
-		}
-
-		return nil
-	}
-
-	slices.Sort(tags)
-	tags = slices.Compact(tags)
-
-	b, err := json.Marshal(tags)
-	if err != nil {
-		return err
-	}
-
-	err = tx.Model(&types.Node{}).Where("id = ?", nodeID).Update("tags", string(b)).Error
-	if err != nil {
-		return fmt.Errorf("updating tags: %w", err)
-	}
-
-	return nil
-}
-
-// SetApprovedRoutes takes a Node struct pointer and updates the approved routes.
-func SetApprovedRoutes(
-	tx *gorm.DB,
-	nodeID types.NodeID,
-	routes []netip.Prefix,
-) error {
-	if len(routes) == 0 {
-		// if no routes are provided, we remove all
-		err := tx.Model(&types.Node{}).Where("id = ?", nodeID).Update("approved_routes", "[]").Error
-		if err != nil {
-			return fmt.Errorf("removing approved routes: %w", err)
-		}
-
-		return nil
-	}
-
-	// When approving exit routes, ensure both IPv4 and IPv6 are included
-	// If either 0.0.0.0/0 or ::/0 is being approved, both should be approved
-	hasIPv4Exit := slices.Contains(routes, tsaddr.AllIPv4())
-	hasIPv6Exit := slices.Contains(routes, tsaddr.AllIPv6())
-
-	if hasIPv4Exit && !hasIPv6Exit {
-		routes = append(routes, tsaddr.AllIPv6())
-	} else if hasIPv6Exit && !hasIPv4Exit {
-		routes = append(routes, tsaddr.AllIPv4())
-	}
-
-	b, err := json.Marshal(routes)
-	if err != nil {
-		return err
-	}
-
-	if err := tx.Model(&types.Node{}).Where("id = ?", nodeID).Update("approved_routes", string(b)).Error; err != nil { //nolint:noinlineerr
-		return fmt.Errorf("updating approved routes: %w", err)
-	}
-
-	return nil
-}
-
 // SetLastSeen sets a node's last seen field indicating that we
 // have recently communicating with this node.
 func (hsdb *HSDatabase) SetLastSeen(nodeID types.NodeID, lastSeen time.Time) error {
@@ -286,12 +178,12 @@ func SetLastSeen(tx *gorm.DB, nodeID types.NodeID, lastSeen time.Time) error {
 	return tx.Model(&types.Node{}).Where("id = ?", nodeID).Update("last_seen", lastSeen).Error
 }
 
-// RenameNode takes a Node struct and a new GivenName for the nodes
+// RenameNode takes a [types.Node] struct and a new [types.Node.GivenName] for the nodes
 // and renames it. Validation should be done in the state layer before calling this function.
 func RenameNode(tx *gorm.DB,
 	nodeID types.NodeID, newName string,
 ) error {
-	err := util.ValidateHostname(newName)
+	err := dnsname.ValidLabel(newName)
 	if err != nil {
 		return fmt.Errorf("renaming node: %w", err)
 	}
@@ -299,8 +191,7 @@ func RenameNode(tx *gorm.DB,
 	// Check if the new name is unique
 	var count int64
 
-	err = tx.Model(&types.Node{}).Where("given_name = ? AND id != ?", newName, nodeID).Count(&count).Error
-	if err != nil {
+	if err := tx.Model(&types.Node{}).Where("given_name = ? AND id != ?", newName, nodeID).Count(&count).Error; err != nil { //nolint:noinlineerr
 		return fmt.Errorf("checking name uniqueness: %w", err)
 	}
 
@@ -333,7 +224,7 @@ func (hsdb *HSDatabase) DeleteNode(node *types.Node) error {
 	})
 }
 
-// DeleteNode deletes a Node from the database.
+// DeleteNode deletes a [types.Node] from the database.
 // Caller is responsible for notifying all of change.
 func DeleteNode(tx *gorm.DB,
 	node *types.Node,
@@ -347,7 +238,7 @@ func DeleteNode(tx *gorm.DB,
 	return nil
 }
 
-// DeleteEphemeralNode deletes a Node from the database, note that this method
+// DeleteEphemeralNode deletes a [types.Node] from the database, note that this method
 // will remove it straight, and not notify any changes or consider any routes.
 // It is intended for Ephemeral nodes.
 func (hsdb *HSDatabase) DeleteEphemeralNode(
@@ -364,7 +255,7 @@ func (hsdb *HSDatabase) DeleteEphemeralNode(
 }
 
 // RegisterNodeForTest is used only for testing purposes to register a node directly in the database.
-// Production code should use state.HandleNodeFromAuthPath or state.HandleNodeFromPreAuthKey.
+// Production code should use [state.State.HandleNodeFromAuthPath] or [state.State.HandleNodeFromPreAuthKey].
 func RegisterNodeForTest(tx *gorm.DB, node types.Node, ipv4 *netip.Addr, ipv6 *netip.Addr) (*types.Node, error) {
 	if !testing.Testing() {
 		panic("RegisterNodeForTest can only be called during tests")
@@ -385,12 +276,16 @@ func RegisterNodeForTest(tx *gorm.DB, node types.Node, ipv4 *netip.Addr, ipv6 *n
 
 	logEvent.Msg("registering test node")
 
-	// If the a new node is registered with the same machine key, to the same user,
-	// update the existing node.
-	// If the same node is registered again, but to a new user, then that is considered
-	// a new node.
-	oldNode, _ := GetNodeByMachineKey(tx, node.MachineKey)
-	if oldNode != nil && oldNode.UserID == node.UserID {
+	// Reuse the existing node's identity only when the same machine
+	// re-registers for the same user; a different user is a new node. Match on
+	// (machine_key, user_id) precisely - a machine key can map to several nodes
+	// (one per user), so a machine-key-only lookup would be ambiguous.
+	var oldNode types.Node
+
+	err := tx.
+		Where("machine_key = ? AND user_id = ?", node.MachineKey.String(), node.UserID).
+		First(&oldNode).Error
+	if err == nil {
 		node.ID = oldNode.ID
 		node.GivenName = oldNode.GivenName
 		node.ApprovedRoutes = oldNode.ApprovedRoutes
@@ -427,22 +322,11 @@ func RegisterNodeForTest(tx *gorm.DB, node types.Node, ipv4 *netip.Addr, ipv6 *n
 	node.IPv4 = ipv4
 	node.IPv6 = ipv6
 
-	var err error
-
-	node.Hostname, err = util.NormaliseHostname(node.Hostname)
-	if err != nil {
-		newHostname := util.InvalidString()
-		log.Info().Err(err).Str(zf.InvalidHostname, node.Hostname).Str(zf.NewHostname, newHostname).Msgf("invalid hostname, replacing")
-		node.Hostname = newHostname
-	}
-
 	if node.GivenName == "" {
-		givenName, err := EnsureUniqueGivenName(tx, node.Hostname)
-		if err != nil {
-			return nil, fmt.Errorf("ensuring unique given name: %w", err)
+		node.GivenName = dnsname.SanitizeHostname(node.Hostname)
+		if node.GivenName == "" {
+			node.GivenName = "node"
 		}
-
-		node.GivenName = givenName
 	}
 
 	if err := tx.Save(&node).Error; err != nil { //nolint:noinlineerr
@@ -484,92 +368,47 @@ func NodeSetMachineKey(
 	}).Error
 }
 
-func generateGivenName(suppliedName string, randomSuffix bool) (string, error) {
-	// Strip invalid DNS characters for givenName
-	suppliedName = strings.ToLower(suppliedName)
-	suppliedName = invalidDNSRegex.ReplaceAllString(suppliedName, "")
-
-	if len(suppliedName) > util.LabelHostnameLength {
-		return "", types.ErrHostnameTooLong
-	}
-
-	if randomSuffix {
-		// Trim if a hostname will be longer than 63 chars after adding the hash.
-		trimmedHostnameLength := util.LabelHostnameLength - NodeGivenNameHashLength - NodeGivenNameTrimSize
-		if len(suppliedName) > trimmedHostnameLength {
-			suppliedName = suppliedName[:trimmedHostnameLength]
-		}
-
-		suffix, err := util.GenerateRandomStringDNSSafe(NodeGivenNameHashLength)
-		if err != nil {
-			return "", err
-		}
-
-		suppliedName += "-" + suffix
-	}
-
-	return suppliedName, nil
-}
-
-func isUniqueName(tx *gorm.DB, name string) (bool, error) {
-	nodes := types.Nodes{}
-
-	err := tx.
-		Where("given_name = ?", name).Find(&nodes).Error
-	if err != nil {
-		return false, err
-	}
-
-	return len(nodes) == 0, nil
-}
-
-// EnsureUniqueGivenName generates a unique given name for a node based on its hostname.
-func EnsureUniqueGivenName(
-	tx *gorm.DB,
-	name string,
-) (string, error) {
-	givenName, err := generateGivenName(name, false)
-	if err != nil {
-		return "", err
-	}
-
-	unique, err := isUniqueName(tx, givenName)
-	if err != nil {
-		return "", err
-	}
-
-	if !unique {
-		postfixedName, err := generateGivenName(name, true)
-		if err != nil {
-			return "", err
-		}
-
-		givenName = postfixedName
-	}
-
-	return givenName, nil
-}
-
 // EphemeralGarbageCollector is a garbage collector that will delete nodes after
 // a certain amount of time.
-// It is used to delete ephemeral nodes that have disconnected and should be
+// It is used to delete ephemeral nodes ([types.Node.IsEphemeral]) that have disconnected and should be
 // cleaned up.
 type EphemeralGarbageCollector struct {
 	mu sync.Mutex
 
 	deleteFunc  func(types.NodeID)
-	toBeDeleted map[types.NodeID]*time.Timer
+	toBeDeleted map[types.NodeID]ephemeralTimer
+	// gen is bumped for every scheduled deletion so a queued deletion that
+	// was superseded by a Cancel or reschedule can be recognised and dropped.
+	gen uint64
 
-	deleteCh chan types.NodeID
+	deleteCh chan pendingDeletion
 	cancelCh chan struct{}
 }
 
-// NewEphemeralGarbageCollector creates a new EphemeralGarbageCollector, it takes
+// ephemeralTimer pairs a node's pending-deletion timer with a done channel
+// used to reap its watcher goroutine on Cancel or reschedule, plus the
+// generation identifying this particular scheduling. Without the done channel
+// a stopped timer never fires and the goroutine leaks until Close.
+type ephemeralTimer struct {
+	timer *time.Timer
+	done  chan struct{}
+	gen   uint64
+}
+
+// pendingDeletion is the generation-stamped deletion a watcher enqueues when
+// its timer fires. Start drops it if the node's current generation no longer
+// matches, i.e. it was cancelled or rescheduled in the meantime.
+type pendingDeletion struct {
+	nodeID types.NodeID
+	gen    uint64
+}
+
+// NewEphemeralGarbageCollector creates a new [EphemeralGarbageCollector], it takes
 // a deleteFunc that will be called when a node is scheduled for deletion.
 func NewEphemeralGarbageCollector(deleteFunc func(types.NodeID)) *EphemeralGarbageCollector {
 	return &EphemeralGarbageCollector{
-		toBeDeleted: make(map[types.NodeID]*time.Timer),
-		deleteCh:    make(chan types.NodeID, 10),
+		toBeDeleted: make(map[types.NodeID]ephemeralTimer),
+		deleteCh:    make(chan pendingDeletion, 10),
 		cancelCh:    make(chan struct{}),
 		deleteFunc:  deleteFunc,
 	}
@@ -581,8 +420,8 @@ func (e *EphemeralGarbageCollector) Close() {
 	defer e.mu.Unlock()
 
 	// Stop all timers
-	for _, timer := range e.toBeDeleted {
-		timer.Stop()
+	for _, t := range e.toBeDeleted {
+		t.timer.Stop()
 	}
 
 	// Close the cancel channel to signal all goroutines to exit
@@ -605,13 +444,18 @@ func (e *EphemeralGarbageCollector) Schedule(nodeID types.NodeID, expiry time.Du
 		// Continue with scheduling
 	}
 
-	// If a timer already exists for this node, stop it first
-	if oldTimer, exists := e.toBeDeleted[nodeID]; exists {
-		oldTimer.Stop()
+	// If a timer already exists for this node, stop it and reap its
+	// watcher goroutine before scheduling a fresh one.
+	if old, exists := e.toBeDeleted[nodeID]; exists {
+		old.timer.Stop()
+		close(old.done)
 	}
 
+	e.gen++
+	gen := e.gen
 	timer := time.NewTimer(expiry)
-	e.toBeDeleted[nodeID] = timer
+	done := make(chan struct{})
+	e.toBeDeleted[nodeID] = ephemeralTimer{timer: timer, done: done, gen: gen}
 	// Start a goroutine to handle the timer completion
 	go func() {
 		select {
@@ -621,12 +465,18 @@ func (e *EphemeralGarbageCollector) Schedule(nodeID types.NodeID, expiry time.Du
 			// i.e. We don't want to send to deleteCh if the GC is shutting down
 			// So, we try to send to deleteCh, but also watch for cancelCh
 			select {
-			case e.deleteCh <- nodeID:
+			case e.deleteCh <- pendingDeletion{nodeID: nodeID, gen: gen}:
 				// Successfully sent to deleteCh
 			case <-e.cancelCh:
 				// GC is shutting down, don't send to deleteCh
 				return
+			case <-done:
+				// Cancelled or rescheduled before the send landed.
+				return
 			}
+		case <-done:
+			// Cancelled or rescheduled before the timer fired.
+			return
 		case <-e.cancelCh:
 			// If the GC is closed, exit the goroutine
 			return
@@ -639,8 +489,9 @@ func (e *EphemeralGarbageCollector) Cancel(nodeID types.NodeID) {
 	e.mu.Lock()
 	defer e.mu.Unlock()
 
-	if timer, ok := e.toBeDeleted[nodeID]; ok {
-		timer.Stop()
+	if t, ok := e.toBeDeleted[nodeID]; ok {
+		t.timer.Stop()
+		close(t.done)
 		delete(e.toBeDeleted, nodeID)
 	}
 }
@@ -651,12 +502,22 @@ func (e *EphemeralGarbageCollector) Start() {
 		select {
 		case <-e.cancelCh:
 			return
-		case nodeID := <-e.deleteCh:
+		case pd := <-e.deleteCh:
 			e.mu.Lock()
-			delete(e.toBeDeleted, nodeID)
+
+			entry, ok := e.toBeDeleted[pd.nodeID]
+			if !ok || entry.gen != pd.gen {
+				// Cancelled or rescheduled after this deletion was queued;
+				// drop it so a reconnected node is not removed.
+				e.mu.Unlock()
+
+				continue
+			}
+
+			delete(e.toBeDeleted, pd.nodeID)
 			e.mu.Unlock()
 
-			go e.deleteFunc(nodeID)
+			go e.deleteFunc(pd.nodeID)
 		}
 	}
 }

hscontrol/db/node_test.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"math/big"
 	"net/netip"
-	"regexp"
 	"runtime"
 	"sync"
 	"sync/atomic"
@@ -179,171 +178,6 @@ func TestDisableNodeExpiry(t *testing.T) {
 	assert.Nil(t, nodeFromDB.Expiry, "expiry should be nil after disabling")
 }
 
-func TestSetTags(t *testing.T) {
-	db, err := newSQLiteTestDB()
-	require.NoError(t, err)
-
-	user, err := db.CreateUser(types.User{Name: "test"})
-	require.NoError(t, err)
-
-	pak, err := db.CreatePreAuthKey(user.TypedID(), false, false, nil, nil)
-	require.NoError(t, err)
-
-	pakID := pak.ID
-
-	_, err = db.getNode(types.UserID(user.ID), "testnode")
-	require.Error(t, err)
-
-	nodeKey := key.NewNode()
-	machineKey := key.NewMachine()
-
-	node := &types.Node{
-		ID:             0,
-		MachineKey:     machineKey.Public(),
-		NodeKey:        nodeKey.Public(),
-		Hostname:       "testnode",
-		UserID:         &user.ID,
-		RegisterMethod: util.RegisterMethodAuthKey,
-		AuthKeyID:      &pakID,
-	}
-
-	trx := db.DB.Save(node)
-	require.NoError(t, trx.Error)
-
-	// assign simple tags
-	sTags := []string{"tag:test", "tag:foo"}
-	err = db.SetTags(node.ID, sTags)
-	require.NoError(t, err)
-	node, err = db.getNode(types.UserID(user.ID), "testnode")
-	require.NoError(t, err)
-	assert.Equal(t, sTags, node.Tags)
-
-	// assign duplicate tags, expect no errors but no doubles in DB
-	eTags := []string{"tag:bar", "tag:test", "tag:unknown", "tag:test"}
-	err = db.SetTags(node.ID, eTags)
-	require.NoError(t, err)
-	node, err = db.getNode(types.UserID(user.ID), "testnode")
-	require.NoError(t, err)
-	assert.Equal(t, []string{"tag:bar", "tag:test", "tag:unknown"}, node.Tags)
-}
-
-func TestHeadscale_generateGivenName(t *testing.T) {
-	type args struct {
-		suppliedName string
-		randomSuffix bool
-	}
-
-	tests := []struct {
-		name    string
-		args    args
-		want    *regexp.Regexp
-		wantErr bool
-	}{
-		{
-			name: "simple node name generation",
-			args: args{
-				suppliedName: "testnode",
-				randomSuffix: false,
-			},
-			want:    regexp.MustCompile("^testnode$"),
-			wantErr: false,
-		},
-		{
-			name: "UPPERCASE node name generation",
-			args: args{
-				suppliedName: "TestNode",
-				randomSuffix: false,
-			},
-			want:    regexp.MustCompile("^testnode$"),
-			wantErr: false,
-		},
-		{
-			name: "node name with 53 chars",
-			args: args{
-				suppliedName: "testmaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaachine",
-				randomSuffix: false,
-			},
-			want:    regexp.MustCompile("^testmaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaachine$"),
-			wantErr: false,
-		},
-		{
-			name: "node name with 63 chars",
-			args: args{
-				suppliedName: "nodeeeeeee12345678901234567890123456789012345678901234567890123",
-				randomSuffix: false,
-			},
-			want:    regexp.MustCompile("^nodeeeeeee12345678901234567890123456789012345678901234567890123$"),
-			wantErr: false,
-		},
-		{
-			name: "node name with 64 chars",
-			args: args{
-				suppliedName: "nodeeeeeee123456789012345678901234567890123456789012345678901234",
-				randomSuffix: false,
-			},
-			want:    nil,
-			wantErr: true,
-		},
-		{
-			name: "node name with 73 chars",
-			args: args{
-				suppliedName: "nodeeeeeee123456789012345678901234567890123456789012345678901234567890123",
-				randomSuffix: false,
-			},
-			want:    nil,
-			wantErr: true,
-		},
-		{
-			name: "node name with random suffix",
-			args: args{
-				suppliedName: "test",
-				randomSuffix: true,
-			},
-			want:    regexp.MustCompile(fmt.Sprintf("^test-[a-z0-9]{%d}$", NodeGivenNameHashLength)),
-			wantErr: false,
-		},
-		{
-			name: "node name with 63 chars with random suffix",
-			args: args{
-				suppliedName: "nodeeee12345678901234567890123456789012345678901234567890123",
-				randomSuffix: true,
-			},
-			want:    regexp.MustCompile(fmt.Sprintf("^nodeeee1234567890123456789012345678901234567890123456-[a-z0-9]{%d}$", NodeGivenNameHashLength)),
-			wantErr: false,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got, err := generateGivenName(tt.args.suppliedName, tt.args.randomSuffix)
-			if (err != nil) != tt.wantErr {
-				t.Errorf(
-					"Headscale.GenerateGivenName() error = %v, wantErr %v",
-					err,
-					tt.wantErr,
-				)
-
-				return
-			}
-
-			if tt.want != nil && !tt.want.MatchString(got) {
-				t.Errorf(
-					"Headscale.GenerateGivenName() = %v, does not match %v",
-					tt.want,
-					got,
-				)
-			}
-
-			if len(got) > util.LabelHostnameLength {
-				t.Errorf(
-					"Headscale.GenerateGivenName() = %v is larger than allowed DNS segment %d",
-					got,
-					util.LabelHostnameLength,
-				)
-			}
-		})
-	}
-}
-
 func TestAutoApproveRoutes(t *testing.T) {
 	tests := []struct {
 		name         string
@@ -526,13 +360,15 @@ func TestAutoApproveRoutes(t *testing.T) {
 				assert.Equal(t, tt.expectChange, changed1)
 
 				if changed1 {
-					err = SetApprovedRoutes(adb.DB, node.ID, newRoutes1)
+					node.ApprovedRoutes = types.Prefixes(newRoutes1)
+					err = adb.DB.Save(&node).Error
 					require.NoError(t, err)
 				}
 
 				newRoutes2, changed2 := policy.ApproveRoutesWithPolicy(pm, nodeTagged.View(), nodeTagged.ApprovedRoutes, tt.routes)
 				if changed2 {
-					err = SetApprovedRoutes(adb.DB, nodeTagged.ID, newRoutes2)
+					nodeTagged.ApprovedRoutes = types.Prefixes(newRoutes2)
+					err = adb.DB.Save(&nodeTagged).Error
 					require.NoError(t, err)
 				}
 
@@ -633,7 +469,7 @@ func TestEphemeralGarbageCollectorLoads(t *testing.T) {
 
 	want := 1000
 
-	var deletedCount int64
+	var deletedCount atomic.Int64
 
 	e := NewEphemeralGarbageCollector(func(ni types.NodeID) {
 		mu.Lock()
@@ -644,7 +480,7 @@ func TestEphemeralGarbageCollectorLoads(t *testing.T) {
 
 		got = append(got, ni)
 
-		atomic.AddInt64(&deletedCount, 1)
+		deletedCount.Add(1)
 	})
 	go e.Start()
 
@@ -655,7 +491,7 @@ func TestEphemeralGarbageCollectorLoads(t *testing.T) {
 
 	// Wait for all deletions to complete
 	assert.EventuallyWithT(t, func(c *assert.CollectT) {
-		count := atomic.LoadInt64(&deletedCount)
+		count := deletedCount.Load()
 		assert.Equal(c, int64(want), count, "all nodes should be deleted")
 	}, 10*time.Second, 50*time.Millisecond, "waiting for all deletions")
 
@@ -742,282 +578,6 @@ func TestListEphemeralNodes(t *testing.T) {
 	assert.Equal(t, nodeEph.Hostname, ephemeralNodes[0].Hostname)
 }
 
-func TestNodeNaming(t *testing.T) {
-	db, err := newSQLiteTestDB()
-	if err != nil {
-		t.Fatalf("creating db: %s", err)
-	}
-
-	user, err := db.CreateUser(types.User{Name: "test"})
-	require.NoError(t, err)
-
-	user2, err := db.CreateUser(types.User{Name: "user2"})
-	require.NoError(t, err)
-
-	node := types.Node{
-		ID:             0,
-		MachineKey:     key.NewMachine().Public(),
-		NodeKey:        key.NewNode().Public(),
-		Hostname:       "test",
-		UserID:         &user.ID,
-		RegisterMethod: util.RegisterMethodAuthKey,
-		Hostinfo:       &tailcfg.Hostinfo{},
-	}
-
-	node2 := types.Node{
-		ID:             0,
-		MachineKey:     key.NewMachine().Public(),
-		NodeKey:        key.NewNode().Public(),
-		Hostname:       "test",
-		UserID:         &user2.ID,
-		RegisterMethod: util.RegisterMethodAuthKey,
-		Hostinfo:       &tailcfg.Hostinfo{},
-	}
-
-	// Using non-ASCII characters in the hostname can
-	// break your network, so they should be replaced when registering
-	// a node.
-	// https://github.com/juanfont/headscale/issues/2343
-	nodeInvalidHostname := types.Node{
-		MachineKey:     key.NewMachine().Public(),
-		NodeKey:        key.NewNode().Public(),
-		Hostname:       "我的电脑", //nolint:gosmopolitan // intentional i18n test data
-		UserID:         &user2.ID,
-		RegisterMethod: util.RegisterMethodAuthKey,
-	}
-
-	nodeShortHostname := types.Node{
-		MachineKey:     key.NewMachine().Public(),
-		NodeKey:        key.NewNode().Public(),
-		Hostname:       "a",
-		UserID:         &user2.ID,
-		RegisterMethod: util.RegisterMethodAuthKey,
-	}
-
-	err = db.DB.Save(&node).Error
-	require.NoError(t, err)
-
-	err = db.DB.Save(&node2).Error
-	require.NoError(t, err)
-
-	err = db.DB.Transaction(func(tx *gorm.DB) error {
-		_, err := RegisterNodeForTest(tx, node, nil, nil)
-		if err != nil {
-			return err
-		}
-
-		_, err = RegisterNodeForTest(tx, node2, nil, nil)
-		if err != nil {
-			return err
-		}
-
-		_, _ = RegisterNodeForTest(tx, nodeInvalidHostname, new(mpp("100.64.0.66/32").Addr()), nil)
-		_, err = RegisterNodeForTest(tx, nodeShortHostname, new(mpp("100.64.0.67/32").Addr()), nil)
-
-		return err
-	})
-	require.NoError(t, err)
-
-	nodes, err := db.ListNodes()
-	require.NoError(t, err)
-
-	assert.Len(t, nodes, 4)
-
-	t.Logf("node1 %s %s", nodes[0].Hostname, nodes[0].GivenName)
-	t.Logf("node2 %s %s", nodes[1].Hostname, nodes[1].GivenName)
-	t.Logf("node3 %s %s", nodes[2].Hostname, nodes[2].GivenName)
-	t.Logf("node4 %s %s", nodes[3].Hostname, nodes[3].GivenName)
-
-	assert.Equal(t, nodes[0].Hostname, nodes[0].GivenName)
-	assert.NotEqual(t, nodes[1].Hostname, nodes[1].GivenName)
-	assert.Equal(t, nodes[0].Hostname, nodes[1].Hostname)
-	assert.NotEqual(t, nodes[0].Hostname, nodes[1].GivenName)
-	assert.Contains(t, nodes[1].GivenName, nodes[0].Hostname)
-	assert.Equal(t, nodes[0].GivenName, nodes[1].Hostname)
-	assert.Len(t, nodes[0].Hostname, 4)
-	assert.Len(t, nodes[1].Hostname, 4)
-	assert.Len(t, nodes[0].GivenName, 4)
-	assert.Len(t, nodes[1].GivenName, 13)
-	assert.Contains(t, nodes[2].Hostname, "invalid-") // invalid chars
-	assert.Contains(t, nodes[2].GivenName, "invalid-")
-	assert.Contains(t, nodes[3].Hostname, "invalid-") // too short
-	assert.Contains(t, nodes[3].GivenName, "invalid-")
-
-	// Nodes can be renamed to a unique name
-	err = db.Write(func(tx *gorm.DB) error {
-		return RenameNode(tx, nodes[0].ID, "newname")
-	})
-	require.NoError(t, err)
-
-	nodes, err = db.ListNodes()
-	require.NoError(t, err)
-	assert.Len(t, nodes, 4)
-	assert.Equal(t, "test", nodes[0].Hostname)
-	assert.Equal(t, "newname", nodes[0].GivenName)
-
-	// Nodes can reuse name that is no longer used
-	err = db.Write(func(tx *gorm.DB) error {
-		return RenameNode(tx, nodes[1].ID, "test")
-	})
-	require.NoError(t, err)
-
-	nodes, err = db.ListNodes()
-	require.NoError(t, err)
-	assert.Len(t, nodes, 4)
-	assert.Equal(t, "test", nodes[0].Hostname)
-	assert.Equal(t, "newname", nodes[0].GivenName)
-	assert.Equal(t, "test", nodes[1].GivenName)
-
-	// Nodes cannot be renamed to used names
-	err = db.Write(func(tx *gorm.DB) error {
-		return RenameNode(tx, nodes[0].ID, "test")
-	})
-	require.ErrorContains(t, err, "name is not unique")
-
-	// Rename invalid chars
-	err = db.Write(func(tx *gorm.DB) error {
-		return RenameNode(tx, nodes[2].ID, "我的电脑") //nolint:gosmopolitan // intentional i18n test data
-	})
-	require.ErrorContains(t, err, "invalid characters")
-
-	// Rename too short
-	err = db.Write(func(tx *gorm.DB) error {
-		return RenameNode(tx, nodes[3].ID, "a")
-	})
-	require.ErrorContains(t, err, "at least 2 characters")
-
-	// Rename with emoji
-	err = db.Write(func(tx *gorm.DB) error {
-		return RenameNode(tx, nodes[0].ID, "hostname-with-💩")
-	})
-	require.ErrorContains(t, err, "invalid characters")
-
-	// Rename with only emoji
-	err = db.Write(func(tx *gorm.DB) error {
-		return RenameNode(tx, nodes[0].ID, "🚀")
-	})
-	assert.ErrorContains(t, err, "invalid characters")
-}
-
-func TestRenameNodeComprehensive(t *testing.T) {
-	db, err := newSQLiteTestDB()
-	if err != nil {
-		t.Fatalf("creating db: %s", err)
-	}
-
-	user, err := db.CreateUser(types.User{Name: "test"})
-	require.NoError(t, err)
-
-	node := types.Node{
-		ID:             0,
-		MachineKey:     key.NewMachine().Public(),
-		NodeKey:        key.NewNode().Public(),
-		Hostname:       "testnode",
-		UserID:         &user.ID,
-		RegisterMethod: util.RegisterMethodAuthKey,
-		Hostinfo:       &tailcfg.Hostinfo{},
-	}
-
-	err = db.DB.Save(&node).Error
-	require.NoError(t, err)
-
-	err = db.DB.Transaction(func(tx *gorm.DB) error {
-		_, err := RegisterNodeForTest(tx, node, nil, nil)
-		return err
-	})
-	require.NoError(t, err)
-
-	nodes, err := db.ListNodes()
-	require.NoError(t, err)
-	assert.Len(t, nodes, 1)
-
-	tests := []struct {
-		name    string
-		newName string
-		wantErr string
-	}{
-		{
-			name:    "uppercase_rejected",
-			newName: "User2-Host",
-			wantErr: "must be lowercase",
-		},
-		{
-			name:    "underscore_rejected",
-			newName: "test_node",
-			wantErr: "invalid characters",
-		},
-		{
-			name:    "at_sign_uppercase_rejected",
-			newName: "Test@Host",
-			wantErr: "must be lowercase",
-		},
-		{
-			name:    "at_sign_rejected",
-			newName: "test@host",
-			wantErr: "invalid characters",
-		},
-		{
-			name:    "chinese_chars_with_dash_rejected",
-			newName: "server-北京-01", //nolint:gosmopolitan // intentional i18n test data
-			wantErr: "invalid characters",
-		},
-		{
-			name:    "chinese_only_rejected",
-			newName: "我的电脑", //nolint:gosmopolitan // intentional i18n test data
-			wantErr: "invalid characters",
-		},
-		{
-			name:    "emoji_with_text_rejected",
-			newName: "laptop-🚀",
-			wantErr: "invalid characters",
-		},
-		{
-			name:    "mixed_chinese_emoji_rejected",
-			newName: "测试💻机器", //nolint:gosmopolitan // intentional i18n test data
-			wantErr: "invalid characters",
-		},
-		{
-			name:    "only_emojis_rejected",
-			newName: "🎉🎊",
-			wantErr: "invalid characters",
-		},
-		{
-			name:    "only_at_signs_rejected",
-			newName: "@@@",
-			wantErr: "invalid characters",
-		},
-		{
-			name:    "starts_with_dash_rejected",
-			newName: "-test",
-			wantErr: "cannot start or end with a hyphen",
-		},
-		{
-			name:    "ends_with_dash_rejected",
-			newName: "test-",
-			wantErr: "cannot start or end with a hyphen",
-		},
-		{
-			name:    "too_long_hostname_rejected",
-			newName: "this-is-a-very-long-hostname-that-exceeds-sixty-three-characters-limit",
-			wantErr: "must not exceed 63 characters",
-		},
-		{
-			name:    "too_short_hostname_rejected",
-			newName: "a",
-			wantErr: "at least 2 characters",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			err := db.Write(func(tx *gorm.DB) error {
-				return RenameNode(tx, nodes[0].ID, tt.newName)
-			})
-			assert.ErrorContains(t, err, tt.wantErr)
-		})
-	}
-}
-
 func TestListPeers(t *testing.T) {
 	// Setup test database
 	db, err := newSQLiteTestDB()

hscontrol/db/policy.go

@@ -31,7 +31,7 @@ func (hsdb *HSDatabase) GetPolicy() (*types.Policy, error) {
 }
 
 // GetPolicy returns the latest policy from the database.
-// This standalone function can be used in contexts where HSDatabase is not available,
+// This standalone function can be used in contexts where [HSDatabase] is not available,
 // such as during migrations.
 func GetPolicy(tx *gorm.DB) (*types.Policy, error) {
 	var p types.Policy
@@ -55,7 +55,7 @@ func GetPolicy(tx *gorm.DB) (*types.Policy, error) {
 
 // PolicyBytes loads policy configuration from file or database based on the configured mode.
 // Returns nil if no policy is configured, which is valid.
-// This standalone function can be used in contexts where HSDatabase is not available,
+// This standalone function can be used in contexts where [HSDatabase] is not available,
 // such as during migrations.
 func PolicyBytes(tx *gorm.DB, cfg *types.Config) ([]byte, error) {
 	switch cfg.Policy.Mode {

hscontrol/db/preauth_keys.go

@@ -15,7 +15,10 @@ import (
 )
 
 var (
-	ErrPreAuthKeyNotFound          = errors.New("auth-key not found")
+	// ErrPreAuthKeyNotFound wraps gorm.ErrRecordNotFound so an unknown or
+	// deleted key is treated as a missing record by callers, which the
+	// registration handler maps to a 401 rather than a raw server error.
+	ErrPreAuthKeyNotFound          = fmt.Errorf("auth-key not found: %w", gorm.ErrRecordNotFound)
 	ErrPreAuthKeyExpired           = errors.New("auth-key expired")
 	ErrSingleUseAuthKeyHasBeenUsed = errors.New("auth-key has already been used")
 	ErrUserMismatch                = errors.New("user mismatch")
@@ -40,7 +43,7 @@ const (
 	authKeyLength       = 64
 )
 
-// CreatePreAuthKey creates a new PreAuthKey in a user, and returns it.
+// CreatePreAuthKey creates a new [types.PreAuthKey] in a user, and returns it.
 // The uid parameter can be nil for system-created tagged keys.
 // For tagged keys, uid tracks "created by" (who created the key).
 // For user-owned keys, uid tracks the node owner.
@@ -158,7 +161,7 @@ func (hsdb *HSDatabase) ListPreAuthKeys() ([]types.PreAuthKey, error) {
 	return Read(hsdb.DB, ListPreAuthKeys)
 }
 
-// ListPreAuthKeys returns all PreAuthKeys in the database.
+// ListPreAuthKeys returns all [types.PreAuthKey] values in the database.
 func ListPreAuthKeys(tx *gorm.DB) ([]types.PreAuthKey, error) {
 	var keys []types.PreAuthKey
 
@@ -170,7 +173,7 @@ func ListPreAuthKeys(tx *gorm.DB) ([]types.PreAuthKey, error) {
 	return keys, nil
 }
 
-// ListPreAuthKeysByUser returns all PreAuthKeys belonging to a specific user.
+// ListPreAuthKeysByUser returns all [types.PreAuthKey] values belonging to a specific user.
 func ListPreAuthKeysByUser(tx *gorm.DB, uid types.UserID) ([]types.PreAuthKey, error) {
 	var keys []types.PreAuthKey
 
@@ -290,13 +293,13 @@ func (hsdb *HSDatabase) GetPreAuthKey(key string) (*types.PreAuthKey, error) {
 	return GetPreAuthKey(hsdb.DB, key)
 }
 
-// GetPreAuthKey returns a PreAuthKey for a given key. The caller is responsible
+// GetPreAuthKey returns a [types.PreAuthKey] for a given key. The caller is responsible
 // for checking if the key is usable (expired or used).
 func GetPreAuthKey(tx *gorm.DB, key string) (*types.PreAuthKey, error) {
 	return findAuthKey(tx, key)
 }
 
-// DestroyPreAuthKey destroys a preauthkey. Returns error if the PreAuthKey
+// DestroyPreAuthKey destroys a preauthkey. Returns error if the [types.PreAuthKey]
 // does not exist. This also clears the auth_key_id on any nodes that reference
 // this key.
 func DestroyPreAuthKey(tx *gorm.DB, id uint64) error {
@@ -331,10 +334,10 @@ func (hsdb *HSDatabase) DeletePreAuthKey(id uint64) error {
 	})
 }
 
-// UsePreAuthKey atomically marks a PreAuthKey as used. The UPDATE is
+// UsePreAuthKey atomically marks a [types.PreAuthKey] as used. The UPDATE is
 // guarded by `used = false` so two concurrent registrations racing for
 // the same single-use key cannot both succeed: the first commits and
-// the second returns PAKError("authkey already used"). Without the
+// the second returns [types.PAKError]("authkey already used"). Without the
 // guard the previous code (Update("used", true) with no WHERE) would
 // silently let both transactions claim the key.
 func UsePreAuthKey(tx *gorm.DB, k *types.PreAuthKey) error {
@@ -354,7 +357,7 @@ func UsePreAuthKey(tx *gorm.DB, k *types.PreAuthKey) error {
 	return nil
 }
 
-// ExpirePreAuthKey marks a PreAuthKey as expired.
+// ExpirePreAuthKey marks a [types.PreAuthKey] as expired.
 func ExpirePreAuthKey(tx *gorm.DB, id uint64) error {
 	now := time.Now()
 	return tx.Model(&types.PreAuthKey{}).Where("id = ?", id).Update("expiration", now).Error

hscontrol/db/preauth_keys_test.go

@@ -487,3 +487,16 @@ func TestUsePreAuthKeyAtomicCAS(t *testing.T) {
 		"second UsePreAuthKey error must be a PAKError, got: %v", err)
 	assert.Equal(t, "authkey already used", pakErr.Error())
 }
+
+// TestGetPreAuthKeyUnknownMapsToRecordNotFound ensures an unknown (or deleted)
+// pre-auth key resolves to a record-not-found error, which the registration
+// handler maps to a 401 rather than a raw server error.
+func TestGetPreAuthKeyUnknownMapsToRecordNotFound(t *testing.T) {
+	db, err := newSQLiteTestDB()
+	require.NoError(t, err)
+
+	_, err = db.GetPreAuthKey("nonexistent-key")
+	require.Error(t, err)
+	require.ErrorIs(t, err, gorm.ErrRecordNotFound,
+		"unknown pre-auth key must map to record-not-found (handled as 401)")
+}

hscontrol/db/randomnext_test.go

@@ -0,0 +1,35 @@
+package db
+
+import (
+	"net/netip"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestRandomNextSingleAddressPrefix ensures a single-address prefix (/32 or
+// /128) does not panic. from == to makes the random range zero, and rand.Int
+// panics on a non-positive bound; the sole address must be returned instead.
+func TestRandomNextSingleAddressPrefix(t *testing.T) {
+	for _, p := range []string{"100.64.0.1/32", "fd7a:115c:a1e0::1/128"} {
+		pfx := netip.MustParsePrefix(p)
+		require.NotPanics(t, func() {
+			ip, err := randomNext(pfx)
+			require.NoError(t, err)
+			assert.Equal(t, pfx.Addr(), ip)
+		}, "prefix %s", p)
+	}
+}
+
+// TestRandomNextLeadingZeroBytes ensures prefixes whose addresses have a zero
+// high byte allocate successfully. big.Int.Bytes() strips leading zeros, so the
+// drawn value would be too short for netip.AddrFromSlice without padding.
+func TestRandomNextLeadingZeroBytes(t *testing.T) {
+	pfx := netip.MustParsePrefix("0.0.0.0/16")
+	for range 100 {
+		ip, err := randomNext(pfx)
+		require.NoError(t, err)
+		assert.True(t, pfx.Contains(ip), "ip %s not in %s", ip, pfx)
+	}
+}

hscontrol/db/testdata/sqlite/null_tags_user_id_migration_test.sql

@@ -0,0 +1,85 @@
+-- Test SQL dump for the clear-tagged-node-user-id migration
+-- (202602201200-clear-tagged-node-user-id) against nodes whose tags
+-- column holds the JSON literal 'null'.
+--
+-- A nil Strings slice marshals to the JSON literal `null`, so pre-0.29
+-- databases contain untagged nodes with tags='null'. The migration's
+-- WHERE clause (tags IS NOT NULL AND tags != '[]' AND tags != '') treats
+-- the 4-character string 'null' as "tagged" and wrongly clears user_id,
+-- detaching the node from its owning user on upgrade.
+-- Fixes: https://github.com/juanfont/headscale/issues/3323
+
+PRAGMA foreign_keys=OFF;
+BEGIN TRANSACTION;
+
+-- Migrations table: every entry BEFORE clear-tagged-node-user-id has been
+-- applied. That migration is intentionally absent so it runs against this dump.
+CREATE TABLE `migrations` (`id` text,PRIMARY KEY (`id`));
+INSERT INTO migrations VALUES('202312101416');
+INSERT INTO migrations VALUES('202312101430');
+INSERT INTO migrations VALUES('202402151347');
+INSERT INTO migrations VALUES('2024041121742');
+INSERT INTO migrations VALUES('202406021630');
+INSERT INTO migrations VALUES('202409271400');
+INSERT INTO migrations VALUES('202407191627');
+INSERT INTO migrations VALUES('202408181235');
+INSERT INTO migrations VALUES('202501221827');
+INSERT INTO migrations VALUES('202501311657');
+INSERT INTO migrations VALUES('202502070949');
+INSERT INTO migrations VALUES('202502131714');
+INSERT INTO migrations VALUES('202502171819');
+INSERT INTO migrations VALUES('202505091439');
+INSERT INTO migrations VALUES('202505141324');
+INSERT INTO migrations VALUES('202507021200');
+INSERT INTO migrations VALUES('202510311551');
+INSERT INTO migrations VALUES('202511101554-drop-old-idx');
+INSERT INTO migrations VALUES('202511011637-preauthkey-bcrypt');
+INSERT INTO migrations VALUES('202511122344-remove-newline-index');
+INSERT INTO migrations VALUES('202511131445-node-forced-tags-to-tags');
+INSERT INTO migrations VALUES('202601121700-migrate-hostinfo-request-tags');
+
+-- Users table
+CREATE TABLE `users` (`id` integer PRIMARY KEY AUTOINCREMENT,`created_at` datetime,`updated_at` datetime,`deleted_at` datetime,`name` text,`display_name` text,`email` text,`provider_identifier` text,`provider` text,`profile_pic_url` text);
+INSERT INTO users VALUES(1,'2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL,'user1','User One','user1@example.com',NULL,NULL,NULL);
+INSERT INTO users VALUES(2,'2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL,'user2','User Two','user2@example.com',NULL,NULL,NULL);
+
+-- Pre-auth keys table
+CREATE TABLE `pre_auth_keys` (`id` integer PRIMARY KEY AUTOINCREMENT,`key` text,`user_id` integer,`reusable` numeric,`ephemeral` numeric DEFAULT false,`used` numeric DEFAULT false,`tags` text,`created_at` datetime,`expiration` datetime,`prefix` text,`hash` blob,CONSTRAINT `fk_pre_auth_keys_user` FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE SET NULL);
+
+-- API keys table
+CREATE TABLE `api_keys` (`id` integer PRIMARY KEY AUTOINCREMENT,`prefix` text,`hash` blob,`created_at` datetime,`expiration` datetime,`last_seen` datetime);
+
+-- Nodes table - current schema (after the tags rename + last_seen/expiry reordering)
+CREATE TABLE IF NOT EXISTS "nodes" (`id` integer PRIMARY KEY AUTOINCREMENT,`machine_key` text,`node_key` text,`disco_key` text,`endpoints` text,`host_info` text,`ipv4` text,`ipv6` text,`hostname` text,`given_name` varchar(63),`user_id` integer,`register_method` text,`tags` text,`auth_key_id` integer,`last_seen` datetime,`expiry` datetime,`approved_routes` text,`created_at` datetime,`updated_at` datetime,`deleted_at` datetime,CONSTRAINT `fk_nodes_user` FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE,CONSTRAINT `fk_nodes_auth_key` FOREIGN KEY (`auth_key_id`) REFERENCES `pre_auth_keys`(`id`));
+
+-- Node 1: tags='null' (untagged, nil slice marshalled to JSON null), owned by user2.
+-- After migration: user_id MUST be preserved (this is the bug).
+INSERT INTO nodes VALUES(1,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e01','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605501','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57701','[]','{}','100.64.0.1','fd7a:115c:a1e0::1','node1','node1',2,'cli','null',NULL,'2024-01-01 00:00:00+00:00',NULL,'[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 2: genuinely tagged, owned by user1.
+-- After migration: user_id MUST be cleared to NULL (tagged nodes are owned by tags).
+INSERT INTO nodes VALUES(2,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e02','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605502','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57702','[]','{}','100.64.0.2','fd7a:115c:a1e0::2','node2','node2',1,'cli','["tag:server"]',NULL,'2024-01-01 00:00:00+00:00',NULL,'[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 3: empty-array tags (untagged), owned by user1.
+-- After migration: user_id MUST be preserved.
+INSERT INTO nodes VALUES(3,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e03','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605503','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57703','[]','{}','100.64.0.3','fd7a:115c:a1e0::3','node3','node3',1,'cli','[]',NULL,'2024-01-01 00:00:00+00:00',NULL,'[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 4: empty-string tags (untagged), owned by user1.
+-- After migration: user_id MUST be preserved.
+INSERT INTO nodes VALUES(4,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e04','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605504','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57704','[]','{}','100.64.0.4','fd7a:115c:a1e0::4','node4','node4',1,'cli','',NULL,'2024-01-01 00:00:00+00:00',NULL,'[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Policies table (empty)
+CREATE TABLE `policies` (`id` integer PRIMARY KEY AUTOINCREMENT,`created_at` datetime,`updated_at` datetime,`deleted_at` datetime,`data` text);
+
+DELETE FROM sqlite_sequence;
+INSERT INTO sqlite_sequence VALUES('users',2);
+INSERT INTO sqlite_sequence VALUES('nodes',4);
+CREATE INDEX idx_users_deleted_at ON users(deleted_at);
+CREATE UNIQUE INDEX idx_api_keys_prefix ON api_keys(prefix);
+CREATE INDEX idx_policies_deleted_at ON policies(deleted_at);
+CREATE UNIQUE INDEX idx_provider_identifier ON users(provider_identifier) WHERE provider_identifier IS NOT NULL;
+CREATE UNIQUE INDEX idx_name_provider_identifier ON users(name, provider_identifier);
+CREATE UNIQUE INDEX idx_name_no_provider_identifier ON users(name) WHERE provider_identifier IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_pre_auth_keys_prefix ON pre_auth_keys(prefix) WHERE prefix IS NOT NULL AND prefix != '';
+
+COMMIT;

hscontrol/db/testdata/sqlite/recover_null_tags_user_id_migration_test.sql

@@ -0,0 +1,87 @@
+-- Test SQL dump for the null-tags user_id RECOVERY migration.
+--
+-- Represents a database that already upgraded to 0.29.0, where the buggy
+-- clear-tagged-node-user-id migration (202602201200) already cleared
+-- user_id on untagged nodes whose tags column held 'null'. The recovery
+-- migration runs against this state and re-derives user_id from the node's
+-- pre-auth key where possible.
+-- Fixes: https://github.com/juanfont/headscale/issues/3323
+
+PRAGMA foreign_keys=OFF;
+BEGIN TRANSACTION;
+
+-- Migrations table: everything through the current last migration has been
+-- applied (this DB already ran the buggy clear-tagged migration). The new
+-- recovery migration is intentionally absent so it runs against this dump.
+CREATE TABLE `migrations` (`id` text,PRIMARY KEY (`id`));
+INSERT INTO migrations VALUES('202312101416');
+INSERT INTO migrations VALUES('202312101430');
+INSERT INTO migrations VALUES('202402151347');
+INSERT INTO migrations VALUES('2024041121742');
+INSERT INTO migrations VALUES('202406021630');
+INSERT INTO migrations VALUES('202409271400');
+INSERT INTO migrations VALUES('202407191627');
+INSERT INTO migrations VALUES('202408181235');
+INSERT INTO migrations VALUES('202501221827');
+INSERT INTO migrations VALUES('202501311657');
+INSERT INTO migrations VALUES('202502070949');
+INSERT INTO migrations VALUES('202502131714');
+INSERT INTO migrations VALUES('202502171819');
+INSERT INTO migrations VALUES('202505091439');
+INSERT INTO migrations VALUES('202505141324');
+INSERT INTO migrations VALUES('202507021200');
+INSERT INTO migrations VALUES('202510311551');
+INSERT INTO migrations VALUES('202511101554-drop-old-idx');
+INSERT INTO migrations VALUES('202511011637-preauthkey-bcrypt');
+INSERT INTO migrations VALUES('202511122344-remove-newline-index');
+INSERT INTO migrations VALUES('202511131445-node-forced-tags-to-tags');
+INSERT INTO migrations VALUES('202601121700-migrate-hostinfo-request-tags');
+INSERT INTO migrations VALUES('202602201200-clear-tagged-node-user-id');
+INSERT INTO migrations VALUES('202605221435-clear-zero-time-node-expiry');
+
+-- Users table
+CREATE TABLE `users` (`id` integer PRIMARY KEY AUTOINCREMENT,`created_at` datetime,`updated_at` datetime,`deleted_at` datetime,`name` text,`display_name` text,`email` text,`provider_identifier` text,`provider` text,`profile_pic_url` text);
+INSERT INTO users VALUES(1,'2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL,'user1','User One','user1@example.com',NULL,NULL,NULL);
+INSERT INTO users VALUES(2,'2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL,'user2','User Two','user2@example.com',NULL,NULL,NULL);
+
+-- Pre-auth keys table. Key 1 belongs to user2, key 2 to user1.
+CREATE TABLE `pre_auth_keys` (`id` integer PRIMARY KEY AUTOINCREMENT,`key` text,`user_id` integer,`reusable` numeric,`ephemeral` numeric DEFAULT false,`used` numeric DEFAULT false,`tags` text,`created_at` datetime,`expiration` datetime,`prefix` text,`hash` blob,CONSTRAINT `fk_pre_auth_keys_user` FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE SET NULL);
+INSERT INTO pre_auth_keys VALUES(1,NULL,2,1,false,true,NULL,'2024-01-01 00:00:00+00:00',NULL,'pak1',NULL);
+INSERT INTO pre_auth_keys VALUES(2,NULL,1,1,false,true,NULL,'2024-01-01 00:00:00+00:00',NULL,'pak2',NULL);
+
+-- API keys table
+CREATE TABLE `api_keys` (`id` integer PRIMARY KEY AUTOINCREMENT,`prefix` text,`hash` blob,`created_at` datetime,`expiration` datetime,`last_seen` datetime);
+
+-- Nodes table
+CREATE TABLE IF NOT EXISTS "nodes" (`id` integer PRIMARY KEY AUTOINCREMENT,`machine_key` text,`node_key` text,`disco_key` text,`endpoints` text,`host_info` text,`ipv4` text,`ipv6` text,`hostname` text,`given_name` varchar(63),`user_id` integer,`register_method` text,`tags` text,`auth_key_id` integer,`last_seen` datetime,`expiry` datetime,`approved_routes` text,`created_at` datetime,`updated_at` datetime,`deleted_at` datetime,CONSTRAINT `fk_nodes_user` FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE,CONSTRAINT `fk_nodes_auth_key` FOREIGN KEY (`auth_key_id`) REFERENCES `pre_auth_keys`(`id`));
+
+-- Node 1: authkey-registered, tags='null', already orphaned (user_id NULL) by
+-- the buggy migration. auth_key_id=1 (user2). Recovery: user_id -> 2.
+INSERT INTO nodes VALUES(1,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e01','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605501','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57701','[]','{}','100.64.0.1','fd7a:115c:a1e0::1','node1','node1',NULL,'authkey','null',1,'2024-01-01 00:00:00+00:00',NULL,'[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 2: genuinely tagged, user_id correctly cleared. Must stay NULL.
+INSERT INTO nodes VALUES(2,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e02','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605502','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57702','[]','{}','100.64.0.2','fd7a:115c:a1e0::2','node2','node2',NULL,'authkey','["tag:server"]',2,'2024-01-01 00:00:00+00:00',NULL,'[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 3: CLI-registered, tags='null', orphaned, no auth_key_id.
+-- Unrecoverable: must stay NULL.
+INSERT INTO nodes VALUES(3,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e03','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605503','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57703','[]','{}','100.64.0.3','fd7a:115c:a1e0::3','node3','node3',NULL,'cli','null',NULL,'2024-01-01 00:00:00+00:00',NULL,'[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 4: authkey-registered, untouched (user_id still set). Must stay user1.
+INSERT INTO nodes VALUES(4,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e04','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605504','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57704','[]','{}','100.64.0.4','fd7a:115c:a1e0::4','node4','node4',1,'authkey','null',2,'2024-01-01 00:00:00+00:00',NULL,'[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Policies table (empty)
+CREATE TABLE `policies` (`id` integer PRIMARY KEY AUTOINCREMENT,`created_at` datetime,`updated_at` datetime,`deleted_at` datetime,`data` text);
+
+DELETE FROM sqlite_sequence;
+INSERT INTO sqlite_sequence VALUES('users',2);
+INSERT INTO sqlite_sequence VALUES('pre_auth_keys',2);
+INSERT INTO sqlite_sequence VALUES('nodes',4);
+CREATE INDEX idx_users_deleted_at ON users(deleted_at);
+CREATE UNIQUE INDEX idx_api_keys_prefix ON api_keys(prefix);
+CREATE INDEX idx_policies_deleted_at ON policies(deleted_at);
+CREATE UNIQUE INDEX idx_provider_identifier ON users(provider_identifier) WHERE provider_identifier IS NOT NULL;
+CREATE UNIQUE INDEX idx_name_provider_identifier ON users(name, provider_identifier);
+CREATE UNIQUE INDEX idx_name_no_provider_identifier ON users(name) WHERE provider_identifier IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_pre_auth_keys_prefix ON pre_auth_keys(prefix) WHERE prefix IS NOT NULL AND prefix != '';
+
+COMMIT;

hscontrol/db/testdata/sqlite/zero_time_expiry_migration_test.sql

@@ -0,0 +1,82 @@
+-- Test SQL dump for zero-time node expiry migration
+-- (202605221435-clear-zero-time-node-expiry)
+--
+-- Pre-0.28 versions of Headscale persisted a zero time.Time as the string
+-- '0001-01-01 00:00:00+00:00' in nodes.expiry instead of NULL. Upgrading
+-- to 0.29 surfaces those rows as "expired" because they look like a
+-- timestamp at year 1. This dump exercises the data fix.
+-- Fixes: https://github.com/juanfont/headscale/issues/3284
+
+PRAGMA foreign_keys=OFF;
+BEGIN TRANSACTION;
+
+-- Migrations table: all entries BEFORE the zero-time fix have been applied.
+-- The new migration is intentionally absent so it runs against this dump.
+CREATE TABLE `migrations` (`id` text,PRIMARY KEY (`id`));
+INSERT INTO migrations VALUES('202312101416');
+INSERT INTO migrations VALUES('202312101430');
+INSERT INTO migrations VALUES('202402151347');
+INSERT INTO migrations VALUES('2024041121742');
+INSERT INTO migrations VALUES('202406021630');
+INSERT INTO migrations VALUES('202409271400');
+INSERT INTO migrations VALUES('202407191627');
+INSERT INTO migrations VALUES('202408181235');
+INSERT INTO migrations VALUES('202501221827');
+INSERT INTO migrations VALUES('202501311657');
+INSERT INTO migrations VALUES('202502070949');
+INSERT INTO migrations VALUES('202502131714');
+INSERT INTO migrations VALUES('202502171819');
+INSERT INTO migrations VALUES('202505091439');
+INSERT INTO migrations VALUES('202505141324');
+INSERT INTO migrations VALUES('202507021200');
+INSERT INTO migrations VALUES('202510311551');
+INSERT INTO migrations VALUES('202511101554-drop-old-idx');
+INSERT INTO migrations VALUES('202511011637-preauthkey-bcrypt');
+INSERT INTO migrations VALUES('202511122344-remove-newline-index');
+INSERT INTO migrations VALUES('202511131445-node-forced-tags-to-tags');
+INSERT INTO migrations VALUES('202601121700-migrate-hostinfo-request-tags');
+INSERT INTO migrations VALUES('202602201200-clear-tagged-node-user-id');
+
+-- Users table
+CREATE TABLE `users` (`id` integer PRIMARY KEY AUTOINCREMENT,`created_at` datetime,`updated_at` datetime,`deleted_at` datetime,`name` text,`display_name` text,`email` text,`provider_identifier` text,`provider` text,`profile_pic_url` text);
+INSERT INTO users VALUES(1,'2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL,'user1','User One','user1@example.com',NULL,NULL,NULL);
+
+-- Pre-auth keys table
+CREATE TABLE `pre_auth_keys` (`id` integer PRIMARY KEY AUTOINCREMENT,`key` text,`user_id` integer,`reusable` numeric,`ephemeral` numeric DEFAULT false,`used` numeric DEFAULT false,`tags` text,`created_at` datetime,`expiration` datetime,`prefix` text,`hash` blob,CONSTRAINT `fk_pre_auth_keys_user` FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE SET NULL);
+
+-- API keys table
+CREATE TABLE `api_keys` (`id` integer PRIMARY KEY AUTOINCREMENT,`prefix` text,`hash` blob,`created_at` datetime,`expiration` datetime,`last_seen` datetime);
+
+-- Nodes table - current schema (after the tags rename + last_seen/expiry reordering)
+CREATE TABLE IF NOT EXISTS "nodes" (`id` integer PRIMARY KEY AUTOINCREMENT,`machine_key` text,`node_key` text,`disco_key` text,`endpoints` text,`host_info` text,`ipv4` text,`ipv6` text,`hostname` text,`given_name` varchar(63),`user_id` integer,`register_method` text,`tags` text,`auth_key_id` integer,`last_seen` datetime,`expiry` datetime,`approved_routes` text,`created_at` datetime,`updated_at` datetime,`deleted_at` datetime,CONSTRAINT `fk_nodes_user` FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON DELETE CASCADE,CONSTRAINT `fk_nodes_auth_key` FOREIGN KEY (`auth_key_id`) REFERENCES `pre_auth_keys`(`id`));
+
+-- Node 1: zero-time expiry. After migration: expiry IS NULL.
+INSERT INTO nodes VALUES(1,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e01','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605501','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57701','[]','{}','100.64.0.1','fd7a:115c:a1e0::1','node1','node1',1,'cli','[]',NULL,'2024-01-01 00:00:00+00:00','0001-01-01 00:00:00+00:00','[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 2: NULL expiry already. After migration: still NULL.
+INSERT INTO nodes VALUES(2,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e02','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605502','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57702','[]','{}','100.64.0.2','fd7a:115c:a1e0::2','node2','node2',1,'cli','[]',NULL,'2024-01-01 00:00:00+00:00',NULL,'[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 3: real future expiry. After migration: preserved.
+INSERT INTO nodes VALUES(3,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e03','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605503','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57703','[]','{}','100.64.0.3','fd7a:115c:a1e0::3','node3','node3',1,'cli','[]',NULL,'2024-01-01 00:00:00+00:00','2099-01-01 00:00:00+00:00','[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 4: real past expiry (legitimately expired). After migration: preserved.
+INSERT INTO nodes VALUES(4,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e04','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605504','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57704','[]','{}','100.64.0.4','fd7a:115c:a1e0::4','node4','node4',1,'cli','[]',NULL,'2024-01-01 00:00:00+00:00','2020-01-01 00:00:00+00:00','[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Node 5: another zero-time row to confirm the WHERE clause matches multiple rows.
+INSERT INTO nodes VALUES(5,'mkey:a0ab77456320823945ae0331823e3c0d516fae9585bd42698dfa1ac3d7679e05','nodekey:7c84167ab68f494942de14deb83587fd841843de2bac105b6c670048c1605505','discokey:53075b3c6cad3b62a2a29caea61beeb93f66b8c75cb89dac465236a5bbf57705','[]','{}','100.64.0.5','fd7a:115c:a1e0::5','node5','node5',1,'cli','[]',NULL,'2024-01-01 00:00:00+00:00','0001-01-01 00:00:00+00:00','[]','2024-01-01 00:00:00+00:00','2024-01-01 00:00:00+00:00',NULL);
+
+-- Policies table (empty)
+CREATE TABLE `policies` (`id` integer PRIMARY KEY AUTOINCREMENT,`created_at` datetime,`updated_at` datetime,`deleted_at` datetime,`data` text);
+
+DELETE FROM sqlite_sequence;
+INSERT INTO sqlite_sequence VALUES('users',1);
+INSERT INTO sqlite_sequence VALUES('nodes',5);
+CREATE INDEX idx_users_deleted_at ON users(deleted_at);
+CREATE UNIQUE INDEX idx_api_keys_prefix ON api_keys(prefix);
+CREATE INDEX idx_policies_deleted_at ON policies(deleted_at);
+CREATE UNIQUE INDEX idx_provider_identifier ON users(provider_identifier) WHERE provider_identifier IS NOT NULL;
+CREATE UNIQUE INDEX idx_name_provider_identifier ON users(name, provider_identifier);
+CREATE UNIQUE INDEX idx_name_no_provider_identifier ON users(name) WHERE provider_identifier IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_pre_auth_keys_prefix ON pre_auth_keys(prefix) WHERE prefix IS NOT NULL AND prefix != '';
+
+COMMIT;

hscontrol/db/text_serialiser.go

@@ -24,7 +24,7 @@ func isTextUnmarshaler(rv reflect.Value) bool {
 }
 
 func maybeInstantiatePtr(rv reflect.Value) {
-	if rv.Kind() == reflect.Ptr && rv.IsNil() {
+	if rv.Kind() == reflect.Pointer && rv.IsNil() {
 		np := reflect.New(rv.Type().Elem())
 		rv.Set(np)
 	}
@@ -34,8 +34,8 @@ func decodingError(name string, err error) error {
 	return fmt.Errorf("decoding to %s: %w", name, err)
 }
 
-// TextSerialiser implements the Serialiser interface for fields that
-// have a type that implements encoding.TextUnmarshaler.
+// TextSerialiser implements the [schema.SerializerInterface] for fields that
+// have a type that implements [encoding.TextUnmarshaler].
 type TextSerialiser struct{}
 
 func (TextSerialiser) Scan(ctx context.Context, field *schema.Field, dst reflect.Value, dbValue any) error {
@@ -43,7 +43,7 @@ func (TextSerialiser) Scan(ctx context.Context, field *schema.Field, dst reflect
 
 	// If the field is a pointer, we need to dereference it to get the actual type
 	// so we do not end with a second pointer.
-	if fieldValue.Elem().Kind() == reflect.Ptr {
+	if fieldValue.Elem().Kind() == reflect.Pointer {
 		fieldValue = fieldValue.Elem()
 	}
 
@@ -76,7 +76,7 @@ func (TextSerialiser) Scan(ctx context.Context, field *schema.Field, dst reflect
 			// If it is not a pointer, we need to assign the value to the
 			// field.
 			dstField := field.ReflectValueOf(ctx, dst)
-			if dstField.Kind() == reflect.Ptr {
+			if dstField.Kind() == reflect.Pointer {
 				dstField.Set(fieldValue)
 			} else {
 				dstField.Set(fieldValue.Elem())
@@ -97,7 +97,7 @@ func (TextSerialiser) Value(ctx context.Context, field *schema.Field, dst reflec
 		// If the value is nil, we return nil, however, go nil values are not
 		// always comparable, particularly when reflection is involved:
 		// https://dev.to/arxeiss/in-go-nil-is-not-equal-to-nil-sometimes-jn8
-		if v == nil || (reflect.ValueOf(v).Kind() == reflect.Ptr && reflect.ValueOf(v).IsNil()) {
+		if v == nil || (reflect.ValueOf(v).Kind() == reflect.Pointer && reflect.ValueOf(v).IsNil()) {
 			return nil, nil //nolint:nilnil // intentional: nil value for GORM serializer
 		}