policy/v2: rewrite tag-name first-letter check via De Morgan

SaaS accepts dst: ["100.64.0.16"] and dst: ["fd7a:115c:a1e0::10"] as
host addresses but rejects dst: ["10.0.0.0/24"]. The earlier typed-Alias
switch rejected every *Prefix and so dropped the bare-IP shape that the
Prefix parser materialises as a /BitLen prefix.

validateSSHTestDestination now distinguishes by *Prefix mask width:
Bits() == Addr().BitLen() accepts (single host, equivalent to bare IP),
anything narrower rejects with the existing ErrSSHTestDstDisallowedElement
wording. The Host branch already used the same width check for
hosts:-table aliases.

Adds two captures for the new shapes (bare IPv4 / IPv6) and parse-time
rows for the same in types_test. The IPv6 capture lands a SaaS-side
engine asymmetry (parse-accept, engine-reject "test(s) failed" while
the IPv4 mirror engine-passes) so it is parked in
knownSSHTesterDivergences for a follow-up.

.claude/agents/headscale-integration-tester.md

@@ -1,870 +0,0 @@
----
-name: headscale-integration-tester
-description: Use this agent when you need to execute, analyze, or troubleshoot Headscale integration tests. This includes running specific test scenarios, investigating test failures, interpreting test artifacts, validating end-to-end functionality, or ensuring integration test quality before releases. Examples: <example>Context: User has made changes to the route management code and wants to validate the changes work correctly. user: 'I've updated the route advertisement logic in poll.go. Can you run the relevant integration tests to make sure everything still works?' assistant: 'I'll use the headscale-integration-tester agent to run the subnet routing integration tests and analyze the results.' <commentary>Since the user wants to validate route-related changes with integration tests, use the headscale-integration-tester agent to execute the appropriate tests and analyze results.</commentary></example> <example>Context: A CI pipeline integration test is failing and the user needs help understanding why. user: 'The TestSubnetRouterMultiNetwork test is failing in CI. The logs show some timing issues but I can't figure out what's wrong.' assistant: 'Let me use the headscale-integration-tester agent to analyze the test failure and examine the artifacts.' <commentary>Since this involves analyzing integration test failures and interpreting test artifacts, use the headscale-integration-tester agent to investigate the issue.</commentary></example>
-color: green
----
-
-You are a specialist Quality Assurance Engineer with deep expertise in Headscale's integration testing system. You understand the Docker-based test infrastructure, real Tailscale client interactions, and the complex timing considerations involved in end-to-end network testing.
-
-## Integration Test System Overview
-
-The Headscale integration test system uses Docker containers running real Tailscale clients against a Headscale server. Tests validate end-to-end functionality including routing, ACLs, node lifecycle, and network coordination. The system is built around the `hi` (Headscale Integration) test runner in `cmd/hi/`.
-
-## Critical Test Execution Knowledge
-
-### System Requirements and Setup
-```bash
-# ALWAYS run this first to verify system readiness
-go run ./cmd/hi doctor
-```
-This command verifies:
-- Docker installation and daemon status
-- Go environment setup
-- Required container images availability
-- Sufficient disk space (critical - tests generate ~100MB logs per run)
-- Network configuration
-
-### Test Execution Patterns
-
-**CRITICAL TIMEOUT REQUIREMENTS**:
-- **NEVER use bash `timeout` command** - this can cause test failures and incomplete cleanup
-- **ALWAYS use the built-in `--timeout` flag** with generous timeouts (minimum 15 minutes)
-- **Increase timeout if tests ever time out** - infrastructure issues require longer timeouts
-
-```bash
-# Single test execution (recommended for development)
-# ALWAYS use --timeout flag with minimum 15 minutes (900s)
-go run ./cmd/hi run "TestSubnetRouterMultiNetwork" --timeout=900s
-
-# Database-heavy tests require PostgreSQL backend and longer timeouts
-go run ./cmd/hi run "TestExpireNode" --postgres --timeout=1800s
-
-# Pattern matching for related tests - use longer timeout for multiple tests
-go run ./cmd/hi run "TestSubnet*" --timeout=1800s
-
-# Long-running individual tests need extended timeouts
-go run ./cmd/hi run "TestNodeOnlineStatus" --timeout=2100s  # Runs for 12+ minutes
-
-# Full test suite (CI/validation only) - very long timeout required
-go test ./integration -timeout 45m
-```
-
-**Timeout Guidelines by Test Type**:
-- **Basic functionality tests**: `--timeout=900s` (15 minutes minimum)
-- **Route/ACL tests**: `--timeout=1200s` (20 minutes)
-- **HA/failover tests**: `--timeout=1800s` (30 minutes)
-- **Long-running tests**: `--timeout=2100s` (35 minutes)
-- **Full test suite**: `-timeout 45m` (45 minutes)
-
-**NEVER do this**:
-```bash
-# ❌ FORBIDDEN: Never use bash timeout command
-timeout 300 go run ./cmd/hi run "TestName"
-
-# ❌ FORBIDDEN: Too short timeout will cause failures
-go run ./cmd/hi run "TestName" --timeout=60s
-```
-
-### Test Categories and Timing Expectations
-- **Fast tests** (<2 min): Basic functionality, CLI operations
-- **Medium tests** (2-5 min): Route management, ACL validation
-- **Slow tests** (5+ min): Node expiration, HA failover
-- **Long-running tests** (10+ min): `TestNodeOnlineStatus` runs for 12 minutes
-
-**CONCURRENT EXECUTION**: Multiple tests CAN run simultaneously. Each test run gets a unique Run ID for isolation. See "Concurrent Execution and Run ID Isolation" section below.
-
-## Test Artifacts and Log Analysis
-
-### Artifact Structure
-All test runs save comprehensive artifacts to `control_logs/TIMESTAMP-ID/`:
-```
-control_logs/20250713-213106-iajsux/
-├── hs-testname-abc123.stderr.log     # Headscale server error logs
-├── hs-testname-abc123.stdout.log     # Headscale server output logs
-├── hs-testname-abc123.db             # Database snapshot for post-mortem
-├── hs-testname-abc123_metrics.txt    # Prometheus metrics dump
-├── hs-testname-abc123-mapresponses/  # Protocol-level debug data
-├── ts-client-xyz789.stderr.log       # Tailscale client error logs
-├── ts-client-xyz789.stdout.log       # Tailscale client output logs
-└── ts-client-xyz789_status.json      # Client network status dump
-```
-
-### Log Analysis Priority Order
-When tests fail, examine artifacts in this specific order:
-
-1. **Headscale server stderr logs** (`hs-*.stderr.log`): Look for errors, panics, database issues, policy evaluation failures
-2. **Tailscale client stderr logs** (`ts-*.stderr.log`): Check for authentication failures, network connectivity issues
-3. **MapResponse JSON files**: Protocol-level debugging for network map generation issues
-4. **Client status dumps** (`*_status.json`): Network state and peer connectivity information
-5. **Database snapshots** (`.db` files): For data consistency and state persistence issues
-
-## Concurrent Execution and Run ID Isolation
-
-### Overview
-
-The integration test system supports running multiple tests concurrently on the same Docker daemon. Each test run is isolated through a unique Run ID that ensures containers, networks, and cleanup operations don't interfere with each other.
-
-### Run ID Format and Usage
-
-Each test run generates a unique Run ID in the format: `YYYYMMDD-HHMMSS-{6-char-hash}`
-- Example: `20260109-104215-mdjtzx`
-
-The Run ID is used for:
-- **Container naming**: `ts-{runIDShort}-{version}-{hash}` (e.g., `ts-mdjtzx-1-74-fgdyls`)
-- **Docker labels**: All containers get `hi.run-id={runID}` label
-- **Log directories**: `control_logs/{runID}/`
-- **Cleanup isolation**: Only containers with matching run ID are cleaned up
-
-### Container Isolation Mechanisms
-
-1. **Unique Container Names**: Each container includes the run ID for identification
-2. **Docker Labels**: `hi.run-id` and `hi.test-type` labels on all containers
-3. **Dynamic Port Allocation**: All ports use `{HostPort: "0"}` to let kernel assign free ports
-4. **Per-Run Networks**: Network names include scenario hash for isolation
-5. **Isolated Cleanup**: `killTestContainersByRunID()` only removes containers matching the run ID
-
-### ⚠️ CRITICAL: Never Interfere with Other Test Runs
-
-**FORBIDDEN OPERATIONS** when other tests may be running:
-
-```bash
-# ❌ NEVER do global container cleanup while tests are running
-docker rm -f $(docker ps -q --filter "name=hs-")
-docker rm -f $(docker ps -q --filter "name=ts-")
-
-# ❌ NEVER kill all test containers
-# This will destroy other agents' test sessions!
-
-# ❌ NEVER prune all Docker resources during active tests
-docker system prune -f  # Only safe when NO tests are running
-```
-
-**SAFE OPERATIONS**:
-
-```bash
-# ✅ Clean up only YOUR test run's containers (by run ID)
-# The test runner does this automatically via cleanup functions
-
-# ✅ Clean stale (stopped/exited) containers only
-# Pre-test cleanup only removes stopped containers, not running ones
-
-# ✅ Check what's running before cleanup
-docker ps --filter "name=headscale-test-suite" --format "{{.Names}}"
-```
-
-### Running Concurrent Tests
-
-```bash
-# Start multiple tests in parallel - each gets unique run ID
-go run ./cmd/hi run "TestPingAllByIP" &
-go run ./cmd/hi run "TestACLAllowUserDst" &
-go run ./cmd/hi run "TestOIDCAuthenticationPingAll" &
-
-# Monitor running test suites
-docker ps --filter "name=headscale-test-suite" --format "table {{.Names}}\t{{.Status}}"
-```
-
-### Agent Session Isolation Rules
-
-When working as an agent:
-
-1. **Your run ID is unique**: Each test you start gets its own run ID
-2. **Never clean up globally**: Only use run ID-specific cleanup
-3. **Check before cleanup**: Verify no other tests are running if you need to prune resources
-4. **Respect other sessions**: Other agents may have tests running concurrently
-5. **Log directories are isolated**: Your artifacts are in `control_logs/{your-run-id}/`
-
-### Identifying Your Containers
-
-Your test containers can be identified by:
-- The run ID in the container name
-- The `hi.run-id` Docker label
-- The test suite container: `headscale-test-suite-{your-run-id}`
-
-```bash
-# List containers for a specific run ID
-docker ps --filter "label=hi.run-id=20260109-104215-mdjtzx"
-
-# Get your run ID from the test output
-# Look for: "Run ID: 20260109-104215-mdjtzx"
-```
-
-## Common Failure Patterns and Root Cause Analysis
-
-### CRITICAL MINDSET: Code Issues vs Infrastructure Issues
-
-**⚠️ IMPORTANT**: When tests fail, it is ALMOST ALWAYS a code issue with Headscale, NOT infrastructure problems. Do not immediately blame disk space, Docker issues, or timing unless you have thoroughly investigated the actual error logs first.
-
-### Systematic Debugging Process
-
-1. **Read the actual error message**: Don't assume - read the stderr logs completely
-2. **Check Headscale server logs first**: Most issues originate from server-side logic
-3. **Verify client connectivity**: Only after ruling out server issues
-4. **Check timing patterns**: Use proper `EventuallyWithT` patterns
-5. **Infrastructure as last resort**: Only blame infrastructure after code analysis
-
-### Real Failure Patterns
-
-#### 1. Timing Issues (Common but fixable)
-```go
-// ❌ Wrong: Immediate assertions after async operations
-client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-nodes, _ := headscale.ListNodes()
-require.Len(t, nodes[0].GetAvailableRoutes(), 1) // WILL FAIL
-
-// ✅ Correct: Wait for async operations
-client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes[0].GetAvailableRoutes(), 1)
-}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
-```
-
-**Timeout Guidelines**:
-- Route operations: 3-5 seconds
-- Node state changes: 5-10 seconds
-- Complex scenarios: 10-15 seconds
-- Policy recalculation: 5-10 seconds
-
-#### 2. NodeStore Synchronization Issues
-Route advertisements must propagate through poll requests (`poll.go:420`). NodeStore updates happen at specific synchronization points after Hostinfo changes.
-
-#### 3. Test Data Management Issues
-```go
-// ❌ Wrong: Assuming array ordering
-require.Len(t, nodes[0].GetAvailableRoutes(), 1)
-
-// ✅ Correct: Identify nodes by properties
-expectedRoutes := map[string]string{"1": "10.33.0.0/16"}
-for _, node := range nodes {
-    nodeIDStr := fmt.Sprintf("%d", node.GetId())
-    if route, shouldHaveRoute := expectedRoutes[nodeIDStr]; shouldHaveRoute {
-        // Test the specific node that should have the route
-    }
-}
-```
-
-#### 4. Database Backend Differences
-SQLite vs PostgreSQL have different timing characteristics:
-- Use `--postgres` flag for database-intensive tests
-- PostgreSQL generally has more consistent timing
-- Some race conditions only appear with specific backends
-
-## Resource Management and Cleanup
-
-### Disk Space Management
-Tests consume significant disk space (~100MB per run):
-```bash
-# Check available space before running tests
-df -h
-
-# Clean up test artifacts periodically
-rm -rf control_logs/older-timestamp-dirs/
-
-# Clean Docker resources
-docker system prune -f
-docker volume prune -f
-```
-
-### Container Cleanup
-- Successful tests clean up automatically
-- Failed tests may leave containers running
-- Manually clean if needed: `docker ps -a` and `docker rm -f <containers>`
-
-## Advanced Debugging Techniques
-
-### Protocol-Level Debugging
-MapResponse JSON files in `control_logs/*/hs-*-mapresponses/` contain:
-- Network topology as sent to clients
-- Peer relationships and visibility
-- Route distribution and primary route selection
-- Policy evaluation results
-
-### Database State Analysis
-Use the database snapshots for post-mortem analysis:
-```bash
-# SQLite examination
-sqlite3 control_logs/TIMESTAMP/hs-*.db
-.tables
-.schema nodes
-SELECT * FROM nodes WHERE name LIKE '%problematic%';
-```
-
-### Performance Analysis
-Prometheus metrics dumps show:
-- Request latencies and error rates
-- NodeStore operation timing
-- Database query performance
-- Memory usage patterns
-
-## Test Development and Quality Guidelines
-
-### Proper Test Patterns
-```go
-// Always use EventuallyWithT for async operations
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    // Test condition that may take time to become true
-}, timeout, interval, "descriptive failure message")
-
-// Handle node identification correctly
-var targetNode *v1.Node
-for _, node := range nodes {
-    if node.GetName() == expectedNodeName {
-        targetNode = node
-        break
-    }
-}
-require.NotNil(t, targetNode, "should find expected node")
-```
-
-### Quality Validation Checklist
-- ✅ Tests use `EventuallyWithT` for asynchronous operations
-- ✅ Tests don't rely on array ordering for node identification
-- ✅ Proper cleanup and resource management
-- ✅ Tests handle both success and failure scenarios
-- ✅ Timing assumptions are realistic for operations being tested
-- ✅ Error messages are descriptive and actionable
-
-## Real-World Test Failure Patterns from HA Debugging
-
-### Infrastructure vs Code Issues - Detailed Examples
-
-**INFRASTRUCTURE FAILURES (Rare but Real)**:
-1. **DNS Resolution in Auth Tests**: `failed to resolve "hs-pingallbyip-jax97k": no DNS fallback candidates remain`
-   - **Pattern**: Client containers can't resolve headscale server hostname during logout
-   - **Detection**: Error messages specifically mention DNS/hostname resolution
-   - **Solution**: Docker networking reset, not code changes
-
-2. **Container Creation Timeouts**: Test gets stuck during client container setup
-   - **Pattern**: Tests hang indefinitely at container startup phase
-   - **Detection**: No progress in logs for >2 minutes during initialization
-   - **Solution**: `docker system prune -f` and retry
-
-3. **Docker Resource Exhaustion**: Too many concurrent tests overwhelming system
-   - **Pattern**: Container creation timeouts, OOM kills, slow test execution
-   - **Detection**: System load high, Docker daemon slow to respond
-   - **Solution**: Reduce number of concurrent tests, wait for completion before starting more
-
-**CODE ISSUES (99% of failures)**:
-1. **Route Approval Process Failures**: Routes not getting approved when they should be
-   - **Pattern**: Tests expecting approved routes but finding none
-   - **Detection**: `SubnetRoutes()` returns empty when `AnnouncedRoutes()` shows routes
-   - **Root Cause**: Auto-approval logic bugs, policy evaluation issues
-
-2. **NodeStore Synchronization Issues**: State updates not propagating correctly
-   - **Pattern**: Route changes not reflected in NodeStore or Primary Routes
-   - **Detection**: Logs show route announcements but no tracking updates
-   - **Root Cause**: Missing synchronization points in `poll.go:420` area
-
-3. **HA Failover Architecture Issues**: Routes removed when nodes go offline
-   - **Pattern**: `TestHASubnetRouterFailover` fails because approved routes disappear
-   - **Detection**: Routes available on online nodes but lost when nodes disconnect
-   - **Root Cause**: Conflating route approval with node connectivity
-
-### Critical Test Environment Setup
-
-**Pre-Test Cleanup**:
-
-The test runner automatically handles cleanup:
-- **Before test**: Removes only stale (stopped/exited) containers - does NOT affect running tests
-- **After test**: Removes only containers belonging to the specific run ID
-
-```bash
-# Only clean old log directories if disk space is low
-rm -rf control_logs/202507*
-df -h  # Verify sufficient disk space
-
-# SAFE: Clean only stale/stopped containers (does not affect running tests)
-# The test runner does this automatically via cleanupStaleTestContainers()
-
-# ⚠️ DANGEROUS: Only use when NO tests are running
-docker system prune -f
-```
-
-**Environment Verification**:
-```bash
-# Verify system readiness
-go run ./cmd/hi doctor
-
-# Check what tests are currently running (ALWAYS check before global cleanup)
-docker ps --filter "name=headscale-test-suite" --format "{{.Names}}"
-```
-
-### Specific Test Categories and Known Issues
-
-#### Route-Related Tests (Primary Focus)
-```bash
-# Core route functionality - these should work first
-# Note: Generous timeouts are required for reliable execution
-go run ./cmd/hi run "TestSubnetRouteACL" --timeout=1200s
-go run ./cmd/hi run "TestAutoApproveMultiNetwork" --timeout=1800s
-go run ./cmd/hi run "TestHASubnetRouterFailover" --timeout=1800s
-```
-
-**Common Route Test Patterns**:
-- Tests validate route announcement, approval, and distribution workflows
-- Route state changes are asynchronous - may need `EventuallyWithT` wrappers
-- Route approval must respect ACL policies - test expectations encode security requirements
-- HA tests verify route persistence during node connectivity changes
-
-#### Authentication Tests (Infrastructure-Prone)
-```bash
-# These tests are more prone to infrastructure issues
-# Require longer timeouts due to auth flow complexity
-go run ./cmd/hi run "TestAuthKeyLogoutAndReloginSameUser" --timeout=1200s
-go run ./cmd/hi run "TestAuthWebFlowLogoutAndRelogin" --timeout=1200s
-go run ./cmd/hi run "TestOIDCExpireNodesBasedOnTokenExpiry" --timeout=1800s
-```
-
-**Common Auth Test Infrastructure Failures**:
-- DNS resolution during logout operations
-- Container creation timeouts
-- HTTP/2 stream errors (often symptoms, not root cause)
-
-### Security-Critical Debugging Rules
-
-**❌ FORBIDDEN CHANGES (Security & Test Integrity)**:
-1. **Never change expected test outputs** - Tests define correct behavior contracts
-   - Changing `require.Len(t, routes, 3)` to `require.Len(t, routes, 2)` because test fails
-   - Modifying expected status codes, node counts, or route counts
-   - Removing assertions that are "inconvenient"
-   - **Why forbidden**: Test expectations encode business requirements and security policies
-
-2. **Never bypass security mechanisms** - Security must never be compromised for convenience
-   - Using `AnnouncedRoutes()` instead of `SubnetRoutes()` in production code
-   - Skipping authentication or authorization checks
-   - **Why forbidden**: Security bypasses create vulnerabilities in production
-
-3. **Never reduce test coverage** - Tests prevent regressions
-   - Removing test cases or assertions
-   - Commenting out "problematic" test sections
-   - **Why forbidden**: Reduced coverage allows bugs to slip through
-
-**✅ ALLOWED CHANGES (Timing & Observability)**:
-1. **Fix timing issues with proper async patterns**
-   ```go
-   // ✅ GOOD: Add EventuallyWithT for async operations
-   require.EventuallyWithT(t, func(c *assert.CollectT) {
-       nodes, err := headscale.ListNodes()
-       assert.NoError(c, err)
-       assert.Len(c, nodes, expectedCount) // Keep original expectation
-   }, 10*time.Second, 100*time.Millisecond, "nodes should reach expected count")
-   ```
-   - **Why allowed**: Fixes race conditions without changing business logic
-
-2. **Add MORE observability and debugging**
-   - Additional logging statements
-   - More detailed error messages
-   - Extra assertions that verify intermediate states
-   - **Why allowed**: Better observability helps debug without changing behavior
-
-3. **Improve test documentation**
-   - Add godoc comments explaining test purpose and business logic
-   - Document timing requirements and async behavior
-   - **Why encouraged**: Helps future maintainers understand intent
-
-### Advanced Debugging Workflows
-
-#### Route Tracking Debug Flow
-```bash
-# Run test with detailed logging and proper timeout
-go run ./cmd/hi run "TestSubnetRouteACL" --timeout=1200s > test_output.log 2>&1
-
-# Check route approval process
-grep -E "(auto-approval|ApproveRoutesWithPolicy|PolicyManager)" test_output.log
-
-# Check route tracking
-tail -50 control_logs/*/hs-*.stderr.log | grep -E "(announced|tracking|SetNodeRoutes)"
-
-# Check for security violations
-grep -E "(AnnouncedRoutes.*SetNodeRoutes|bypass.*approval)" test_output.log
-```
-
-#### HA Failover Debug Flow
-```bash
-# Test HA failover specifically with adequate timeout
-go run ./cmd/hi run "TestHASubnetRouterFailover" --timeout=1800s
-
-# Check route persistence during disconnect
-grep -E "(Disconnect|NodeWentOffline|PrimaryRoutes)" control_logs/*/hs-*.stderr.log
-
-# Verify routes don't disappear inappropriately
-grep -E "(removing.*routes|SetNodeRoutes.*empty)" control_logs/*/hs-*.stderr.log
-```
-
-### Test Result Interpretation Guidelines
-
-#### Success Patterns to Look For
-- `"updating node routes for tracking"` in logs
-- Routes appearing in `announcedRoutes` logs
-- Proper `ApproveRoutesWithPolicy` calls for auto-approval
-- Routes persisting through node connectivity changes (HA tests)
-
-#### Failure Patterns to Investigate
-- `SubnetRoutes()` returning empty when `AnnouncedRoutes()` has routes
-- Routes disappearing when nodes go offline (HA architectural issue)
-- Missing `EventuallyWithT` causing timing race conditions
-- Security bypass attempts using wrong route methods
-
-### Critical Testing Methodology
-
-**Phase-Based Testing Approach**:
-1. **Phase 1**: Core route tests (ACL, auto-approval, basic functionality)
-2. **Phase 2**: HA and complex route scenarios
-3. **Phase 3**: Auth tests (infrastructure-sensitive, test last)
-
-**Per-Test Process**:
-1. Clean environment before each test
-2. Monitor logs for route tracking and approval messages
-3. Check artifacts in `control_logs/` if test fails
-4. Focus on actual error messages, not assumptions
-5. Document results and patterns discovered
-
-## Test Documentation and Code Quality Standards
-
-### Adding Missing Test Documentation
-When you understand a test's purpose through debugging, always add comprehensive godoc:
-
-```go
-// TestSubnetRoutes validates the complete subnet route lifecycle including
-// advertisement from clients, policy-based approval, and distribution to peers.
-// This test ensures that route security policies are properly enforced and that
-// only approved routes are distributed to the network.
-//
-// The test verifies:
-// - Route announcements are received and tracked
-// - ACL policies control route approval correctly
-// - Only approved routes appear in peer network maps
-// - Route state persists correctly in the database
-func TestSubnetRoutes(t *testing.T) {
-    // Test implementation...
-}
-```
-
-**Why add documentation**: Future maintainers need to understand business logic and security requirements encoded in tests.
-
-### Comment Guidelines - Focus on WHY, Not WHAT
-
-```go
-// ✅ GOOD: Explains reasoning and business logic
-// Wait for route propagation because NodeStore updates are asynchronous
-// and happen after poll requests complete processing
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    // Check that security policies are enforced...
-}, timeout, interval, "route approval must respect ACL policies")
-
-// ❌ BAD: Just describes what the code does
-// Wait for routes
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    // Get routes and check length
-}, timeout, interval, "checking routes")
-```
-
-**Why focus on WHY**: Helps maintainers understand architectural decisions and security requirements.
-
-## EventuallyWithT Pattern for External Calls
-
-### Overview
-EventuallyWithT is a testing pattern used to handle eventual consistency in distributed systems. In Headscale integration tests, many operations are asynchronous - clients advertise routes, the server processes them, updates propagate through the network. EventuallyWithT allows tests to wait for these operations to complete while making assertions.
-
-### External Calls That Must Be Wrapped
-The following operations are **external calls** that interact with the headscale server or tailscale clients and MUST be wrapped in EventuallyWithT:
-- `headscale.ListNodes()` - Queries server state
-- `client.Status()` - Gets client network status
-- `client.Curl()` - Makes HTTP requests through the network
-- `client.Traceroute()` - Performs network diagnostics
-- `client.Execute()` when running commands that query state
-- Any operation that reads from the headscale server or tailscale client
-
-### Five Key Rules for EventuallyWithT
-
-1. **One External Call Per EventuallyWithT Block**
-   - Each EventuallyWithT should make ONE external call (e.g., ListNodes OR Status)
-   - Related assertions based on that single call can be grouped together
-   - Unrelated external calls must be in separate EventuallyWithT blocks
-
-2. **Variable Scoping**
-   - Declare variables that need to be shared across EventuallyWithT blocks at function scope
-   - Use `=` for assignment inside EventuallyWithT, not `:=` (unless the variable is only used within that block)
-   - Variables declared with `:=` inside EventuallyWithT are not accessible outside
-
-3. **No Nested EventuallyWithT**
-   - NEVER put an EventuallyWithT inside another EventuallyWithT
-   - This is a critical anti-pattern that must be avoided
-
-4. **Use CollectT for Assertions**
-   - Inside EventuallyWithT, use `assert` methods with the CollectT parameter
-   - Helper functions called within EventuallyWithT must accept `*assert.CollectT`
-
-5. **Descriptive Messages**
-   - Always provide a descriptive message as the last parameter
-   - Message should explain what condition is being waited for
-
-### Correct Pattern Examples
-
-```go
-// CORRECT: Single external call with related assertions
-var nodes []*v1.Node
-var err error
-
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err = headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 2)
-    // These assertions are all based on the ListNodes() call
-    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
-    requireNodeRouteCountWithCollect(c, nodes[1], 1, 1, 1)
-}, 10*time.Second, 500*time.Millisecond, "nodes should have expected route counts")
-
-// CORRECT: Separate EventuallyWithT for different external call
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-    // All these assertions are based on the single Status() call
-    for _, peerKey := range status.Peers() {
-        peerStatus := status.Peer[peerKey]
-        requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedPrefixes)
-    }
-}, 10*time.Second, 500*time.Millisecond, "client should see expected routes")
-
-// CORRECT: Variable scoping for sharing between blocks
-var routeNode *v1.Node
-var nodeKey key.NodePublic
-
-// First EventuallyWithT to get the node
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-
-    for _, node := range nodes {
-        if node.GetName() == "router" {
-            routeNode = node
-            nodeKey, _ = key.ParseNodePublicUntyped(mem.S(node.GetNodeKey()))
-            break
-        }
-    }
-    assert.NotNil(c, routeNode, "should find router node")
-}, 10*time.Second, 100*time.Millisecond, "router node should exist")
-
-// Second EventuallyWithT using the nodeKey from first block
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-
-    peerStatus, ok := status.Peer[nodeKey]
-    assert.True(c, ok, "peer should exist in status")
-    requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedPrefixes)
-}, 10*time.Second, 100*time.Millisecond, "routes should be visible to client")
-```
-
-### Incorrect Patterns to Avoid
-
-```go
-// INCORRECT: Multiple unrelated external calls in same EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    // First external call
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 2)
-
-    // Second unrelated external call - WRONG!
-    status, err := client.Status()
-    assert.NoError(c, err)
-    assert.NotNil(c, status)
-}, 10*time.Second, 500*time.Millisecond, "mixed operations")
-
-// INCORRECT: Nested EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-
-    // NEVER do this!
-    assert.EventuallyWithT(t, func(c2 *assert.CollectT) {
-        status, _ := client.Status()
-        assert.NotNil(c2, status)
-    }, 5*time.Second, 100*time.Millisecond, "nested")
-}, 10*time.Second, 500*time.Millisecond, "outer")
-
-// INCORRECT: Variable scoping error
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes() // This shadows outer 'nodes' variable
-    assert.NoError(c, err)
-}, 10*time.Second, 500*time.Millisecond, "get nodes")
-
-// This will fail - nodes is nil because := created a new variable inside the block
-require.Len(t, nodes, 2) // COMPILATION ERROR or nil pointer
-
-// INCORRECT: Not wrapping external calls
-nodes, err := headscale.ListNodes() // External call not wrapped!
-require.NoError(t, err)
-```
-
-### Helper Functions for EventuallyWithT
-
-When creating helper functions for use within EventuallyWithT:
-
-```go
-// Helper function that accepts CollectT
-func requireNodeRouteCountWithCollect(c *assert.CollectT, node *v1.Node, available, approved, primary int) {
-    assert.Len(c, node.GetAvailableRoutes(), available, "available routes for node %s", node.GetName())
-    assert.Len(c, node.GetApprovedRoutes(), approved, "approved routes for node %s", node.GetName())
-    assert.Len(c, node.GetPrimaryRoutes(), primary, "primary routes for node %s", node.GetName())
-}
-
-// Usage within EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
-}, 10*time.Second, 500*time.Millisecond, "route counts should match expected")
-```
-
-### Operations That Must NOT Be Wrapped
-
-**CRITICAL**: The following operations are **blocking/mutating operations** that change state and MUST NOT be wrapped in EventuallyWithT:
-- `tailscale set` commands (e.g., `--advertise-routes`, `--accept-routes`)
-- `headscale.ApproveRoute()` - Approves routes on server
-- `headscale.CreateUser()` - Creates users
-- `headscale.CreatePreAuthKey()` - Creates authentication keys
-- `headscale.RegisterNode()` - Registers new nodes
-- Any `client.Execute()` that modifies configuration
-- Any operation that creates, updates, or deletes resources
-
-These operations:
-1. Complete synchronously or fail immediately
-2. Should not be retried automatically
-3. Need explicit error handling with `require.NoError()`
-
-### Correct Pattern for Blocking Operations
-
-```go
-// CORRECT: Blocking operation NOT wrapped
-status := client.MustStatus()
-command := []string{"tailscale", "set", "--advertise-routes=" + expectedRoutes[string(status.Self.ID)]}
-_, _, err = client.Execute(command)
-require.NoErrorf(t, err, "failed to advertise route: %s", err)
-
-// Then wait for the result with EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Contains(c, nodes[0].GetAvailableRoutes(), expectedRoutes[string(status.Self.ID)])
-}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
-
-// INCORRECT: Blocking operation wrapped (DON'T DO THIS)
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    _, _, err = client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-    assert.NoError(c, err) // This might retry the command multiple times!
-}, 10*time.Second, 100*time.Millisecond, "advertise routes")
-```
-
-### Assert vs Require Pattern
-
-When working within EventuallyWithT blocks where you need to prevent panics:
-
-```go
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-
-    // For array bounds - use require with t to prevent panic
-    assert.Len(c, nodes, 6)  // Test expectation
-    require.GreaterOrEqual(t, len(nodes), 3, "need at least 3 nodes to avoid panic")
-
-    // For nil pointer access - use require with t before dereferencing
-    assert.NotNil(c, srs1PeerStatus.PrimaryRoutes)  // Test expectation
-    require.NotNil(t, srs1PeerStatus.PrimaryRoutes, "primary routes must be set to avoid panic")
-    assert.Contains(c,
-        srs1PeerStatus.PrimaryRoutes.AsSlice(),
-        pref,
-    )
-}, 5*time.Second, 200*time.Millisecond, "checking route state")
-```
-
-**Key Principle**:
-- Use `assert` with `c` (*assert.CollectT) for test expectations that can be retried
-- Use `require` with `t` (*testing.T) for MUST conditions that prevent panics
-- Within EventuallyWithT, both are available - choose based on whether failure would cause a panic
-
-### Common Scenarios
-
-1. **Waiting for route advertisement**:
-```go
-client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Contains(c, nodes[0].GetAvailableRoutes(), "10.0.0.0/24")
-}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
-```
-
-2. **Checking client sees routes**:
-```go
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-
-    // Check all peers have expected routes
-    for _, peerKey := range status.Peers() {
-        peerStatus := status.Peer[peerKey]
-        assert.Contains(c, peerStatus.AllowedIPs, expectedPrefix)
-    }
-}, 10*time.Second, 100*time.Millisecond, "all peers should see route")
-```
-
-3. **Sequential operations**:
-```go
-// First wait for node to appear
-var nodeID uint64
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 1)
-    nodeID = nodes[0].GetId()
-}, 10*time.Second, 100*time.Millisecond, "node should register")
-
-// Then perform operation
-_, err := headscale.ApproveRoute(nodeID, "10.0.0.0/24")
-require.NoError(t, err)
-
-// Then wait for result
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Contains(c, nodes[0].GetApprovedRoutes(), "10.0.0.0/24")
-}, 10*time.Second, 100*time.Millisecond, "route should be approved")
-```
-
-## Your Core Responsibilities
-
-1. **Test Execution Strategy**: Execute integration tests with appropriate configurations, understanding when to use `--postgres` and timing requirements for different test categories. Follow phase-based testing approach prioritizing route tests.
-   - **Why this priority**: Route tests are less infrastructure-sensitive and validate core security logic
-
-2. **Systematic Test Analysis**: When tests fail, systematically examine artifacts starting with Headscale server logs, then client logs, then protocol data. Focus on CODE ISSUES first (99% of cases), not infrastructure. Use real-world failure patterns to guide investigation.
-   - **Why this approach**: Most failures are logic bugs, not environment issues - efficient debugging saves time
-
-3. **Timing & Synchronization Expertise**: Understand asynchronous Headscale operations, particularly route advertisements, NodeStore synchronization at `poll.go:420`, and policy propagation. Fix timing with `EventuallyWithT` while preserving original test expectations.
-   - **Why preserve expectations**: Test assertions encode business requirements and security policies
-   - **Key Pattern**: Apply the EventuallyWithT pattern correctly for all external calls as documented above
-
-4. **Root Cause Analysis**: Distinguish between actual code regressions (route approval logic, HA failover architecture), timing issues requiring `EventuallyWithT` patterns, and genuine infrastructure problems (DNS, Docker, container issues).
-   - **Why this distinction matters**: Different problem types require completely different solution approaches
-   - **EventuallyWithT Issues**: Often manifest as flaky tests or immediate assertion failures after async operations
-
-5. **Security-Aware Quality Validation**: Ensure tests properly validate end-to-end functionality with realistic timing expectations and proper error handling. Never suggest security bypasses or test expectation changes. Add comprehensive godoc when you understand test business logic.
-   - **Why security focus**: Integration tests are the last line of defense against security regressions
-   - **EventuallyWithT Usage**: Proper use prevents race conditions without weakening security assertions
-
-6. **Concurrent Execution Awareness**: Respect run ID isolation and never interfere with other agents' test sessions. Each test run has a unique run ID - only clean up YOUR containers (by run ID label), never perform global cleanup while tests may be running.
-   - **Why this matters**: Multiple agents/users may run tests concurrently on the same Docker daemon
-   - **Key Rule**: NEVER use global container cleanup commands - the test runner handles cleanup automatically per run ID
-
-**CRITICAL PRINCIPLE**: Test expectations are sacred contracts that define correct system behavior. When tests fail, fix the code to match the test, never change the test to match broken code. Only timing and observability improvements are allowed - business logic expectations are immutable.
-
-**ISOLATION PRINCIPLE**: Each test run is isolated by its unique Run ID. Never interfere with other test sessions. The system handles cleanup automatically - manual global cleanup commands are forbidden when other tests may be running.
-
-**EventuallyWithT PRINCIPLE**: Every external call to headscale server or tailscale client must be wrapped in EventuallyWithT. Follow the five key rules strictly: one external call per block, proper variable scoping, no nesting, use CollectT for assertions, and provide descriptive messages.
-
-**Remember**: Test failures are usually code issues in Headscale that need to be fixed, not infrastructure problems to be ignored. Use the specific debugging workflows and failure patterns documented above to efficiently identify root causes. Infrastructure issues have very specific signatures - everything else is code-related.

.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

@@ -0,0 +1,112 @@
+---
+name: Build (main)
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "*.nix"
+      - "go.*"
+      - "**/*.go"
+      - ".github/workflows/container-main.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  container:
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Login to DockerHub
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Login to GHCR
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - 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: Set commit timestamp
+        run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> $GITHUB_ENV
+
+      - name: Build and push to GHCR
+        env:
+          KO_DOCKER_REPO: ghcr.io/juanfont/headscale
+          KO_DEFAULTBASEIMAGE: gcr.io/distroless/base-debian13
+          CGO_ENABLED: "0"
+        run: |
+          nix develop --command -- ko build \
+            --bare \
+            --platform=linux/amd64,linux/arm64 \
+            --tags=main-${GITHUB_SHA::7},development \
+            ./cmd/headscale
+
+      - name: Push to Docker Hub
+        env:
+          KO_DOCKER_REPO: headscale/headscale
+          KO_DEFAULTBASEIMAGE: gcr.io/distroless/base-debian13
+          CGO_ENABLED: "0"
+        run: |
+          nix develop --command -- ko build \
+            --bare \
+            --platform=linux/amd64,linux/arm64 \
+            --tags=main-${GITHUB_SHA::7},development \
+            ./cmd/headscale
+
+  binaries:
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
+            goarch: arm64
+          - goos: darwin
+            goarch: amd64
+          - goos: darwin
+            goarch: arm64
+    steps:
+      - name: Checkout
+        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: Build binary
+        env:
+          CGO_ENABLED: "0"
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+        run: nix develop --command -- go build -o headscale ./cmd/headscale
+
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: headscale-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: headscale

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

@@ -66,7 +66,9 @@ func findTests() []string {
 	}
 
 	args := []string{
+		"--type", "go",
 		"--regexp", "func (Test.+)\\(.*",
+		"--max-depth", "1",
 		"../../integration/",
 		"--replace", "$1",
 		"--sort", "path",

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

@@ -16,7 +16,7 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04-arm
     env:
       # Github does not allow us to access secrets in pull requests,
       # so this env var is used to check if we have the secret or not.

.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

@@ -12,7 +12,7 @@ jobs:
   # sqlite: Runs all integration tests with SQLite backend.
   # postgres: Runs a subset of tests with PostgreSQL to verify database compatibility.
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04-arm
     outputs:
       files-changed: ${{ steps.changed-files.outputs.files }}
     steps:
@@ -119,7 +119,7 @@ jobs:
           path: tailscale-head-image.tar.gz
           retention-days: 10
   build-postgres:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04-arm
     needs: build
     if: needs.build.outputs.files-changed == 'true'
     steps:
@@ -202,6 +202,8 @@ jobs:
           - TestAuthWebFlowAuthenticationPingAll
           - TestAuthWebFlowLogoutAndReloginSameUser
           - TestAuthWebFlowLogoutAndReloginNewUser
+          - TestPolicyCheckCommand
+          - TestSSHTestsRejectFailingPolicy
           - TestUserCommand
           - TestPreAuthKeyCommand
           - TestPreAuthKeyCommandWithoutExpiry
@@ -233,10 +235,13 @@ jobs:
           - TestNodeOnlineStatus
           - TestPingAllByIPManyUpDown
           - Test2118DeletingOnlineNodePanics
+          - TestGrantCapRelay
+          - TestGrantCapDrive
           - TestEnablingRoutes
           - TestHASubnetRouterFailover
           - TestSubnetRouteACL
           - TestEnablingExitRoutes
+          - TestExitRoutesWithAutogroupInternetACL
           - TestSubnetRouterMultiNetwork
           - TestSubnetRouterMultiNetworkExitNode
           - TestAutoApproveMultiNetwork/authkey-tag.*
@@ -246,6 +251,11 @@ jobs:
           - TestAutoApproveMultiNetwork/webauth-user.*
           - TestAutoApproveMultiNetwork/webauth-group.*
           - TestSubnetRouteACLFiltering
+          - TestGrantViaSubnetSteering
+          - TestHASubnetRouterPingFailover
+          - TestHASubnetRouterFailoverBothOffline
+          - TestHASubnetRouterFailoverBothOfflineCablePull
+          - TestHASubnetRouterFailoverDockerDisconnect
           - TestHeadscale
           - TestTailscaleNodesJoiningHeadcale
           - TestSSHOneUserToAll
@@ -293,6 +303,7 @@ jobs:
           - TestTagsAuthKeyWithoutUserInheritsTags
           - TestTagsAuthKeyWithoutUserRejectsAdvertisedTags
           - TestTagsAuthKeyConvertToUserViaCLIRegister
+          - TestTailscaleRustAxum
     uses: ./.github/workflows/integration-test-template.yml
     secrets: inherit
     with:

.gitignore

@@ -29,6 +29,7 @@ config*.yaml
 !config-example.yaml
 derp.yaml
 *.hujson
+!hscontrol/policy/v2/testdata/*/*.hujson
 *.key
 /db.sqlite
 *.sqlite3

.goreleaser.yml

@@ -27,8 +27,6 @@ builds:
       - linux_arm64
     flags:
       - -mod=readonly
-    tags:
-      - ts2019
 
 archives:
   - id: golang-cross
@@ -44,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
@@ -81,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

CHANGELOG.md

@@ -15,7 +15,8 @@ overall our implementation was very close.
 
 SSH rules with `"action": "check"` are now supported. When a client initiates a SSH connection to a node
 with a `check` action policy, the user is prompted to authenticate via OIDC or CLI approval before access
-is granted.
+is granted. OIDC approval requires the authenticated user to own the source node; tagged source nodes
+cannot use SSH check-mode.
 
 A new `headscale auth` CLI command group supports the approval flow:
 
@@ -24,41 +25,310 @@ A new `headscale auth` CLI command group supports the approval flow:
 - `headscale auth register --auth-id <id> --user <user>` registers a node (replaces deprecated `headscale nodes register`)
 
 [#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. Tests assert which SSH login users
+can connect from a named source to named destinations against the same SSH rules clients receive.
+They 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.
+
+An entry has the shape:
+
+```hujson
+"sshTests": [
+    {
+        "src":    "alice@example.com",
+        "dst":    ["tag:server"],
+        "accept": ["root"],
+        "deny":   ["alice"],
+        "check":  ["ubuntu"]
+    }
+]
+```
+
+`accept` asserts the listed login users reach every dst via an accept- or check-action SSH rule,
+`deny` asserts none of them reach any dst, and `check` requires reachability specifically via a
+check-action rule.
+
+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.
+
+### Grants
+
+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
+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
+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 handling (cleanroom rewrite)
+
+The hostname ingest pipeline has been rewritten to match Tailscale SaaS byte-for-byte.
+Headscale previously had three overlapping regexes and two disagreeing entry points
+(registration vs map-request update), which caused a recurring class of bugs: names
+containing apostrophes, spaces, dots, or non-ASCII characters were alternately rejected
+(dropping updates with log spam) or stored as `invalid-<rand>` surrogates
+([#3188](https://github.com/juanfont/headscale/issues/3188),
+[#2926](https://github.com/juanfont/headscale/issues/2926),
+[#2343](https://github.com/juanfont/headscale/issues/2343),
+[#2762](https://github.com/juanfont/headscale/issues/2762),
+[#2177](https://github.com/juanfont/headscale/issues/2177),
+[#2121](https://github.com/juanfont/headscale/issues/2121),
+[#2449](https://github.com/juanfont/headscale/issues/2449),
+[#363](https://github.com/juanfont/headscale/issues/363)).
+
+What changed:
+
+- Sanitisation and validation now come directly from
+  `tailscale.com/util/dnsname.SanitizeHostname` / `ValidLabel`.
+- Admin rename (`headscale nodes rename`) now validates via `dnsname.ValidLabel` and
+  rejects labels already held by another node (previously coerced invalid input silently).
+
+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`                |
 
 ### 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.
+
+#### 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 relying on wildcard to match non-Tailscale IPs will need to use explicit CIDR ranges instead
+  - 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)
+- 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)
+- 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.
+  Headscale refuses to start when the old key is set. Move it to the
+  policy file referenced by `policy.path` (defaults to
+  `/etc/headscale/policy.hujson`):
+
+  ```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
 
+### 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.
+
 ### Changes
 
-- **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)
+#### 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)
+
+#### Grants
+
+- 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)
+
+#### 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)
-- 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)
+- **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)
+- `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`
+
+#### 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)
+- **Node Expiry**: 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)
+  - Pre-existing rows with `0001-01-01 00:00:00` are not backfilled; they clear themselves the next time the node re-registers
+
 ## 0.28.0 (2026-02-04)
 
 **Minimum supported Tailscale client version: v1.74.0**
@@ -68,7 +338,7 @@ A new `headscale auth` CLI command group supports the approval flow:
 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
@@ -167,7 +437,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
 
@@ -296,8 +566,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
@@ -460,7 +730,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
@@ -974,7 +1244,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:
@@ -1051,7 +1321,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
 
@@ -1081,7 +1351,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.1-alpine AS build-env
+FROM golang:1.26.3-alpine AS build-env
 
 WORKDIR /go/src
 

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.2-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.1-alpine AS build-env
+FROM golang:1.26.3-alpine AS build-env
 
 WORKDIR /go/src
 

Dockerfile.tailscale-rs

@@ -0,0 +1,26 @@
+FROM rust:1.94-bookworm 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:bookworm-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

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
@@ -65,6 +65,12 @@ Please have a look at the [`documentation`](https://headscale.net/stable/).
 
 For NixOS users, a module is available in [`nix/`](./nix/).
 
+## Builds from `main`
+
+Development builds from the `main` branch are available as container images and
+binaries. See the [development builds](https://headscale.net/stable/setup/install/main/)
+documentation for details.
+
 ## Talks
 
 - Fosdem 2026 (video): [Headscale & Tailscale: The complementary open source clone](https://fosdem.org/2026/schedule/event/KYQ3LL-headscale-the-complementary-open-source-clone/)

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

@@ -81,7 +81,7 @@ 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.`,
+If you lose a key, create a new one and revoke (expire) the old one.`,
 	Aliases: []string{"c", "new"},
 	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
 		expiration, err := expirationFromFlag(cmd)

cmd/headscale/cli/nodes.go

@@ -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)
@@ -397,6 +399,7 @@ func nodesToPtables(
 		}
 
 		var ipBuilder strings.Builder
+
 		for _, addr := range node.GetIpAddresses() {
 			ip, err := netip.ParseAddr(addr)
 			if err == nil {

cmd/headscale/cli/policy.go

@@ -28,7 +28,7 @@ func bypassDatabase() (*db.HSDatabase, error) {
 		return nil, fmt.Errorf("loading config: %w", err)
 	}
 
-	d, err := db.NewHeadscaleDatabase(cfg, nil)
+	d, err := db.NewHeadscaleDatabase(cfg)
 	if err != nil {
 		return nil, fmt.Errorf("opening database: %w", err)
 	}
@@ -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 validate user@ token references and to evaluate the policy's tests and sshTests blocks. Required when those checks are needed.")
 	mustMarkRequired(checkPolicy, "file")
 	policyCmd.AddCommand(checkPolicy)
 }
@@ -63,6 +64,7 @@ var getPolicy = &cobra.Command{
 	Aliases: []string{"show", "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)
+			}
+
+			// NewPolicyManager validates structure and user references
+			// but intentionally skips test evaluation (boot path).
+			// 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/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)")

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/README.md

@@ -1,6 +1,262 @@
-# hi
+# hi — Headscale Integration test runner
 
-hi (headscale integration runner) is an entirely "vibe coded" wrapper around our
-[integration test suite](../integration). It essentially runs the docker
-commands for you with some added benefits of extracting resources like logs and
-databases.
+`hi` wraps Docker container orchestration around the tests in
+[`../../integration`](../../integration) and extracts debugging artefacts
+(logs, database snapshots, MapResponse protocol captures) for post-mortem
+analysis.
+
+**Read this file in full before running any `hi` command.** The test
+runner has sharp edges — wrong flags produce stale containers, lost
+artefacts, or hung CI.
+
+For test-authoring patterns (scenario setup, `EventuallyWithT`,
+`IntegrationSkip`, helper variants), read
+[`../../integration/README.md`](../../integration/README.md).
+
+## Quick Start
+
+```bash
+# Verify system requirements (Docker, Go, disk space, images)
+go run ./cmd/hi doctor
+
+# Run a single test (the default flags are tuned for development)
+go run ./cmd/hi run "TestPingAllByIP"
+
+# Run a database-heavy test against PostgreSQL
+go run ./cmd/hi run "TestExpireNode" --postgres
+
+# Pattern matching
+go run ./cmd/hi run "TestSubnet*"
+```
+
+Run `doctor` before the first `run` in any new environment. Tests
+generate ~100 MB of logs per run in `control_logs/`; `doctor` verifies
+there is enough space and that the required Docker images are available.
+
+## Commands
+
+| Command            | Purpose                                              |
+| ------------------ | ---------------------------------------------------- |
+| `run [pattern]`    | Execute the test(s) matching `pattern`               |
+| `doctor`           | Verify system requirements                           |
+| `clean networks`   | Prune unused Docker networks                         |
+| `clean images`     | Clean old test images                                |
+| `clean containers` | Kill **all** test containers (dangerous — see below) |
+| `clean cache`      | Clean Go module cache volume                         |
+| `clean all`        | Run all cleanup operations                           |
+
+## Flags
+
+Defaults are tuned for single-test development runs. Review before
+changing.
+
+| Flag                | Default        | Purpose                                                                     |
+| ------------------- | -------------- | --------------------------------------------------------------------------- |
+| `--timeout`         | `120m`         | Total test timeout. Use the built-in flag — never wrap with bash `timeout`. |
+| `--postgres`        | `false`        | Use PostgreSQL instead of SQLite                                            |
+| `--failfast`        | `true`         | Stop on first test failure                                                  |
+| `--go-version`      | auto           | Detected from `go.mod` (currently 1.26.1)                                   |
+| `--clean-before`    | `true`         | Clean stale (stopped/exited) containers before starting                     |
+| `--clean-after`     | `true`         | Clean this run's containers after completion                                |
+| `--keep-on-failure` | `false`        | Preserve containers for manual inspection on failure                        |
+| `--logs-dir`        | `control_logs` | Where to save run artefacts                                                 |
+| `--verbose`         | `false`        | Verbose output                                                              |
+| `--stats`           | `false`        | Collect container resource-usage stats                                      |
+| `--hs-memory-limit` | `0`            | Fail if any headscale container exceeds N MB (0 = disabled)                 |
+| `--ts-memory-limit` | `0`            | Fail if any tailscale container exceeds N MB                                |
+
+### Timeout guidance
+
+The default `120m` is generous for a single test. If you must tune it,
+these are realistic floors by category:
+
+| Test type                 | Minimum     | Examples                              |
+| ------------------------- | ----------- | ------------------------------------- |
+| Basic functionality / CLI | 900s (15m)  | `TestPingAllByIP`, `TestCLI*`         |
+| Route / ACL               | 1200s (20m) | `TestSubnet*`, `TestACL*`             |
+| HA / failover             | 1800s (30m) | `TestHASubnetRouter*`                 |
+| Long-running              | 2100s (35m) | `TestNodeOnlineStatus` (~12 min body) |
+| Full suite                | 45m         | `go test ./integration -timeout 45m`  |
+
+**Never** use the shell `timeout` command around `hi`. It kills the
+process mid-cleanup and leaves stale containers:
+
+```bash
+timeout 300 go run ./cmd/hi run "TestName"   # WRONG — orphaned containers
+go run ./cmd/hi run "TestName" --timeout=900s  # correct
+```
+
+## Concurrent Execution
+
+Multiple `hi run` invocations can run simultaneously on the same Docker
+daemon. Each invocation gets a unique **Run ID** (format
+`YYYYMMDD-HHMMSS-6charhash`, e.g. `20260409-104215-mdjtzx`).
+
+- **Container names** include the short run ID: `ts-mdjtzx-1-74-fgdyls`
+- **Docker labels**: `hi.run-id={runID}` on every container
+- **Port allocation**: dynamic — kernel assigns free ports, no conflicts
+- **Cleanup isolation**: each run cleans only its own containers
+- **Log directories**: `control_logs/{runID}/`
+
+```bash
+# Start three tests in parallel — each gets its own run ID
+go run ./cmd/hi run "TestPingAllByIP" &
+go run ./cmd/hi run "TestACLAllowUserDst" &
+go run ./cmd/hi run "TestOIDCAuthenticationPingAll" &
+```
+
+### Safety rules for concurrent runs
+
+- ✅ Your run cleans only containers labelled with its own `hi.run-id`
+- ✅ `--clean-before` removes only stopped/exited containers
+- ❌ **Never** run `docker rm -f $(docker ps -q --filter name=hs-)` —
+  this destroys other agents' live test sessions
+- ❌ **Never** run `docker system prune -f` while any tests are running
+- ❌ **Never** run `hi clean containers` / `hi clean all` while other
+  tests are running — both kill all test containers on the daemon
+
+To identify your own containers:
+
+```bash
+docker ps --filter "label=hi.run-id=20260409-104215-mdjtzx"
+```
+
+The run ID appears at the top of the `hi run` output — copy it from
+there rather than trying to reconstruct it.
+
+## Artefacts
+
+Every run saves debugging artefacts under `control_logs/{runID}/`:
+
+```
+control_logs/20260409-104215-mdjtzx/
+├── hs-<test>-<hash>.stderr.log        # headscale server errors
+├── hs-<test>-<hash>.stdout.log        # headscale server output
+├── hs-<test>-<hash>.db                # database snapshot (SQLite)
+├── hs-<test>-<hash>_metrics.txt       # Prometheus metrics dump
+├── hs-<test>-<hash>-mapresponses/     # MapResponse protocol captures
+├── ts-<client>-<hash>.stderr.log      # tailscale client errors
+├── ts-<client>-<hash>.stdout.log      # tailscale client output
+└── ts-<client>-<hash>_status.json     # client network-status dump
+```
+
+Artefacts persist after cleanup. Old runs accumulate fast — delete
+unwanted directories to reclaim disk.
+
+## Debugging workflow
+
+When a test fails, read the artefacts **in this order**:
+
+1. **`hs-*.stderr.log`** — headscale server errors, panics, policy
+   evaluation failures. Most issues originate server-side.
+
+   ```bash
+   grep -E "ERROR|panic|FATAL" control_logs/*/hs-*.stderr.log
+   ```
+
+2. **`ts-*.stderr.log`** — authentication failures, connectivity issues,
+   DNS resolution problems on the client side.
+
+3. **MapResponse JSON** in `hs-*-mapresponses/` — protocol-level
+   debugging for network map generation, peer visibility, route
+   distribution, policy evaluation results.
+
+   ```bash
+   ls control_logs/*/hs-*-mapresponses/
+   jq '.Peers[] | {Name, Tags, PrimaryRoutes}' \
+       control_logs/*/hs-*-mapresponses/001.json
+   ```
+
+4. **`*_status.json`** — client peer-connectivity state.
+
+5. **`hs-*.db`** — SQLite snapshot for post-mortem consistency checks.
+
+   ```bash
+   sqlite3 control_logs/<runID>/hs-*.db
+   sqlite> .tables
+   sqlite> .schema nodes
+   sqlite> SELECT id, hostname, user_id, tags FROM nodes WHERE hostname LIKE '%problematic%';
+   ```
+
+6. **`*_metrics.txt`** — Prometheus dumps for latency, NodeStore
+   operation timing, database query performance, memory usage.
+
+## Heuristic: infrastructure vs code
+
+**Before blaming Docker, disk, or network: read `hs-*.stderr.log` in
+full.** In practice, well over 99% of failures are code bugs (policy
+evaluation, NodeStore sync, route approval) rather than infrastructure.
+
+Actual infrastructure failures have signature error messages:
+
+| Signature                                                       | Cause                     | Fix                                                           |
+| --------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------- |
+| `failed to resolve "hs-...": no DNS fallback candidates remain` | Docker DNS                | Reset Docker networking                                       |
+| `container creation timeout`, no progress >2 min                | Resource exhaustion       | `docker system prune -f` (when no other tests running), retry |
+| OOM kills, slow Docker daemon                                   | Too many concurrent tests | Reduce concurrency, wait for completion                       |
+| `no space left on device`                                       | Disk full                 | Delete old `control_logs/`                                    |
+
+If you don't see a signature error, **assume it's a code regression** —
+do not retry hoping the flake goes away.
+
+## Common failure patterns (code bugs)
+
+### Route advertisement timing
+
+Test asserts route state before the client has finished propagating its
+Hostinfo update. Symptom: `nodes[0].GetAvailableRoutes()` empty when
+the test expects a route.
+
+- **Wrong fix**: `time.Sleep(5 * time.Second)` — fragile and slow.
+- **Right fix**: wrap the assertion in `EventuallyWithT`. See
+  [`../../integration/README.md`](../../integration/README.md).
+
+### NodeStore sync issues
+
+Route changes not reflected in the NodeStore snapshot. Symptom: route
+advertisements in logs but no tracking updates in subsequent reads.
+
+The sync point is `State.UpdateNodeFromMapRequest()` in
+`hscontrol/state/state.go`. If you added a new kind of client state
+update, make sure it lands here.
+
+### HA failover: routes disappearing on disconnect
+
+`TestHASubnetRouterFailover` fails because approved routes vanish when
+a subnet router goes offline. **This is a bug, not expected behaviour.**
+Route approval must not be coupled to client connectivity — routes
+stay approved; only the primary-route selection is affected by
+connectivity.
+
+### Policy evaluation race
+
+Symptom: tests that change policy and immediately assert peer visibility
+fail intermittently. Policy changes trigger async recomputation.
+
+- See recent fixes in `git log -- hscontrol/state/` for examples (e.g.
+  the `PolicyChange` trigger on every Connect/Disconnect).
+
+### SQLite vs PostgreSQL timing differences
+
+Some race conditions only surface on one backend. If a test is flaky,
+try the other backend with `--postgres`:
+
+```bash
+go run ./cmd/hi run "TestName" --postgres --verbose
+```
+
+PostgreSQL generally has more consistent timing; SQLite can expose
+races during rapid writes.
+
+## Keeping containers for inspection
+
+If you need to inspect a failed test's state manually:
+
+```bash
+go run ./cmd/hi run "TestName" --keep-on-failure
+# containers survive — inspect them
+docker exec -it ts-<runID>-<...> /bin/sh
+docker logs hs-<runID>-<...>
+# clean up manually when done
+go run ./cmd/hi clean all   # only when no other tests are running
+```

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.
@@ -50,12 +50,21 @@ noise:
 # List of IP prefixes to allocate tailaddresses from.
 # Each prefix consists of either an IPv4 or IPv6 address,
 # and the associated prefix length, delimited by a slash.
-# It must be within IP ranges supported by the Tailscale
-# client - i.e., subnets of 100.64.0.0/10 and fd7a:115c:a1e0::/48.
-# See below:
-# IPv6: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#LL81C52-L81C71
+#
+# WARNING: These prefixes MUST be subsets of the standard Tailscale ranges:
+#   - IPv4: 100.64.0.0/10 (CGNAT range)
+#   - IPv6: fd7a:115c:a1e0::/48 (Tailscale ULA range)
+#
+# Using a SUBSET of these ranges is supported and useful if you want to
+# limit IP allocation to a smaller block (e.g., 100.64.0.0/24).
+#
+# Using ranges OUTSIDE of CGNAT/ULA is NOT supported and will cause
+# undefined behaviour. The Tailscale client has hard-coded assumptions
+# about these ranges and will break in subtle, hard-to-debug ways.
+#
+# See:
 # IPv4: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#L33
-# Any other range is NOT supported, and it will cause unexpected issues.
+# IPv6: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#LL81C52-L81C71
 prefixes:
   v4: 100.64.0.0/10
   v6: fd7a:115c:a1e0::/48
@@ -119,7 +128,7 @@ derp:
   #
   # This option is mostly interesting for people hosting
   # their own DERP servers:
-  # https://tailscale.com/kb/1118/custom-derp-servers/
+  # https://tailscale.com/docs/reference/derp-servers/custom-derp-servers
   #
   # paths:
   #   - /etc/headscale/derp-example.yaml
@@ -136,8 +145,45 @@ derp:
 # Disables the automatic check for headscale updates on startup
 disable_check_updates: false
 
-# Time before an inactive ephemeral node is deleted?
-ephemeral_node_inactivity_timeout: 30m
+# Node lifecycle configuration.
+node:
+  # Default key expiry for non-tagged nodes, regardless of registration method
+  # (auth key, CLI, web auth). Tagged nodes are exempt and never expire.
+  #
+  # This is the base default. OIDC can override this via oidc.expiry.
+  # If a client explicitly requests a specific expiry, the client value is used.
+  #
+  # Setting the value to "0" means no default expiry (nodes never expire unless
+  # explicitly expired via `headscale nodes expire`).
+  #
+  # Tailscale SaaS uses 180d; set to a positive duration to match that behaviour.
+  #
+  # Default: 0 (no default expiry)
+  expiry: 0
+
+  ephemeral:
+    # 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
@@ -235,25 +281,25 @@ 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/access-control/acls
+# - 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
@@ -263,12 +309,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](https://tailscale.com/docs/features/magicdns).
   magic_dns: true
 
   # Defines the base domain to create the hostnames for MagicDNS.
@@ -290,11 +336,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:
@@ -346,15 +392,11 @@ unix_socket_permission: "0770"
 #   # `LoadCredential` straightforward:
 #   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
 #
-#   # The amount of time a node is authenticated with OpenID until it expires
-#   # and needs to reauthenticate.
-#   # Setting the value to "0" will mean no expiry.
-#   expiry: 180d
-#
 #   # Use the expiry from the token received from OpenID when the user logged
 #   # in. This will typically lead to frequent need to reauthenticate and should
 #   # only be enabled if you know what you are doing.
-#   # Note: enabling this will cause `oidc.expiry` to be ignored.
+#   # Note: enabling this will cause `node.expiry` to be ignored for
+#   # OIDC-authenticated nodes.
 #   use_expiry_from_token: false
 #
 #   # The OIDC scopes to use, defaults to "openid", "profile" and "email".
@@ -403,31 +445,41 @@ 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.
 #
 # tuning:
+#   # Maximum number of pending registration entries in the auth cache.
+#   # Oldest entries are evicted when the cap is reached.
+#   #
+#   # register_cache_max_entries: 1024
+#
 #   # NodeStore write batching configuration.
 #   # The NodeStore batches write operations before rebuilding peer relationships,
 #   # which is computationally expensive. Batching reduces rebuild frequency.

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,32 @@ 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] [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 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/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

@@ -145,16 +145,12 @@ oidc:
 ### Customize node expiration
 
 The node expiration is the amount of time a node is authenticated with OpenID Connect until it expires and needs to
-reauthenticate. The default node expiration is 180 days. This can either be customized or set to the expiration from the
-Access Token.
+reauthenticate. The default node expiration can be configured via the top-level `node.expiry` setting.
 
 === "Customize node expiration"
 
-    ```yaml hl_lines="5"
-    oidc:
-      issuer: "https://sso.example.com"
-      client_id: "headscale"
-      client_secret: "generated-secret"
+    ```yaml hl_lines="2"
+    node:
       expiry: 30d   # Use 0 to disable node expiration
     ```
 
@@ -191,8 +187,10 @@ You may refer to users in the Headscale policy via:
 !!! note "A user identifier in the policy must contain a single `@`"
 
     The Headscale policy requires a single `@` to reference a user. If the username or provider identifier doesn't
-    already contain a single `@`, it needs to be appended at the end. For example: the username `ssmith` has to be
-    written as `ssmith@` to be correctly identified as user within the policy.
+    already contain a single `@`, it needs to be appended at the end. For example: the Headscale username `ssmith` has
+    to be written as `ssmith@` to be correctly identified as user within the policy.
+
+    Ensure that the Headscale username itself does not end with `@`.
 
 !!! warning "Email address or username might be updated by users"
 
@@ -216,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": ["*"]
         }
       ]
     }
@@ -248,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 `@`.
@@ -285,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,200 @@
+# 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.
+
+[^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.

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
@@ -33,7 +33,8 @@ node can be approved with:
 - [Headscale API](api.md)
 - Or delegated to an identity provider via [OpenID Connect](oidc.md)
 
-Web authentication relies on the presence of a Headscale user. Use the `headscale users` command to create a new user:
+Web authentication relies on the presence of a Headscale user. Use the `headscale users` command to create a new
+user[^1]:
 
 ```console
 headscale users create <USER>
@@ -60,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"
     {
@@ -98,7 +99,7 @@ Its best suited for automation.
 
 === "Personal devices"
 
-    A personal node is always assigned to a Headscale user. Use the `headscale users` command to create a new user:
+    A personal node is always assigned to a Headscale user. Use the `headscale users` command to create a new user[^1]:
 
     ```console
     headscale users create <USER>
@@ -139,3 +140,5 @@ Its best suited for automation.
     The registration of a tagged node is complete and it should be listed as "online" in the output of
     `headscale nodes list`. The "User" column displays `tagged-devices` as the owner of the node. See the "Tags" column for the list of
     assigned tags.
+
+[^1]: [Ensure that the Headscale username does not end with `@`.](oidc.md#reference-a-user-in-the-policy)

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/requirements.txt

@@ -1,6 +1,6 @@
 mike~=2.1
-mkdocs-include-markdown-plugin~=7.1
-mkdocs-macros-plugin~=1.3
-mkdocs-material[imaging]~=9.5
-mkdocs-minify-plugin~=0.7
+mkdocs-include-markdown-plugin~=7.2
+mkdocs-macros-plugin~=1.5
+mkdocs-materialx[imaging]~=10.1
+mkdocs-minify-plugin~=0.8
 mkdocs-redirects~=1.2

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

@@ -0,0 +1,58 @@
+# Development builds
+
+!!! warning
+
+    Development builds are created automatically from the latest `main` branch
+    and are **not versioned releases**. They may contain incomplete features,
+    breaking changes, or bugs. Use them for testing only.
+
+Each push to `main` produces container images and cross-compiled binaries.
+Container images are multi-arch (amd64, arm64) and use the same distroless
+base image as official releases.
+
+## Container images
+
+Images are available from both Docker Hub and GitHub Container Registry, tagged
+with the short commit hash of the build (e.g. `main-abc1234`):
+
+- Docker Hub: `docker.io/headscale/headscale:main-<sha>`
+- GitHub Container Registry: `ghcr.io/juanfont/headscale:main-<sha>`
+
+To find the latest available tag, check the
+[GitHub Actions workflow](https://github.com/juanfont/headscale/actions/workflows/container-main.yml)
+or the [GitHub Container Registry package page](https://github.com/juanfont/headscale/pkgs/container/headscale).
+
+For example, to run a specific development build:
+
+```shell
+docker run \
+  --name headscale \
+  --detach \
+  --read-only \
+  --tmpfs /var/run/headscale \
+  --volume "$(pwd)/config:/etc/headscale:ro" \
+  --volume "$(pwd)/lib:/var/lib/headscale" \
+  --publish 127.0.0.1:8080:8080 \
+  --publish 127.0.0.1:9090:9090 \
+  --health-cmd "CMD headscale health" \
+  docker.io/headscale/headscale:main-<sha> \
+  serve
+```
+
+See [Running headscale in a container](container.md) for full container setup instructions.
+
+## Binaries
+
+Pre-built binaries from the latest successful build on `main` are available
+via [nightly.link](https://nightly.link/juanfont/headscale/workflows/container-main/main):
+
+| OS    | Arch  | Download                                                                                                                   |
+| ----- | ----- | -------------------------------------------------------------------------------------------------------------------------- |
+| Linux | amd64 | [headscale-linux-amd64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-linux-amd64.zip)   |
+| Linux | arm64 | [headscale-linux-arm64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-linux-arm64.zip)   |
+| macOS | amd64 | [headscale-darwin-amd64](https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-darwin-amd64.zip) |
+| 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)
+instructions for setting up the service.

docs/setup/install/official.md

@@ -24,7 +24,8 @@ 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
@@ -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
 

docs/usage/getting-started.md

@@ -61,7 +61,7 @@ options, run:
 ## Manage headscale users
 
 In headscale, a node (also known as machine or device) is [typically assigned to a headscale
-user](../ref/registration.md#identity-model). Such a headscale user may have many nodes assigned to them and can be
+user](../ref/registration.md#identity-model). Such a headscale user[^1] may have many nodes assigned to them and can be
 managed with the `headscale users` command. Invoke the built-in help for more information: `headscale users --help`.
 
 ### Create a headscale user
@@ -149,3 +149,5 @@ The command returns the preauthkey on success which is used to connect a node to
 ```shell
 tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
 ```
+
+[^1]: [Ensure that the Headscale username does not end with `@`.](../ref/oidc.md#reference-a-user-in-the-policy)

flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1772956932,
-        "narHash": "sha256-M0yS4AafhKxPPmOHGqIV0iKxgNO8bHDWdl1kOwGBwRY=",
+        "lastModified": 1777270315,
+        "narHash": "sha256-yKB4G6cKsQsWN7M6rZGk6gkJPDNPIzT05y4qzRyCDlI=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "608d0cadfed240589a7eea422407a547ad626a14",
+        "rev": "6368eda62c9775c38ef7f714b2555a741c20c72d",
         "type": "github"
       },
       "original": {

flake.nix

@@ -27,7 +27,7 @@
         let
           pkgs = nixpkgs.legacyPackages.${prev.stdenv.hostPlatform.system};
           buildGo = pkgs.buildGo126Module;
-          vendorHash = "sha256-oUN53ELb3+xn4yA7lEfXyT2c7NxbQC6RtbkGVq6+RLU=";
+          vendorHash = (builtins.fromJSON (builtins.readFile ./flakehashes.json)).vendor.sri;
         in
         {
           headscale = buildGo {
@@ -38,8 +38,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 +62,16 @@
 
           protoc-gen-grpc-gateway = buildGo rec {
             pname = "grpc-gateway";
-            version = "2.27.7";
+            version = "2.28.0";
 
             src = pkgs.fetchFromGitHub {
               owner = "grpc-ecosystem";
               repo = "grpc-gateway";
               rev = "v${version}";
-              sha256 = "sha256-6R0EhNnOBEISJddjkbVTcBvUuU5U3r9Hu2UPfAZDep4=";
+              sha256 = "sha256-93omvHb+b+S0w4D+FGEEwYYDjgumJFDAruc1P4elfvA=";
             };
 
-            vendorHash = "sha256-SOAbRrzMf2rbKaG9PGSnPSLY/qZVgbHcNjOLmVonycY=";
+            vendorHash = "sha256-jVP5zfFPfHeAEApKNJzZwuZLA+DjKgkL7m2DFG72UNs=";
 
             nativeBuildInputs = [ pkgs.installShellFiles ];
 
@@ -80,13 +80,13 @@
 
           protobuf-language-server = buildGo rec {
             pname = "protobuf-language-server";
-            version = "1cf777d";
+            version = "ab4c128";
 
             src = pkgs.fetchFromGitHub {
               owner = "lasorda";
               repo = "protobuf-language-server";
-              rev = "1cf777de4d35a6e493a689e3ca1a6183ce3206b6";
-              sha256 = "sha256-9MkBQPxr/TDr/sNz/Sk7eoZwZwzdVbE5u6RugXXk5iY=";
+              rev = "ab4c128f00774d51bd6d1f4cfa735f4b7c8619e3";
+              sha256 = "sha256-yF6kG+qTRxVO/qp2V9HgTyFBeOm5RQzeqdZFrdidwxM=";
             };
 
             vendorHash = "sha256-4nTpKBe7ekJsfQf+P6edT/9Vp2SBYbKz1ITawD3bhkI=";
@@ -97,16 +97,16 @@
           # Build golangci-lint with Go 1.26 (upstream uses hardcoded Go version)
           golangci-lint = buildGo rec {
             pname = "golangci-lint";
-            version = "2.9.0";
+            version = "2.11.4";
 
             src = pkgs.fetchFromGitHub {
               owner = "golangci";
               repo = "golangci-lint";
               rev = "v${version}";
-              hash = "sha256-8LEtm1v0slKwdLBtS41OilKJLXytSxcI9fUlZbj5Gfw=";
+              hash = "sha256-B19aLvfNRY9TOYw/71f2vpNUuSIz8OI4dL0ijGezsas=";
             };
 
-            vendorHash = "sha256-w8JfF6n1ylrU652HEv/cYdsOdDZz9J2uRQDqxObyhkY=";
+            vendorHash = "sha256-xuoj4+U4tB5gpABKq4Dbp2cxnljxdYoBbO8A7DqPM5E=";
 
             subPackages = [ "cmd/golangci-lint" ];
 
@@ -166,7 +166,7 @@
             golangci-lint
             golangci-lint-langserver
             golines
-            nodePackages.prettier
+            prettier
             nixpkgs-fmt
             goreleaser
             nfpm
@@ -223,13 +223,7 @@
                 "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

flakehashes.json

@@ -0,0 +1,6 @@
+{
+  "vendor": {
+    "goModSum": "sha256-IE0n9cSqO4XNX4RN+CGBk9VC46iACiZKDFf/215iivk=",
+    "sri": "sha256-ijEIP9NSomhlWOgsVN7tPvSuvkTiLtnvXvhZmatIDLM="
+  }
+}

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.0
+// - protoc-gen-go-grpc v1.6.1
 // - 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,14 +1,14 @@
 module github.com/juanfont/headscale
 
-go 1.26.1
+go 1.26.2
 
 require (
 	github.com/arl/statsviz v0.8.0
 	github.com/cenkalti/backoff/v5 v5.0.3
 	github.com/chasefleming/elem-go v0.31.0
 	github.com/coder/websocket v1.8.14
-	github.com/coreos/go-oidc/v3 v3.17.0
-	github.com/creachadair/command v0.2.0
+	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/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc
 	github.com/docker/docker v28.5.2+incompatible
@@ -17,11 +17,12 @@ require (
 	github.com/go-chi/chi/v5 v5.2.5
 	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-20251027170946-4849db3c2f7e
+	github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433
 	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.27.7
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.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
 	github.com/ory/dockertest/v3 v3.12.0
@@ -29,32 +30,32 @@ require (
 	github.com/pkg/profile v1.7.0
 	github.com/prometheus/client_golang v1.23.2
 	github.com/prometheus/common v0.67.5
-	github.com/pterm/pterm v0.12.82
+	github.com/pterm/pterm v0.12.83
 	github.com/puzpuzpuz/xsync/v4 v4.4.0
-	github.com/rs/zerolog v1.34.0
-	github.com/samber/lo v1.52.0
-	github.com/sasha-s/go-deadlock v0.3.6
+	github.com/rs/zerolog v1.35.0
+	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-20250605163823-992244df8c5a
-	github.com/tailscale/squibble v0.0.0-20251104223530-a961feffb67f
-	github.com/tailscale/tailsql v0.0.0-20260105194658-001575c3ca09
+	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/tcnksm/go-latest v0.0.0-20170313132115-e3007ae9052e
 	go4.org/netipx v0.0.0-20231129151722-fdeea329fbba
-	golang.org/x/crypto v0.47.0
-	golang.org/x/exp v0.0.0-20260112195511-716be5621a96
-	golang.org/x/net v0.49.0
-	golang.org/x/oauth2 v0.34.0
-	golang.org/x/sync v0.19.0
-	google.golang.org/genproto/googleapis/api v0.0.0-20260203192932-546029d2fa20
-	google.golang.org/grpc v1.78.0
+	golang.org/x/crypto v0.50.0
+	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90
+	golang.org/x/net v0.53.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
 	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.94.1
-	zgo.at/zcache/v2 v2.4.1
+	pgregory.net/rapid v1.2.0
+	tailscale.com v1.97.0-pre.0.20260429005429-40088602c960
 	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.67.6 // indirect
+	modernc.org/libc v1.70.0 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
-	modernc.org/sqlite v1.44.3
+	modernc.org/sqlite v1.48.2
 )
 
 // NOTE: gvisor must be updated in lockstep with
@@ -88,19 +89,22 @@ require (
 // To find the correct version, check tailscale.com's
 // go.mod file for the gvisor.dev/gvisor version:
 // https://github.com/tailscale/tailscale/blob/main/go.mod
-require gvisor.dev/gvisor v0.0.0-20250205023644-9414b50a5633 // indirect
+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/schedule v0.1.0 // indirect
 	dario.cat/mergo v1.0.2 // indirect
-	filippo.io/edwards25519 v1.1.0 // 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
@@ -119,33 +124,34 @@ require (
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
-	github.com/clipperhouse/stringish v0.1.1 // indirect
-	github.com/clipperhouse/uax29/v2 v2.5.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/errdefs v1.0.0 // indirect
 	github.com/containerd/errdefs/pkg v0.3.0 // indirect
-	github.com/creachadair/mds v0.25.15 // indirect
+	github.com/creachadair/mds v0.26.2 // 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/cli v29.4.0+incompatible // indirect
 	github.com/docker/go-connections v0.6.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/v4 v4.1.3 // 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/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
@@ -166,20 +172,22 @@ require (
 	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/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 // indirect
+	github.com/klauspost/compress v1.18.5 // indirect
 	github.com/lib/pq v1.11.1 // 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.19 // indirect
+	github.com/mattn/go-runewidth v0.0.20 // 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.1 // indirect
+	github.com/moby/moby/client v0.4.0 // 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
@@ -190,6 +198,7 @@ require (
 	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/peterbourgon/ff/v3 v3.4.0 // indirect
 	github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741 // indirect
 	github.com/pires/go-proxyproto v0.9.2 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
@@ -201,16 +210,18 @@ require (
 	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/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-20260304043104-4184faf59e56 // 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
@@ -225,18 +236,25 @@ require (
 	go.yaml.in/yaml/v2 v2.4.3 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	go4.org/mem v0.0.0-20240501181205-ae6ca9944745 // indirect
-	golang.org/x/mod v0.32.0 // indirect
-	golang.org/x/sys v0.40.0 // indirect
-	golang.org/x/term v0.39.0 // indirect
-	golang.org/x/text v0.33.0 // indirect
-	golang.org/x/time v0.14.0 // indirect
-	golang.org/x/tools v0.41.0 // indirect
+	golang.org/x/image v0.27.0 // 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/time v0.15.0 // indirect
+	golang.org/x/tools v0.44.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-20260203192932-546029d2fa20 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 // 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

@@ -10,14 +10,18 @@ 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=
 dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
-filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
-filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+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/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.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=
@@ -40,6 +44,8 @@ github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be/go.mod h1:ySMOLuW
 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=
@@ -103,10 +109,8 @@ github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMn
 github.com/chzyer/test v1.0.0/go.mod h1:2JlltgoNkt4TW/z9V/IzDdFaMTM2JPIi26O1pF38GC8=
 github.com/cilium/ebpf v0.17.3 h1:FnP4r16PWYSE4ux6zN+//jMcW4nMVRvuTLVTvCjyyjg=
 github.com/cilium/ebpf v0.17.3/go.mod h1:G5EDHij8yiLzaqn0WjyfJHvRa+3aDlReIaLVRMvOyJk=
-github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
-github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
-github.com/clipperhouse/uax29/v2 v2.5.0 h1:x7T0T4eTHDONxFJsL94uKNKPHrclyFI0lm7+w94cO8U=
-github.com/clipperhouse/uax29/v2 v2.5.0/go.mod h1:Wn1g7MK6OoeDT0vL+Q0SQLDz/KpfsVRgg6W7ihQeh4g=
+github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
+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=
@@ -122,16 +126,15 @@ github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
 github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
 github.com/coreos/go-iptables v0.7.1-0.20240112124308-65c67c9f46e6 h1:8h5+bWd7R6AYUslN6c6iuZWTKsKxUFDlpnmilO6R2n0=
 github.com/coreos/go-iptables v0.7.1-0.20240112124308-65c67c9f46e6/go.mod h1:Qe8Bv2Xik5FyTXwgIbLAnv2sWSBmvWdFETJConOQ//Q=
-github.com/coreos/go-oidc/v3 v3.17.0 h1:hWBGaQfbi0iVviX4ibC7bk8OKT5qNr4klBaCHVNvehc=
-github.com/coreos/go-oidc/v3 v3.17.0/go.mod h1:wqPbKFrVnE90vty060SB40FCJ8fTHTxSwyXJqZH+sI8=
-github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+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.0 h1:qTA9cMMhZePAxFoNdnk6F6nn94s1qPndIg9hJbqI9cA=
-github.com/creachadair/command v0.2.0/go.mod h1:j+Ar+uYnFsHpkMeV9kGj6lJ45y9u2xqtg8FYy6cm+0o=
+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.25.15 h1:i8CUqtfgbCqbvZ++L7lm8No3cOeic9YKF4vHEvEoj+Y=
-github.com/creachadair/mds v0.25.15/go.mod h1:XtMfRW15sjd1iOi1Z1k+dq0pRsR5xPbulpoTrpyhk8w=
+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/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=
@@ -152,8 +155,8 @@ 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.4.0+incompatible h1:+IjXULMetlvWJiuSI0Nbor36lcJ5BTcVpUmB21KBoVM=
+github.com/docker/cli v29.4.0+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=
@@ -167,6 +170,8 @@ 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=
@@ -189,10 +194,10 @@ github.com/go-gormigrate/gormigrate/v2 v2.1.5 h1:1OyorA5LtdQw12cyJDEHuTrEV3GiXiI
 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-jose/go-jose/v4 v4.1.3 h1:CVLmWDhDVRa6Mi/IgCgaopNosCaHz7zrMeF9MlZRkrs=
-github.com/go-jose/go-jose/v4 v4.1.3/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
-github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e h1:Lf/gRkoycfOBPa42vU2bbgPurFong6zXeFtPoxholzU=
-github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e/go.mod h1:uNVvRXArCGbZ508SxYYTC5v1JWoz2voff5pm25jU1Ok=
+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-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=
@@ -209,13 +214,14 @@ github.com/go4org/plan9netshell v0.0.0-20250324183649-788daa080737/go.mod h1:MIS
 github.com/gobwas/httphead v0.1.0/go.mod h1:O/RXo79gxV8G+RqlR/otEwx4Q36zl9rqC5u12GKvMCM=
 github.com/gobwas/pool v0.2.1/go.mod h1:q8bcK0KcYlCgd9e7WYLm9LpyS+YeLd8JVDW6WezmKEw=
 github.com/gobwas/ws v1.2.1/go.mod h1:hRKAFb8wOxFROYNsT1bqfWnhX+b5MFeJM9r2ZSwg/KY=
-github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
 github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
 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=
@@ -252,11 +258,10 @@ github.com/gorilla/mux v1.8.1 h1:TuBL49tXwgrFYWhqrNgrUNEY92u81SPhu7sTdzQEiWY=
 github.com/gorilla/mux v1.8.1/go.mod h1:AKf9I4AEqPTmMytcMc0KkNouC66V3BtZ4qD5fmWSiMQ=
 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.27.7 h1:X+2YciYSxvMQK0UZ7sg45ZVabVZBeBuvMkmuI2V3Fak=
-github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.7/go.mod h1:lW34nIZuQ8UDPdkon5fmfp2l3+ZkQ2me/+oecHYLOII=
+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/hashicorp/golang-lru v0.6.0 h1:uL2shRDx7RTrOrTCUZEGP/wJUFiUI8QT6E7z5o8jga4=
 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=
@@ -289,13 +294,17 @@ 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/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.5 h1:/h1gH5Ce+VWNLSWqPzOVn6XBO+vJbCNGvjoaGBFW2IE=
+github.com/klauspost/compress v1.18.5/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
 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=
@@ -321,16 +330,13 @@ github.com/lib/pq v1.11.1/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.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
 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.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
-github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 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.19 h1:v++JhqYnZuu5jSKrk9RbgF5v4CGUjqRfBm05byFGLdw=
-github.com/mattn/go-runewidth v0.0.19/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+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/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=
@@ -345,10 +351,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.1 h1:TqVzuJkOLsgLDDwNLmYqACUuTehOHRGKiPhvH8V3Nn4=
+github.com/moby/moby/api v1.54.1/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs=
+github.com/moby/moby/client v0.4.0 h1:S+2XegzHQrrvTCvF6s5HFzcrywWQmuVnhOXe2kiWjIw=
+github.com/moby/moby/client v0.4.0/go.mod h1:QWPbvWchQbxBNdaLSpoKpCdf5E+WxFAgNHogCWDoa7g=
 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=
@@ -378,13 +384,15 @@ github.com/ory/dockertest/v3 v3.12.0 h1:3oV9d0sDzlSQfHtIaB5k6ghUCVMVLpAY8hwrqoCy
 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/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/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.21 h1:yOVMLb6qSIDP67pl/5F7RepeKYu/VmTyEXvuMI5d9mQ=
-github.com/pierrec/lz4/v4 v4.1.21/go.mod h1:gZWDp/Ze/IJXGXf23ltt2EXimqmTUXEy0GFuRQyBid4=
+github.com/pierrec/lz4/v4 v4.1.25 h1:kocOqRffaIbU5djlIBr7Wh+cx82C0vtFb0fOurZHqD0=
+github.com/pierrec/lz4/v4 v4.1.25/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
 github.com/pires/go-proxyproto v0.9.2 h1:H1UdHn695zUVVmB0lQ354lOWHOy6TZSpzBl3tgN0s1U=
 github.com/pires/go-proxyproto v0.9.2/go.mod h1:ZKAAyp3cgy5Y5Mo4n9AlScrkCZwUy0g3Jf+slqQVcuU=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
@@ -413,8 +421,8 @@ github.com/pterm/pterm v0.12.31/go.mod h1:32ZAWZVXD7ZfG0s8qqHXePte42kdz8ECtRyEej
 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/pterm/pterm v0.12.82 h1:+D9wYhCaeaK0FIQoZtqbNQuNpe2lB2tajKKsTd5paVQ=
-github.com/pterm/pterm v0.12.82/go.mod h1:TyuyrPjnxfwP+ccJdBTeWHtd/e0ybQHkOS/TakajZCw=
+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/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
@@ -422,23 +430,24 @@ github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qq
 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/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
-github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
-github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
+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/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=
 github.com/sagikazarmark/locafero v0.12.0 h1:/NQhBAkUb4+fH1jivKHWusDYFjMOOKU88eegjfxfHb4=
 github.com/sagikazarmark/locafero v0.12.0/go.mod h1:sZh36u/YSZ918v0Io+U9ogLYQJ9tLLBmM4eneO6WwsI=
-github.com/samber/lo v1.52.0 h1:Rvi+3BFHES3A8meP33VPAxiBZX/Aws5RxrschYGjomw=
-github.com/samber/lo v1.52.0/go.mod h1:4+MXEGsJzbKGaUEQFKBq2xtfuznW9oz/WrgyzMzRoM0=
-github.com/sasha-s/go-deadlock v0.3.6 h1:TR7sfOnZ7x00tWPfD397Peodt57KzMDo+9Ae9rMiUmw=
-github.com/sasha-s/go-deadlock v0.3.6/go.mod h1:CUqNyyvMxTyjFqDT7MRg9mb4Dv/btmGTqSR+rky/UXo=
+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/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=
@@ -464,30 +473,32 @@ 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=
 github.com/tailscale/golang-x-crypto v0.0.0-20250404221719-a5573b049869/go.mod h1:ikbF+YT089eInTp9f2vmvy4+ZVnW5hzX1q2WknxSprQ=
-github.com/tailscale/hujson v0.0.0-20250605163823-992244df8c5a h1:a6TNDN9CgG+cYjaeN8l2mc4kSz2iMiCDQxPEyltUV/I=
-github.com/tailscale/hujson v0.0.0-20250605163823-992244df8c5a/go.mod h1:EbW0wDK/qEUYI0A5bqq0C2kF8JTQwWONmGDBbzsxxHo=
+github.com/tailscale/hujson v0.0.0-20260302212456-ecc657c15afd h1:Rf9uhF1+VJ7ZHqxrG8pJ6YacmHvVCmByDmGbAWCc/gA=
+github.com/tailscale/hujson v0.0.0-20260302212456-ecc657c15afd/go.mod h1:EbW0wDK/qEUYI0A5bqq0C2kF8JTQwWONmGDBbzsxxHo=
 github.com/tailscale/netlink v1.1.1-0.20240822203006-4d49adab4de7 h1:uFsXVBE9Qr4ZoF094vE6iYTLDl0qCiKzYXlL6UeWObU=
 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-20251104223530-a961feffb67f h1:CL6gu95Y1o2ko4XiWPvWkJka0QmQWcUyPywWVWDPQbQ=
-github.com/tailscale/squibble v0.0.0-20251104223530-a961feffb67f/go.mod h1:xJkMmR3t+thnUQhA3Q4m2VSlS5pcOq+CIjmU/xfKKx4=
-github.com/tailscale/tailsql v0.0.0-20260105194658-001575c3ca09 h1:Fc9lE2cDYJbBLpCqnVmoLdf7McPqoHZiDxDPPpkJM04=
-github.com/tailscale/tailsql v0.0.0-20260105194658-001575c3ca09/go.mod h1:QMNhC4XGFiXKngHVLXE+ERDmQoH0s5fD7AUxupykocQ=
+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/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-20260304043104-4184faf59e56 h1:/R1vu+eNhg1eKstmVPEKvsJgkh4TUyb+J+Eadwv+d/I=
+github.com/tailscale/wireguard-go v0.0.0-20260304043104-4184faf59e56/go.mod h1:zvaAPQrjUBWufXgqpSQ1/BYu9ZFOKnsNWLFQe+E78cM=
 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=
@@ -496,6 +507,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=
@@ -548,33 +561,33 @@ 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.47.0 h1:V6e3FRj+n4dbpw86FJ8Fv7XVOql7TEwpHapKoMJ/GO8=
-golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4A=
-golang.org/x/exp v0.0.0-20260112195511-716be5621a96 h1:Z/6YuSHTLOHfNFdb8zVZomZr7cqNgTJvA8+Qz75D8gU=
-golang.org/x/exp v0.0.0-20260112195511-716be5621a96/go.mod h1:nzimsREAkjBCIEFtHiYkrJyT+2uy9YZJB7H1k68CXZU=
+golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=
+golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
+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/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.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=
-golang.org/x/mod v0.32.0/go.mod h1:SgipZ/3h2Ci89DlEtEXWUk/HteuRin+HHhN+WbNhguU=
+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/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.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
-golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
-golang.org/x/oauth2 v0.34.0 h1:hqK/t4AKgbqWkdkcAeI8XLmbK+4m4G5YeQRrmiotGlw=
-golang.org/x/oauth2 v0.34.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
+golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
+golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
+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.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+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/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=
@@ -587,15 +600,13 @@ golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/go.mod h1:oPkhp1MJrh7nUepCBc
 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.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 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.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
-golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
+golang.org/x/sys v0.43.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=
@@ -603,37 +614,37 @@ golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuX
 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.39.0 h1:RclSuaJf32jOqZz74CkPA9qFuVTX7vhLlpfj/IGWlqY=
-golang.org/x/term v0.39.0/go.mod h1:yxzUCTP/U+FzoxfdKmLaA0RV1WgE0VY7hXBwKtY/4ww=
+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/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.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
-golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
-golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
-golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
+golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
+golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+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.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=
-golang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg=
+golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
+golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
 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=
 golang.zx2c4.com/wireguard/windows v0.5.3 h1:On6j2Rpn3OEMXqBq00QEDC7bWSZrPIHKIus8eIuExIE=
 golang.zx2c4.com/wireguard/windows v0.5.3/go.mod h1:9TEe8TJmtwyQebdFwAkEWOPr3prrtqm+REGFifP60hI=
-gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
-gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
-google.golang.org/genproto/googleapis/api v0.0.0-20260203192932-546029d2fa20 h1:7ei4lp52gK1uSejlA8AZl5AJjeLUOHBQscRQZUgAcu0=
-google.golang.org/genproto/googleapis/api v0.0.0-20260203192932-546029d2fa20/go.mod h1:ZdbssH/1SOVnjnDlXzxDHK2MCidiqXtbYccJNzNYPEE=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260203192932-546029d2fa20 h1:Jr5R2J6F6qWyzINc+4AM8t5pfUz6beZpHp678GNrMbE=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260203192932-546029d2fa20/go.mod h1:j9x/tPzZkyxcgEFkiKEEGxfvyumM01BEtsW8xzOahRQ=
-google.golang.org/grpc v1.78.0 h1:K1XZG/yGDJnzMdd/uZHAkVqJE+xIDOcmdSFZkBUicNc=
-google.golang.org/grpc v1.78.0/go.mod h1:I47qjTo4OKbMkjA/aOOwxDIiPSBofUtQUI5EfpWvW7U=
+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/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=
@@ -642,6 +653,9 @@ gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntN
 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=
@@ -652,26 +666,28 @@ gorm.io/gorm v1.31.1 h1:7CA8FTFz/gRfgqgpeKIBcervUn3xSyPUmr6B2WXJ7kg=
 gorm.io/gorm v1.31.1/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=
 gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
 gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
-gvisor.dev/gvisor v0.0.0-20250205023644-9414b50a5633 h1:2gap+Kh/3F47cO6hAu3idFvsJ0ue6TRcEi2IUkv/F8k=
-gvisor.dev/gvisor v0.0.0-20250205023644-9414b50a5633/go.mod h1:5DMfjtclAbTIjbXqO1qCe2K5GKKxWz2JHvCChuTcJEM=
-honnef.co/go/tools v0.7.0-0.dev.0.20251022135355-8273271481d0 h1:5SXjd4ET5dYijLaf0O3aOenC0Z4ZafIWSpjUzsQaNho=
-honnef.co/go/tools v0.7.0-0.dev.0.20251022135355-8273271481d0/go.mod h1:EPDDhEZqVHhWuPI5zPAsjU0U7v9xNIWjoOVyZ5ZcniQ=
+gvisor.dev/gvisor v0.0.0-20260224225140-573d5e7127a8 h1:Zy8IV/+FMLxy6j6p87vk/vQGKcdnbprwjTxc8UiUtsA=
+gvisor.dev/gvisor v0.0.0-20260224225140-573d5e7127a8/go.mod h1:QkHjoMIBaYtpVufgwv3keYAbln78mBoCuShZrPrer1Q=
+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=
+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.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=
 modernc.org/cc/v4 v4.27.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
-modernc.org/ccgo/v4 v4.30.1 h1:4r4U1J6Fhj98NKfSjnPUN7Ze2c6MnAdL0hWw6+LrJpc=
-modernc.org/ccgo/v4 v4.30.1/go.mod h1:bIOeI1JL54Utlxn+LwrFyjCx2n2RDiYEaJVSrgdrRfM=
-modernc.org/fileutil v1.3.40 h1:ZGMswMNc9JOCrcrakF1HrvmergNLAmxOPjizirpfqBA=
-modernc.org/fileutil v1.3.40/go.mod h1:HxmghZSZVAz/LXcMNwZPA/DRrQZEVP9VX0V4LQGQFOc=
+modernc.org/ccgo/v4 v4.32.0 h1:hjG66bI/kqIPX1b2yT6fr/jt+QedtP2fqojG2VrFuVw=
+modernc.org/ccgo/v4 v4.32.0/go.mod h1:6F08EBCx5uQc38kMGl+0Nm0oWczoo1c7cgpzEry7Uc0=
+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=
 modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
-modernc.org/gc/v3 v3.1.1 h1:k8T3gkXWY9sEiytKhcgyiZ2L0DTyCQ/nvX+LoCljoRE=
-modernc.org/gc/v3 v3.1.1/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+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.67.6 h1:eVOQvpModVLKOdT+LvBPjdQqfrZq+pC39BygcT+E7OI=
-modernc.org/libc v1.67.6/go.mod h1:JAhxUVlolfYDErnwiqaLvUqc8nfb2r6S6slAgZOnaiE=
+modernc.org/libc v1.70.0 h1:U58NawXqXbgpZ/dcdS9kMshu08aiA6b7gusEusqzNkw=
+modernc.org/libc v1.70.0/go.mod h1:OVmxFGP1CI/Z4L3E0Q3Mf1PDE0BucwMkcXjjLntvHJo=
 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=
@@ -680,19 +696,19 @@ modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
 modernc.org/opt v0.1.4/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.44.3 h1:+39JvV/HWMcYslAwRxHb8067w+2zowvFOUrOWIy9PjY=
-modernc.org/sqlite v1.44.3/go.mod h1:CzbrU2lSB1DKUusvwGz7rqEKIq+NUd8GWuBBZDs9/nA=
+modernc.org/sqlite v1.48.2 h1:5CnW4uP8joZtA0LedVqLbZV5GD7F/0x91AXeSyjoh5c=
+modernc.org/sqlite v1.48.2/go.mod h1:hWjRO6Tj/5Ik8ieqxQybiEOUXy0NJFNp2tpvVpKlvig=
 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=
+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.94.1 h1:0dAst/ozTuFkgmxZULc3oNwR9+qPIt5ucvzH7kaM0Jw=
-tailscale.com v1.94.1/go.mod h1:gLnVrEOP32GWvroaAHHGhjSGMPJ1i4DvqNwEg+Yuov4=
-zgo.at/zcache/v2 v2.4.1 h1:Dfjoi8yI0Uq7NCc4lo2kaQJJmp9Mijo21gef+oJstbY=
-zgo.at/zcache/v2 v2.4.1/go.mod h1:gyCeoLVo01QjDZynjime8xUGHHMbsLiPyUTBpDGd4Gk=
+tailscale.com v1.97.0-pre.0.20260429005429-40088602c960 h1:I56vAGia4DV24Dbv8N07F/Awtnguvmm7PAgWCxCIdqw=
+tailscale.com v1.97.0-pre.0.20260429005429-40088602c960/go.mod h1:8nwFkmNdNRtTIM2dkmr/DhbzSKeLmzusWOTacX1zVKk=
 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

@@ -16,6 +16,7 @@ import (
 	"strings"
 	"sync"
 	"syscall"
+	"testing"
 	"time"
 
 	"github.com/cenkalti/backoff/v5"
@@ -101,7 +102,7 @@ type Headscale struct {
 	// Things that generate changes
 	extraRecordMan *dns.ExtraRecordsMan
 	authProvider   AuthProvider
-	mapBatcher     mapper.Batcher
+	mapBatcher     *mapper.Batcher
 
 	clientStreamsOpen sync.WaitGroup
 }
@@ -275,6 +276,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():
@@ -331,6 +357,9 @@ func (h *Headscale) scheduledTasks(ctx context.Context) {
 			h.cfg.TailcfgDNSConfig.ExtraRecords = records
 
 			h.Change(change.ExtraRecords())
+
+		case <-haHealthChan:
+			haProber.ProbeOnce(ctx, h.Change)
 		}
 	}
 }
@@ -459,6 +488,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{
@@ -472,6 +515,7 @@ func (h *Headscale) createRouter(grpcMux *grpcRuntime.ServeMux) *chi.Mux {
 	r.Use(middleware.RealIP)
 	r.Use(middleware.RequestLogger(&zerologRequestLogger{}))
 	r.Use(middleware.Recoverer)
+	r.Use(securityHeaders)
 
 	r.Post(ts2021UpgradePath, h.NoiseUpgradeHandler)
 
@@ -484,6 +528,7 @@ func (h *Headscale) createRouter(grpcMux *grpcRuntime.ServeMux) *chi.Mux {
 
 	if provider, ok := h.authProvider.(*AuthProviderOIDC); ok {
 		r.Get("/oidc/callback", provider.OIDCCallbackHandler)
+		r.Post("/register/confirm/{auth_id}", provider.RegisterConfirmHandler)
 	}
 
 	r.Get("/apple", h.AppleConfigMessage)
@@ -507,6 +552,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 PingRequest. The unguessable ping ID serves as authentication.
+	r.Head("/machine/ping-response", h.PingResponseHandler)
+
 	r.Get("/favicon.ico", FaviconHandler)
 	r.Get("/", BlankHandler)
 
@@ -582,7 +631,7 @@ func (h *Headscale) Serve() error {
 
 	ephmNodes := h.state.ListEphemeralNodes()
 	for _, node := range ephmNodes.All() {
-		h.ephemeralGC.Schedule(node.ID(), h.cfg.EphemeralNodeInactivityTimeout)
+		h.ephemeralGC.Schedule(node.ID(), h.cfg.Node.Ephemeral.InactivityTimeout)
 	}
 
 	if h.cfg.DNSConfig.ExtraRecordsPath != "" {
@@ -726,7 +775,6 @@ func (h *Headscale) Serve() error {
 		grpcServer = grpc.NewServer(grpcOptions...)
 
 		v1.RegisterHeadscaleServiceServer(grpcServer, newHeadscaleV1APIServer(h))
-		reflection.Register(grpcServer)
 
 		grpcListener, err = new(net.ListenConfig).Listen(context.Background(), "tcp", h.cfg.GRPCAddr)
 		if err != nil {
@@ -1069,6 +1117,61 @@ func (h *Headscale) Change(cs ...change.Change) {
 	h.mapBatcher.AddWork(cs...)
 }
 
+// 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 {
+	return h.createRouter(grpcRuntime.NewServeMux())
+}
+
+// NoisePublicKey returns the server's Noise protocol public key.
+func (h *Headscale) NoisePublicKey() key.MachinePublic {
+	return h.noisePrivateKey.Public()
+}
+
+// GetState returns the server's state manager for programmatic access
+// to users, nodes, policies, and other server state.
+func (h *Headscale) GetState() *state.State {
+	return h.state
+}
+
+// SetServerURLForTest updates the server URL in the configuration.
+// This is needed for test servers where the URL is not known until
+// the HTTP test server starts.
+// It panics when called outside of tests.
+func (h *Headscale) SetServerURLForTest(tb testing.TB, url string) {
+	tb.Helper()
+
+	h.cfg.ServerURL = url
+}
+
+// StartBatcherForTest initialises and starts the map response batcher.
+// It registers a cleanup function on tb to stop the batcher.
+// It panics when called outside of tests.
+func (h *Headscale) StartBatcherForTest(tb testing.TB) {
+	tb.Helper()
+
+	h.mapBatcher = mapper.NewBatcherAndMapper(h.cfg, h.state)
+	h.mapBatcher.Start()
+	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.
+func (h *Headscale) StartEphemeralGCForTest(tb testing.TB) {
+	tb.Helper()
+
+	go h.ephemeralGC.Start()
+
+	tb.Cleanup(func() { h.ephemeralGC.Close() })
+}
+
 // Provide some middleware that can inspect the ACME/autocert https calls
 // and log when things are failing.
 type acmeLogger 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

@@ -1,7 +1,6 @@
 package hscontrol
 
 import (
-	"cmp"
 	"context"
 	"errors"
 	"fmt"
@@ -11,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"
@@ -71,6 +69,20 @@ func (h *Headscale) handleRegister(
 		// We do not look up nodes by [key.MachinePublic] as it might belong to multiple
 		// nodes, separated by users and this path is handling expiring/logout paths.
 		if node, ok := h.state.GetNodeByNodeKey(req.NodeKey); ok {
+			// Refuse to act on a node looked up purely by NodeKey unless
+			// 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.
+			if node.MachineKey() != machineKey {
+				return nil, NewHTTPError(
+					http.StatusUnauthorized,
+					"node exists with a different machine key",
+					nil,
+				)
+			}
+
 			// When tailscaled restarts, it sends RegisterRequest with Auth=nil and Expiry=zero.
 			// Return the current node state without modification.
 			// See: https://github.com/juanfont/headscale/issues/2862
@@ -302,31 +314,10 @@ func (h *Headscale) reqToNewRegisterResponse(
 		return nil, NewHTTPError(http.StatusInternalServerError, "failed to generate registration ID", err)
 	}
 
-	// Ensure we have a valid hostname
-	hostname := util.EnsureHostname(
-		req.Hostinfo.View(),
-		machineKey.String(),
-		req.NodeKey.String(),
+	authRegReq := types.NewRegisterAuthRequest(
+		registrationDataFromRequest(req, machineKey),
 	)
 
-	// Ensure we have valid hostinfo
-	hostinfo := cmp.Or(req.Hostinfo, &tailcfg.Hostinfo{})
-	hostinfo.Hostname = hostname
-
-	nodeToRegister := types.Node{
-		Hostname:   hostname,
-		MachineKey: machineKey,
-		NodeKey:    req.NodeKey,
-		Hostinfo:   hostinfo,
-		LastSeen:   new(time.Now()),
-	}
-
-	if !req.Expiry.IsZero() {
-		nodeToRegister.Expiry = &req.Expiry
-	}
-
-	authRegReq := types.NewRegisterAuthRequest(nodeToRegister)
-
 	log.Info().Msgf("new followup node registration using auth id: %s", newAuthID)
 	h.state.SetAuthCacheEntry(newAuthID, authRegReq)
 
@@ -335,6 +326,35 @@ func (h *Headscale) reqToNewRegisterResponse(
 	}, nil
 }
 
+// registrationDataFromRequest builds the RegistrationData payload stored
+// in the auth cache for a pending registration. The original 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.
+func registrationDataFromRequest(
+	req tailcfg.RegisterRequest,
+	machineKey key.MachinePublic,
+) *types.RegistrationData {
+	var hostname string
+	if req.Hostinfo != nil {
+		hostname = req.Hostinfo.Hostname
+	}
+
+	regData := &types.RegistrationData{
+		MachineKey: machineKey,
+		NodeKey:    req.NodeKey,
+		Hostname:   hostname,
+		Hostinfo:   req.Hostinfo,
+	}
+
+	if !req.Expiry.IsZero() {
+		expiry := req.Expiry
+		regData.Expiry = &expiry
+	}
+
+	return regData
+}
+
 func (h *Headscale) handleRegisterWithAuthKey(
 	req tailcfg.RegisterRequest,
 	machineKey key.MachinePublic,
@@ -408,50 +428,24 @@ func (h *Headscale) handleRegisterInteractive(
 		return nil, fmt.Errorf("generating registration ID: %w", err)
 	}
 
-	// Ensure we have a valid hostname
-	hostname := util.EnsureHostname(
-		req.Hostinfo.View(),
-		machineKey.String(),
-		req.NodeKey.String(),
-	)
-
-	// Ensure we have valid hostinfo
-	hostinfo := cmp.Or(req.Hostinfo, &tailcfg.Hostinfo{})
 	if req.Hostinfo == nil {
 		log.Warn().
 			Str("machine.key", machineKey.ShortString()).
 			Str("node.key", req.NodeKey.ShortString()).
-			Str("generated.hostname", hostname).
 			Msg("Received registration request with nil hostinfo, generated default hostname")
 	} else if req.Hostinfo.Hostname == "" {
 		log.Warn().
 			Str("machine.key", machineKey.ShortString()).
 			Str("node.key", req.NodeKey.ShortString()).
-			Str("generated.hostname", hostname).
 			Msg("Received registration request with empty hostname, generated default")
 	}
 
-	hostinfo.Hostname = hostname
-
-	nodeToRegister := types.Node{
-		Hostname:   hostname,
-		MachineKey: machineKey,
-		NodeKey:    req.NodeKey,
-		Hostinfo:   hostinfo,
-		LastSeen:   new(time.Now()),
-	}
-
-	if !req.Expiry.IsZero() {
-		nodeToRegister.Expiry = &req.Expiry
-	}
-
-	authRegReq := types.NewRegisterAuthRequest(nodeToRegister)
-
-	h.state.SetAuthCacheEntry(
-		authID,
-		authRegReq,
+	authRegReq := types.NewRegisterAuthRequest(
+		registrationDataFromRequest(req, machineKey),
 	)
 
+	h.state.SetAuthCacheEntry(authID, authRegReq)
+
 	log.Info().Msgf("starting node registration using auth id: %s", authID)
 
 	return &tailcfg.RegisterResponse{

hscontrol/auth_tags_test.go

@@ -4,6 +4,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/juanfont/headscale/hscontrol/mapper"
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -11,6 +12,49 @@ import (
 	"tailscale.com/types/key"
 )
 
+// createTestAppWithNodeExpiry creates a test app with a specific node.expiry config.
+func createTestAppWithNodeExpiry(t *testing.T, nodeExpiry time.Duration) *Headscale {
+	t.Helper()
+
+	tmpDir := t.TempDir()
+
+	cfg := types.Config{
+		ServerURL:           "http://localhost:8080",
+		NoisePrivateKeyPath: tmpDir + "/noise_private.key",
+		Node: types.NodeConfig{
+			Expiry: nodeExpiry,
+		},
+		Database: types.DatabaseConfig{
+			Type: "sqlite3",
+			Sqlite: types.SqliteConfig{
+				Path: tmpDir + "/headscale_test.db",
+			},
+		},
+		OIDC: types.OIDCConfig{},
+		Policy: types.PolicyConfig{
+			Mode: types.PolicyModeDB,
+		},
+		Tuning: types.Tuning{
+			BatchChangeDelay: 100 * time.Millisecond,
+			BatcherWorkers:   1,
+		},
+	}
+
+	app, err := NewHeadscale(&cfg)
+	require.NoError(t, err)
+
+	app.mapBatcher = mapper.NewBatcherAndMapper(&cfg, app.state)
+	app.mapBatcher.Start()
+
+	t.Cleanup(func() {
+		if app.mapBatcher != nil {
+			app.mapBatcher.Close()
+		}
+	})
+
+	return app
+}
+
 // TestTaggedPreAuthKeyCreatesTaggedNode tests that a PreAuthKey with tags creates
 // a tagged node with:
 // - Tags from the PreAuthKey
@@ -652,7 +696,7 @@ func TestExpiryDuringPersonalToTaggedConversion(t *testing.T) {
 	// Step 1: Create user-owned node WITH expiry set
 	clientExpiry := time.Now().Add(24 * time.Hour)
 	registrationID1 := types.MustAuthID()
-	regEntry1 := types.NewRegisterAuthRequest(types.Node{
+	regEntry1 := types.NewRegisterAuthRequest(&types.RegistrationData{
 		MachineKey: machineKey.Public(),
 		NodeKey:    nodeKey1.Public(),
 		Hostname:   "personal-to-tagged",
@@ -674,7 +718,7 @@ func TestExpiryDuringPersonalToTaggedConversion(t *testing.T) {
 	// Step 2: Re-auth with tags (Personal → Tagged conversion)
 	nodeKey2 := key.NewNode()
 	registrationID2 := types.MustAuthID()
-	regEntry2 := types.NewRegisterAuthRequest(types.Node{
+	regEntry2 := types.NewRegisterAuthRequest(&types.RegistrationData{
 		MachineKey: machineKey.Public(),
 		NodeKey:    nodeKey2.Public(),
 		Hostname:   "personal-to-tagged",
@@ -724,7 +768,7 @@ func TestExpiryDuringTaggedToPersonalConversion(t *testing.T) {
 
 	// Step 1: Create tagged node (expiry should be nil)
 	registrationID1 := types.MustAuthID()
-	regEntry1 := types.NewRegisterAuthRequest(types.Node{
+	regEntry1 := types.NewRegisterAuthRequest(&types.RegistrationData{
 		MachineKey: machineKey.Public(),
 		NodeKey:    nodeKey1.Public(),
 		Hostname:   "tagged-to-personal",
@@ -746,7 +790,7 @@ func TestExpiryDuringTaggedToPersonalConversion(t *testing.T) {
 	nodeKey2 := key.NewNode()
 	clientExpiry := time.Now().Add(48 * time.Hour)
 	registrationID2 := types.MustAuthID()
-	regEntry2 := types.NewRegisterAuthRequest(types.Node{
+	regEntry2 := types.NewRegisterAuthRequest(&types.RegistrationData{
 		MachineKey: machineKey.Public(),
 		NodeKey:    nodeKey2.Public(),
 		Hostname:   "tagged-to-personal",
@@ -833,3 +877,314 @@ func TestReAuthWithDifferentMachineKey(t *testing.T) {
 	assert.True(t, node2.IsTagged())
 	assert.ElementsMatch(t, tags, node2.Tags().AsSlice())
 }
+
+// TestUntaggedAuthKeyZeroExpiryGetsDefault tests that when node.expiry is configured
+// and a client registers with an untagged auth key without requesting a specific expiry,
+// the node gets the configured default expiry.
+// This is the core fix for https://github.com/juanfont/headscale/issues/1711
+func TestUntaggedAuthKeyZeroExpiryGetsDefault(t *testing.T) {
+	t.Parallel()
+
+	nodeExpiry := 180 * 24 * time.Hour // 180 days
+	app := createTestAppWithNodeExpiry(t, nodeExpiry)
+
+	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()
+
+	// Client sends zero expiry (the default behaviour of tailscale up --authkey).
+	regReq := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pak.Key,
+		},
+		NodeKey: nodeKey.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "default-expiry-test",
+		},
+		Expiry: time.Time{}, // zero — no client-requested expiry
+	}
+
+	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.IsTagged())
+	assert.True(t, node.Expiry().Valid(), "node should have expiry set from config default")
+	assert.False(t, node.IsExpired(), "node should not be expired yet")
+
+	expectedExpiry := time.Now().Add(nodeExpiry)
+	assert.WithinDuration(t, expectedExpiry, node.Expiry().Get(), 10*time.Second,
+		"node expiry should be ~180 days from now")
+}
+
+// TestTaggedAuthKeyIgnoresNodeExpiry tests that tagged nodes still get nil
+// expiry even when node.expiry is configured.
+func TestTaggedAuthKeyIgnoresNodeExpiry(t *testing.T) {
+	t.Parallel()
+
+	nodeExpiry := 180 * 24 * time.Hour
+	app := createTestAppWithNodeExpiry(t, nodeExpiry)
+
+	user := app.state.CreateUserForTest("tag-creator")
+	tags := []string{"tag:server"}
+
+	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-no-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.True(t, node.IsTagged())
+	assert.False(t, node.Expiry().Valid(),
+		"tagged node should have expiry disabled (nil) even with node.expiry configured")
+}
+
+// TestNodeExpiryZeroDisablesDefault tests that setting node.expiry to 0
+// preserves the old behaviour where nodes registered without a client-requested
+// expiry get no expiry (never expire).
+func TestNodeExpiryZeroDisablesDefault(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()
+
+	regReq := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pak.Key,
+		},
+		NodeKey: nodeKey.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "no-default-expiry",
+		},
+		Expiry: time.Time{}, // zero
+	}
+
+	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.IsTagged())
+	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.
+	if node.Expiry().Valid() {
+		assert.True(t, node.Expiry().Get().IsZero(),
+			"with node.expiry=0 and zero client expiry, expiry should be zero time")
+	}
+}
+
+// TestClientNonZeroExpiryTakesPrecedence tests that when a client explicitly
+// requests an expiry, that value is used instead of the configured default.
+func TestClientNonZeroExpiryTakesPrecedence(t *testing.T) {
+	t.Parallel()
+
+	nodeExpiry := 180 * 24 * time.Hour // 180 days
+	app := createTestAppWithNodeExpiry(t, nodeExpiry)
+
+	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()
+
+	// Client explicitly requests 24h expiry
+	clientExpiry := time.Now().Add(24 * time.Hour)
+
+	regReq := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pak.Key,
+		},
+		NodeKey: nodeKey.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "client-expiry-test",
+		},
+		Expiry: clientExpiry,
+	}
+
+	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.True(t, node.Expiry().Valid(), "node should have expiry set")
+	assert.WithinDuration(t, clientExpiry, node.Expiry().Get(), 5*time.Second,
+		"client-requested expiry should take precedence over node.expiry default")
+}
+
+// TestReregistrationAppliesDefaultExpiry tests that when a node re-registers
+// with an untagged auth key and the client sends zero expiry, the configured
+// default is applied.
+func TestReregistrationAppliesDefaultExpiry(t *testing.T) {
+	t.Parallel()
+
+	nodeExpiry := 90 * 24 * time.Hour // 90 days
+	app := createTestAppWithNodeExpiry(t, nodeExpiry)
+
+	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 expiry
+	regReq := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pak.Key,
+		},
+		NodeKey: nodeKey.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "reregister-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)
+	assert.True(t, node.Expiry().Valid(), "initial registration should get default expiry")
+
+	firstExpiry := node.Expiry().Get()
+
+	// Re-register with a new node key but same machine key
+	nodeKey2 := key.NewNode()
+	regReq2 := tailcfg.RegisterRequest{
+		Auth: &tailcfg.RegisterResponseAuth{
+			AuthKey: pak.Key,
+		},
+		NodeKey: nodeKey2.Public(),
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname: "reregister-test",
+		},
+		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.True(t, node2.Expiry().Valid(), "re-registration should also get default expiry")
+
+	// The expiry should be refreshed (new 90d from now), not the old one
+	expectedExpiry := time.Now().Add(nodeExpiry)
+	assert.WithinDuration(t, expectedExpiry, node2.Expiry().Get(), 10*time.Second,
+		"re-registration should refresh the default expiry")
+	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 (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

@@ -681,7 +681,7 @@ func TestAuthenticationFlows(t *testing.T) {
 					return "", err
 				}
 
-				nodeToRegister := types.NewRegisterAuthRequest(types.Node{
+				nodeToRegister := types.NewRegisterAuthRequest(&types.RegistrationData{
 					Hostname: "followup-success-node",
 				})
 				app.state.SetAuthCacheEntry(regID, nodeToRegister)
@@ -723,7 +723,7 @@ func TestAuthenticationFlows(t *testing.T) {
 					return "", err
 				}
 
-				nodeToRegister := types.NewRegisterAuthRequest(types.Node{
+				nodeToRegister := types.NewRegisterAuthRequest(&types.RegistrationData{
 					Hostname: "followup-timeout-node",
 				})
 				app.state.SetAuthCacheEntry(regID, nodeToRegister)
@@ -816,10 +816,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
+				// 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
@@ -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 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())
 			},
 		},
 
@@ -1341,7 +1343,7 @@ func TestAuthenticationFlows(t *testing.T) {
 					return "", err
 				}
 
-				nodeToRegister := types.NewRegisterAuthRequest(types.Node{
+				nodeToRegister := types.NewRegisterAuthRequest(&types.RegistrationData{
 					Hostname: "nil-response-node",
 				})
 				app.state.SetAuthCacheEntry(regID, nodeToRegister)
@@ -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())
 				}
 			},
 		},
@@ -2507,7 +2509,7 @@ func TestAuthenticationFlows(t *testing.T) {
 			if req.Followup != "" {
 				var cancel context.CancelFunc
 
-				ctx, cancel = context.WithTimeout(context.Background(), 100*time.Millisecond)
+				ctx, cancel = context.WithTimeout(context.Background(), 5*time.Second)
 				defer cancel()
 			}
 
@@ -2618,7 +2620,7 @@ func runInteractiveWorkflowTest(t *testing.T, tt struct {
 				cacheEntry, found := app.state.GetAuthCacheEntry(registrationID)
 				require.True(t, found, "registration cache entry should exist")
 				require.NotNil(t, cacheEntry, "cache entry should not be nil")
-				require.Equal(t, req.NodeKey, cacheEntry.Node().NodeKey(), "cache entry should have correct node key")
+				require.Equal(t, req.NodeKey, cacheEntry.RegistrationData().NodeKey, "cache entry should have correct node key")
 			}
 
 		case stepTypeAuthCompletion:
@@ -3570,7 +3572,7 @@ func TestWebAuthRejectsUnauthorizedRequestTags(t *testing.T) {
 
 	// Simulate a registration cache entry (as would be created during web auth)
 	registrationID := types.MustAuthID()
-	regEntry := types.NewRegisterAuthRequest(types.Node{
+	regEntry := types.NewRegisterAuthRequest(&types.RegistrationData{
 		MachineKey: machineKey.Public(),
 		NodeKey:    nodeKey.Public(),
 		Hostname:   "webauth-tags-node",
@@ -3633,7 +3635,7 @@ func TestWebAuthReauthWithEmptyTagsRemovesAllTags(t *testing.T) {
 
 	// Step 1: Initial registration with tags
 	registrationID1 := types.MustAuthID()
-	regEntry1 := types.NewRegisterAuthRequest(types.Node{
+	regEntry1 := types.NewRegisterAuthRequest(&types.RegistrationData{
 		MachineKey: machineKey.Public(),
 		NodeKey:    nodeKey1.Public(),
 		Hostname:   "reauth-untag-node",
@@ -3660,7 +3662,7 @@ func TestWebAuthReauthWithEmptyTagsRemovesAllTags(t *testing.T) {
 	// Step 2: Reauth with EMPTY tags to untag
 	nodeKey2 := key.NewNode() // New node key for reauth
 	registrationID2 := types.MustAuthID()
-	regEntry2 := types.NewRegisterAuthRequest(types.Node{
+	regEntry2 := types.NewRegisterAuthRequest(&types.RegistrationData{
 		MachineKey: machineKey.Public(), // Same machine key
 		NodeKey:    nodeKey2.Public(),   // Different node key (rotation)
 		Hostname:   "reauth-untag-node",
@@ -3746,7 +3748,7 @@ func TestAuthKeyTaggedToUserOwnedViaReauth(t *testing.T) {
 	// Step 2: Reauth via web auth with EMPTY tags to transition to user-owned
 	nodeKey2 := key.NewNode() // New node key for reauth
 	registrationID := types.MustAuthID()
-	regEntry := types.NewRegisterAuthRequest(types.Node{
+	regEntry := types.NewRegisterAuthRequest(&types.RegistrationData{
 		MachineKey: machineKey.Public(), // Same machine key
 		NodeKey:    nodeKey2.Public(),   // Different node key (rotation)
 		Hostname:   "authkey-tagged-node",
@@ -3945,7 +3947,7 @@ func TestTaggedNodeWithoutUserToDifferentUser(t *testing.T) {
 	// This is what happens when running: headscale auth register --auth-id <id> --user alice
 	nodeKey2 := key.NewNode()
 	registrationID := types.MustAuthID()
-	regEntry := types.NewRegisterAuthRequest(types.Node{
+	regEntry := types.NewRegisterAuthRequest(&types.RegistrationData{
 		MachineKey: machineKey.Public(), // Same machine key as the tagged node
 		NodeKey:    nodeKey2.Public(),
 		Hostname:   "tagged-orphan-node",
@@ -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_generated.go

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

hscontrol/capver/capver_test_data.go

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

hscontrol/db/db.go

@@ -24,7 +24,6 @@ import (
 	"gorm.io/gorm"
 	"gorm.io/gorm/logger"
 	"gorm.io/gorm/schema"
-	"zgo.at/zcache/v2"
 )
 
 //go:embed schema.sql
@@ -45,19 +44,15 @@ const (
 )
 
 type HSDatabase struct {
-	DB       *gorm.DB
-	cfg      *types.Config
-	regCache *zcache.Cache[types.AuthID, types.AuthRequest]
+	DB  *gorm.DB
+	cfg *types.Config
 }
 
 // NewHeadscaleDatabase creates a new database connection and runs migrations.
 // It accepts the full configuration to allow migrations access to policy settings.
 //
 //nolint:gocyclo // complex database initialization with many migrations
-func NewHeadscaleDatabase(
-	cfg *types.Config,
-	regCache *zcache.Cache[types.AuthID, types.AuthRequest],
-) (*HSDatabase, error) {
+func NewHeadscaleDatabase(cfg *types.Config) (*HSDatabase, error) {
 	dbConn, err := openDB(cfg.Database)
 	if err != nil {
 		return nil, err
@@ -677,7 +672,7 @@ AND auth_key_id NOT IN (
 							continue
 						}
 
-						mergedTags := append(existingTags, validatedTags...)
+						mergedTags := append(slices.Clone(existingTags), validatedTags...)
 						slices.Sort(mergedTags)
 						mergedTags = slices.Compact(mergedTags)
 
@@ -838,9 +833,8 @@ WHERE tags IS NOT NULL AND tags != '[]' AND tags != '';
 	}
 
 	db := HSDatabase{
-		DB:       dbConn,
-		cfg:      cfg,
-		regCache: regCache,
+		DB:  dbConn,
+		cfg: cfg,
 	}
 
 	return &db, err

hscontrol/db/db_test.go

@@ -8,13 +8,11 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"gorm.io/gorm"
-	"zgo.at/zcache/v2"
 )
 
 // TestSQLiteMigrationAndDataValidation tests specific SQLite migration scenarios
@@ -162,10 +160,6 @@ func TestSQLiteMigrationAndDataValidation(t *testing.T) {
 	}
 }
 
-func emptyCache() *zcache.Cache[types.AuthID, types.AuthRequest] {
-	return zcache.New[types.AuthID, types.AuthRequest](time.Minute, time.Hour)
-}
-
 func createSQLiteFromSQLFile(sqlFilePath, dbPath string) error {
 	db, err := sql.Open("sqlite", dbPath)
 	if err != nil {
@@ -379,7 +373,6 @@ func dbForTestWithPath(t *testing.T, sqlFilePath string) *HSDatabase {
 				Mode: types.PolicyModeDB,
 			},
 		},
-		emptyCache(),
 	)
 	if err != nil {
 		t.Fatalf("setting up database: %s", err)
@@ -439,7 +432,6 @@ func TestSQLiteAllTestdataMigrations(t *testing.T) {
 						Mode: types.PolicyModeDB,
 					},
 				},
-				emptyCache(),
 			)
 			require.NoError(t, err)
 		})

hscontrol/db/ephemeral_garbage_collector_test.go

@@ -379,7 +379,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 +396,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 +410,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/main_test.go

@@ -0,0 +1,25 @@
+package db
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+)
+
+// TestMain ensures the working directory is set to the package source directory
+// so that relative testdata/ paths resolve correctly when the test binary is
+// executed from an arbitrary location (e.g., via "go tool stress").
+func TestMain(m *testing.M) {
+	_, filename, _, ok := runtime.Caller(0)
+	if !ok {
+		panic("could not determine test source directory")
+	}
+
+	err := os.Chdir(filepath.Dir(filename))
+	if err != nil {
+		panic("could not chdir to test source directory: " + err.Error())
+	}
+
+	os.Exit(m.Run())
+}

hscontrol/db/node.go

@@ -5,11 +5,9 @@ import (
 	"errors"
 	"fmt"
 	"net/netip"
-	"regexp"
 	"slices"
 	"sort"
 	"strconv"
-	"strings"
 	"sync"
 	"testing"
 	"time"
@@ -21,6 +19,7 @@ import (
 	"gorm.io/gorm"
 	"tailscale.com/net/tsaddr"
 	"tailscale.com/types/key"
+	"tailscale.com/util/dnsname"
 )
 
 const (
@@ -34,8 +33,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")
@@ -291,7 +288,7 @@ func SetLastSeen(tx *gorm.DB, nodeID types.NodeID, lastSeen time.Time) error {
 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 +296,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)
 	}
 
@@ -427,22 +423,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,72 +469,6 @@ 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

hscontrol/db/node_test.go

@@ -5,7 +5,6 @@ import (
 	"fmt"
 	"math/big"
 	"net/netip"
-	"regexp"
 	"runtime"
 	"sync"
 	"sync/atomic"
@@ -227,122 +226,6 @@ func TestSetTags(t *testing.T) {
 	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 {
@@ -633,7 +516,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 +527,7 @@ func TestEphemeralGarbageCollectorLoads(t *testing.T) {
 
 		got = append(got, ni)
 
-		atomic.AddInt64(&deletedCount, 1)
+		deletedCount.Add(1)
 	})
 	go e.Start()
 
@@ -655,7 +538,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,281 +625,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

hscontrol/db/preauth_keys.go

@@ -170,6 +170,18 @@ func ListPreAuthKeys(tx *gorm.DB) ([]types.PreAuthKey, error) {
 	return keys, nil
 }
 
+// ListPreAuthKeysByUser returns all PreAuthKeys belonging to a specific user.
+func ListPreAuthKeysByUser(tx *gorm.DB, uid types.UserID) ([]types.PreAuthKey, error) {
+	var keys []types.PreAuthKey
+
+	err := tx.Preload("User").Where("user_id = ?", uint(uid)).Find(&keys).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return keys, nil
+}
+
 var (
 	ErrPreAuthKeyFailedToParse    = errors.New("failed to parse auth-key")
 	ErrPreAuthKeyNotTaggedOrOwned = errors.New("auth-key must be either tagged or owned by user")
@@ -319,11 +331,22 @@ func (hsdb *HSDatabase) DeletePreAuthKey(id uint64) error {
 	})
 }
 
-// UsePreAuthKey marks a PreAuthKey as used.
+// UsePreAuthKey atomically marks a 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
+// 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 {
-	err := tx.Model(k).Update("used", true).Error
-	if err != nil {
-		return fmt.Errorf("updating key used status in database: %w", err)
+	res := tx.Model(&types.PreAuthKey{}).
+		Where("id = ? AND used = ?", k.ID, false).
+		Update("used", true)
+	if res.Error != nil {
+		return fmt.Errorf("updating key used status in database: %w", res.Error)
+	}
+
+	if res.RowsAffected == 0 {
+		return types.PAKError("authkey already used")
 	}
 
 	k.Used = true

hscontrol/db/preauth_keys_test.go

@@ -11,6 +11,7 @@ import (
 	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
 )
 
 func TestCreatePreAuthKey(t *testing.T) {
@@ -444,3 +445,45 @@ func TestMultipleLegacyKeysAllowed(t *testing.T) {
 	require.Error(t, err, "duplicate non-empty prefix should be rejected")
 	assert.Contains(t, err.Error(), "UNIQUE constraint failed", "should fail with UNIQUE constraint error")
 }
+
+// TestUsePreAuthKeyAtomicCAS verifies that UsePreAuthKey is an atomic
+// compare-and-set: a second call against an already-used key reports
+// PAKError("authkey already used") rather than silently succeeding.
+func TestUsePreAuthKeyAtomicCAS(t *testing.T) {
+	db, err := newSQLiteTestDB()
+	require.NoError(t, err)
+
+	user, err := db.CreateUser(types.User{Name: "atomic-cas"})
+	require.NoError(t, err)
+
+	pakNew, err := db.CreatePreAuthKey(user.TypedID(), false /* reusable */, false, nil, nil)
+	require.NoError(t, err)
+
+	pak, err := db.GetPreAuthKey(pakNew.Key)
+	require.NoError(t, err)
+	require.False(t, pak.Reusable, "test sanity: key must be single-use")
+
+	// First Use should commit cleanly.
+	err = db.Write(func(tx *gorm.DB) error {
+		return UsePreAuthKey(tx, pak)
+	})
+	require.NoError(t, err, "first UsePreAuthKey should succeed")
+
+	// Reload from disk to drop the in-memory Used=true the first call
+	// set on the struct, simulating a second concurrent transaction
+	// that loaded the same row before the first one committed.
+	stale, err := db.GetPreAuthKey(pakNew.Key)
+	require.NoError(t, err)
+
+	stale.Used = false
+
+	err = db.Write(func(tx *gorm.DB) error {
+		return UsePreAuthKey(tx, stale)
+	})
+	require.Error(t, err, "second UsePreAuthKey on the same single-use key must fail")
+
+	var pakErr types.PAKError
+	require.ErrorAs(t, err, &pakErr,
+		"second UsePreAuthKey error must be a PAKError, got: %v", err)
+	assert.Equal(t, "authkey already used", pakErr.Error())
+}

hscontrol/db/suite_test.go

@@ -9,7 +9,6 @@ import (
 	"testing"
 
 	"github.com/juanfont/headscale/hscontrol/types"
-	"github.com/rs/zerolog"
 	"zombiezen.com/go/postgrestest"
 )
 
@@ -20,7 +19,6 @@ func newSQLiteTestDB() (*HSDatabase, error) {
 	}
 
 	log.Printf("database path: %s", tmpDir+"/headscale_test.db")
-	zerolog.SetGlobalLevel(zerolog.Disabled)
 
 	db, err := NewHeadscaleDatabase(
 		&types.Config{
@@ -34,7 +32,6 @@ func newSQLiteTestDB() (*HSDatabase, error) {
 				Mode: types.PolicyModeDB,
 			},
 		},
-		emptyCache(),
 	)
 	if err != nil {
 		return nil, err
@@ -56,7 +53,7 @@ func newPostgresDBForTest(t *testing.T) *url.URL {
 
 	srv, err := postgrestest.Start(ctx)
 	if err != nil {
-		t.Fatal(err)
+		t.Skipf("start postgres: %s", err)
 	}
 
 	t.Cleanup(srv.Cleanup)
@@ -95,7 +92,6 @@ func newHeadscaleDBFromPostgresURL(t *testing.T, pu *url.URL) *HSDatabase {
 				Mode: types.PolicyModeDB,
 			},
 		},
-		emptyCache(),
 	)
 	if err != nil {
 		t.Fatal(err)

hscontrol/db/users.go

@@ -28,7 +28,7 @@ func (hsdb *HSDatabase) CreateUser(user types.User) (*types.User, error) {
 // CreateUser creates a new User. Returns error if could not be created
 // or another user already exists.
 func CreateUser(tx *gorm.DB, user types.User) (*types.User, error) {
-	err := util.ValidateHostname(user.Name)
+	err := util.ValidateUsername(user.Name)
 	if err != nil {
 		return nil, err
 	}
@@ -65,7 +65,7 @@ func DestroyUser(tx *gorm.DB, uid types.UserID) error {
 		return ErrUserStillHasNodes
 	}
 
-	keys, err := ListPreAuthKeys(tx)
+	keys, err := ListPreAuthKeysByUser(tx, uid)
 	if err != nil {
 		return err
 	}
@@ -102,7 +102,7 @@ func RenameUser(tx *gorm.DB, uid types.UserID, newName string) error {
 		return err
 	}
 
-	if err = util.ValidateHostname(newName); err != nil { //nolint:noinlineerr
+	if err = util.ValidateUsername(newName); err != nil { //nolint:noinlineerr
 		return err
 	}
 

hscontrol/db/users_test.go

@@ -100,7 +100,7 @@ func TestDestroyUserErrors(t *testing.T) {
 				user, err := db.CreateUser(types.User{Name: "test"})
 				require.NoError(t, err)
 
-				// Create a tagged node with no user_id (the invariant).
+				// Create a tagged node with no user_id (the rule for tagged nodes).
 				node := types.Node{
 					ID:             0,
 					Hostname:       "tagged-node",
@@ -160,6 +160,48 @@ func TestDestroyUserErrors(t *testing.T) {
 				require.ErrorIs(t, err, ErrUserStillHasNodes)
 			},
 		},
+		{
+			// Regression test for https://github.com/juanfont/headscale/issues/3154
+			// DestroyUser must only delete the target user's pre-auth keys,
+			// not all pre-auth keys in the database.
+			name: "success_only_deletes_own_preauthkeys",
+			test: func(t *testing.T, db *HSDatabase) {
+				t.Helper()
+
+				userA := db.CreateUserForTest("usera")
+				userB := db.CreateUserForTest("userb")
+
+				// Create 2 keys for userA, 1 key for userB.
+				_, err := db.CreatePreAuthKey(userA.TypedID(), false, false, nil, nil)
+				require.NoError(t, err)
+				_, err = db.CreatePreAuthKey(userA.TypedID(), false, false, nil, nil)
+				require.NoError(t, err)
+				_, err = db.CreatePreAuthKey(userB.TypedID(), false, false, nil, nil)
+				require.NoError(t, err)
+
+				// Sanity check: 3 keys exist.
+				allKeys, err := db.ListPreAuthKeys()
+				require.NoError(t, err)
+				require.Len(t, allKeys, 3)
+
+				// Delete userB.
+				err = db.DestroyUser(types.UserID(userB.ID))
+				require.NoError(t, err)
+
+				// Only userA's 2 keys should remain.
+				remaining, err := db.ListPreAuthKeys()
+				require.NoError(t, err)
+				assert.Len(t, remaining, 2,
+					"expected 2 keys for userA, got %d — DestroyUser deleted keys from other users",
+					len(remaining))
+
+				for _, key := range remaining {
+					assert.NotNil(t, key.UserID)
+					assert.Equal(t, userA.ID, *key.UserID,
+						"remaining key should belong to userA")
+				}
+			},
+		},
 	}
 
 	for _, tt := range tests {

hscontrol/debug.go

@@ -1,18 +1,53 @@
 package hscontrol
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
+	"net"
 	"net/http"
+	"net/netip"
 	"strings"
+	"time"
 
 	"github.com/arl/statsviz"
-	"github.com/juanfont/headscale/hscontrol/mapper"
+	"github.com/juanfont/headscale/hscontrol/templates"
 	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/juanfont/headscale/hscontrol/types/change"
 	"github.com/prometheus/client_golang/prometheus/promhttp"
+	"tailscale.com/tailcfg"
 	"tailscale.com/tsweb"
 )
 
+// protectedDebugHandler wraps an http.Handler with an access check that
+// allows requests from loopback, Tailscale CGNAT IPs, and private
+// (RFC 1918 / RFC 4193) addresses. This extends tsweb.Protected which
+// only allows loopback and Tailscale IPs.
+func protectedDebugHandler(h http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if tsweb.AllowDebugAccess(r) {
+			h.ServeHTTP(w, r)
+
+			return
+		}
+
+		// tsweb.AllowDebugAccess rejects X-Forwarded-For and non-TS IPs.
+		// Additionally allow private/LAN addresses so operators can reach
+		// debug endpoints from their local network without tailscaled.
+		ipStr, _, err := net.SplitHostPort(r.RemoteAddr)
+		if err == nil {
+			ip, parseErr := netip.ParseAddr(ipStr)
+			if parseErr == nil && ip.IsPrivate() {
+				h.ServeHTTP(w, r)
+
+				return
+			}
+		}
+
+		http.Error(w, "debug access denied", http.StatusForbidden)
+	})
+}
+
 func (h *Headscale) debugHTTPServer() *http.Server {
 	debugMux := http.NewServeMux()
 	debug := tsweb.Debugger(debugMux)
@@ -294,8 +329,48 @@ func (h *Headscale) debugHTTPServer() *http.Server {
 		}
 	}))
 
-	err := statsviz.Register(debugMux)
+	// Ping endpoint: sends a PingRequest to a node and waits for it to respond.
+	// Supports POST (form submit) and GET with ?node= (clickable quick-ping links).
+	debug.Handle("ping", "Ping a node to check connectivity", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var (
+			query  string
+			result *templates.PingResult
+		)
+
+		switch r.Method {
+		case http.MethodPost:
+			r.Body = http.MaxBytesReader(w, r.Body, 4096) //nolint:mnd
+
+			err := r.ParseForm()
+			if err != nil {
+				http.Error(w, "bad form data", http.StatusBadRequest)
+				return
+			}
+
+			query = r.FormValue("node")
+			result = h.doPing(r.Context(), query)
+		case http.MethodGet:
+			// Support ?node= for auto-ping links from other debug pages.
+			if q := r.URL.Query().Get("node"); q != "" {
+				query = q
+				result = h.doPing(r.Context(), query)
+			}
+		}
+
+		nodes := h.connectedNodesList()
+
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(templates.PingPage(query, result, nodes).Render()))
+	}))
+
+	// statsviz.Register would mount handlers directly on the raw mux,
+	// bypassing the access gate. Build the server by hand and wrap
+	// each handler with protectedDebugHandler.
+	statsvizSrv, err := statsviz.NewServer()
 	if err == nil {
+		debugMux.Handle("/debug/statsviz/", protectedDebugHandler(statsvizSrv.Index()))
+		debugMux.Handle("/debug/statsviz/ws", protectedDebugHandler(statsvizSrv.Ws()))
 		debug.URL("/debug/statsviz", "Statsviz (visualise go metrics)")
 	}
 
@@ -304,7 +379,7 @@ func (h *Headscale) debugHTTPServer() *http.Server {
 
 	debugHTTPServer := &http.Server{
 		Addr:         h.cfg.MetricsAddr,
-		Handler:      debugMux,
+		Handler:      securityHeaders(debugMux),
 		ReadTimeout:  types.HTTPTimeout,
 		WriteTimeout: 0,
 	}
@@ -329,38 +404,18 @@ func (h *Headscale) debugBatcher() string {
 
 	var nodes []nodeStatus
 
-	// Try to get detailed debug info if we have a LockFreeBatcher
-	if batcher, ok := h.mapBatcher.(*mapper.LockFreeBatcher); ok {
-		debugInfo := batcher.Debug()
-		for nodeID, info := range debugInfo {
-			nodes = append(nodes, nodeStatus{
-				id:                nodeID,
-				connected:         info.Connected,
-				activeConnections: info.ActiveConnections,
-			})
-			totalNodes++
-
-			if info.Connected {
-				connectedCount++
-			}
-		}
-	} else {
-		// Fallback to basic connection info
-		connectedMap := h.mapBatcher.ConnectedMap()
-		connectedMap.Range(func(nodeID types.NodeID, connected bool) bool {
-			nodes = append(nodes, nodeStatus{
-				id:                nodeID,
-				connected:         connected,
-				activeConnections: 0,
-			})
-			totalNodes++
-
-			if connected {
-				connectedCount++
-			}
-
-			return true
+	debugInfo := h.mapBatcher.Debug()
+	for nodeID, info := range debugInfo {
+		nodes = append(nodes, nodeStatus{
+			id:                nodeID,
+			connected:         info.Connected,
+			activeConnections: info.ActiveConnections,
 		})
+		totalNodes++
+
+		if info.Connected {
+			connectedCount++
+		}
 	}
 
 	// Sort by node ID
@@ -380,13 +435,13 @@ func (h *Headscale) debugBatcher() string {
 		}
 
 		if node.activeConnections > 0 {
-			sb.WriteString(fmt.Sprintf("Node %d:\t%s (%d connections)\n", node.id, status, node.activeConnections))
+			fmt.Fprintf(&sb, "Node %d:\t%s (%d connections)\n", node.id, status, node.activeConnections)
 		} else {
-			sb.WriteString(fmt.Sprintf("Node %d:\t%s\n", node.id, status))
+			fmt.Fprintf(&sb, "Node %d:\t%s\n", node.id, status)
 		}
 	}
 
-	sb.WriteString(fmt.Sprintf("\nSummary: %d connected, %d total\n", connectedCount, totalNodes))
+	fmt.Fprintf(&sb, "\nSummary: %d connected, %d total\n", connectedCount, totalNodes)
 
 	return sb.String()
 }
@@ -410,29 +465,108 @@ func (h *Headscale) debugBatcherJSON() DebugBatcherInfo {
 		TotalNodes:     0,
 	}
 
-	// Try to get detailed debug info if we have a LockFreeBatcher
-	if batcher, ok := h.mapBatcher.(*mapper.LockFreeBatcher); ok {
-		debugInfo := batcher.Debug()
-		for nodeID, debugData := range debugInfo {
-			info.ConnectedNodes[fmt.Sprintf("%d", nodeID)] = DebugBatcherNodeInfo{
-				Connected:         debugData.Connected,
-				ActiveConnections: debugData.ActiveConnections,
-			}
-			info.TotalNodes++
+	debugInfo := h.mapBatcher.Debug()
+	for nodeID, debugData := range debugInfo {
+		info.ConnectedNodes[fmt.Sprintf("%d", nodeID)] = DebugBatcherNodeInfo{
+			Connected:         debugData.Connected,
+			ActiveConnections: debugData.ActiveConnections,
 		}
-	} else {
-		// Fallback to basic connection info
-		connectedMap := h.mapBatcher.ConnectedMap()
-		connectedMap.Range(func(nodeID types.NodeID, connected bool) bool {
-			info.ConnectedNodes[fmt.Sprintf("%d", nodeID)] = DebugBatcherNodeInfo{
-				Connected:         connected,
-				ActiveConnections: 0,
-			}
-			info.TotalNodes++
-
-			return true
-		})
+		info.TotalNodes++
 	}
 
 	return info
 }
+
+// connectedNodesList returns a list of connected nodes for the ping page.
+func (h *Headscale) connectedNodesList() []templates.ConnectedNode {
+	debugInfo := h.mapBatcher.Debug()
+
+	var nodes []templates.ConnectedNode
+
+	for nodeID, info := range debugInfo {
+		if !info.Connected {
+			continue
+		}
+
+		nv, ok := h.state.GetNodeByID(nodeID)
+		if !ok {
+			continue
+		}
+
+		cn := templates.ConnectedNode{
+			ID:       nodeID,
+			Hostname: nv.Hostname(),
+		}
+
+		for _, ip := range nv.IPs() {
+			cn.IPs = append(cn.IPs, ip.String())
+		}
+
+		nodes = append(nodes, cn)
+	}
+
+	return nodes
+}
+
+const pingTimeout = 30 * time.Second
+
+// doPing sends a PingRequest to the node identified by query and waits for a response.
+func (h *Headscale) doPing(ctx context.Context, query string) *templates.PingResult {
+	if query == "" {
+		return &templates.PingResult{
+			Status:  "error",
+			Message: "No node specified.",
+		}
+	}
+
+	node, ok := h.state.ResolveNode(query)
+	if !ok {
+		return &templates.PingResult{
+			Status:  "error",
+			Message: fmt.Sprintf("Node %q not found.", query),
+		}
+	}
+
+	nodeID := node.ID()
+
+	if !h.mapBatcher.IsConnected(nodeID) {
+		return &templates.PingResult{
+			Status:  "error",
+			NodeID:  nodeID,
+			Message: fmt.Sprintf("Node %d is not connected.", nodeID),
+		}
+	}
+
+	pingID, responseCh := h.state.RegisterPing(nodeID)
+	defer h.state.CancelPing(pingID)
+
+	// The callback hits /machine/ping-response on the main TLS router,
+	// not the noise chain, so URLIsNoise stays false. Operators running
+	// server_url over plain HTTP are on their own — don't do that.
+	callbackURL := h.cfg.ServerURL + "/machine/ping-response?id=" + pingID
+	h.Change(change.PingNode(nodeID, &tailcfg.PingRequest{
+		URL: callbackURL,
+		Log: true,
+	}))
+
+	select {
+	case latency := <-responseCh:
+		return &templates.PingResult{
+			Status:  "ok",
+			Latency: latency,
+			NodeID:  nodeID,
+		}
+	case <-time.After(pingTimeout):
+		return &templates.PingResult{
+			Status:  "timeout",
+			NodeID:  nodeID,
+			Message: fmt.Sprintf("No response after %s.", pingTimeout),
+		}
+	case <-ctx.Done():
+		return &templates.PingResult{
+			Status:  "error",
+			NodeID:  nodeID,
+			Message: "Request cancelled.",
+		}
+	}
+}

hscontrol/grpcv1.go

@@ -26,6 +26,7 @@ import (
 	"tailscale.com/types/views"
 
 	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2"
 	"github.com/juanfont/headscale/hscontrol/state"
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/juanfont/headscale/hscontrol/util"
@@ -781,6 +782,35 @@ func (api headscaleV1APIServer) SetPolicy(
 	return response, nil
 }
 
+// CheckPolicy validates the given policy against the server's live users
+// and nodes, running its `tests` block as a sandbox. Nothing is persisted
+// and the live PolicyManager is not touched. Works regardless of
+// policy.mode so operators can validate a policy file before storing it.
+func (api headscaleV1APIServer) CheckPolicy(
+	_ context.Context,
+	request *v1.CheckPolicyRequest,
+) (*v1.CheckPolicyResponse, error) {
+	polB := []byte(request.GetPolicy())
+
+	users, err := api.h.state.ListAllUsers()
+	if err != nil {
+		return nil, status.Errorf(codes.Internal, "loading users: %s", err)
+	}
+
+	nodes := api.h.state.ListNodes()
+
+	pm, err := policyv2.NewPolicyManager(polB, users, nodes)
+	if err != nil {
+		return nil, status.Error(codes.InvalidArgument, err.Error())
+	}
+
+	if _, err := pm.SetPolicy(polB); err != nil {
+		return nil, status.Error(codes.InvalidArgument, err.Error())
+	}
+
+	return &v1.CheckPolicyResponse{}, nil
+}
+
 // The following service calls are for testing and debugging
 func (api headscaleV1APIServer) DebugCreateNode(
 	ctx context.Context,
@@ -802,27 +832,16 @@ func (api headscaleV1APIServer) DebugCreateNode(
 		Interface("route-str", request.GetRoutes()).
 		Msg("Creating routes for node")
 
-	hostinfo := tailcfg.Hostinfo{
-		RoutableIPs: routes,
-		OS:          "TestOS",
-		Hostname:    request.GetName(),
-	}
-
 	registrationId, err := types.AuthIDFromString(request.GetKey())
 	if err != nil {
 		return nil, err
 	}
 
-	newNode := types.Node{
+	regData := &types.RegistrationData{
 		NodeKey:    key.NewNode().Public(),
 		MachineKey: key.NewMachine().Public(),
 		Hostname:   request.GetName(),
-		User:       user,
-
-		Expiry:   &time.Time{},
-		LastSeen: &time.Time{},
-
-		Hostinfo: &hostinfo,
+		Expiry:     &time.Time{}, // zero time, not nil — preserves proto JSON round-trip semantics
 	}
 
 	log.Debug().
@@ -830,10 +849,27 @@ func (api headscaleV1APIServer) DebugCreateNode(
 		Str("registration_id", registrationId.String()).
 		Msg("adding debug machine via CLI, appending to registration cache")
 
-	authRegReq := types.NewRegisterAuthRequest(newNode)
+	authRegReq := types.NewRegisterAuthRequest(regData)
 	api.h.state.SetAuthCacheEntry(registrationId, authRegReq)
 
-	return &v1.DebugCreateNodeResponse{Node: newNode.Proto()}, nil
+	// Echo back a synthetic Node so the debug response surface stays
+	// stable. The actual node is created later by AuthApprove via
+	// HandleNodeFromAuthPath using the cached RegistrationData.
+	echoNode := types.Node{
+		NodeKey:    regData.NodeKey,
+		MachineKey: regData.MachineKey,
+		Hostname:   regData.Hostname,
+		User:       user,
+		Expiry:     &time.Time{},
+		LastSeen:   &time.Time{},
+		Hostinfo: &tailcfg.Hostinfo{
+			Hostname:    request.GetName(),
+			OS:          "TestOS",
+			RoutableIPs: routes,
+		},
+	}
+
+	return &v1.DebugCreateNodeResponse{Node: echoNode.Proto()}, nil
 }
 
 func (api headscaleV1APIServer) Health(

hscontrol/grpcv1_test.go

@@ -264,6 +264,284 @@ func TestSetTags_CannotRemoveAllTags(t *testing.T) {
 	assert.Nil(t, resp.GetNode())
 }
 
+// TestSetTags_ClearsUserIDInDatabase tests that converting a user-owned node
+// to a tagged node via SetTags correctly persists user_id = NULL in the
+// database, not just in-memory.
+// https://github.com/juanfont/headscale/issues/3161
+func TestSetTags_ClearsUserIDInDatabase(t *testing.T) {
+	t.Parallel()
+
+	app := createTestApp(t)
+
+	user := app.state.CreateUserForTest("tag-owner")
+	err := app.state.UpdatePolicyManagerUsersForTest()
+	require.NoError(t, err)
+
+	_, err = app.state.SetPolicy([]byte(`{
+		"tagOwners": {"tag:server": ["tag-owner@"]},
+		"acls": [{"action": "accept", "src": ["*"], "dst": ["*:*"]}]
+	}`))
+	require.NoError(t, err)
+
+	// Register a user-owned node (untagged PreAuthKey).
+	pak, err := app.state.CreatePreAuthKey(user.TypedID(), false, 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: "user-owned-node",
+		},
+	}
+	_, err = app.handleRegisterWithAuthKey(regReq, machineKey.Public())
+	require.NoError(t, err)
+
+	node, found := app.state.GetNodeByNodeKey(nodeKey.Public())
+	require.True(t, found)
+	require.False(t, node.IsTagged(), "node should start as user-owned")
+	require.True(t, node.UserID().Valid(), "user-owned node must have UserID")
+
+	nodeID := node.ID()
+
+	// Convert to tagged via SetTags API.
+	apiServer := newHeadscaleV1APIServer(app)
+	_, err = apiServer.SetTags(context.Background(), &v1.SetTagsRequest{
+		NodeId: uint64(nodeID),
+		Tags:   []string{"tag:server"},
+	})
+	require.NoError(t, err)
+
+	// Verify in-memory state is correct.
+	nsNode, found := app.state.GetNodeByID(nodeID)
+	require.True(t, found)
+	assert.True(t, nsNode.IsTagged(), "NodeStore: node should be tagged")
+	assert.False(t, nsNode.UserID().Valid(),
+		"NodeStore: UserID should be nil for tagged node")
+
+	// THE CRITICAL CHECK: verify database has user_id = NULL.
+	dbNode, err := app.state.DB().GetNodeByID(nodeID)
+	require.NoError(t, err)
+	assert.Nil(t, dbNode.UserID,
+		"Database: user_id must be NULL after converting to tagged node")
+	assert.True(t, dbNode.IsTagged(),
+		"Database: tags must be set")
+}
+
+// TestSetTags_NodeDisappearsFromUserListing tests issue #3161:
+// after converting a user-owned node to tagged, it must no longer appear
+// when listing nodes filtered by the original user.
+// https://github.com/juanfont/headscale/issues/3161
+func TestSetTags_NodeDisappearsFromUserListing(t *testing.T) {
+	t.Parallel()
+
+	app := createTestApp(t)
+
+	user := app.state.CreateUserForTest("list-user")
+	err := app.state.UpdatePolicyManagerUsersForTest()
+	require.NoError(t, err)
+
+	_, err = app.state.SetPolicy([]byte(`{
+		"tagOwners": {"tag:web": ["list-user@"]},
+		"acls": [{"action": "accept", "src": ["*"], "dst": ["*:*"]}]
+	}`))
+	require.NoError(t, err)
+
+	// Register a user-owned node.
+	pak, err := app.state.CreatePreAuthKey(user.TypedID(), false, 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: "web-server",
+		},
+	}
+	_, err = app.handleRegisterWithAuthKey(regReq, machineKey.Public())
+	require.NoError(t, err)
+
+	node, found := app.state.GetNodeByNodeKey(nodeKey.Public())
+	require.True(t, found)
+
+	// Verify node appears under user before tagging.
+	apiServer := newHeadscaleV1APIServer(app)
+	resp, err := apiServer.ListNodes(context.Background(), &v1.ListNodesRequest{
+		User: "list-user",
+	})
+	require.NoError(t, err)
+	assert.Len(t, resp.GetNodes(), 1, "user-owned node should appear under user")
+
+	// Convert to tagged.
+	_, err = apiServer.SetTags(context.Background(), &v1.SetTagsRequest{
+		NodeId: uint64(node.ID()),
+		Tags:   []string{"tag:web"},
+	})
+	require.NoError(t, err)
+
+	// Node must NOT appear when listing by original user.
+	resp, err = apiServer.ListNodes(context.Background(), &v1.ListNodesRequest{
+		User: "list-user",
+	})
+	require.NoError(t, err)
+	assert.Empty(t, resp.GetNodes(),
+		"tagged node must not appear when listing nodes for original user")
+
+	// Node must still appear in unfiltered listing.
+	allResp, err := apiServer.ListNodes(context.Background(), &v1.ListNodesRequest{})
+	require.NoError(t, err)
+	require.Len(t, allResp.GetNodes(), 1)
+	assert.Contains(t, allResp.GetNodes()[0].GetTags(), "tag:web")
+}
+
+// TestSetTags_NodeStoreAndDBConsistency verifies that after SetTags, the
+// in-memory NodeStore and the database agree on the node's ownership state.
+// https://github.com/juanfont/headscale/issues/3161
+func TestSetTags_NodeStoreAndDBConsistency(t *testing.T) {
+	t.Parallel()
+
+	app := createTestApp(t)
+
+	user := app.state.CreateUserForTest("consistency-user")
+	err := app.state.UpdatePolicyManagerUsersForTest()
+	require.NoError(t, err)
+
+	_, err = app.state.SetPolicy([]byte(`{
+		"tagOwners": {"tag:db": ["consistency-user@"]},
+		"acls": [{"action": "accept", "src": ["*"], "dst": ["*:*"]}]
+	}`))
+	require.NoError(t, err)
+
+	pak, err := app.state.CreatePreAuthKey(user.TypedID(), false, 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: "db-node",
+		},
+	}
+	_, err = app.handleRegisterWithAuthKey(regReq, machineKey.Public())
+	require.NoError(t, err)
+
+	node, found := app.state.GetNodeByNodeKey(nodeKey.Public())
+	require.True(t, found)
+
+	nodeID := node.ID()
+
+	// Convert to tagged.
+	apiServer := newHeadscaleV1APIServer(app)
+	_, err = apiServer.SetTags(context.Background(), &v1.SetTagsRequest{
+		NodeId: uint64(nodeID),
+		Tags:   []string{"tag:db"},
+	})
+	require.NoError(t, err)
+
+	// In-memory state.
+	nsNode, found := app.state.GetNodeByID(nodeID)
+	require.True(t, found)
+
+	// Database state.
+	dbNode, err := app.state.DB().GetNodeByID(nodeID)
+	require.NoError(t, err)
+
+	// Both must agree: tagged, no UserID.
+	assert.True(t, nsNode.IsTagged(), "NodeStore: should be tagged")
+	assert.True(t, dbNode.IsTagged(), "Database: should be tagged")
+
+	assert.False(t, nsNode.UserID().Valid(),
+		"NodeStore: UserID should be nil")
+	assert.Nil(t, dbNode.UserID,
+		"Database: user_id should be NULL")
+
+	assert.Equal(t,
+		nsNode.UserID().Valid(),
+		dbNode.UserID != nil,
+		"NodeStore and database must agree on UserID state")
+}
+
+// TestSetTags_UserDeletionDoesNotCascadeToTaggedNode tests that deleting the
+// original user does not cascade-delete a node that was converted to tagged
+// via SetTags. This catches the real-world consequence of stale user_id:
+// ON DELETE CASCADE would destroy the tagged node.
+// https://github.com/juanfont/headscale/issues/3161
+func TestSetTags_UserDeletionDoesNotCascadeToTaggedNode(t *testing.T) {
+	t.Parallel()
+
+	app := createTestApp(t)
+
+	user := app.state.CreateUserForTest("doomed-user")
+	err := app.state.UpdatePolicyManagerUsersForTest()
+	require.NoError(t, err)
+
+	_, err = app.state.SetPolicy([]byte(`{
+		"tagOwners": {"tag:survivor": ["doomed-user@"]},
+		"acls": [{"action": "accept", "src": ["*"], "dst": ["*:*"]}]
+	}`))
+	require.NoError(t, err)
+
+	pak, err := app.state.CreatePreAuthKey(user.TypedID(), false, 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: "survivor-node",
+		},
+	}
+	_, err = app.handleRegisterWithAuthKey(regReq, machineKey.Public())
+	require.NoError(t, err)
+
+	node, found := app.state.GetNodeByNodeKey(nodeKey.Public())
+	require.True(t, found)
+
+	nodeID := node.ID()
+
+	// Convert to tagged.
+	apiServer := newHeadscaleV1APIServer(app)
+	_, err = apiServer.SetTags(context.Background(), &v1.SetTagsRequest{
+		NodeId: uint64(nodeID),
+		Tags:   []string{"tag:survivor"},
+	})
+	require.NoError(t, err)
+
+	// Delete the original user.
+	_, err = app.state.DeleteUser(*user.TypedID())
+	require.NoError(t, err)
+
+	// The tagged node must survive in both NodeStore and database.
+	nsNode, found := app.state.GetNodeByID(nodeID)
+	require.True(t, found, "tagged node must survive user deletion in NodeStore")
+	assert.True(t, nsNode.IsTagged())
+
+	dbNode, err := app.state.DB().GetNodeByID(nodeID)
+	require.NoError(t, err, "tagged node must survive user deletion in database")
+	assert.True(t, dbNode.IsTagged())
+	assert.Nil(t, dbNode.UserID)
+}
+
 // TestDeleteUser_ReturnsProperChangeSignal tests issue #2967 fix:
 // When a user is deleted, the state should return a non-empty change signal
 // to ensure policy manager is updated and clients are notified immediately.
@@ -318,7 +596,7 @@ func TestDeleteUser_TaggedNodeSurvives(t *testing.T) {
 	require.NoError(t, err)
 	require.True(t, resp.MachineAuthorized)
 
-	// Verify the registered node has nil UserID (enforced invariant).
+	// Verify the registered node has nil UserID (enforced at registration).
 	node, found := app.state.GetNodeByNodeKey(nodeKey.Public())
 	require.True(t, found)
 	require.True(t, node.IsTagged())

hscontrol/handlers.go

@@ -44,6 +44,54 @@ func httpError(w http.ResponseWriter, err error) {
 	}
 }
 
+// httpUserError logs an error and sends a styled HTML error page.
+// Use this for browser-facing error paths (OIDC, registration confirm)
+// where the user should see a branded page instead of plain text.
+// Technical details go to the server log; the HTML page only shows
+// an actionable message derived from the HTTP status code.
+func httpUserError(w http.ResponseWriter, err error) {
+	code := http.StatusInternalServerError
+
+	if herr, ok := errors.AsType[HTTPError](err); ok {
+		if herr.Code != 0 {
+			code = herr.Code
+		}
+
+		log.Error().Err(herr.Err).Int("code", code).Msgf("user msg: %s", herr.Msg)
+	} else {
+		log.Error().Err(err).Int("code", code).Msg("http internal server error")
+	}
+
+	userMsg := userMessageForStatusCode(code)
+
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.WriteHeader(code)
+
+	page := templates.AuthError(templates.AuthErrorResult{
+		Title:   "Headscale - Error",
+		Heading: http.StatusText(code),
+		Message: userMsg,
+	})
+
+	_, werr := w.Write([]byte(page.Render()))
+	if werr != nil {
+		log.Error().Err(werr).Msg("failed to write HTML error response")
+	}
+}
+
+func userMessageForStatusCode(code int) string {
+	switch {
+	case code == http.StatusUnauthorized || code == http.StatusForbidden:
+		return "You are not authorized. Please contact your administrator."
+	case code == http.StatusGone:
+		return "Your session has expired. Please try again."
+	case code >= 400 && code < 500:
+		return "The request could not be processed. Please try again."
+	default:
+		return "Something went wrong. Please try again later."
+	}
+}
+
 // HTTPError represents an error that is surfaced to the user via web.
 type HTTPError struct {
 	Code int    // HTTP response code to send to client; 0 means 500
@@ -80,13 +128,19 @@ func parseCapabilityVersion(req *http.Request) (tailcfg.CapabilityVersion, error
 	return tailcfg.CapabilityVersion(clientCapabilityVersion), nil
 }
 
+// verifyBodyLimit caps the request body for /verify. The DERP verify
+// protocol payload (tailcfg.DERPAdmitClientRequest) is a few hundred
+// bytes; 4 KiB is generous and prevents an unauthenticated client from
+// OOMing the public router with arbitrarily large POSTs.
+const verifyBodyLimit int64 = 4 * 1024
+
 func (h *Headscale) handleVerifyRequest(
 	req *http.Request,
 	writer io.Writer,
 ) error {
 	body, err := io.ReadAll(req.Body)
 	if err != nil {
-		return fmt.Errorf("reading request body: %w", err)
+		return NewHTTPError(http.StatusRequestEntityTooLarge, "request body too large", fmt.Errorf("reading request body: %w", err))
 	}
 
 	var derpAdmitClientRequest tailcfg.DERPAdmitClientRequest
@@ -124,6 +178,8 @@ func (h *Headscale) VerifyHandler(
 		return
 	}
 
+	req.Body = http.MaxBytesReader(writer, req.Body, verifyBodyLimit)
+
 	err := h.handleVerifyRequest(req, writer)
 	if err != nil {
 		httpError(writer, err)

hscontrol/handlers_test.go

@@ -0,0 +1,129 @@
+package hscontrol
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+var errTestUnexpected = errors.New("unexpected failure")
+
+// TestHandleVerifyRequest_OversizedBodyRejected verifies that the
+// /verify handler refuses POST bodies larger than verifyBodyLimit.
+// The MaxBytesReader is applied in VerifyHandler, so we simulate
+// the same wrapping here.
+func TestHandleVerifyRequest_OversizedBodyRejected(t *testing.T) {
+	t.Parallel()
+
+	body := strings.Repeat("x", int(verifyBodyLimit)+128)
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequestWithContext(
+		context.Background(),
+		http.MethodPost,
+		"/verify",
+		bytes.NewReader([]byte(body)),
+	)
+	req.Body = http.MaxBytesReader(rec, req.Body, verifyBodyLimit)
+
+	h := &Headscale{}
+
+	err := h.handleVerifyRequest(req, &bytes.Buffer{})
+	if err == nil {
+		t.Fatal("oversized verify body must be rejected")
+	}
+
+	httpErr, ok := errorAsHTTPError(err)
+	if !ok {
+		t.Fatalf("error must be an HTTPError, got: %T (%v)", err, err)
+	}
+
+	assert.Equal(t, http.StatusRequestEntityTooLarge, httpErr.Code,
+		"oversized body must surface 413")
+}
+
+// errorAsHTTPError is a small local helper that unwraps an HTTPError
+// from an error chain.
+func errorAsHTTPError(err error) (HTTPError, bool) {
+	var h HTTPError
+	if errors.As(err, &h) {
+		return h, true
+	}
+
+	return HTTPError{}, false
+}
+
+func TestHttpUserError(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name           string
+		err            error
+		wantCode       int
+		wantContains   string
+		wantNotContain string
+	}{
+		{
+			name:           "forbidden_renders_authorization_message",
+			err:            NewHTTPError(http.StatusForbidden, "csrf token mismatch", nil),
+			wantCode:       http.StatusForbidden,
+			wantContains:   "You are not authorized. Please contact your administrator.",
+			wantNotContain: "csrf token mismatch",
+		},
+		{
+			name:           "unauthorized_renders_authorization_message",
+			err:            NewHTTPError(http.StatusUnauthorized, "unauthorised domain", nil),
+			wantCode:       http.StatusUnauthorized,
+			wantContains:   "You are not authorized. Please contact your administrator.",
+			wantNotContain: "unauthorised domain",
+		},
+		{
+			name:           "gone_renders_session_expired",
+			err:            NewHTTPError(http.StatusGone, "login session expired, try again", nil),
+			wantCode:       http.StatusGone,
+			wantContains:   "Your session has expired. Please try again.",
+			wantNotContain: "login session expired",
+		},
+		{
+			name:           "bad_request_renders_generic_retry",
+			err:            NewHTTPError(http.StatusBadRequest, "state not found", nil),
+			wantCode:       http.StatusBadRequest,
+			wantContains:   "The request could not be processed. Please try again.",
+			wantNotContain: "state not found",
+		},
+		{
+			name:         "plain_error_renders_500",
+			err:          errTestUnexpected,
+			wantCode:     http.StatusInternalServerError,
+			wantContains: "Something went wrong. Please try again later.",
+		},
+		{
+			name:         "html_structure_present",
+			err:          NewHTTPError(http.StatusGone, "session expired", nil),
+			wantCode:     http.StatusGone,
+			wantContains: "<!DOCTYPE html>",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			rec := httptest.NewRecorder()
+			httpUserError(rec, tt.err)
+
+			assert.Equal(t, tt.wantCode, rec.Code)
+			assert.Contains(t, rec.Header().Get("Content-Type"), "text/html")
+			assert.Contains(t, rec.Body.String(), tt.wantContains)
+
+			if tt.wantNotContain != "" {
+				assert.NotContains(t, rec.Body.String(), tt.wantNotContain)
+			}
+		})
+	}
+}

hscontrol/mapper/batcher.go

@@ -3,6 +3,8 @@ package mapper
 import (
 	"errors"
 	"fmt"
+	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/juanfont/headscale/hscontrol/state"
@@ -24,43 +26,31 @@ var (
 	ErrNodeNotFoundMapper = errors.New("node not found")
 )
 
+// offlineNodeCleanupThreshold is how long a node must be disconnected
+// before cleanupOfflineNodes removes its in-memory state.
+const offlineNodeCleanupThreshold = 15 * time.Minute
+
 var mapResponseGenerated = promauto.NewCounterVec(prometheus.CounterOpts{
 	Namespace: "headscale",
 	Name:      "mapresponse_generated_total",
 	Help:      "total count of mapresponses generated by response type",
 }, []string{"response_type"})
 
-type batcherFunc func(cfg *types.Config, state *state.State) Batcher
-
-// Batcher defines the common interface for all batcher implementations.
-type Batcher interface {
-	Start()
-	Close()
-	AddNode(id types.NodeID, c chan<- *tailcfg.MapResponse, version tailcfg.CapabilityVersion, stop func()) error
-	RemoveNode(id types.NodeID, c chan<- *tailcfg.MapResponse) bool
-	IsConnected(id types.NodeID) bool
-	ConnectedMap() *xsync.Map[types.NodeID, bool]
-	AddWork(r ...change.Change)
-	MapResponseFromChange(id types.NodeID, r change.Change) (*tailcfg.MapResponse, error)
-	DebugMapResponses() (map[types.NodeID][]tailcfg.MapResponse, error)
-}
-
-func NewBatcher(batchTime time.Duration, workers int, mapper *mapper) *LockFreeBatcher {
-	return &LockFreeBatcher{
+func NewBatcher(batchTime time.Duration, workers int, mapper *mapper) *Batcher {
+	return &Batcher{
 		mapper:  mapper,
 		workers: workers,
 		tick:    time.NewTicker(batchTime),
 
 		// The size of this channel is arbitrary chosen, the sizing should be revisited.
-		workCh:         make(chan work, workers*200),
-		nodes:          xsync.NewMap[types.NodeID, *multiChannelNodeConn](),
-		connected:      xsync.NewMap[types.NodeID, *time.Time](),
-		pendingChanges: xsync.NewMap[types.NodeID, []change.Change](),
+		workCh: make(chan work, workers*200),
+		done:   make(chan struct{}),
+		nodes:  xsync.NewMap[types.NodeID, *multiChannelNodeConn](),
 	}
 }
 
-// NewBatcherAndMapper creates a Batcher implementation.
-func NewBatcherAndMapper(cfg *types.Config, state *state.State) Batcher {
+// NewBatcherAndMapper creates a new Batcher with its mapper.
+func NewBatcherAndMapper(cfg *types.Config, state *state.State) *Batcher {
 	m := newMapper(cfg, state)
 	b := NewBatcher(cfg.Tuning.BatchChangeDelay, cfg.Tuning.BatcherWorkers, m)
 	m.batcher = b
@@ -138,6 +128,30 @@ func generateMapResponse(nc nodeConnection, mapper *mapper, r change.Change) (*t
 		return nil, fmt.Errorf("generating map response for nodeID %d: %w", nodeID, err)
 	}
 
+	// When a full update (SendAllPeers=true) produces zero visible peers
+	// (e.g., a restrictive policy isolates this node), the resulting
+	// MapResponse has Peers: []*tailcfg.Node{} (empty non-nil slice).
+	//
+	// The Tailscale client only treats Peers as a full authoritative
+	// replacement when len(Peers) > 0 (controlclient/map.go:462).
+	// An empty Peers slice is indistinguishable from a delta response,
+	// so the client silently preserves its existing peer state.
+	//
+	// This matters when a FullUpdate() replaces a pending PolicyChange()
+	// in the batcher (addToBatch short-circuits on HasFull). The
+	// PolicyChange would have computed PeersRemoved via computePeerDiff,
+	// but the FullUpdate path uses WithPeers which sets Peers: [].
+	//
+	// Fix: when a full update results in zero peers, compute the diff
+	// against lastSentPeers and add explicit PeersRemoved entries so
+	// the client correctly clears its stale peer state.
+	if mapResp != nil && r.SendAllPeers && len(mapResp.Peers) == 0 {
+		removedPeers := nc.computePeerDiff(nil)
+		if len(removedPeers) > 0 {
+			mapResp.PeersRemoved = removedPeers
+		}
+	}
+
 	return mapResp, nil
 }
 
@@ -164,10 +178,20 @@ func handleNodeChange(nc nodeConnection, mapper *mapper, r change.Change) error
 	// Send the map response
 	err = nc.send(data)
 	if err != nil {
+		// If the node has no active connections, the data was not
+		// delivered. Do not update lastSentPeers — recording phantom
+		// peer state would corrupt future computePeerDiff calculations,
+		// causing the node to miss peer additions or removals after
+		// reconnection.
+		if errors.Is(err, errNoActiveConnections) {
+			return nil
+		}
+
 		return fmt.Errorf("sending map response to node %d: %w", nodeID, err)
 	}
 
-	// Update peer tracking after successful send
+	// Update peer tracking only after confirmed delivery to at
+	// least one active connection.
 	nc.updateSentPeers(data)
 
 	return nil
@@ -180,8 +204,568 @@ type workResult struct {
 }
 
 // work represents a unit of work to be processed by workers.
+// All pending changes for a node are bundled into a single work item
+// so that one worker processes them sequentially. This prevents
+// out-of-order MapResponse delivery and races on lastSentPeers
+// that occur when multiple workers process changes for the same node.
 type work struct {
-	c        change.Change
+	changes  []change.Change
 	nodeID   types.NodeID
 	resultCh chan<- workResult // optional channel for synchronous operations
 }
+
+// Batcher errors.
+var (
+	errConnectionClosed      = errors.New("connection channel already closed")
+	ErrInitialMapSendTimeout = errors.New("sending initial map: timeout")
+	ErrBatcherShuttingDown   = errors.New("batcher shutting down")
+	ErrConnectionSendTimeout = errors.New("timeout sending to channel (likely stale connection)")
+)
+
+// Batcher batches and distributes map responses to connected nodes.
+// It uses concurrent maps, per-node mutexes, and a worker pool.
+//
+// Lifecycle: Call Start() to spawn workers, then Close() to shut down.
+// Close() blocks until all workers have exited. A Batcher must not
+// be reused after Close().
+type Batcher struct {
+	tick    *time.Ticker
+	mapper  *mapper
+	workers int
+
+	nodes *xsync.Map[types.NodeID, *multiChannelNodeConn]
+
+	// Work queue channel
+	workCh   chan work
+	done     chan struct{}
+	doneOnce sync.Once // Ensures done is only closed once
+
+	// wg tracks the doWork and all worker goroutines so that Close()
+	// can block until they have fully exited.
+	wg sync.WaitGroup
+
+	started atomic.Bool // Ensures Start() is only called once
+
+	// Metrics
+	totalNodes      atomic.Int64
+	workQueuedCount atomic.Int64
+	workProcessed   atomic.Int64
+	workErrors      atomic.Int64
+}
+
+// AddNode registers a new node connection with the batcher and sends an initial map response.
+// It creates or updates the node's connection data, validates the initial map generation,
+// and notifies other nodes that this node has come online.
+// The stop function tears down the owning session if this connection is later declared stale.
+func (b *Batcher) AddNode(
+	id types.NodeID,
+	c chan<- *tailcfg.MapResponse,
+	version tailcfg.CapabilityVersion,
+	stop func(),
+) error {
+	addNodeStart := time.Now()
+	nlog := log.With().Uint64(zf.NodeID, id.Uint64()).Logger()
+
+	// Generate connection ID
+	connID := generateConnectionID()
+
+	// Create new connection entry
+	now := time.Now()
+	newEntry := &connectionEntry{
+		id:      connID,
+		c:       c,
+		version: version,
+		created: now,
+		stop:    stop,
+	}
+	// Initialize last used timestamp
+	newEntry.lastUsed.Store(now.Unix())
+
+	// Get or create multiChannelNodeConn - this reuses existing offline nodes for rapid reconnection
+	nodeConn, loaded := b.nodes.LoadOrStore(id, newMultiChannelNodeConn(id, b.mapper))
+
+	if !loaded {
+		b.totalNodes.Add(1)
+	}
+
+	// Add connection to the list (lock-free)
+	nodeConn.addConnection(newEntry)
+
+	// Use the worker pool for controlled concurrency instead of direct generation
+	initialMap, err := b.MapResponseFromChange(id, change.FullSelf(id))
+	if err != nil {
+		nlog.Error().Err(err).Msg("initial map generation failed")
+		nodeConn.removeConnectionByChannel(c)
+
+		if !nodeConn.hasActiveConnections() {
+			nodeConn.markDisconnected()
+		}
+
+		return fmt.Errorf("generating initial map for node %d: %w", id, err)
+	}
+
+	// Use a blocking send with timeout for initial map since the channel should be ready
+	// and we want to avoid the race condition where the receiver isn't ready yet
+	select {
+	case c <- initialMap:
+		// Success
+	case <-time.After(5 * time.Second): //nolint:mnd
+		nlog.Error().Err(ErrInitialMapSendTimeout).Msg("initial map send timeout")
+		nlog.Debug().Caller().Dur("timeout.duration", 5*time.Second). //nolint:mnd
+										Msg("initial map send timed out because channel was blocked or receiver not ready")
+		nodeConn.removeConnectionByChannel(c)
+
+		if !nodeConn.hasActiveConnections() {
+			nodeConn.markDisconnected()
+		}
+
+		return fmt.Errorf("%w for node %d", ErrInitialMapSendTimeout, id)
+	}
+
+	// Mark the node as connected now that the initial map was sent.
+	nodeConn.markConnected()
+
+	// Node will automatically receive updates through the normal flow
+	// The initial full map already contains all current state
+
+	nlog.Debug().Caller().Dur(zf.TotalDuration, time.Since(addNodeStart)).
+		Int("active.connections", nodeConn.getActiveConnectionCount()).
+		Msg("node connection established in batcher")
+
+	return nil
+}
+
+// RemoveNode disconnects a node from the batcher, marking it as offline and cleaning up its state.
+// It validates the connection channel matches one of the current connections, closes that specific connection,
+// and keeps the node entry alive for rapid reconnections instead of aggressive deletion.
+// Reports if the node still has active connections after removal.
+func (b *Batcher) RemoveNode(id types.NodeID, c chan<- *tailcfg.MapResponse) bool {
+	nlog := log.With().Uint64(zf.NodeID, id.Uint64()).Logger()
+
+	nodeConn, exists := b.nodes.Load(id)
+	if !exists || nodeConn == nil {
+		nlog.Debug().Caller().Msg("removeNode called for non-existent node")
+		return false
+	}
+
+	// Remove specific connection
+	removed := nodeConn.removeConnectionByChannel(c)
+	if !removed {
+		nlog.Debug().Caller().Msg("removeNode: channel not found, connection already removed or invalid")
+	}
+
+	// Check if node has any remaining active connections
+	if nodeConn.hasActiveConnections() {
+		nlog.Debug().Caller().
+			Int("active.connections", nodeConn.getActiveConnectionCount()).
+			Msg("node connection removed but keeping online, other connections remain")
+
+		return true // Node still has active connections
+	}
+
+	// No active connections - keep the node entry alive for rapid reconnections
+	// The node will get a fresh full map when it reconnects
+	nlog.Debug().Caller().Msg("node disconnected from batcher, keeping entry for rapid reconnection")
+	nodeConn.markDisconnected()
+
+	return false
+}
+
+// AddWork queues a change to be processed by the batcher.
+func (b *Batcher) AddWork(r ...change.Change) {
+	b.addToBatch(r...)
+}
+
+func (b *Batcher) Start() {
+	if !b.started.CompareAndSwap(false, true) {
+		return
+	}
+
+	b.wg.Add(1)
+
+	go b.doWork()
+}
+
+func (b *Batcher) Close() {
+	// Signal shutdown to all goroutines, only once.
+	// Workers and queueWork both select on done, so closing it
+	// is sufficient for graceful shutdown. We intentionally do NOT
+	// close workCh here because processBatchedChanges or
+	// MapResponseFromChange may still be sending on it concurrently.
+	b.doneOnce.Do(func() {
+		close(b.done)
+	})
+
+	// Wait for all worker goroutines (and doWork) to exit before
+	// tearing down node connections. This prevents workers from
+	// sending on connections that are being closed concurrently.
+	b.wg.Wait()
+
+	// Stop the ticker to prevent resource leaks.
+	b.tick.Stop()
+
+	// Close the underlying channels supplying the data to the clients.
+	b.nodes.Range(func(nodeID types.NodeID, conn *multiChannelNodeConn) bool {
+		if conn == nil {
+			return true
+		}
+
+		conn.close()
+
+		return true
+	})
+}
+
+func (b *Batcher) doWork() {
+	defer b.wg.Done()
+
+	for i := range b.workers {
+		b.wg.Add(1)
+
+		go b.worker(i + 1)
+	}
+
+	// Create a cleanup ticker for removing truly disconnected nodes
+	cleanupTicker := time.NewTicker(5 * time.Minute)
+	defer cleanupTicker.Stop()
+
+	for {
+		select {
+		case <-b.tick.C:
+			// Process batched changes
+			b.processBatchedChanges()
+		case <-cleanupTicker.C:
+			// Clean up nodes that have been offline for too long
+			b.cleanupOfflineNodes()
+		case <-b.done:
+			log.Info().Msg("batcher done channel closed, stopping to feed workers")
+			return
+		}
+	}
+}
+
+func (b *Batcher) worker(workerID int) {
+	defer b.wg.Done()
+
+	wlog := log.With().Int(zf.WorkerID, workerID).Logger()
+
+	for {
+		select {
+		case w, ok := <-b.workCh:
+			if !ok {
+				wlog.Debug().Msg("worker channel closing, shutting down")
+				return
+			}
+
+			b.workProcessed.Add(1)
+
+			// Synchronous path: a caller is blocking on resultCh
+			// waiting for a generated MapResponse (used by AddNode
+			// for the initial map). Always contains a single change.
+			if w.resultCh != nil {
+				var result workResult
+
+				if nc, exists := b.nodes.Load(w.nodeID); exists && nc != nil {
+					// Hold workMu so concurrent async work for this
+					// node waits until the initial map is sent.
+					nc.workMu.Lock()
+
+					var err error
+
+					result.mapResponse, err = generateMapResponse(nc, b.mapper, w.changes[0])
+
+					result.err = err
+					if result.err != nil {
+						b.workErrors.Add(1)
+						wlog.Error().Err(result.err).
+							Uint64(zf.NodeID, w.nodeID.Uint64()).
+							Str(zf.Reason, w.changes[0].Reason).
+							Msg("failed to generate map response for synchronous work")
+					} else if result.mapResponse != nil {
+						nc.updateSentPeers(result.mapResponse)
+					}
+
+					nc.workMu.Unlock()
+				} else {
+					result.err = fmt.Errorf("%w: %d", ErrNodeNotFoundMapper, w.nodeID)
+
+					b.workErrors.Add(1)
+					wlog.Error().Err(result.err).
+						Uint64(zf.NodeID, w.nodeID.Uint64()).
+						Msg("node not found for synchronous work")
+				}
+
+				select {
+				case w.resultCh <- result:
+				case <-b.done:
+					return
+				}
+
+				continue
+			}
+
+			// Async path: process all bundled changes sequentially.
+			// workMu ensures that if another worker picks up the next
+			// tick's bundle for the same node, it waits until we
+			// finish — preventing out-of-order delivery and races
+			// on lastSentPeers (Clear+Store vs Range).
+			if nc, exists := b.nodes.Load(w.nodeID); exists && nc != nil {
+				nc.workMu.Lock()
+				for _, ch := range w.changes {
+					err := nc.change(ch)
+					if err != nil {
+						b.workErrors.Add(1)
+						wlog.Error().Err(err).
+							Uint64(zf.NodeID, w.nodeID.Uint64()).
+							Str(zf.Reason, ch.Reason).
+							Msg("failed to apply change")
+					}
+				}
+				nc.workMu.Unlock()
+			}
+		case <-b.done:
+			wlog.Debug().Msg("batcher shutting down, exiting worker")
+			return
+		}
+	}
+}
+
+// queueWork safely queues work.
+func (b *Batcher) queueWork(w work) {
+	b.workQueuedCount.Add(1)
+
+	select {
+	case b.workCh <- w:
+		// Successfully queued
+	case <-b.done:
+		// Batcher is shutting down
+		return
+	}
+}
+
+// addToBatch adds changes to the pending batch.
+func (b *Batcher) addToBatch(changes ...change.Change) {
+	// Clean up any nodes being permanently removed from the system.
+	//
+	// This handles the case where a node is deleted from state but the batcher
+	// still has it registered. By cleaning up here, we prevent "node not found"
+	// errors when workers try to generate map responses for deleted nodes.
+	//
+	// Safety: change.Change.PeersRemoved is ONLY populated when nodes are actually
+	// deleted from the system (via change.NodeRemoved in state.DeleteNode). Policy
+	// changes that affect peer visibility do NOT use this field - they set
+	// RequiresRuntimePeerComputation=true and compute removed peers at runtime,
+	// putting them in tailcfg.MapResponse.PeersRemoved (a different struct).
+	// Therefore, this cleanup only removes nodes that are truly being deleted,
+	// not nodes that are still connected but have lost visibility of certain peers.
+	//
+	// See: https://github.com/juanfont/headscale/issues/2924
+	for _, ch := range changes {
+		for _, removedID := range ch.PeersRemoved {
+			if _, existed := b.nodes.LoadAndDelete(removedID); existed {
+				b.totalNodes.Add(-1)
+				log.Debug().
+					Uint64(zf.NodeID, removedID.Uint64()).
+					Msg("removed deleted node from batcher")
+			}
+		}
+	}
+
+	// Short circuit if any of the changes is a full update, which
+	// means we can skip sending individual changes.
+	if change.HasFull(changes) {
+		b.nodes.Range(func(_ types.NodeID, nc *multiChannelNodeConn) bool {
+			if nc == nil {
+				return true
+			}
+
+			nc.pendingMu.Lock()
+			nc.pending = []change.Change{change.FullUpdate()}
+			nc.pendingMu.Unlock()
+
+			return true
+		})
+
+		return
+	}
+
+	broadcast, targeted := change.SplitTargetedAndBroadcast(changes)
+
+	// Handle targeted changes - send only to the specific node
+	for _, ch := range targeted {
+		if nc, ok := b.nodes.Load(ch.TargetNode); ok && nc != nil {
+			nc.appendPending(ch)
+		}
+	}
+
+	// Handle broadcast changes - send to all nodes, filtering as needed
+	if len(broadcast) > 0 {
+		b.nodes.Range(func(nodeID types.NodeID, nc *multiChannelNodeConn) bool {
+			if nc == nil {
+				return true
+			}
+
+			filtered := change.FilterForNode(nodeID, broadcast)
+
+			if len(filtered) > 0 {
+				nc.appendPending(filtered...)
+			}
+
+			return true
+		})
+	}
+}
+
+// processBatchedChanges processes all pending batched changes.
+func (b *Batcher) processBatchedChanges() {
+	b.nodes.Range(func(nodeID types.NodeID, nc *multiChannelNodeConn) bool {
+		if nc == nil {
+			return true
+		}
+
+		pending := nc.drainPending()
+		if len(pending) == 0 {
+			return true
+		}
+
+		// Queue a single work item containing all pending changes.
+		// One item per node ensures a single worker processes them
+		// sequentially, preventing out-of-order delivery.
+		b.queueWork(work{changes: pending, nodeID: nodeID, resultCh: nil})
+
+		return true
+	})
+}
+
+// cleanupOfflineNodes removes nodes that have been offline for too long to prevent memory leaks.
+// Uses Compute() for atomic check-and-delete to prevent TOCTOU races where a node
+// reconnects between the hasActiveConnections() check and the Delete() call.
+func (b *Batcher) cleanupOfflineNodes() {
+	var nodesToCleanup []types.NodeID
+
+	// Find nodes that have been offline for too long by scanning b.nodes
+	// and checking each node's disconnectedAt timestamp.
+	b.nodes.Range(func(nodeID types.NodeID, nc *multiChannelNodeConn) bool {
+		if nc != nil && !nc.hasActiveConnections() && nc.offlineDuration() > offlineNodeCleanupThreshold {
+			nodesToCleanup = append(nodesToCleanup, nodeID)
+		}
+
+		return true
+	})
+
+	// Clean up the identified nodes using Compute() for atomic check-and-delete.
+	// This prevents a TOCTOU race where a node reconnects (adding an active
+	// connection) between the hasActiveConnections() check and the Delete() call.
+	cleaned := 0
+
+	for _, nodeID := range nodesToCleanup {
+		b.nodes.Compute(
+			nodeID,
+			func(conn *multiChannelNodeConn, loaded bool) (*multiChannelNodeConn, xsync.ComputeOp) {
+				if !loaded || conn == nil || conn.hasActiveConnections() {
+					return conn, xsync.CancelOp
+				}
+
+				// Perform all bookkeeping inside the Compute callback so
+				// that a concurrent AddNode (which calls LoadOrStore on
+				// b.nodes) cannot slip in between the delete and the
+				// counter update.
+				b.totalNodes.Add(-1)
+
+				cleaned++
+
+				log.Info().Uint64(zf.NodeID, nodeID.Uint64()).
+					Dur("offline_duration", offlineNodeCleanupThreshold).
+					Msg("cleaning up node that has been offline for too long")
+
+				return conn, xsync.DeleteOp
+			},
+		)
+	}
+
+	if cleaned > 0 {
+		log.Info().Int(zf.CleanedNodes, cleaned).
+			Msg("completed cleanup of long-offline nodes")
+	}
+}
+
+// IsConnected is a lock-free read that checks if a node is connected.
+// A node is considered connected if it has active connections or has
+// not been marked as disconnected.
+func (b *Batcher) IsConnected(id types.NodeID) bool {
+	nodeConn, exists := b.nodes.Load(id)
+	if !exists || nodeConn == nil {
+		return false
+	}
+
+	return nodeConn.isConnected()
+}
+
+// ConnectedMap returns a lock-free map of all known nodes and their
+// connection status (true = connected, false = disconnected).
+func (b *Batcher) ConnectedMap() *xsync.Map[types.NodeID, bool] {
+	ret := xsync.NewMap[types.NodeID, bool]()
+
+	b.nodes.Range(func(id types.NodeID, nc *multiChannelNodeConn) bool {
+		if nc != nil {
+			ret.Store(id, nc.isConnected())
+		}
+
+		return true
+	})
+
+	return ret
+}
+
+// MapResponseFromChange queues work to generate a map response and waits for the result.
+// This allows synchronous map generation using the same worker pool.
+func (b *Batcher) MapResponseFromChange(id types.NodeID, ch change.Change) (*tailcfg.MapResponse, error) {
+	resultCh := make(chan workResult, 1)
+
+	// Queue the work with a result channel using the safe queueing method
+	b.queueWork(work{changes: []change.Change{ch}, nodeID: id, resultCh: resultCh})
+
+	// Wait for the result
+	select {
+	case result := <-resultCh:
+		return result.mapResponse, result.err
+	case <-b.done:
+		return nil, fmt.Errorf("%w while generating map response for node %d", ErrBatcherShuttingDown, id)
+	}
+}
+
+// DebugNodeInfo contains debug information about a node's connections.
+type DebugNodeInfo struct {
+	Connected         bool `json:"connected"`
+	ActiveConnections int  `json:"active_connections"`
+}
+
+// Debug returns a pre-baked map of node debug information for the debug interface.
+func (b *Batcher) Debug() map[types.NodeID]DebugNodeInfo {
+	result := make(map[types.NodeID]DebugNodeInfo)
+
+	b.nodes.Range(func(id types.NodeID, nc *multiChannelNodeConn) bool {
+		if nc == nil {
+			return true
+		}
+
+		result[id] = DebugNodeInfo{
+			Connected:         nc.isConnected(),
+			ActiveConnections: nc.getActiveConnectionCount(),
+		}
+
+		return true
+	})
+
+	return result
+}
+
+func (b *Batcher) DebugMapResponses() (map[types.NodeID][]tailcfg.MapResponse, error) {
+	return b.mapper.debugMapResponses()
+}
+
+// WorkErrors returns the count of work errors encountered.
+// This is primarily useful for testing and debugging.
+func (b *Batcher) WorkErrors() int64 {
+	return b.workErrors.Load()
+}

hscontrol/mapper/batcher_bench_test.go

@@ -0,0 +1,742 @@
+package mapper
+
+// Benchmarks for batcher components and full pipeline.
+//
+// Organized into three tiers:
+// - Component benchmarks: individual functions (connectionEntry.send, computePeerDiff, etc.)
+// - System benchmarks: batching mechanics (addToBatch, processBatchedChanges, broadcast)
+// - Full pipeline benchmarks: end-to-end with real DB (gated behind !testing.Short())
+//
+// All benchmarks use sub-benchmarks with 10/100/1000 node counts for scaling analysis.
+
+import (
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/juanfont/headscale/hscontrol/types/change"
+	"github.com/puzpuzpuz/xsync/v4"
+	"tailscale.com/tailcfg"
+)
+
+// ============================================================================
+// Component Benchmarks
+// ============================================================================
+
+// BenchmarkConnectionEntry_Send measures the throughput of sending a single
+// MapResponse through a connectionEntry with a buffered channel.
+func BenchmarkConnectionEntry_Send(b *testing.B) {
+	ch := make(chan *tailcfg.MapResponse, b.N+1)
+	entry := makeConnectionEntry("bench-conn", ch)
+	data := testMapResponse()
+
+	b.ResetTimer()
+
+	for range b.N {
+		_ = entry.send(data)
+	}
+}
+
+// BenchmarkMultiChannelSend measures broadcast throughput to multiple connections.
+func BenchmarkMultiChannelSend(b *testing.B) {
+	for _, connCount := range []int{1, 3, 10} {
+		b.Run(fmt.Sprintf("%dconn", connCount), func(b *testing.B) {
+			mc := newMultiChannelNodeConn(1, nil)
+
+			channels := make([]chan *tailcfg.MapResponse, connCount)
+			for i := range channels {
+				channels[i] = make(chan *tailcfg.MapResponse, b.N+1)
+				mc.addConnection(makeConnectionEntry(fmt.Sprintf("conn-%d", i), channels[i]))
+			}
+
+			data := testMapResponse()
+
+			b.ResetTimer()
+
+			for range b.N {
+				_ = mc.send(data)
+			}
+		})
+	}
+}
+
+// BenchmarkComputePeerDiff measures the cost of computing peer diffs at scale.
+func BenchmarkComputePeerDiff(b *testing.B) {
+	for _, peerCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dpeers", peerCount), func(b *testing.B) {
+			mc := newMultiChannelNodeConn(1, nil)
+
+			// Populate tracked peers: 1..peerCount
+			for i := 1; i <= peerCount; i++ {
+				mc.lastSentPeers.Store(tailcfg.NodeID(i), struct{}{})
+			}
+
+			// Current peers: remove ~10% (every 10th peer is missing)
+			current := make([]tailcfg.NodeID, 0, peerCount)
+			for i := 1; i <= peerCount; i++ {
+				if i%10 != 0 {
+					current = append(current, tailcfg.NodeID(i))
+				}
+			}
+
+			b.ResetTimer()
+
+			for range b.N {
+				_ = mc.computePeerDiff(current)
+			}
+		})
+	}
+}
+
+// BenchmarkUpdateSentPeers measures the cost of updating peer tracking state.
+func BenchmarkUpdateSentPeers(b *testing.B) {
+	for _, peerCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dpeers_full", peerCount), func(b *testing.B) {
+			mc := newMultiChannelNodeConn(1, nil)
+
+			// Pre-build response with full peer list
+			peerIDs := make([]tailcfg.NodeID, peerCount)
+			for i := range peerIDs {
+				peerIDs[i] = tailcfg.NodeID(i + 1)
+			}
+
+			resp := testMapResponseWithPeers(peerIDs...)
+
+			b.ResetTimer()
+
+			for range b.N {
+				mc.updateSentPeers(resp)
+			}
+		})
+
+		b.Run(fmt.Sprintf("%dpeers_incremental", peerCount), func(b *testing.B) {
+			mc := newMultiChannelNodeConn(1, nil)
+
+			// Pre-populate with existing peers
+			for i := 1; i <= peerCount; i++ {
+				mc.lastSentPeers.Store(tailcfg.NodeID(i), struct{}{})
+			}
+
+			// Build incremental response: add 10% new peers
+			addCount := peerCount / 10
+			if addCount == 0 {
+				addCount = 1
+			}
+
+			resp := testMapResponse()
+
+			resp.PeersChanged = make([]*tailcfg.Node, addCount)
+			for i := range addCount {
+				resp.PeersChanged[i] = &tailcfg.Node{ID: tailcfg.NodeID(peerCount + i + 1)}
+			}
+
+			b.ResetTimer()
+
+			for range b.N {
+				mc.updateSentPeers(resp)
+			}
+		})
+	}
+}
+
+// ============================================================================
+// System Benchmarks (no DB, batcher mechanics only)
+// ============================================================================
+
+// benchBatcher creates a lightweight batcher for benchmarks. Unlike the test
+// helper, it doesn't register cleanup and suppresses logging.
+func benchBatcher(nodeCount, bufferSize int) (*Batcher, map[types.NodeID]chan *tailcfg.MapResponse) {
+	b := &Batcher{
+		tick:    time.NewTicker(1 * time.Hour), // never fires during bench
+		workers: 4,
+		workCh:  make(chan work, 4*200),
+		nodes:   xsync.NewMap[types.NodeID, *multiChannelNodeConn](),
+		done:    make(chan struct{}),
+	}
+
+	channels := make(map[types.NodeID]chan *tailcfg.MapResponse, nodeCount)
+	for i := 1; i <= nodeCount; i++ {
+		id := types.NodeID(i) //nolint:gosec // benchmark with small controlled values
+		mc := newMultiChannelNodeConn(id, nil)
+		ch := make(chan *tailcfg.MapResponse, bufferSize)
+		entry := &connectionEntry{
+			id:      fmt.Sprintf("conn-%d", i),
+			c:       ch,
+			version: tailcfg.CapabilityVersion(100),
+			created: time.Now(),
+		}
+		entry.lastUsed.Store(time.Now().Unix())
+		mc.addConnection(entry)
+		b.nodes.Store(id, mc)
+		channels[id] = ch
+	}
+
+	b.totalNodes.Store(int64(nodeCount))
+
+	return b, channels
+}
+
+// BenchmarkAddToBatch_Broadcast measures the cost of broadcasting a change
+// to all nodes via addToBatch (no worker processing, just queuing).
+func BenchmarkAddToBatch_Broadcast(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, _ := benchBatcher(nodeCount, 10)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			ch := change.DERPMap()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.addToBatch(ch)
+				// Clear pending to avoid unbounded growth
+				batcher.nodes.Range(func(_ types.NodeID, nc *multiChannelNodeConn) bool {
+					nc.drainPending()
+					return true
+				})
+			}
+		})
+	}
+}
+
+// BenchmarkAddToBatch_Targeted measures the cost of adding a targeted change
+// to a single node.
+func BenchmarkAddToBatch_Targeted(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, _ := benchBatcher(nodeCount, 10)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				targetID := types.NodeID(1 + (i % nodeCount)) //nolint:gosec // benchmark
+				ch := change.Change{
+					Reason:     "bench-targeted",
+					TargetNode: targetID,
+					PeerPatches: []*tailcfg.PeerChange{
+						{NodeID: tailcfg.NodeID(targetID)}, //nolint:gosec // benchmark
+					},
+				}
+				batcher.addToBatch(ch)
+				// Clear pending periodically to avoid growth
+				if i%100 == 99 {
+					batcher.nodes.Range(func(_ types.NodeID, nc *multiChannelNodeConn) bool {
+						nc.drainPending()
+						return true
+					})
+				}
+			}
+		})
+	}
+}
+
+// BenchmarkAddToBatch_FullUpdate measures the cost of a FullUpdate broadcast.
+func BenchmarkAddToBatch_FullUpdate(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, _ := benchBatcher(nodeCount, 10)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.addToBatch(change.FullUpdate())
+			}
+		})
+	}
+}
+
+// BenchmarkProcessBatchedChanges measures the cost of moving pending changes
+// to the work queue.
+func BenchmarkProcessBatchedChanges(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dpending", nodeCount), func(b *testing.B) {
+			batcher, _ := benchBatcher(nodeCount, 10)
+			// Use a very large work channel to avoid blocking
+			batcher.workCh = make(chan work, nodeCount*b.N+1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for range b.N {
+				b.StopTimer()
+				// Seed pending changes
+				for i := 1; i <= nodeCount; i++ {
+					if nc, ok := batcher.nodes.Load(types.NodeID(i)); ok { //nolint:gosec // benchmark
+						nc.appendPending(change.DERPMap())
+					}
+				}
+
+				b.StartTimer()
+
+				batcher.processBatchedChanges()
+			}
+		})
+	}
+}
+
+// BenchmarkBroadcastToN measures end-to-end broadcast: addToBatch + processBatchedChanges
+// to N nodes. Does NOT include worker processing (MapResponse generation).
+func BenchmarkBroadcastToN(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, _ := benchBatcher(nodeCount, 10)
+			batcher.workCh = make(chan work, nodeCount*b.N+1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			ch := change.DERPMap()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.addToBatch(ch)
+				batcher.processBatchedChanges()
+			}
+		})
+	}
+}
+
+// BenchmarkMultiChannelBroadcast measures the cost of sending a MapResponse
+// to N nodes each with varying connection counts.
+func BenchmarkMultiChannelBroadcast(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, _ := benchBatcher(nodeCount, b.N+1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			// Add extra connections to every 3rd node
+			for i := 1; i <= nodeCount; i++ {
+				if i%3 == 0 {
+					if mc, ok := batcher.nodes.Load(types.NodeID(i)); ok { //nolint:gosec // benchmark
+						for j := range 2 {
+							ch := make(chan *tailcfg.MapResponse, b.N+1)
+							entry := &connectionEntry{
+								id:      fmt.Sprintf("extra-%d-%d", i, j),
+								c:       ch,
+								version: tailcfg.CapabilityVersion(100),
+								created: time.Now(),
+							}
+							entry.lastUsed.Store(time.Now().Unix())
+							mc.addConnection(entry)
+						}
+					}
+				}
+			}
+
+			data := testMapResponse()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.nodes.Range(func(_ types.NodeID, mc *multiChannelNodeConn) bool {
+					_ = mc.send(data)
+					return true
+				})
+			}
+		})
+	}
+}
+
+// BenchmarkConcurrentAddToBatch measures addToBatch throughput under
+// concurrent access from multiple goroutines.
+func BenchmarkConcurrentAddToBatch(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, _ := benchBatcher(nodeCount, 10)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			// Background goroutine to drain pending periodically
+			drainDone := make(chan struct{})
+
+			go func() {
+				defer close(drainDone)
+
+				for {
+					select {
+					case <-batcher.done:
+						return
+					default:
+						batcher.nodes.Range(func(_ types.NodeID, nc *multiChannelNodeConn) bool {
+							nc.drainPending()
+							return true
+						})
+						time.Sleep(time.Millisecond) //nolint:forbidigo // benchmark drain loop
+					}
+				}
+			}()
+
+			ch := change.DERPMap()
+
+			b.ResetTimer()
+			b.RunParallel(func(pb *testing.PB) {
+				for pb.Next() {
+					batcher.addToBatch(ch)
+				}
+			})
+			b.StopTimer()
+
+			// Cleanup
+			close(batcher.done)
+			<-drainDone
+			// Re-open done so the defer doesn't double-close
+			batcher.done = make(chan struct{})
+		})
+	}
+}
+
+// BenchmarkIsConnected measures the read throughput of IsConnected checks.
+func BenchmarkIsConnected(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, _ := benchBatcher(nodeCount, 1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				id := types.NodeID(1 + (i % nodeCount)) //nolint:gosec // benchmark
+				_ = batcher.IsConnected(id)
+			}
+		})
+	}
+}
+
+// BenchmarkConnectedMap measures the cost of building the full connected map.
+func BenchmarkConnectedMap(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, channels := benchBatcher(nodeCount, 1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			// Disconnect 10% of nodes for a realistic mix
+			for i := 1; i <= nodeCount; i++ {
+				if i%10 == 0 {
+					id := types.NodeID(i) //nolint:gosec // benchmark
+					if mc, ok := batcher.nodes.Load(id); ok {
+						mc.removeConnectionByChannel(channels[id])
+						mc.markDisconnected()
+					}
+				}
+			}
+
+			b.ResetTimer()
+
+			for range b.N {
+				_ = batcher.ConnectedMap()
+			}
+		})
+	}
+}
+
+// BenchmarkConnectionChurn measures the cost of add/remove connection cycling
+// which simulates client reconnection patterns.
+func BenchmarkConnectionChurn(b *testing.B) {
+	for _, nodeCount := range []int{10, 100, 1000} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, channels := benchBatcher(nodeCount, 10)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				id := types.NodeID(1 + (i % nodeCount)) //nolint:gosec // benchmark
+
+				mc, ok := batcher.nodes.Load(id)
+				if !ok {
+					continue
+				}
+
+				// Remove old connection
+				oldCh := channels[id]
+				mc.removeConnectionByChannel(oldCh)
+
+				// Add new connection
+				newCh := make(chan *tailcfg.MapResponse, 10)
+				entry := &connectionEntry{
+					id:      fmt.Sprintf("churn-%d", i),
+					c:       newCh,
+					version: tailcfg.CapabilityVersion(100),
+					created: time.Now(),
+				}
+				entry.lastUsed.Store(time.Now().Unix())
+				mc.addConnection(entry)
+
+				channels[id] = newCh
+			}
+		})
+	}
+}
+
+// BenchmarkConcurrentSendAndChurn measures the combined cost of sends happening
+// concurrently with connection churn - the hot path in production.
+func BenchmarkConcurrentSendAndChurn(b *testing.B) {
+	for _, nodeCount := range []int{10, 100} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			batcher, channels := benchBatcher(nodeCount, 100)
+
+			var mu sync.Mutex // protect channels map
+
+			stopChurn := make(chan struct{})
+			defer close(stopChurn)
+
+			// Background churn on 10% of nodes
+			go func() {
+				i := 0
+
+				for {
+					select {
+					case <-stopChurn:
+						return
+					default:
+						id := types.NodeID(1 + (i % nodeCount)) //nolint:gosec // benchmark
+						if i%10 == 0 {                          // only churn 10%
+							mc, ok := batcher.nodes.Load(id)
+							if ok {
+								mu.Lock()
+								oldCh := channels[id]
+								mu.Unlock()
+								mc.removeConnectionByChannel(oldCh)
+
+								newCh := make(chan *tailcfg.MapResponse, 100)
+								entry := &connectionEntry{
+									id:      fmt.Sprintf("churn-%d", i),
+									c:       newCh,
+									version: tailcfg.CapabilityVersion(100),
+									created: time.Now(),
+								}
+								entry.lastUsed.Store(time.Now().Unix())
+								mc.addConnection(entry)
+								mu.Lock()
+								channels[id] = newCh
+								mu.Unlock()
+							}
+						}
+
+						i++
+					}
+				}
+			}()
+
+			data := testMapResponse()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.nodes.Range(func(_ types.NodeID, mc *multiChannelNodeConn) bool {
+					_ = mc.send(data)
+					return true
+				})
+			}
+		})
+	}
+}
+
+// ============================================================================
+// Full Pipeline Benchmarks (with DB)
+// ============================================================================
+
+// BenchmarkAddNode measures the cost of adding nodes to the batcher,
+// including initial MapResponse generation from a real database.
+func BenchmarkAddNode(b *testing.B) {
+	if testing.Short() {
+		b.Skip("skipping full pipeline benchmark in short mode")
+	}
+
+	for _, nodeCount := range []int{10, 100} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			testData, cleanup := setupBatcherWithTestData(b, NewBatcherAndMapper, 1, nodeCount, largeBufferSize)
+			defer cleanup()
+
+			batcher := testData.Batcher
+			allNodes := testData.Nodes
+
+			// Start consumers
+			for i := range allNodes {
+				allNodes[i].start()
+			}
+
+			defer func() {
+				for i := range allNodes {
+					allNodes[i].cleanup()
+				}
+			}()
+
+			b.ResetTimer()
+
+			for range b.N {
+				// Connect all nodes (measuring AddNode cost)
+				for i := range allNodes {
+					node := &allNodes[i]
+					_ = batcher.AddNode(node.n.ID, node.ch, tailcfg.CapabilityVersion(100), nil)
+				}
+
+				b.StopTimer()
+				// Disconnect for next iteration
+				for i := range allNodes {
+					node := &allNodes[i]
+					batcher.RemoveNode(node.n.ID, node.ch)
+				}
+				// Drain channels
+				for i := range allNodes {
+					for {
+						select {
+						case <-allNodes[i].ch:
+						default:
+							goto drained
+						}
+					}
+
+				drained:
+				}
+
+				b.StartTimer()
+			}
+		})
+	}
+}
+
+// BenchmarkFullPipeline measures the full pipeline cost: addToBatch → processBatchedChanges
+// → worker → generateMapResponse → send, with real nodes from a database.
+func BenchmarkFullPipeline(b *testing.B) {
+	if testing.Short() {
+		b.Skip("skipping full pipeline benchmark in short mode")
+	}
+
+	for _, nodeCount := range []int{10, 100} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			testData, cleanup := setupBatcherWithTestData(b, NewBatcherAndMapper, 1, nodeCount, largeBufferSize)
+			defer cleanup()
+
+			batcher := testData.Batcher
+			allNodes := testData.Nodes
+
+			// Start consumers
+			for i := range allNodes {
+				allNodes[i].start()
+			}
+
+			defer func() {
+				for i := range allNodes {
+					allNodes[i].cleanup()
+				}
+			}()
+
+			// Connect all nodes first
+			for i := range allNodes {
+				node := &allNodes[i]
+
+				err := batcher.AddNode(node.n.ID, node.ch, tailcfg.CapabilityVersion(100), nil)
+				if err != nil {
+					b.Fatalf("failed to add node %d: %v", i, err)
+				}
+			}
+
+			// Wait for initial maps to settle
+			time.Sleep(200 * time.Millisecond) //nolint:forbidigo // benchmark coordination
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.AddWork(change.DERPMap())
+				// Allow workers to process (the batcher tick is what normally
+				// triggers processBatchedChanges, but for benchmarks we need
+				// to give the system time to process)
+				time.Sleep(20 * time.Millisecond) //nolint:forbidigo // benchmark coordination
+			}
+		})
+	}
+}
+
+// BenchmarkMapResponseFromChange measures the cost of synchronous
+// MapResponse generation for individual nodes.
+func BenchmarkMapResponseFromChange(b *testing.B) {
+	if testing.Short() {
+		b.Skip("skipping full pipeline benchmark in short mode")
+	}
+
+	for _, nodeCount := range []int{10, 100} {
+		b.Run(fmt.Sprintf("%dnodes", nodeCount), func(b *testing.B) {
+			testData, cleanup := setupBatcherWithTestData(b, NewBatcherAndMapper, 1, nodeCount, largeBufferSize)
+			defer cleanup()
+
+			batcher := testData.Batcher
+			allNodes := testData.Nodes
+
+			// Start consumers
+			for i := range allNodes {
+				allNodes[i].start()
+			}
+
+			defer func() {
+				for i := range allNodes {
+					allNodes[i].cleanup()
+				}
+			}()
+
+			// Connect all nodes
+			for i := range allNodes {
+				node := &allNodes[i]
+
+				err := batcher.AddNode(node.n.ID, node.ch, tailcfg.CapabilityVersion(100), nil)
+				if err != nil {
+					b.Fatalf("failed to add node %d: %v", i, err)
+				}
+			}
+
+			time.Sleep(200 * time.Millisecond) //nolint:forbidigo // benchmark coordination
+
+			ch := change.DERPMap()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				nodeIdx := i % len(allNodes)
+				_, _ = batcher.MapResponseFromChange(allNodes[nodeIdx].n.ID, ch)
+			}
+		})
+	}
+}

hscontrol/mapper/batcher_lockfree.go

@@ -1,889 +0,0 @@
-package mapper
-
-import (
-	"crypto/rand"
-	"encoding/hex"
-	"errors"
-	"fmt"
-	"sync"
-	"sync/atomic"
-	"time"
-
-	"github.com/juanfont/headscale/hscontrol/types"
-	"github.com/juanfont/headscale/hscontrol/types/change"
-	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
-	"github.com/puzpuzpuz/xsync/v4"
-	"github.com/rs/zerolog"
-	"github.com/rs/zerolog/log"
-	"tailscale.com/tailcfg"
-)
-
-// LockFreeBatcher errors.
-var (
-	errConnectionClosed      = errors.New("connection channel already closed")
-	ErrInitialMapSendTimeout = errors.New("sending initial map: timeout")
-	ErrBatcherShuttingDown   = errors.New("batcher shutting down")
-	ErrConnectionSendTimeout = errors.New("timeout sending to channel (likely stale connection)")
-)
-
-// LockFreeBatcher uses atomic operations and concurrent maps to eliminate mutex contention.
-type LockFreeBatcher struct {
-	tick    *time.Ticker
-	mapper  *mapper
-	workers int
-
-	nodes     *xsync.Map[types.NodeID, *multiChannelNodeConn]
-	connected *xsync.Map[types.NodeID, *time.Time]
-
-	// Work queue channel
-	workCh     chan work
-	workChOnce sync.Once // Ensures workCh is only closed once
-	done       chan struct{}
-	doneOnce   sync.Once // Ensures done is only closed once
-
-	// Batching state
-	pendingChanges *xsync.Map[types.NodeID, []change.Change]
-
-	// Metrics
-	totalNodes      atomic.Int64
-	workQueuedCount atomic.Int64
-	workProcessed   atomic.Int64
-	workErrors      atomic.Int64
-}
-
-// AddNode registers a new node connection with the batcher and sends an initial map response.
-// It creates or updates the node's connection data, validates the initial map generation,
-// and notifies other nodes that this node has come online.
-// The stop function tears down the owning session if this connection is later declared stale.
-func (b *LockFreeBatcher) AddNode(
-	id types.NodeID,
-	c chan<- *tailcfg.MapResponse,
-	version tailcfg.CapabilityVersion,
-	stop func(),
-) error {
-	addNodeStart := time.Now()
-	nlog := log.With().Uint64(zf.NodeID, id.Uint64()).Logger()
-
-	// Generate connection ID
-	connID := generateConnectionID()
-
-	// Create new connection entry
-	now := time.Now()
-	newEntry := &connectionEntry{
-		id:      connID,
-		c:       c,
-		version: version,
-		created: now,
-		stop:    stop,
-	}
-	// Initialize last used timestamp
-	newEntry.lastUsed.Store(now.Unix())
-
-	// Get or create multiChannelNodeConn - this reuses existing offline nodes for rapid reconnection
-	nodeConn, loaded := b.nodes.LoadOrStore(id, newMultiChannelNodeConn(id, b.mapper))
-
-	if !loaded {
-		b.totalNodes.Add(1)
-	}
-
-	// Add connection to the list (lock-free)
-	nodeConn.addConnection(newEntry)
-
-	// Use the worker pool for controlled concurrency instead of direct generation
-	initialMap, err := b.MapResponseFromChange(id, change.FullSelf(id))
-	if err != nil {
-		nlog.Error().Err(err).Msg("initial map generation failed")
-		nodeConn.removeConnectionByChannel(c)
-
-		return fmt.Errorf("generating initial map for node %d: %w", id, err)
-	}
-
-	// Use a blocking send with timeout for initial map since the channel should be ready
-	// and we want to avoid the race condition where the receiver isn't ready yet
-	select {
-	case c <- initialMap:
-		// Success
-	case <-time.After(5 * time.Second): //nolint:mnd
-		nlog.Error().Err(ErrInitialMapSendTimeout).Msg("initial map send timeout")
-		nlog.Debug().Caller().Dur("timeout.duration", 5*time.Second). //nolint:mnd
-										Msg("initial map send timed out because channel was blocked or receiver not ready")
-		nodeConn.removeConnectionByChannel(c)
-
-		return fmt.Errorf("%w for node %d", ErrInitialMapSendTimeout, id)
-	}
-
-	// Update connection status
-	b.connected.Store(id, nil) // nil = connected
-
-	// Node will automatically receive updates through the normal flow
-	// The initial full map already contains all current state
-
-	nlog.Debug().Caller().Dur(zf.TotalDuration, time.Since(addNodeStart)).
-		Int("active.connections", nodeConn.getActiveConnectionCount()).
-		Msg("node connection established in batcher")
-
-	return nil
-}
-
-// RemoveNode disconnects a node from the batcher, marking it as offline and cleaning up its state.
-// It validates the connection channel matches one of the current connections, closes that specific connection,
-// and keeps the node entry alive for rapid reconnections instead of aggressive deletion.
-// Reports if the node still has active connections after removal.
-func (b *LockFreeBatcher) RemoveNode(id types.NodeID, c chan<- *tailcfg.MapResponse) bool {
-	nlog := log.With().Uint64(zf.NodeID, id.Uint64()).Logger()
-
-	nodeConn, exists := b.nodes.Load(id)
-	if !exists {
-		nlog.Debug().Caller().Msg("removeNode called for non-existent node")
-		return false
-	}
-
-	// Remove specific connection
-	removed := nodeConn.removeConnectionByChannel(c)
-	if !removed {
-		nlog.Debug().Caller().Msg("removeNode: channel not found, connection already removed or invalid")
-	}
-
-	// Check if node has any remaining active connections
-	if nodeConn.hasActiveConnections() {
-		nlog.Debug().Caller().
-			Int("active.connections", nodeConn.getActiveConnectionCount()).
-			Msg("node connection removed but keeping online, other connections remain")
-
-		return true // Node still has active connections
-	}
-
-	// No active connections - keep the node entry alive for rapid reconnections
-	// The node will get a fresh full map when it reconnects
-	nlog.Debug().Caller().Msg("node disconnected from batcher, keeping entry for rapid reconnection")
-	b.connected.Store(id, new(time.Now()))
-
-	return false
-}
-
-// AddWork queues a change to be processed by the batcher.
-func (b *LockFreeBatcher) AddWork(r ...change.Change) {
-	b.addWork(r...)
-}
-
-func (b *LockFreeBatcher) Start() {
-	b.done = make(chan struct{})
-	go b.doWork()
-}
-
-func (b *LockFreeBatcher) Close() {
-	// Signal shutdown to all goroutines, only once
-	b.doneOnce.Do(func() {
-		if b.done != nil {
-			close(b.done)
-		}
-	})
-
-	// Only close workCh once using sync.Once to prevent races
-	b.workChOnce.Do(func() {
-		close(b.workCh)
-	})
-
-	// Close the underlying channels supplying the data to the clients.
-	b.nodes.Range(func(nodeID types.NodeID, conn *multiChannelNodeConn) bool {
-		conn.close()
-		return true
-	})
-}
-
-func (b *LockFreeBatcher) doWork() {
-	for i := range b.workers {
-		go b.worker(i + 1)
-	}
-
-	// Create a cleanup ticker for removing truly disconnected nodes
-	cleanupTicker := time.NewTicker(5 * time.Minute)
-	defer cleanupTicker.Stop()
-
-	for {
-		select {
-		case <-b.tick.C:
-			// Process batched changes
-			b.processBatchedChanges()
-		case <-cleanupTicker.C:
-			// Clean up nodes that have been offline for too long
-			b.cleanupOfflineNodes()
-		case <-b.done:
-			log.Info().Msg("batcher done channel closed, stopping to feed workers")
-			return
-		}
-	}
-}
-
-func (b *LockFreeBatcher) worker(workerID int) {
-	wlog := log.With().Int(zf.WorkerID, workerID).Logger()
-
-	for {
-		select {
-		case w, ok := <-b.workCh:
-			if !ok {
-				wlog.Debug().Msg("worker channel closing, shutting down")
-				return
-			}
-
-			b.workProcessed.Add(1)
-
-			// If the resultCh is set, it means that this is a work request
-			// where there is a blocking function waiting for the map that
-			// is being generated.
-			// This is used for synchronous map generation.
-			if w.resultCh != nil {
-				var result workResult
-
-				if nc, exists := b.nodes.Load(w.nodeID); exists {
-					var err error
-
-					result.mapResponse, err = generateMapResponse(nc, b.mapper, w.c)
-
-					result.err = err
-					if result.err != nil {
-						b.workErrors.Add(1)
-						wlog.Error().Err(result.err).
-							Uint64(zf.NodeID, w.nodeID.Uint64()).
-							Str(zf.Reason, w.c.Reason).
-							Msg("failed to generate map response for synchronous work")
-					} else if result.mapResponse != nil {
-						// Update peer tracking for synchronous responses too
-						nc.updateSentPeers(result.mapResponse)
-					}
-				} else {
-					result.err = fmt.Errorf("%w: %d", ErrNodeNotFoundMapper, w.nodeID)
-
-					b.workErrors.Add(1)
-					wlog.Error().Err(result.err).
-						Uint64(zf.NodeID, w.nodeID.Uint64()).
-						Msg("node not found for synchronous work")
-				}
-
-				// Send result
-				select {
-				case w.resultCh <- result:
-				case <-b.done:
-					return
-				}
-
-				continue
-			}
-
-			// If resultCh is nil, this is an asynchronous work request
-			// that should be processed and sent to the node instead of
-			// returned to the caller.
-			if nc, exists := b.nodes.Load(w.nodeID); exists {
-				// Apply change to node - this will handle offline nodes gracefully
-				// and queue work for when they reconnect
-				err := nc.change(w.c)
-				if err != nil {
-					b.workErrors.Add(1)
-					wlog.Error().Err(err).
-						Uint64(zf.NodeID, w.nodeID.Uint64()).
-						Str(zf.Reason, w.c.Reason).
-						Msg("failed to apply change")
-				}
-			}
-		case <-b.done:
-			wlog.Debug().Msg("batcher shutting down, exiting worker")
-			return
-		}
-	}
-}
-
-func (b *LockFreeBatcher) addWork(r ...change.Change) {
-	b.addToBatch(r...)
-}
-
-// queueWork safely queues work.
-func (b *LockFreeBatcher) queueWork(w work) {
-	b.workQueuedCount.Add(1)
-
-	select {
-	case b.workCh <- w:
-		// Successfully queued
-	case <-b.done:
-		// Batcher is shutting down
-		return
-	}
-}
-
-// addToBatch adds changes to the pending batch.
-func (b *LockFreeBatcher) addToBatch(changes ...change.Change) {
-	// Clean up any nodes being permanently removed from the system.
-	//
-	// This handles the case where a node is deleted from state but the batcher
-	// still has it registered. By cleaning up here, we prevent "node not found"
-	// errors when workers try to generate map responses for deleted nodes.
-	//
-	// Safety: change.Change.PeersRemoved is ONLY populated when nodes are actually
-	// deleted from the system (via change.NodeRemoved in state.DeleteNode). Policy
-	// changes that affect peer visibility do NOT use this field - they set
-	// RequiresRuntimePeerComputation=true and compute removed peers at runtime,
-	// putting them in tailcfg.MapResponse.PeersRemoved (a different struct).
-	// Therefore, this cleanup only removes nodes that are truly being deleted,
-	// not nodes that are still connected but have lost visibility of certain peers.
-	//
-	// See: https://github.com/juanfont/headscale/issues/2924
-	for _, ch := range changes {
-		for _, removedID := range ch.PeersRemoved {
-			if _, existed := b.nodes.LoadAndDelete(removedID); existed {
-				b.totalNodes.Add(-1)
-				log.Debug().
-					Uint64(zf.NodeID, removedID.Uint64()).
-					Msg("removed deleted node from batcher")
-			}
-
-			b.connected.Delete(removedID)
-			b.pendingChanges.Delete(removedID)
-		}
-	}
-
-	// Short circuit if any of the changes is a full update, which
-	// means we can skip sending individual changes.
-	if change.HasFull(changes) {
-		b.nodes.Range(func(nodeID types.NodeID, _ *multiChannelNodeConn) bool {
-			b.pendingChanges.Store(nodeID, []change.Change{change.FullUpdate()})
-
-			return true
-		})
-
-		return
-	}
-
-	broadcast, targeted := change.SplitTargetedAndBroadcast(changes)
-
-	// Handle targeted changes - send only to the specific node
-	for _, ch := range targeted {
-		pending, _ := b.pendingChanges.LoadOrStore(ch.TargetNode, []change.Change{})
-		pending = append(pending, ch)
-		b.pendingChanges.Store(ch.TargetNode, pending)
-	}
-
-	// Handle broadcast changes - send to all nodes, filtering as needed
-	if len(broadcast) > 0 {
-		b.nodes.Range(func(nodeID types.NodeID, _ *multiChannelNodeConn) bool {
-			filtered := change.FilterForNode(nodeID, broadcast)
-
-			if len(filtered) > 0 {
-				pending, _ := b.pendingChanges.LoadOrStore(nodeID, []change.Change{})
-				pending = append(pending, filtered...)
-				b.pendingChanges.Store(nodeID, pending)
-			}
-
-			return true
-		})
-	}
-}
-
-// processBatchedChanges processes all pending batched changes.
-func (b *LockFreeBatcher) processBatchedChanges() {
-	if b.pendingChanges == nil {
-		return
-	}
-
-	// Process all pending changes
-	b.pendingChanges.Range(func(nodeID types.NodeID, pending []change.Change) bool {
-		if len(pending) == 0 {
-			return true
-		}
-
-		// Send all batched changes for this node
-		for _, ch := range pending {
-			b.queueWork(work{c: ch, nodeID: nodeID, resultCh: nil})
-		}
-
-		// Clear the pending changes for this node
-		b.pendingChanges.Delete(nodeID)
-
-		return true
-	})
-}
-
-// cleanupOfflineNodes removes nodes that have been offline for too long to prevent memory leaks.
-// TODO(kradalby): reevaluate if we want to keep this.
-func (b *LockFreeBatcher) cleanupOfflineNodes() {
-	cleanupThreshold := 15 * time.Minute
-	now := time.Now()
-
-	var nodesToCleanup []types.NodeID
-
-	// Find nodes that have been offline for too long
-	b.connected.Range(func(nodeID types.NodeID, disconnectTime *time.Time) bool {
-		if disconnectTime != nil && now.Sub(*disconnectTime) > cleanupThreshold {
-			// Double-check the node doesn't have active connections
-			if nodeConn, exists := b.nodes.Load(nodeID); exists {
-				if !nodeConn.hasActiveConnections() {
-					nodesToCleanup = append(nodesToCleanup, nodeID)
-				}
-			}
-		}
-
-		return true
-	})
-
-	// Clean up the identified nodes
-	for _, nodeID := range nodesToCleanup {
-		log.Info().Uint64(zf.NodeID, nodeID.Uint64()).
-			Dur("offline_duration", cleanupThreshold).
-			Msg("cleaning up node that has been offline for too long")
-
-		b.nodes.Delete(nodeID)
-		b.connected.Delete(nodeID)
-		b.totalNodes.Add(-1)
-	}
-
-	if len(nodesToCleanup) > 0 {
-		log.Info().Int(zf.CleanedNodes, len(nodesToCleanup)).
-			Msg("completed cleanup of long-offline nodes")
-	}
-}
-
-// IsConnected is lock-free read that checks if a node has any active connections.
-func (b *LockFreeBatcher) IsConnected(id types.NodeID) bool {
-	// First check if we have active connections for this node
-	if nodeConn, exists := b.nodes.Load(id); exists {
-		if nodeConn.hasActiveConnections() {
-			return true
-		}
-	}
-
-	// Check disconnected timestamp with grace period
-	val, ok := b.connected.Load(id)
-	if !ok {
-		return false
-	}
-
-	// nil means connected
-	if val == nil {
-		return true
-	}
-
-	return false
-}
-
-// ConnectedMap returns a lock-free map of all connected nodes.
-func (b *LockFreeBatcher) ConnectedMap() *xsync.Map[types.NodeID, bool] {
-	ret := xsync.NewMap[types.NodeID, bool]()
-
-	// First, add all nodes with active connections
-	b.nodes.Range(func(id types.NodeID, nodeConn *multiChannelNodeConn) bool {
-		if nodeConn.hasActiveConnections() {
-			ret.Store(id, true)
-		}
-
-		return true
-	})
-
-	// Then add all entries from the connected map
-	b.connected.Range(func(id types.NodeID, val *time.Time) bool {
-		// Only add if not already added as connected above
-		if _, exists := ret.Load(id); !exists {
-			if val == nil {
-				// nil means connected
-				ret.Store(id, true)
-			} else {
-				// timestamp means disconnected
-				ret.Store(id, false)
-			}
-		}
-
-		return true
-	})
-
-	return ret
-}
-
-// MapResponseFromChange queues work to generate a map response and waits for the result.
-// This allows synchronous map generation using the same worker pool.
-func (b *LockFreeBatcher) MapResponseFromChange(id types.NodeID, ch change.Change) (*tailcfg.MapResponse, error) {
-	resultCh := make(chan workResult, 1)
-
-	// Queue the work with a result channel using the safe queueing method
-	b.queueWork(work{c: ch, nodeID: id, resultCh: resultCh})
-
-	// Wait for the result
-	select {
-	case result := <-resultCh:
-		return result.mapResponse, result.err
-	case <-b.done:
-		return nil, fmt.Errorf("%w while generating map response for node %d", ErrBatcherShuttingDown, id)
-	}
-}
-
-// connectionEntry represents a single connection to a node.
-type connectionEntry struct {
-	id       string // unique connection ID
-	c        chan<- *tailcfg.MapResponse
-	version  tailcfg.CapabilityVersion
-	created  time.Time
-	stop     func()
-	lastUsed atomic.Int64 // Unix timestamp of last successful send
-	closed   atomic.Bool  // Indicates if this connection has been closed
-}
-
-// multiChannelNodeConn manages multiple concurrent connections for a single node.
-type multiChannelNodeConn struct {
-	id     types.NodeID
-	mapper *mapper
-	log    zerolog.Logger
-
-	mutex       sync.RWMutex
-	connections []*connectionEntry
-
-	updateCount atomic.Int64
-
-	// lastSentPeers tracks which peers were last sent to this node.
-	// This enables computing diffs for policy changes instead of sending
-	// full peer lists (which clients interpret as "no change" when empty).
-	// Using xsync.Map for lock-free concurrent access.
-	lastSentPeers *xsync.Map[tailcfg.NodeID, struct{}]
-}
-
-// generateConnectionID generates a unique connection identifier.
-func generateConnectionID() string {
-	bytes := make([]byte, 8)
-	_, _ = rand.Read(bytes)
-
-	return hex.EncodeToString(bytes)
-}
-
-// newMultiChannelNodeConn creates a new multi-channel node connection.
-func newMultiChannelNodeConn(id types.NodeID, mapper *mapper) *multiChannelNodeConn {
-	return &multiChannelNodeConn{
-		id:            id,
-		mapper:        mapper,
-		lastSentPeers: xsync.NewMap[tailcfg.NodeID, struct{}](),
-		log:           log.With().Uint64(zf.NodeID, id.Uint64()).Logger(),
-	}
-}
-
-func (mc *multiChannelNodeConn) close() {
-	mc.mutex.Lock()
-	defer mc.mutex.Unlock()
-
-	for _, conn := range mc.connections {
-		mc.stopConnection(conn)
-	}
-}
-
-// stopConnection marks a connection as closed and tears down the owning session
-// at most once, even if multiple cleanup paths race to remove it.
-func (mc *multiChannelNodeConn) stopConnection(conn *connectionEntry) {
-	if conn.closed.CompareAndSwap(false, true) {
-		if conn.stop != nil {
-			conn.stop()
-		}
-	}
-}
-
-// removeConnectionAtIndexLocked removes the active connection at index.
-// If stopConnection is true, it also stops that session.
-// Caller must hold mc.mutex.
-func (mc *multiChannelNodeConn) removeConnectionAtIndexLocked(i int, stopConnection bool) *connectionEntry {
-	conn := mc.connections[i]
-	mc.connections = append(mc.connections[:i], mc.connections[i+1:]...)
-
-	if stopConnection {
-		mc.stopConnection(conn)
-	}
-
-	return conn
-}
-
-// addConnection adds a new connection.
-func (mc *multiChannelNodeConn) addConnection(entry *connectionEntry) {
-	mutexWaitStart := time.Now()
-
-	mc.log.Debug().Caller().Str(zf.Chan, fmt.Sprintf("%p", entry.c)).Str(zf.ConnID, entry.id).
-		Msg("addConnection: waiting for mutex - POTENTIAL CONTENTION POINT")
-
-	mc.mutex.Lock()
-
-	mutexWaitDur := time.Since(mutexWaitStart)
-
-	defer mc.mutex.Unlock()
-
-	mc.connections = append(mc.connections, entry)
-	mc.log.Debug().Caller().Str(zf.Chan, fmt.Sprintf("%p", entry.c)).Str(zf.ConnID, entry.id).
-		Int("total_connections", len(mc.connections)).
-		Dur("mutex_wait_time", mutexWaitDur).
-		Msg("successfully added connection after mutex wait")
-}
-
-// removeConnectionByChannel removes a connection by matching channel pointer.
-func (mc *multiChannelNodeConn) removeConnectionByChannel(c chan<- *tailcfg.MapResponse) bool {
-	mc.mutex.Lock()
-	defer mc.mutex.Unlock()
-
-	for i, entry := range mc.connections {
-		if entry.c == c {
-			mc.removeConnectionAtIndexLocked(i, false)
-			mc.log.Debug().Caller().Str(zf.Chan, fmt.Sprintf("%p", c)).
-				Int("remaining_connections", len(mc.connections)).
-				Msg("successfully removed connection")
-
-			return true
-		}
-	}
-
-	return false
-}
-
-// hasActiveConnections checks if the node has any active connections.
-func (mc *multiChannelNodeConn) hasActiveConnections() bool {
-	mc.mutex.RLock()
-	defer mc.mutex.RUnlock()
-
-	return len(mc.connections) > 0
-}
-
-// getActiveConnectionCount returns the number of active connections.
-func (mc *multiChannelNodeConn) getActiveConnectionCount() int {
-	mc.mutex.RLock()
-	defer mc.mutex.RUnlock()
-
-	return len(mc.connections)
-}
-
-// send broadcasts data to all active connections for the node.
-func (mc *multiChannelNodeConn) send(data *tailcfg.MapResponse) error {
-	if data == nil {
-		return nil
-	}
-
-	mc.mutex.Lock()
-	defer mc.mutex.Unlock()
-
-	if len(mc.connections) == 0 {
-		// During rapid reconnection, nodes may temporarily have no active connections
-		// This is not an error - the node will receive a full map when it reconnects
-		mc.log.Debug().Caller().
-			Msg("send: skipping send to node with no active connections (likely rapid reconnection)")
-
-		return nil // Return success instead of error
-	}
-
-	mc.log.Debug().Caller().
-		Int("total_connections", len(mc.connections)).
-		Msg("send: broadcasting to all connections")
-
-	var lastErr error
-
-	successCount := 0
-
-	var failedConnections []int // Track failed connections for removal
-
-	// Send to all connections
-	for i, conn := range mc.connections {
-		mc.log.Debug().Caller().Str(zf.Chan, fmt.Sprintf("%p", conn.c)).
-			Str(zf.ConnID, conn.id).Int(zf.ConnectionIndex, i).
-			Msg("send: attempting to send to connection")
-
-		err := conn.send(data)
-		if err != nil {
-			lastErr = err
-
-			failedConnections = append(failedConnections, i)
-			mc.log.Warn().Err(err).Str(zf.Chan, fmt.Sprintf("%p", conn.c)).
-				Str(zf.ConnID, conn.id).Int(zf.ConnectionIndex, i).
-				Msg("send: connection send failed")
-		} else {
-			successCount++
-
-			mc.log.Debug().Caller().Str(zf.Chan, fmt.Sprintf("%p", conn.c)).
-				Str(zf.ConnID, conn.id).Int(zf.ConnectionIndex, i).
-				Msg("send: successfully sent to connection")
-		}
-	}
-
-	// Remove failed connections (in reverse order to maintain indices)
-	for i := len(failedConnections) - 1; i >= 0; i-- {
-		idx := failedConnections[i]
-		entry := mc.removeConnectionAtIndexLocked(idx, true)
-		mc.log.Debug().Caller().
-			Str(zf.ConnID, entry.id).
-			Msg("send: removed failed connection")
-	}
-
-	mc.updateCount.Add(1)
-
-	mc.log.Debug().
-		Int("successful_sends", successCount).
-		Int("failed_connections", len(failedConnections)).
-		Int("remaining_connections", len(mc.connections)).
-		Msg("send: completed broadcast")
-
-	// Success if at least one send succeeded
-	if successCount > 0 {
-		return nil
-	}
-
-	return fmt.Errorf("node %d: all connections failed, last error: %w", mc.id, lastErr)
-}
-
-// send sends data to a single connection entry with timeout-based stale connection detection.
-func (entry *connectionEntry) send(data *tailcfg.MapResponse) error {
-	if data == nil {
-		return nil
-	}
-
-	// Check if the connection has been closed to prevent send on closed channel panic.
-	// This can happen during shutdown when Close() is called while workers are still processing.
-	if entry.closed.Load() {
-		return fmt.Errorf("connection %s: %w", entry.id, errConnectionClosed)
-	}
-
-	// Use a short timeout to detect stale connections where the client isn't reading the channel.
-	// This is critical for detecting Docker containers that are forcefully terminated
-	// but still have channels that appear open.
-	select {
-	case entry.c <- data:
-		// Update last used timestamp on successful send
-		entry.lastUsed.Store(time.Now().Unix())
-		return nil
-	case <-time.After(50 * time.Millisecond):
-		// Connection is likely stale - client isn't reading from channel
-		// This catches the case where Docker containers are killed but channels remain open
-		return fmt.Errorf("connection %s: %w", entry.id, ErrConnectionSendTimeout)
-	}
-}
-
-// nodeID returns the node ID.
-func (mc *multiChannelNodeConn) nodeID() types.NodeID {
-	return mc.id
-}
-
-// version returns the capability version from the first active connection.
-// All connections for a node should have the same version in practice.
-func (mc *multiChannelNodeConn) version() tailcfg.CapabilityVersion {
-	mc.mutex.RLock()
-	defer mc.mutex.RUnlock()
-
-	if len(mc.connections) == 0 {
-		return 0
-	}
-
-	return mc.connections[0].version
-}
-
-// updateSentPeers updates the tracked peer state based on a sent MapResponse.
-// This must be called after successfully sending a response to keep track of
-// what the client knows about, enabling accurate diffs for future updates.
-func (mc *multiChannelNodeConn) updateSentPeers(resp *tailcfg.MapResponse) {
-	if resp == nil {
-		return
-	}
-
-	// Full peer list replaces tracked state entirely
-	if resp.Peers != nil {
-		mc.lastSentPeers.Clear()
-
-		for _, peer := range resp.Peers {
-			mc.lastSentPeers.Store(peer.ID, struct{}{})
-		}
-	}
-
-	// Incremental additions
-	for _, peer := range resp.PeersChanged {
-		mc.lastSentPeers.Store(peer.ID, struct{}{})
-	}
-
-	// Incremental removals
-	for _, id := range resp.PeersRemoved {
-		mc.lastSentPeers.Delete(id)
-	}
-}
-
-// computePeerDiff compares the current peer list against what was last sent
-// and returns the peers that were removed (in lastSentPeers but not in current).
-func (mc *multiChannelNodeConn) computePeerDiff(currentPeers []tailcfg.NodeID) []tailcfg.NodeID {
-	currentSet := make(map[tailcfg.NodeID]struct{}, len(currentPeers))
-	for _, id := range currentPeers {
-		currentSet[id] = struct{}{}
-	}
-
-	var removed []tailcfg.NodeID
-
-	// Find removed: in lastSentPeers but not in current
-	mc.lastSentPeers.Range(func(id tailcfg.NodeID, _ struct{}) bool {
-		if _, exists := currentSet[id]; !exists {
-			removed = append(removed, id)
-		}
-
-		return true
-	})
-
-	return removed
-}
-
-// change applies a change to all active connections for the node.
-func (mc *multiChannelNodeConn) change(r change.Change) error {
-	return handleNodeChange(mc, mc.mapper, r)
-}
-
-// DebugNodeInfo contains debug information about a node's connections.
-type DebugNodeInfo struct {
-	Connected         bool `json:"connected"`
-	ActiveConnections int  `json:"active_connections"`
-}
-
-// Debug returns a pre-baked map of node debug information for the debug interface.
-func (b *LockFreeBatcher) Debug() map[types.NodeID]DebugNodeInfo {
-	result := make(map[types.NodeID]DebugNodeInfo)
-
-	// Get all nodes with their connection status using immediate connection logic
-	// (no grace period) for debug purposes
-	b.nodes.Range(func(id types.NodeID, nodeConn *multiChannelNodeConn) bool {
-		nodeConn.mutex.RLock()
-		activeConnCount := len(nodeConn.connections)
-		nodeConn.mutex.RUnlock()
-
-		// Use immediate connection status: if active connections exist, node is connected
-		// If not, check the connected map for nil (connected) vs timestamp (disconnected)
-		connected := false
-		if activeConnCount > 0 {
-			connected = true
-		} else {
-			// Check connected map for immediate status
-			if val, ok := b.connected.Load(id); ok && val == nil {
-				connected = true
-			}
-		}
-
-		result[id] = DebugNodeInfo{
-			Connected:         connected,
-			ActiveConnections: activeConnCount,
-		}
-
-		return true
-	})
-
-	// Add all entries from the connected map to capture both connected and disconnected nodes
-	b.connected.Range(func(id types.NodeID, val *time.Time) bool {
-		// Only add if not already processed above
-		if _, exists := result[id]; !exists {
-			// Use immediate connection status for debug (no grace period)
-			connected := (val == nil) // nil means connected, timestamp means disconnected
-			result[id] = DebugNodeInfo{
-				Connected:         connected,
-				ActiveConnections: 0,
-			}
-		}
-
-		return true
-	})
-
-	return result
-}
-
-func (b *LockFreeBatcher) DebugMapResponses() (map[types.NodeID][]tailcfg.MapResponse, error) {
-	return b.mapper.debugMapResponses()
-}
-
-// WorkErrors returns the count of work errors encountered.
-// This is primarily useful for testing and debugging.
-func (b *LockFreeBatcher) WorkErrors() int64 {
-	return b.workErrors.Load()
-}

hscontrol/mapper/batcher_scale_bench_test.go

@@ -0,0 +1,887 @@
+package mapper
+
+// Scale benchmarks for the batcher system.
+//
+// These benchmarks systematically increase node counts to find scaling limits
+// and identify bottlenecks. Organized into tiers:
+//
+// Tier 1 - O(1) operations: should stay flat regardless of node count
+// Tier 2 - O(N) lightweight: batch queuing and processing (no MapResponse generation)
+// Tier 3 - O(N) heavier: map building, peer diff, peer tracking
+// Tier 4 - Concurrent contention: multi-goroutine access under load
+//
+// Node count progression: 100, 500, 1000, 2000, 5000, 10000, 20000, 50000
+
+import (
+	"fmt"
+	"strconv"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/juanfont/headscale/hscontrol/types/change"
+	"tailscale.com/tailcfg"
+)
+
+// scaleCounts defines the node counts used across all scaling benchmarks.
+// Tier 1 (O(1)) tests up to 50k; Tier 2-4 test up to 10k-20k.
+var (
+	scaleCountsO1     = []int{100, 500, 1000, 2000, 5000, 10000, 20000, 50000}
+	scaleCountsLinear = []int{100, 500, 1000, 2000, 5000, 10000}
+	scaleCountsHeavy  = []int{100, 500, 1000, 2000, 5000, 10000}
+	scaleCountsConc   = []int{100, 500, 1000, 2000, 5000}
+)
+
+// ============================================================================
+// Tier 1: O(1) Operations — should scale flat
+// ============================================================================
+
+// BenchmarkScale_IsConnected tests single-node lookup at increasing map sizes.
+func BenchmarkScale_IsConnected(b *testing.B) {
+	for _, n := range scaleCountsO1 {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, _ := benchBatcher(n, 1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				id := types.NodeID(1 + (i % n)) //nolint:gosec
+				_ = batcher.IsConnected(id)
+			}
+		})
+	}
+}
+
+// BenchmarkScale_AddToBatch_Targeted tests single-node targeted change at
+// increasing map sizes. The map size should not affect per-operation cost.
+func BenchmarkScale_AddToBatch_Targeted(b *testing.B) {
+	for _, n := range scaleCountsO1 {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, _ := benchBatcher(n, 10)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				targetID := types.NodeID(1 + (i % n)) //nolint:gosec
+				ch := change.Change{
+					Reason:     "scale-targeted",
+					TargetNode: targetID,
+					PeerPatches: []*tailcfg.PeerChange{
+						{NodeID: tailcfg.NodeID(targetID)}, //nolint:gosec
+					},
+				}
+				batcher.addToBatch(ch)
+				// Drain every 100 ops to avoid unbounded growth
+				if i%100 == 99 {
+					batcher.nodes.Range(func(_ types.NodeID, nc *multiChannelNodeConn) bool {
+						nc.drainPending()
+						return true
+					})
+				}
+			}
+		})
+	}
+}
+
+// BenchmarkScale_ConnectionChurn tests add/remove connection cycle.
+// The map size should not affect per-operation cost for a single node.
+func BenchmarkScale_ConnectionChurn(b *testing.B) {
+	for _, n := range scaleCountsO1 {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, channels := benchBatcher(n, 10)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				id := types.NodeID(1 + (i % n)) //nolint:gosec
+
+				mc, ok := batcher.nodes.Load(id)
+				if !ok {
+					continue
+				}
+
+				oldCh := channels[id]
+				mc.removeConnectionByChannel(oldCh)
+
+				newCh := make(chan *tailcfg.MapResponse, 10)
+				entry := &connectionEntry{
+					id:      fmt.Sprintf("sc-%d", i),
+					c:       newCh,
+					version: tailcfg.CapabilityVersion(100),
+					created: time.Now(),
+				}
+				entry.lastUsed.Store(time.Now().Unix())
+				mc.addConnection(entry)
+
+				channels[id] = newCh
+			}
+		})
+	}
+}
+
+// ============================================================================
+// Tier 2: O(N) Lightweight — batch mechanics without MapResponse generation
+// ============================================================================
+
+// BenchmarkScale_AddToBatch_Broadcast tests broadcasting a change to ALL nodes.
+// Cost should scale linearly with node count.
+func BenchmarkScale_AddToBatch_Broadcast(b *testing.B) {
+	for _, n := range scaleCountsLinear {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, _ := benchBatcher(n, 10)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			ch := change.DERPMap()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.addToBatch(ch)
+				// Drain to avoid unbounded growth
+				batcher.nodes.Range(func(_ types.NodeID, nc *multiChannelNodeConn) bool {
+					nc.drainPending()
+					return true
+				})
+			}
+		})
+	}
+}
+
+// BenchmarkScale_AddToBatch_FullUpdate tests FullUpdate broadcast cost.
+func BenchmarkScale_AddToBatch_FullUpdate(b *testing.B) {
+	for _, n := range scaleCountsLinear {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, _ := benchBatcher(n, 10)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.addToBatch(change.FullUpdate())
+			}
+		})
+	}
+}
+
+// BenchmarkScale_ProcessBatchedChanges tests draining pending changes into work queue.
+func BenchmarkScale_ProcessBatchedChanges(b *testing.B) {
+	for _, n := range scaleCountsLinear {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, _ := benchBatcher(n, 10)
+			batcher.workCh = make(chan work, n*b.N+1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			b.ResetTimer()
+
+			for range b.N {
+				b.StopTimer()
+
+				for i := 1; i <= n; i++ {
+					if nc, ok := batcher.nodes.Load(types.NodeID(i)); ok { //nolint:gosec
+						nc.appendPending(change.DERPMap())
+					}
+				}
+
+				b.StartTimer()
+				batcher.processBatchedChanges()
+			}
+		})
+	}
+}
+
+// BenchmarkScale_BroadcastToN tests end-to-end: addToBatch + processBatchedChanges.
+func BenchmarkScale_BroadcastToN(b *testing.B) {
+	for _, n := range scaleCountsLinear {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, _ := benchBatcher(n, 10)
+			batcher.workCh = make(chan work, n*b.N+1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			ch := change.DERPMap()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.addToBatch(ch)
+				batcher.processBatchedChanges()
+			}
+		})
+	}
+}
+
+// BenchmarkScale_SendToAll tests raw channel send cost to N nodes (no batching).
+// This isolates the multiChannelNodeConn.send() cost.
+// Uses large buffered channels to avoid goroutine drain overhead.
+func BenchmarkScale_SendToAll(b *testing.B) {
+	for _, n := range scaleCountsLinear {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			// b.N+1 buffer so sends never block
+			batcher, _ := benchBatcher(n, b.N+1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			data := testMapResponse()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.nodes.Range(func(_ types.NodeID, mc *multiChannelNodeConn) bool {
+					_ = mc.send(data)
+					return true
+				})
+			}
+		})
+	}
+}
+
+// ============================================================================
+// Tier 3: O(N) Heavier — map building, peer diff, peer tracking
+// ============================================================================
+
+// BenchmarkScale_ConnectedMap tests building the full connected/disconnected map.
+func BenchmarkScale_ConnectedMap(b *testing.B) {
+	for _, n := range scaleCountsHeavy {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, channels := benchBatcher(n, 1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			// 10% disconnected for realism
+			for i := 1; i <= n; i++ {
+				if i%10 == 0 {
+					id := types.NodeID(i) //nolint:gosec
+					if mc, ok := batcher.nodes.Load(id); ok {
+						mc.removeConnectionByChannel(channels[id])
+						mc.markDisconnected()
+					}
+				}
+			}
+
+			b.ResetTimer()
+
+			for range b.N {
+				_ = batcher.ConnectedMap()
+			}
+		})
+	}
+}
+
+// BenchmarkScale_ComputePeerDiff tests peer diff computation at scale.
+// Each node tracks N-1 peers, with 10% removed.
+func BenchmarkScale_ComputePeerDiff(b *testing.B) {
+	for _, n := range scaleCountsHeavy {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			mc := newMultiChannelNodeConn(1, nil)
+
+			// Track N peers
+			for i := 1; i <= n; i++ {
+				mc.lastSentPeers.Store(tailcfg.NodeID(i), struct{}{})
+			}
+
+			// Current: 90% present (every 10th missing)
+			current := make([]tailcfg.NodeID, 0, n)
+			for i := 1; i <= n; i++ {
+				if i%10 != 0 {
+					current = append(current, tailcfg.NodeID(i))
+				}
+			}
+
+			b.ResetTimer()
+
+			for range b.N {
+				_ = mc.computePeerDiff(current)
+			}
+		})
+	}
+}
+
+// BenchmarkScale_UpdateSentPeers_Full tests full peer list update.
+func BenchmarkScale_UpdateSentPeers_Full(b *testing.B) {
+	for _, n := range scaleCountsHeavy {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			mc := newMultiChannelNodeConn(1, nil)
+
+			peerIDs := make([]tailcfg.NodeID, n)
+			for i := range peerIDs {
+				peerIDs[i] = tailcfg.NodeID(i + 1)
+			}
+
+			resp := testMapResponseWithPeers(peerIDs...)
+
+			b.ResetTimer()
+
+			for range b.N {
+				mc.updateSentPeers(resp)
+			}
+		})
+	}
+}
+
+// BenchmarkScale_UpdateSentPeers_Incremental tests incremental peer updates (10% new).
+func BenchmarkScale_UpdateSentPeers_Incremental(b *testing.B) {
+	for _, n := range scaleCountsHeavy {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			mc := newMultiChannelNodeConn(1, nil)
+
+			// Pre-populate
+			for i := 1; i <= n; i++ {
+				mc.lastSentPeers.Store(tailcfg.NodeID(i), struct{}{})
+			}
+
+			addCount := n / 10
+			if addCount == 0 {
+				addCount = 1
+			}
+
+			resp := testMapResponse()
+
+			resp.PeersChanged = make([]*tailcfg.Node, addCount)
+			for i := range addCount {
+				resp.PeersChanged[i] = &tailcfg.Node{ID: tailcfg.NodeID(n + i + 1)}
+			}
+
+			b.ResetTimer()
+
+			for range b.N {
+				mc.updateSentPeers(resp)
+			}
+		})
+	}
+}
+
+// BenchmarkScale_MultiChannelBroadcast tests sending to N nodes, each with
+// ~1.6 connections on average (every 3rd node has 3 connections).
+// Uses large buffered channels to avoid goroutine drain overhead.
+func BenchmarkScale_MultiChannelBroadcast(b *testing.B) {
+	for _, n := range scaleCountsHeavy {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			// Use b.N+1 buffer so sends never block
+			batcher, _ := benchBatcher(n, b.N+1)
+
+			defer func() {
+				close(batcher.done)
+				batcher.tick.Stop()
+			}()
+
+			// Add extra connections to every 3rd node (also buffered)
+			for i := 1; i <= n; i++ {
+				if i%3 == 0 {
+					if mc, ok := batcher.nodes.Load(types.NodeID(i)); ok { //nolint:gosec
+						for j := range 2 {
+							ch := make(chan *tailcfg.MapResponse, b.N+1)
+							entry := &connectionEntry{
+								id:      fmt.Sprintf("extra-%d-%d", i, j),
+								c:       ch,
+								version: tailcfg.CapabilityVersion(100),
+								created: time.Now(),
+							}
+							entry.lastUsed.Store(time.Now().Unix())
+							mc.addConnection(entry)
+						}
+					}
+				}
+			}
+
+			data := testMapResponse()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.nodes.Range(func(_ types.NodeID, mc *multiChannelNodeConn) bool {
+					_ = mc.send(data)
+					return true
+				})
+			}
+		})
+	}
+}
+
+// ============================================================================
+// Tier 4: Concurrent Contention — multi-goroutine access
+// ============================================================================
+
+// BenchmarkScale_ConcurrentAddToBatch tests parallel addToBatch throughput.
+func BenchmarkScale_ConcurrentAddToBatch(b *testing.B) {
+	for _, n := range scaleCountsConc {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, _ := benchBatcher(n, 10)
+
+			drainDone := make(chan struct{})
+
+			go func() {
+				defer close(drainDone)
+
+				for {
+					select {
+					case <-batcher.done:
+						return
+					default:
+						batcher.nodes.Range(func(_ types.NodeID, nc *multiChannelNodeConn) bool {
+							nc.drainPending()
+							return true
+						})
+						time.Sleep(time.Millisecond) //nolint:forbidigo
+					}
+				}
+			}()
+
+			ch := change.DERPMap()
+
+			b.ResetTimer()
+			b.RunParallel(func(pb *testing.PB) {
+				for pb.Next() {
+					batcher.addToBatch(ch)
+				}
+			})
+			b.StopTimer()
+
+			close(batcher.done)
+			<-drainDone
+
+			batcher.done = make(chan struct{})
+			batcher.tick.Stop()
+		})
+	}
+}
+
+// BenchmarkScale_ConcurrentSendAndChurn tests the production hot path:
+// sending to all nodes while 10% of connections are churning concurrently.
+// Uses large buffered channels to avoid goroutine drain overhead.
+func BenchmarkScale_ConcurrentSendAndChurn(b *testing.B) {
+	for _, n := range scaleCountsConc {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, channels := benchBatcher(n, b.N+1)
+
+			var mu sync.Mutex
+
+			stopChurn := make(chan struct{})
+
+			go func() {
+				i := 0
+
+				for {
+					select {
+					case <-stopChurn:
+						return
+					default:
+						id := types.NodeID(1 + (i % n)) //nolint:gosec
+						if i%10 == 0 {
+							mc, ok := batcher.nodes.Load(id)
+							if ok {
+								mu.Lock()
+								oldCh := channels[id]
+								mu.Unlock()
+								mc.removeConnectionByChannel(oldCh)
+
+								newCh := make(chan *tailcfg.MapResponse, b.N+1)
+								entry := &connectionEntry{
+									id:      fmt.Sprintf("sc-churn-%d", i),
+									c:       newCh,
+									version: tailcfg.CapabilityVersion(100),
+									created: time.Now(),
+								}
+								entry.lastUsed.Store(time.Now().Unix())
+								mc.addConnection(entry)
+								mu.Lock()
+								channels[id] = newCh
+								mu.Unlock()
+							}
+						}
+
+						i++
+					}
+				}
+			}()
+
+			data := testMapResponse()
+
+			b.ResetTimer()
+
+			for range b.N {
+				batcher.nodes.Range(func(_ types.NodeID, mc *multiChannelNodeConn) bool {
+					_ = mc.send(data)
+					return true
+				})
+			}
+
+			b.StopTimer()
+			close(stopChurn)
+			close(batcher.done)
+			batcher.tick.Stop()
+		})
+	}
+}
+
+// BenchmarkScale_MixedWorkload simulates a realistic production workload:
+// - 70% targeted changes (single node updates)
+// - 20% DERP map changes (broadcast)
+// - 10% full updates (broadcast with full map)
+// All while 10% of connections are churning.
+func BenchmarkScale_MixedWorkload(b *testing.B) {
+	for _, n := range scaleCountsConc {
+		b.Run(strconv.Itoa(n), func(b *testing.B) {
+			batcher, channels := benchBatcher(n, 10)
+			batcher.workCh = make(chan work, n*100+1)
+
+			var mu sync.Mutex
+
+			stopChurn := make(chan struct{})
+
+			// Background churn on 10% of nodes
+			go func() {
+				i := 0
+
+				for {
+					select {
+					case <-stopChurn:
+						return
+					default:
+						id := types.NodeID(1 + (i % n)) //nolint:gosec
+						if i%10 == 0 {
+							mc, ok := batcher.nodes.Load(id)
+							if ok {
+								mu.Lock()
+								oldCh := channels[id]
+								mu.Unlock()
+								mc.removeConnectionByChannel(oldCh)
+
+								newCh := make(chan *tailcfg.MapResponse, 10)
+								entry := &connectionEntry{
+									id:      fmt.Sprintf("mix-churn-%d", i),
+									c:       newCh,
+									version: tailcfg.CapabilityVersion(100),
+									created: time.Now(),
+								}
+								entry.lastUsed.Store(time.Now().Unix())
+								mc.addConnection(entry)
+								mu.Lock()
+								channels[id] = newCh
+								mu.Unlock()
+							}
+						}
+
+						i++
+					}
+				}
+			}()
+
+			// Background batch processor
+			stopProc := make(chan struct{})
+
+			go func() {
+				for {
+					select {
+					case <-stopProc:
+						return
+					default:
+						batcher.processBatchedChanges()
+						time.Sleep(time.Millisecond) //nolint:forbidigo
+					}
+				}
+			}()
+
+			// Background work channel consumer (simulates workers)
+			stopWorkers := make(chan struct{})
+
+			go func() {
+				for {
+					select {
+					case <-batcher.workCh:
+					case <-stopWorkers:
+						return
+					}
+				}
+			}()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				switch {
+				case i%10 < 7: // 70% targeted
+					targetID := types.NodeID(1 + (i % n)) //nolint:gosec
+					batcher.addToBatch(change.Change{
+						Reason:     "mixed-targeted",
+						TargetNode: targetID,
+						PeerPatches: []*tailcfg.PeerChange{
+							{NodeID: tailcfg.NodeID(targetID)}, //nolint:gosec
+						},
+					})
+				case i%10 < 9: // 20% DERP map broadcast
+					batcher.addToBatch(change.DERPMap())
+				default: // 10% full update
+					batcher.addToBatch(change.FullUpdate())
+				}
+			}
+
+			b.StopTimer()
+			close(stopChurn)
+			close(stopProc)
+			close(stopWorkers)
+			close(batcher.done)
+			batcher.tick.Stop()
+		})
+	}
+}
+
+// ============================================================================
+// Tier 5: DB-dependent — AddNode with real MapResponse generation
+// ============================================================================
+
+// BenchmarkScale_AddAllNodes measures the cost of connecting ALL N nodes
+// to a batcher backed by a real database. Each AddNode generates an initial
+// MapResponse containing all peer data, so cost is O(N) per node, O(N²) total.
+func BenchmarkScale_AddAllNodes(b *testing.B) {
+	if testing.Short() {
+		b.Skip("skipping full pipeline benchmark in short mode")
+	}
+
+	for _, nodeCount := range []int{10, 50, 100, 200, 500} {
+		b.Run(strconv.Itoa(nodeCount), func(b *testing.B) {
+			testData, cleanup := setupBatcherWithTestData(b, NewBatcherAndMapper, 1, nodeCount, largeBufferSize)
+			defer cleanup()
+
+			batcher := testData.Batcher
+			allNodes := testData.Nodes
+
+			for i := range allNodes {
+				allNodes[i].start()
+			}
+
+			defer func() {
+				for i := range allNodes {
+					allNodes[i].cleanup()
+				}
+			}()
+
+			b.ResetTimer()
+
+			for range b.N {
+				for i := range allNodes {
+					node := &allNodes[i]
+					_ = batcher.AddNode(node.n.ID, node.ch, tailcfg.CapabilityVersion(100), nil)
+				}
+
+				b.StopTimer()
+
+				for i := range allNodes {
+					node := &allNodes[i]
+					batcher.RemoveNode(node.n.ID, node.ch)
+				}
+
+				for i := range allNodes {
+					for {
+						select {
+						case <-allNodes[i].ch:
+						default:
+							goto drained
+						}
+					}
+
+				drained:
+				}
+
+				b.StartTimer()
+			}
+		})
+	}
+}
+
+// BenchmarkScale_SingleAddNode measures the cost of adding ONE node to an
+// already-populated batcher. This is the real production scenario: a new node
+// joins an existing network. The cost should scale with the number of existing
+// peers since the initial MapResponse includes all peer data.
+func BenchmarkScale_SingleAddNode(b *testing.B) {
+	if testing.Short() {
+		b.Skip("skipping full pipeline benchmark in short mode")
+	}
+
+	for _, nodeCount := range []int{10, 50, 100, 200, 500, 1000} {
+		b.Run(strconv.Itoa(nodeCount), func(b *testing.B) {
+			testData, cleanup := setupBatcherWithTestData(b, NewBatcherAndMapper, 1, nodeCount, largeBufferSize)
+			defer cleanup()
+
+			batcher := testData.Batcher
+			allNodes := testData.Nodes
+
+			for i := range allNodes {
+				allNodes[i].start()
+			}
+
+			defer func() {
+				for i := range allNodes {
+					allNodes[i].cleanup()
+				}
+			}()
+
+			// Connect all nodes except the last one
+			for i := range len(allNodes) - 1 {
+				node := &allNodes[i]
+
+				err := batcher.AddNode(node.n.ID, node.ch, tailcfg.CapabilityVersion(100), nil)
+				if err != nil {
+					b.Fatalf("failed to add node %d: %v", i, err)
+				}
+			}
+
+			time.Sleep(200 * time.Millisecond) //nolint:forbidigo
+
+			// Benchmark: repeatedly add and remove the last node
+			lastNode := &allNodes[len(allNodes)-1]
+
+			b.ResetTimer()
+
+			for range b.N {
+				_ = batcher.AddNode(lastNode.n.ID, lastNode.ch, tailcfg.CapabilityVersion(100), nil)
+
+				b.StopTimer()
+				batcher.RemoveNode(lastNode.n.ID, lastNode.ch)
+
+				for {
+					select {
+					case <-lastNode.ch:
+					default:
+						goto drainDone
+					}
+				}
+
+			drainDone:
+				b.StartTimer()
+			}
+		})
+	}
+}
+
+// BenchmarkScale_MapResponse_DERPMap measures MapResponse generation for a
+// DERPMap change. This is a lightweight change that doesn't touch peers.
+func BenchmarkScale_MapResponse_DERPMap(b *testing.B) {
+	if testing.Short() {
+		b.Skip("skipping full pipeline benchmark in short mode")
+	}
+
+	for _, nodeCount := range []int{10, 50, 100, 200, 500} {
+		b.Run(strconv.Itoa(nodeCount), func(b *testing.B) {
+			testData, cleanup := setupBatcherWithTestData(b, NewBatcherAndMapper, 1, nodeCount, largeBufferSize)
+			defer cleanup()
+
+			batcher := testData.Batcher
+			allNodes := testData.Nodes
+
+			for i := range allNodes {
+				allNodes[i].start()
+			}
+
+			defer func() {
+				for i := range allNodes {
+					allNodes[i].cleanup()
+				}
+			}()
+
+			for i := range allNodes {
+				node := &allNodes[i]
+
+				err := batcher.AddNode(node.n.ID, node.ch, tailcfg.CapabilityVersion(100), nil)
+				if err != nil {
+					b.Fatalf("failed to add node %d: %v", i, err)
+				}
+			}
+
+			time.Sleep(200 * time.Millisecond) //nolint:forbidigo
+
+			ch := change.DERPMap()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				nodeIdx := i % len(allNodes)
+				_, _ = batcher.MapResponseFromChange(allNodes[nodeIdx].n.ID, ch)
+			}
+		})
+	}
+}
+
+// BenchmarkScale_MapResponse_FullUpdate measures MapResponse generation for a
+// FullUpdate change. This forces full peer serialization — the primary bottleneck
+// for large networks.
+func BenchmarkScale_MapResponse_FullUpdate(b *testing.B) {
+	if testing.Short() {
+		b.Skip("skipping full pipeline benchmark in short mode")
+	}
+
+	for _, nodeCount := range []int{10, 50, 100, 200, 500} {
+		b.Run(strconv.Itoa(nodeCount), func(b *testing.B) {
+			testData, cleanup := setupBatcherWithTestData(b, NewBatcherAndMapper, 1, nodeCount, largeBufferSize)
+			defer cleanup()
+
+			batcher := testData.Batcher
+			allNodes := testData.Nodes
+
+			for i := range allNodes {
+				allNodes[i].start()
+			}
+
+			defer func() {
+				for i := range allNodes {
+					allNodes[i].cleanup()
+				}
+			}()
+
+			for i := range allNodes {
+				node := &allNodes[i]
+
+				err := batcher.AddNode(node.n.ID, node.ch, tailcfg.CapabilityVersion(100), nil)
+				if err != nil {
+					b.Fatalf("failed to add node %d: %v", i, err)
+				}
+			}
+
+			time.Sleep(200 * time.Millisecond) //nolint:forbidigo
+
+			ch := change.FullUpdate()
+
+			b.ResetTimer()
+
+			for i := range b.N {
+				nodeIdx := i % len(allNodes)
+				_, _ = batcher.MapResponseFromChange(allNodes[nodeIdx].n.ID, ch)
+			}
+		})
+	}
+}

hscontrol/mapper/builder.go

@@ -2,10 +2,12 @@ package mapper
 
 import (
 	"net/netip"
+	"slices"
 	"sort"
 	"time"
 
 	"github.com/juanfont/headscale/hscontrol/policy"
+	policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2"
 	"github.com/juanfont/headscale/hscontrol/types"
 	"tailscale.com/tailcfg"
 	"tailscale.com/types/views"
@@ -78,9 +80,14 @@ func (b *MapResponseBuilder) WithSelfNode() *MapResponseBuilder {
 	tailnode, err := nv.TailNode(
 		b.capVer,
 		func(id types.NodeID) []netip.Prefix {
-			return policy.ReduceRoutes(nv, b.mapper.state.GetNodePrimaryRoutes(id), matchers)
+			// Self node: include own primaries + exit routes (no via steering for self).
+			primaries := policy.ReduceRoutes(nv, b.mapper.state.GetNodePrimaryRoutes(id), matchers)
+
+			return slices.Concat(primaries, nv.ExitRoutes())
 		},
-		b.mapper.cfg)
+		b.mapper.cfg,
+		b.mapper.state.NodeCapMap(nv.ID()),
+	)
 	if err != nil {
 		b.addError(err)
 		return b
@@ -154,7 +161,7 @@ func (b *MapResponseBuilder) WithDNSConfig() *MapResponseBuilder {
 		return b
 	}
 
-	b.resp.DNSConfig = generateDNSConfig(b.mapper.cfg, node)
+	b.resp.DNSConfig = generateDNSConfig(b.mapper.cfg, node, b.mapper.state.NodeCapMap(node.ID()))
 
 	return b
 }
@@ -251,14 +258,38 @@ func (b *MapResponseBuilder) buildTailPeers(peers views.Slice[types.NodeView]) (
 		changedViews = peers
 	}
 
-	tailPeers, err := types.TailNodes(
-		changedViews, b.capVer,
-		func(id types.NodeID) []netip.Prefix {
-			return policy.ReduceRoutes(node, b.mapper.state.GetNodePrimaryRoutes(id), matchers)
-		},
-		b.mapper.cfg)
-	if err != nil {
-		return nil, err
+	// Snapshot the per-node policy CapMap once per peer-list build
+	// instead of locking the policy manager per peer. The per-call
+	// path used to take pm.mu N times for an N-peer response.
+	allCapMaps := b.mapper.state.NodeCapMaps()
+
+	// Build tail nodes with per-peer via-aware route function.
+	tailPeers := make([]*tailcfg.Node, 0, changedViews.Len())
+
+	for _, peer := range changedViews.All() {
+		// Pass the peer's policy CapMap as selfPolicyCaps so per-peer
+		// address-shape rules (today: disable-ipv4) apply consistently
+		// in the viewer's netmap. The CapMap merge into tn.CapMap is
+		// overwritten by the PeerCapMap call below; only the address
+		// filtering side-effect inside TailNode survives.
+		tn, err := peer.TailNode(b.capVer, func(_ types.NodeID) []netip.Prefix {
+			return b.mapper.state.RoutesForPeer(node, peer, matchers)
+		}, b.mapper.cfg, allCapMaps[peer.ID()])
+		if err != nil {
+			return nil, err
+		}
+
+		// [tailcfg.Node.CapMap] on a peer carries the small set of
+		// caps the Tailscale client reads from the peer view rather
+		// than the self view (suggest-exit-node, dns-subdomain-resolve
+		// — see ipn/ipnlocal/local.go:7534 and node_backend.go:745).
+		// The Tailscale-hosted control plane stamps these only when
+		// the peer satisfies the cap's emission condition; every other
+		// cap stays off the peer view, leaving CapMap empty for most
+		// peers. [policyv2.PeerCapMap] encodes those conditions.
+		tn.CapMap = policyv2.PeerCapMap(peer, allCapMaps[peer.ID()])
+
+		tailPeers = append(tailPeers, tn)
 	}
 
 	// Peers is always returned sorted by Node.ID.
@@ -269,6 +300,12 @@ func (b *MapResponseBuilder) buildTailPeers(peers views.Slice[types.NodeView]) (
 	return tailPeers, nil
 }
 
+// WithPingRequest adds a PingRequest to the response.
+func (b *MapResponseBuilder) WithPingRequest(pr *tailcfg.PingRequest) *MapResponseBuilder {
+	b.resp.PingRequest = pr
+	return b
+}
+
 // WithPeerChangedPatch adds peer change patches.
 func (b *MapResponseBuilder) WithPeerChangedPatch(changes []*tailcfg.PeerChange) *MapResponseBuilder {
 	b.resp.PeersChangedPatch = changes

hscontrol/mapper/mapper.go

@@ -7,6 +7,7 @@ import (
 	"net/url"
 	"os"
 	"path"
+	"regexp"
 	"slices"
 	"strconv"
 	"strings"
@@ -44,7 +45,7 @@ type mapper struct {
 	// Configuration
 	state   *state.State
 	cfg     *types.Config
-	batcher Batcher
+	batcher *Batcher
 
 	created time.Time
 }
@@ -114,9 +115,25 @@ func generateUserProfiles(
 	return profiles
 }
 
+// nextDNSAttrPrefix is the form Tailscale uses for per-node NextDNS profile
+// selection: an "attr" entry of "nextdns:<profile-id>" overrides the resolver
+// path, and "nextdns:no-device-info" suppresses the metadata-appending step.
+// See https://tailscale.com/docs/integrations/nextdns.
+const (
+	nextDNSAttrPrefix                        = "nextdns:"
+	nextDNSAttrNoInfo tailcfg.NodeCapability = "nextdns:no-device-info"
+)
+
+// nextDNSProfileRE bounds the characters accepted in a `nextdns:<profile>`
+// suffix. NextDNS profile IDs are short alphanumeric strings; restricting
+// to that charset prevents a policy author from injecting `?`, `/`, `@`,
+// or `..` into the resolver URL via a crafted cap name.
+var nextDNSProfileRE = regexp.MustCompile(`^[A-Za-z0-9._-]{1,64}$`)
+
 func generateDNSConfig(
 	cfg *types.Config,
 	node types.NodeView,
+	capMap tailcfg.NodeCapMap,
 ) *tailcfg.DNSConfig {
 	if cfg.TailcfgDNSConfig == nil {
 		return nil
@@ -124,32 +141,129 @@ func generateDNSConfig(
 
 	dnsConfig := cfg.TailcfgDNSConfig.Clone()
 
-	addNextDNSMetadata(dnsConfig.Resolvers, node)
+	profile := nextDNSProfileFromCapMap(capMap)
+	if profile != "" {
+		applyNextDNSProfile(dnsConfig.Resolvers, profile)
+		applyNextDNSProfile(dnsConfig.FallbackResolvers, profile)
+
+		for suffix, rs := range dnsConfig.Routes {
+			applyNextDNSProfile(rs, profile)
+			dnsConfig.Routes[suffix] = rs
+		}
+	}
+
+	if _, suppressMetadata := capMap[nextDNSAttrNoInfo]; !suppressMetadata {
+		addNextDNSMetadata(dnsConfig.Resolvers, node)
+		addNextDNSMetadata(dnsConfig.FallbackResolvers, node)
+
+		for suffix, rs := range dnsConfig.Routes {
+			addNextDNSMetadata(rs, node)
+			dnsConfig.Routes[suffix] = rs
+		}
+	}
 
 	return dnsConfig
 }
 
-// If any nextdns DoH resolvers are present in the list of resolvers it will
-// take metadata from the node metadata and instruct tailscale to add it
-// to the requests. This makes it possible to identify from which device the
-// requests come in the NextDNS dashboard.
+// nextDNSProfileFromCapMap returns the policy-selected
+// `nextdns:<profile>` value on the node, or the empty string when none
+// is set or the cap is malformed. The reserved
+// `nextdns:no-device-info` string is not a profile — it controls
+// metadata appending and is handled separately.
 //
-// This will produce a resolver like:
-// `https://dns.nextdns.io/<nextdns-id>?device_name=node-name&device_model=linux&device_ip=100.64.0.1`
+// The profile pick is deterministic across reloads: cap keys are
+// gathered, sorted, and the first valid profile wins. Map iteration
+// order in Go is randomised, so taking the literal first match would
+// cause the chosen profile to flip between reloads when a node has
+// multiple `nextdns:` caps. The profile string is also validated
+// against [nextDNSProfileRE] so a crafted cap cannot inject path or
+// query characters into the resolver URL.
+func nextDNSProfileFromCapMap(capMap tailcfg.NodeCapMap) string {
+	if len(capMap) == 0 {
+		return ""
+	}
+
+	candidates := make([]string, 0, len(capMap))
+
+	for cap := range capMap {
+		if cap == nextDNSAttrNoInfo {
+			continue
+		}
+
+		profile, ok := strings.CutPrefix(string(cap), nextDNSAttrPrefix)
+		if !ok || profile == "" {
+			continue
+		}
+
+		if !nextDNSProfileRE.MatchString(profile) {
+			log.Warn().
+				Str("cap", string(cap)).
+				Msg("nextdns profile rejected: must match [A-Za-z0-9._-]{1,64}")
+
+			continue
+		}
+
+		candidates = append(candidates, profile)
+	}
+
+	if len(candidates) == 0 {
+		return ""
+	}
+
+	slices.Sort(candidates)
+
+	return candidates[0]
+}
+
+// nextDNSDoHHost matches a NextDNS DoH resolver address. The check is
+// anchored on the host segment so a typo-squatted operator-configured
+// resolver such as `https://dns.nextdns.io.attacker.example/x` does
+// not slip through.
+func nextDNSDoHHost(addr string) bool {
+	return addr == nextDNSDoHPrefix ||
+		strings.HasPrefix(addr, nextDNSDoHPrefix+"/") ||
+		strings.HasPrefix(addr, nextDNSDoHPrefix+"?")
+}
+
+// applyNextDNSProfile rewrites every NextDNS DoH resolver to point at
+// the given profile, dropping any existing profile path or query. Per
+// the Tailscale spec the per-node profile overrides the global value,
+// so the rewrite is unconditional rather than additive.
+func applyNextDNSProfile(resolvers []*dnstype.Resolver, profile string) {
+	for _, resolver := range resolvers {
+		if !nextDNSDoHHost(resolver.Addr) {
+			continue
+		}
+
+		resolver.Addr = nextDNSDoHPrefix + "/" + profile
+	}
+}
+
+// addNextDNSMetadata appends device metadata as a query string to
+// every NextDNS DoH resolver. Existing query parameters on the
+// resolver address are preserved by parsing the URL and merging into
+// its [url.URL.RawQuery] rather than concatenating with `?`.
 func addNextDNSMetadata(resolvers []*dnstype.Resolver, node types.NodeView) {
 	for _, resolver := range resolvers {
-		if strings.HasPrefix(resolver.Addr, nextDNSDoHPrefix) {
-			attrs := url.Values{
-				"device_name":  []string{node.Hostname()},
-				"device_model": []string{node.Hostinfo().OS()},
-			}
-
-			if len(node.IPs()) > 0 {
-				attrs.Add("device_ip", node.IPs()[0].String())
-			}
-
-			resolver.Addr = fmt.Sprintf("%s?%s", resolver.Addr, attrs.Encode())
+		if !nextDNSDoHHost(resolver.Addr) {
+			continue
 		}
+
+		u, err := url.Parse(resolver.Addr)
+		if err != nil {
+			continue
+		}
+
+		q := u.Query()
+		q.Set("device_name", node.Hostname())
+		q.Set("device_model", node.Hostinfo().OS())
+
+		if ips := node.IPs(); len(ips) > 0 {
+			q.Set("device_ip", ips[0].String())
+		}
+
+		u.RawQuery = q.Encode()
+		resolver.Addr = u.String()
 	}
 }
 
@@ -239,7 +353,10 @@ func (m *mapper) policyChangeResponse(
 
 	// Send remaining peers in PeersChanged - their AllowedIPs may have
 	// changed due to the policy update (e.g., different routes allowed).
+	// Cross-user peers must also carry their user profile, otherwise the
+	// client's netmap shows the peer without a UserProfiles[user] entry.
 	if currentPeers.Len() > 0 {
+		builder.WithUserProfiles(currentPeers)
 		builder.WithPeerChanges(currentPeers)
 	}
 
@@ -308,6 +425,10 @@ func (m *mapper) buildFromChange(
 		builder.WithPeerChangedPatch(resp.PeerPatches)
 	}
 
+	if resp.PingRequest != nil {
+		builder.WithPingRequest(resp.PingRequest)
+	}
+
 	return builder.Build()
 }
 

hscontrol/mapper/mapper_test.go

@@ -68,6 +68,7 @@ func TestDNSConfigMapResponse(t *testing.T) {
 					TailcfgDNSConfig: &dnsConfigOrig,
 				},
 				nodeInShared1.View(),
+				nil,
 			)
 
 			if diff := cmp.Diff(tt.want, got, cmpopts.EquateEmpty()); diff != "" {
@@ -76,3 +77,119 @@ func TestDNSConfigMapResponse(t *testing.T) {
 		})
 	}
 }
+
+func TestNextDNSCapMapRendering(t *testing.T) {
+	t.Parallel()
+
+	mkConfig := func(addrs ...string) *types.Config {
+		resolvers := make([]*dnstype.Resolver, len(addrs))
+		for i, a := range addrs {
+			resolvers[i] = &dnstype.Resolver{Addr: a}
+		}
+
+		return &types.Config{
+			TailcfgDNSConfig: &tailcfg.DNSConfig{
+				Resolvers: resolvers,
+			},
+		}
+	}
+
+	mkNode := func() types.NodeView {
+		return (&types.Node{
+			ID:       1,
+			Hostname: "node1",
+			IPv4:     iap("100.64.0.1"),
+			Hostinfo: &tailcfg.Hostinfo{OS: "linux"},
+		}).View()
+	}
+
+	// resolverAddr extracts the first resolver's address with a
+	// bounds check. Without it, a regression that drops the
+	// resolver list would nil-panic instead of failing cleanly.
+	resolverAddr := func(t *testing.T, got *tailcfg.DNSConfig) string {
+		t.Helper()
+
+		if got == nil {
+			t.Fatalf("generateDNSConfig returned nil")
+		}
+
+		if len(got.Resolvers) == 0 {
+			t.Fatalf("generateDNSConfig returned no Resolvers")
+		}
+
+		return got.Resolvers[0].Addr
+	}
+
+	t.Run("no_capmap_metadata_appended", func(t *testing.T) {
+		t.Parallel()
+
+		got := generateDNSConfig(
+			mkConfig("https://dns.nextdns.io/abc"),
+			mkNode(),
+			nil,
+		)
+
+		want := "https://dns.nextdns.io/abc?device_ip=100.64.0.1&device_model=linux&device_name=node1"
+		if addr := resolverAddr(t, got); addr != want {
+			t.Errorf("addr = %q, want %q", addr, want)
+		}
+	})
+
+	t.Run("profile_overrides_global", func(t *testing.T) {
+		t.Parallel()
+
+		capMap := tailcfg.NodeCapMap{
+			"nextdns:override": []tailcfg.RawMessage{},
+		}
+
+		got := generateDNSConfig(
+			mkConfig("https://dns.nextdns.io/global"),
+			mkNode(),
+			capMap,
+		)
+
+		want := "https://dns.nextdns.io/override?device_ip=100.64.0.1&device_model=linux&device_name=node1"
+		if addr := resolverAddr(t, got); addr != want {
+			t.Errorf("addr = %q, want %q", addr, want)
+		}
+	})
+
+	t.Run("no_device_info_skips_metadata", func(t *testing.T) {
+		t.Parallel()
+
+		capMap := tailcfg.NodeCapMap{
+			"nextdns:abc":            []tailcfg.RawMessage{},
+			"nextdns:no-device-info": []tailcfg.RawMessage{},
+		}
+
+		got := generateDNSConfig(
+			mkConfig("https://dns.nextdns.io/global"),
+			mkNode(),
+			capMap,
+		)
+
+		want := "https://dns.nextdns.io/abc"
+		if addr := resolverAddr(t, got); addr != want {
+			t.Errorf("addr = %q, want %q", addr, want)
+		}
+	})
+
+	t.Run("non_nextdns_resolver_untouched", func(t *testing.T) {
+		t.Parallel()
+
+		capMap := tailcfg.NodeCapMap{
+			"nextdns:abc": []tailcfg.RawMessage{},
+		}
+
+		got := generateDNSConfig(
+			mkConfig("https://dns.example.org/dns-query"),
+			mkNode(),
+			capMap,
+		)
+
+		want := "https://dns.example.org/dns-query"
+		if addr := resolverAddr(t, got); addr != want {
+			t.Errorf("non-nextdns resolver was rewritten: %q", addr)
+		}
+	})
+}

hscontrol/mapper/node_conn.go

@@ -0,0 +1,445 @@
+package mapper
+
+import (
+	"errors"
+	"fmt"
+	"strconv"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/juanfont/headscale/hscontrol/types/change"
+	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
+	"github.com/puzpuzpuz/xsync/v4"
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+	"tailscale.com/tailcfg"
+)
+
+// errNoActiveConnections is returned by send when a node has no active
+// connections (disconnected but kept in the batcher for rapid reconnection).
+// Callers must not update peer tracking state (lastSentPeers) after this
+// error because the data was never delivered to any client.
+var errNoActiveConnections = errors.New("no active connections")
+
+// connectionEntry represents a single connection to a node.
+type connectionEntry struct {
+	id       string // unique connection ID
+	c        chan<- *tailcfg.MapResponse
+	version  tailcfg.CapabilityVersion
+	created  time.Time
+	stop     func()
+	lastUsed atomic.Int64 // Unix timestamp of last successful send
+	closed   atomic.Bool  // Indicates if this connection has been closed
+}
+
+// multiChannelNodeConn manages multiple concurrent connections for a single node.
+type multiChannelNodeConn struct {
+	id     types.NodeID
+	mapper *mapper
+	log    zerolog.Logger
+
+	mutex       sync.RWMutex
+	connections []*connectionEntry
+
+	// pendingMu protects pending changes independently of the connection mutex.
+	// This avoids contention between addToBatch (which appends changes) and
+	// send() (which sends data to connections).
+	pendingMu sync.Mutex
+	pending   []change.Change
+
+	// workMu serializes change processing for this node across batch ticks.
+	// Without this, two workers could process consecutive ticks' bundles
+	// concurrently, causing out-of-order MapResponse delivery and races
+	// on lastSentPeers (Clear+Store in updateSentPeers vs Range in
+	// computePeerDiff).
+	workMu sync.Mutex
+
+	closeOnce   sync.Once
+	updateCount atomic.Int64
+
+	// disconnectedAt records when the last connection was removed.
+	// nil means the node is considered connected (or newly created);
+	// non-nil means the node disconnected at the stored timestamp.
+	// Used by cleanupOfflineNodes to evict stale entries.
+	disconnectedAt atomic.Pointer[time.Time]
+
+	// lastSentPeers tracks which peers were last sent to this node.
+	// This enables computing diffs for policy changes instead of sending
+	// full peer lists (which clients interpret as "no change" when empty).
+	// Using xsync.Map for lock-free concurrent access.
+	lastSentPeers *xsync.Map[tailcfg.NodeID, struct{}]
+}
+
+// connIDCounter is a monotonically increasing counter used to generate
+// unique connection identifiers without the overhead of crypto/rand.
+// Connection IDs are process-local and need not be cryptographically random.
+var connIDCounter atomic.Uint64
+
+// generateConnectionID generates a unique connection identifier.
+func generateConnectionID() string {
+	return strconv.FormatUint(connIDCounter.Add(1), 10)
+}
+
+// newMultiChannelNodeConn creates a new multi-channel node connection.
+func newMultiChannelNodeConn(id types.NodeID, mapper *mapper) *multiChannelNodeConn {
+	return &multiChannelNodeConn{
+		id:            id,
+		mapper:        mapper,
+		lastSentPeers: xsync.NewMap[tailcfg.NodeID, struct{}](),
+		log:           log.With().Uint64(zf.NodeID, id.Uint64()).Logger(),
+	}
+}
+
+func (mc *multiChannelNodeConn) close() {
+	mc.closeOnce.Do(func() {
+		mc.mutex.Lock()
+		defer mc.mutex.Unlock()
+
+		for _, conn := range mc.connections {
+			mc.stopConnection(conn)
+		}
+	})
+}
+
+// stopConnection marks a connection as closed and tears down the owning session
+// at most once, even if multiple cleanup paths race to remove it.
+func (mc *multiChannelNodeConn) stopConnection(conn *connectionEntry) {
+	if conn.closed.CompareAndSwap(false, true) {
+		if conn.stop != nil {
+			conn.stop()
+		}
+	}
+}
+
+// removeConnectionAtIndexLocked removes the active connection at index.
+// If stopConnection is true, it also stops that session.
+// Caller must hold mc.mutex.
+func (mc *multiChannelNodeConn) removeConnectionAtIndexLocked(i int, stopConnection bool) *connectionEntry {
+	conn := mc.connections[i]
+	copy(mc.connections[i:], mc.connections[i+1:])
+	mc.connections[len(mc.connections)-1] = nil // release pointer for GC
+	mc.connections = mc.connections[:len(mc.connections)-1]
+
+	if stopConnection {
+		mc.stopConnection(conn)
+	}
+
+	return conn
+}
+
+// addConnection adds a new connection.
+func (mc *multiChannelNodeConn) addConnection(entry *connectionEntry) {
+	mc.mutex.Lock()
+	defer mc.mutex.Unlock()
+
+	mc.connections = append(mc.connections, entry)
+	mc.log.Debug().Str(zf.ConnID, entry.id).
+		Int("total_connections", len(mc.connections)).
+		Msg("connection added")
+}
+
+// removeConnectionByChannel removes a connection by matching channel pointer.
+func (mc *multiChannelNodeConn) removeConnectionByChannel(c chan<- *tailcfg.MapResponse) bool {
+	mc.mutex.Lock()
+	defer mc.mutex.Unlock()
+
+	for i, entry := range mc.connections {
+		if entry.c == c {
+			mc.removeConnectionAtIndexLocked(i, false)
+			mc.log.Debug().Str(zf.ConnID, entry.id).
+				Int("remaining_connections", len(mc.connections)).
+				Msg("connection removed")
+
+			return true
+		}
+	}
+
+	return false
+}
+
+// hasActiveConnections checks if the node has any active connections.
+func (mc *multiChannelNodeConn) hasActiveConnections() bool {
+	mc.mutex.RLock()
+	defer mc.mutex.RUnlock()
+
+	return len(mc.connections) > 0
+}
+
+// getActiveConnectionCount returns the number of active connections.
+func (mc *multiChannelNodeConn) getActiveConnectionCount() int {
+	mc.mutex.RLock()
+	defer mc.mutex.RUnlock()
+
+	return len(mc.connections)
+}
+
+// markConnected clears the disconnect timestamp, indicating the node
+// has an active connection.
+func (mc *multiChannelNodeConn) markConnected() {
+	mc.disconnectedAt.Store(nil)
+}
+
+// markDisconnected records the current time as the moment the node
+// lost its last connection. Used by cleanupOfflineNodes to determine
+// how long the node has been offline.
+func (mc *multiChannelNodeConn) markDisconnected() {
+	now := time.Now()
+	mc.disconnectedAt.Store(&now)
+}
+
+// isConnected returns true if the node has active connections or has
+// not been marked as disconnected.
+func (mc *multiChannelNodeConn) isConnected() bool {
+	if mc.hasActiveConnections() {
+		return true
+	}
+
+	return mc.disconnectedAt.Load() == nil
+}
+
+// offlineDuration returns how long the node has been disconnected.
+// Returns 0 if the node is connected or has never been marked as disconnected.
+func (mc *multiChannelNodeConn) offlineDuration() time.Duration {
+	t := mc.disconnectedAt.Load()
+	if t == nil {
+		return 0
+	}
+
+	return time.Since(*t)
+}
+
+// appendPending appends changes to this node's pending change list.
+// Thread-safe via pendingMu; does not contend with the connection mutex.
+func (mc *multiChannelNodeConn) appendPending(changes ...change.Change) {
+	mc.pendingMu.Lock()
+	mc.pending = append(mc.pending, changes...)
+	mc.pendingMu.Unlock()
+}
+
+// drainPending atomically removes and returns all pending changes.
+// Returns nil if there are no pending changes.
+func (mc *multiChannelNodeConn) drainPending() []change.Change {
+	mc.pendingMu.Lock()
+	p := mc.pending
+	mc.pending = nil
+	mc.pendingMu.Unlock()
+
+	return p
+}
+
+// send broadcasts data to all active connections for the node.
+//
+// To avoid holding the write lock during potentially slow sends (each stale
+// connection can block for up to 50ms), the method snapshots connections under
+// a read lock, sends without any lock held, then write-locks only to remove
+// failures. New connections added between the snapshot and cleanup are safe:
+// they receive a full initial map via AddNode, so missing this update causes
+// no data loss.
+func (mc *multiChannelNodeConn) send(data *tailcfg.MapResponse) error {
+	if data == nil {
+		return nil
+	}
+
+	// Snapshot connections under read lock.
+	mc.mutex.RLock()
+
+	if len(mc.connections) == 0 {
+		mc.mutex.RUnlock()
+		mc.log.Trace().
+			Msg("send: no active connections, skipping")
+
+		return errNoActiveConnections
+	}
+
+	// Copy the slice so we can release the read lock before sending.
+	snapshot := make([]*connectionEntry, len(mc.connections))
+	copy(snapshot, mc.connections)
+	mc.mutex.RUnlock()
+
+	mc.log.Trace().
+		Int("total_connections", len(snapshot)).
+		Msg("send: broadcasting")
+
+	// Send to all connections without holding any lock.
+	// Stale connection timeouts (50ms each) happen here without blocking
+	// other goroutines that need the mutex.
+	var (
+		lastErr      error
+		successCount int
+		failed       []*connectionEntry
+	)
+
+	for _, conn := range snapshot {
+		err := conn.send(data)
+		if err != nil {
+			lastErr = err
+
+			failed = append(failed, conn)
+
+			mc.log.Warn().Err(err).
+				Str(zf.ConnID, conn.id).
+				Msg("send: connection failed")
+		} else {
+			successCount++
+		}
+	}
+
+	// Write-lock only to remove failed connections.
+	if len(failed) > 0 {
+		mc.mutex.Lock()
+		// Remove by pointer identity: only remove entries that still exist
+		// in the current connections slice and match a failed pointer.
+		// New connections added since the snapshot are not affected.
+		failedSet := make(map[*connectionEntry]struct{}, len(failed))
+		for _, f := range failed {
+			failedSet[f] = struct{}{}
+		}
+
+		clean := mc.connections[:0]
+		for _, conn := range mc.connections {
+			if _, isFailed := failedSet[conn]; !isFailed {
+				clean = append(clean, conn)
+			} else {
+				mc.log.Debug().
+					Str(zf.ConnID, conn.id).
+					Msg("send: removing failed connection")
+				// Tear down the owning session so the old serveLongPoll
+				// goroutine exits instead of lingering as a stale session.
+				mc.stopConnection(conn)
+			}
+		}
+
+		// Nil out trailing slots so removed *connectionEntry values
+		// are not retained by the backing array.
+		for i := len(clean); i < len(mc.connections); i++ {
+			mc.connections[i] = nil
+		}
+
+		mc.connections = clean
+		mc.mutex.Unlock()
+	}
+
+	mc.updateCount.Add(1)
+
+	mc.log.Trace().
+		Int("successful_sends", successCount).
+		Int("failed_connections", len(failed)).
+		Msg("send: broadcast complete")
+
+	// Success if at least one send succeeded
+	if successCount > 0 {
+		return nil
+	}
+
+	return fmt.Errorf("node %d: all connections failed, last error: %w", mc.id, lastErr)
+}
+
+// send sends data to a single connection entry with timeout-based stale connection detection.
+func (entry *connectionEntry) send(data *tailcfg.MapResponse) error {
+	if data == nil {
+		return nil
+	}
+
+	// Check if the connection has been closed to prevent send on closed channel panic.
+	// This can happen during shutdown when Close() is called while workers are still processing.
+	if entry.closed.Load() {
+		return fmt.Errorf("connection %s: %w", entry.id, errConnectionClosed)
+	}
+
+	// Use a short timeout to detect stale connections where the client isn't reading the channel.
+	// This is critical for detecting Docker containers that are forcefully terminated
+	// but still have channels that appear open.
+	//
+	// We use time.NewTimer + Stop instead of time.After to avoid leaking timers.
+	// time.After creates a timer that lives in the runtime's timer heap until it fires,
+	// even when the send succeeds immediately. On the hot path (1000+ nodes per tick),
+	// this leaks thousands of timers per second.
+	timer := time.NewTimer(50 * time.Millisecond) //nolint:mnd
+	defer timer.Stop()
+
+	select {
+	case entry.c <- data:
+		// Update last used timestamp on successful send
+		entry.lastUsed.Store(time.Now().Unix())
+		return nil
+	case <-timer.C:
+		// Connection is likely stale - client isn't reading from channel
+		// This catches the case where Docker containers are killed but channels remain open
+		return fmt.Errorf("connection %s: %w", entry.id, ErrConnectionSendTimeout)
+	}
+}
+
+// nodeID returns the node ID.
+func (mc *multiChannelNodeConn) nodeID() types.NodeID {
+	return mc.id
+}
+
+// version returns the capability version from the first active connection.
+// All connections for a node should have the same version in practice.
+func (mc *multiChannelNodeConn) version() tailcfg.CapabilityVersion {
+	mc.mutex.RLock()
+	defer mc.mutex.RUnlock()
+
+	if len(mc.connections) == 0 {
+		return 0
+	}
+
+	return mc.connections[0].version
+}
+
+// updateSentPeers updates the tracked peer state based on a sent MapResponse.
+// This must be called after successfully sending a response to keep track of
+// what the client knows about, enabling accurate diffs for future updates.
+func (mc *multiChannelNodeConn) updateSentPeers(resp *tailcfg.MapResponse) {
+	if resp == nil {
+		return
+	}
+
+	// Full peer list replaces tracked state entirely
+	if resp.Peers != nil {
+		mc.lastSentPeers.Clear()
+
+		for _, peer := range resp.Peers {
+			mc.lastSentPeers.Store(peer.ID, struct{}{})
+		}
+	}
+
+	// Incremental additions
+	for _, peer := range resp.PeersChanged {
+		mc.lastSentPeers.Store(peer.ID, struct{}{})
+	}
+
+	// Incremental removals
+	for _, id := range resp.PeersRemoved {
+		mc.lastSentPeers.Delete(id)
+	}
+}
+
+// computePeerDiff compares the current peer list against what was last sent
+// and returns the peers that were removed (in lastSentPeers but not in current).
+func (mc *multiChannelNodeConn) computePeerDiff(currentPeers []tailcfg.NodeID) []tailcfg.NodeID {
+	currentSet := make(map[tailcfg.NodeID]struct{}, len(currentPeers))
+	for _, id := range currentPeers {
+		currentSet[id] = struct{}{}
+	}
+
+	var removed []tailcfg.NodeID
+
+	// Find removed: in lastSentPeers but not in current
+	mc.lastSentPeers.Range(func(id tailcfg.NodeID, _ struct{}) bool {
+		if _, exists := currentSet[id]; !exists {
+			removed = append(removed, id)
+		}
+
+		return true
+	})
+
+	return removed
+}
+
+// change applies a change to all active connections for the node.
+func (mc *multiChannelNodeConn) change(r change.Change) error {
+	return handleNodeChange(mc, mc.mapper, r)
+}

hscontrol/mapper/tail_test.go

@@ -3,12 +3,12 @@ package mapper
 import (
 	"encoding/json"
 	"net/netip"
+	"slices"
 	"testing"
 	"time"
 
 	"github.com/google/go-cmp/cmp"
 	"github.com/google/go-cmp/cmp/cmpopts"
-	"github.com/juanfont/headscale/hscontrol/routes"
 	"github.com/juanfont/headscale/hscontrol/types"
 	"tailscale.com/net/tsaddr"
 	"tailscale.com/tailcfg"
@@ -16,6 +16,8 @@ import (
 )
 
 func TestTailNode(t *testing.T) {
+	t.Parallel()
+
 	mustNK := func(str string) key.NodePublic {
 		var k key.NodePublic
 
@@ -51,7 +53,6 @@ func TestTailNode(t *testing.T) {
 	tests := []struct {
 		name       string
 		node       *types.Node
-		pol        []byte
 		dnsConfig  *tailcfg.DNSConfig
 		baseDomain string
 		want       *tailcfg.Node
@@ -74,9 +75,10 @@ func TestTailNode(t *testing.T) {
 				MachineAuthorized: true,
 
 				CapMap: tailcfg.NodeCapMap{
-					tailcfg.CapabilityFileSharing: []tailcfg.RawMessage{},
-					tailcfg.CapabilityAdmin:       []tailcfg.RawMessage{},
-					tailcfg.CapabilitySSH:         []tailcfg.RawMessage{},
+					tailcfg.CapabilityAdmin:           []tailcfg.RawMessage{},
+					tailcfg.CapabilitySSH:             []tailcfg.RawMessage{},
+					tailcfg.CapabilityFileSharing:     []tailcfg.RawMessage{},
+					tailcfg.NodeAttrDefaultAutoUpdate: []tailcfg.RawMessage{tailcfg.RawMessage("false")},
 				},
 			},
 			wantErr: false,
@@ -163,9 +165,10 @@ func TestTailNode(t *testing.T) {
 				MachineAuthorized: true,
 
 				CapMap: tailcfg.NodeCapMap{
-					tailcfg.CapabilityFileSharing: []tailcfg.RawMessage{},
-					tailcfg.CapabilityAdmin:       []tailcfg.RawMessage{},
-					tailcfg.CapabilitySSH:         []tailcfg.RawMessage{},
+					tailcfg.CapabilityAdmin:           []tailcfg.RawMessage{},
+					tailcfg.CapabilitySSH:             []tailcfg.RawMessage{},
+					tailcfg.CapabilityFileSharing:     []tailcfg.RawMessage{},
+					tailcfg.NodeAttrDefaultAutoUpdate: []tailcfg.RawMessage{tailcfg.RawMessage("false")},
 				},
 			},
 			wantErr: false,
@@ -188,9 +191,10 @@ func TestTailNode(t *testing.T) {
 				MachineAuthorized: true,
 
 				CapMap: tailcfg.NodeCapMap{
-					tailcfg.CapabilityFileSharing: []tailcfg.RawMessage{},
-					tailcfg.CapabilityAdmin:       []tailcfg.RawMessage{},
-					tailcfg.CapabilitySSH:         []tailcfg.RawMessage{},
+					tailcfg.CapabilityAdmin:           []tailcfg.RawMessage{},
+					tailcfg.CapabilitySSH:             []tailcfg.RawMessage{},
+					tailcfg.CapabilityFileSharing:     []tailcfg.RawMessage{},
+					tailcfg.NodeAttrDefaultAutoUpdate: []tailcfg.RawMessage{tailcfg.RawMessage("false")},
 				},
 			},
 			wantErr: false,
@@ -202,24 +206,34 @@ func TestTailNode(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			primary := routes.New()
-			cfg := &types.Config{
-				BaseDomain:          tt.baseDomain,
-				TailcfgDNSConfig:    tt.dnsConfig,
-				RandomizeClientPort: false,
-				Taildrop:            types.TaildropConfig{Enabled: true},
-			}
-			_ = primary.SetRoutes(tt.node.ID, tt.node.SubnetRoutes()...)
+			t.Parallel()
 
-			// This is a hack to avoid having a second node to test the primary route.
-			// This should be baked into the test case proper if it is extended in the future.
-			_ = primary.SetRoutes(2, netip.MustParsePrefix("192.168.0.0/24"))
-			got, err := tt.node.View().TailNode(
+			cfg := &types.Config{
+				BaseDomain:       tt.baseDomain,
+				TailcfgDNSConfig: tt.dnsConfig,
+				Taildrop:         types.TaildropConfig{Enabled: true},
+			}
+
+			// Stub primary-route lookup: tt.node owns its SubnetRoutes,
+			// node ID 2 owns 192.168.0.0/24 (a hack carried over from
+			// the original routes-package-driven version of this test —
+			// avoids spinning up a second node just to validate that
+			// other nodes' primaries don't leak into tt.node's TailNode
+			// output).
+			primaries := map[types.NodeID][]netip.Prefix{
+				tt.node.ID: tt.node.SubnetRoutes(),
+				2:          {netip.MustParsePrefix("192.168.0.0/24")},
+			}
+			nv := tt.node.View()
+			got, err := nv.TailNode(
 				0,
 				func(id types.NodeID) []netip.Prefix {
-					return primary.PrimaryRoutes(id)
+					// Route function returns primaries + exit routes
+					// (matching the real caller contract).
+					return slices.Concat(primaries[id], nv.ExitRoutes())
 				},
 				cfg,
+				nil,
 			)
 
 			if (err != nil) != tt.wantErr {
@@ -235,6 +249,208 @@ func TestTailNode(t *testing.T) {
 	}
 }
 
+// TestTailNodeBaselineGates focuses on the cfg-driven baseline cap
+// emission: cfg.Taildrop.Enabled gates [tailcfg.CapabilityFileSharing]
+// and cfg.AutoUpdate.Enabled controls the value of
+// [tailcfg.NodeAttrDefaultAutoUpdate]. Admin and SSH are unconditional
+// baseline.
+func TestTailNodeBaselineGates(t *testing.T) {
+	t.Parallel()
+
+	autoUpdate := func(b bool) []tailcfg.RawMessage {
+		if b {
+			return []tailcfg.RawMessage{tailcfg.RawMessage("true")}
+		}
+
+		return []tailcfg.RawMessage{tailcfg.RawMessage("false")}
+	}
+
+	tests := []struct {
+		name string
+		cfg  *types.Config
+		want tailcfg.NodeCapMap
+	}{
+		{
+			name: "taildrop_on_autoupdate_off",
+			cfg: &types.Config{
+				Taildrop:   types.TaildropConfig{Enabled: true},
+				AutoUpdate: types.AutoUpdateConfig{Enabled: false},
+			},
+			want: tailcfg.NodeCapMap{
+				tailcfg.CapabilityAdmin:           []tailcfg.RawMessage{},
+				tailcfg.CapabilitySSH:             []tailcfg.RawMessage{},
+				tailcfg.CapabilityFileSharing:     []tailcfg.RawMessage{},
+				tailcfg.NodeAttrDefaultAutoUpdate: autoUpdate(false),
+			},
+		},
+		{
+			name: "taildrop_off_autoupdate_off",
+			cfg: &types.Config{
+				Taildrop:   types.TaildropConfig{Enabled: false},
+				AutoUpdate: types.AutoUpdateConfig{Enabled: false},
+			},
+			want: tailcfg.NodeCapMap{
+				tailcfg.CapabilityAdmin:           []tailcfg.RawMessage{},
+				tailcfg.CapabilitySSH:             []tailcfg.RawMessage{},
+				tailcfg.NodeAttrDefaultAutoUpdate: autoUpdate(false),
+			},
+		},
+		{
+			name: "taildrop_on_autoupdate_on",
+			cfg: &types.Config{
+				Taildrop:   types.TaildropConfig{Enabled: true},
+				AutoUpdate: types.AutoUpdateConfig{Enabled: true},
+			},
+			want: tailcfg.NodeCapMap{
+				tailcfg.CapabilityAdmin:           []tailcfg.RawMessage{},
+				tailcfg.CapabilitySSH:             []tailcfg.RawMessage{},
+				tailcfg.CapabilityFileSharing:     []tailcfg.RawMessage{},
+				tailcfg.NodeAttrDefaultAutoUpdate: autoUpdate(true),
+			},
+		},
+		{
+			name: "taildrop_off_autoupdate_on",
+			cfg: &types.Config{
+				Taildrop:   types.TaildropConfig{Enabled: false},
+				AutoUpdate: types.AutoUpdateConfig{Enabled: true},
+			},
+			want: tailcfg.NodeCapMap{
+				tailcfg.CapabilityAdmin:           []tailcfg.RawMessage{},
+				tailcfg.CapabilitySSH:             []tailcfg.RawMessage{},
+				tailcfg.NodeAttrDefaultAutoUpdate: autoUpdate(true),
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			node := &types.Node{GivenName: "baseline-node", Hostinfo: &tailcfg.Hostinfo{}}
+
+			got, err := node.View().TailNode(
+				0,
+				func(types.NodeID) []netip.Prefix { return nil },
+				tt.cfg,
+				nil,
+			)
+			if err != nil {
+				t.Fatalf("TailNode: %v", err)
+			}
+
+			if diff := cmp.Diff(tt.want, got.CapMap, cmpopts.EquateEmpty()); diff != "" {
+				t.Errorf("CapMap mismatch (-want +got):\n%s", diff)
+			}
+		})
+	}
+}
+
+// TestTailNodeDisableIPv4 asserts that a node with the disable-ipv4
+// nodeAttr has its own IPv4 (the CGNAT /32) stripped from Addresses
+// and AllowedIPs, while subnet routes the node advertises -- even
+// IPv4 ones -- remain in AllowedIPs and PrimaryRoutes. Matches the
+// SaaS behaviour captured in
+// hscontrol/policy/v2/testdata/nodeattrs_results/nodeattrs-attr-c1{5,6}-disable-ipv4*.hujson.
+func TestTailNodeDisableIPv4(t *testing.T) {
+	t.Parallel()
+
+	const NodeAttrDisableIPv4 tailcfg.NodeCapability = "disable-ipv4"
+
+	v4 := iap("100.64.0.1")
+	v6Addr := netip.MustParseAddr("fd7a:115c:a1e0::1")
+	v6 := &v6Addr
+	subnet := netip.MustParsePrefix("10.33.0.0/16")
+
+	tests := []struct {
+		name        string
+		hasCap      bool
+		approved    []netip.Prefix
+		wantAllowed []netip.Prefix
+		wantPrimary []netip.Prefix
+		wantAddrs   []netip.Prefix
+	}{
+		{
+			name:        "no-cap_emits_both_families",
+			hasCap:      false,
+			wantAllowed: []netip.Prefix{netip.MustParsePrefix("100.64.0.1/32"), netip.MustParsePrefix("fd7a:115c:a1e0::1/128")},
+			wantAddrs:   []netip.Prefix{netip.MustParsePrefix("100.64.0.1/32"), netip.MustParsePrefix("fd7a:115c:a1e0::1/128")},
+		},
+		{
+			name:        "cap_strips_own_ipv4",
+			hasCap:      true,
+			wantAllowed: []netip.Prefix{netip.MustParsePrefix("fd7a:115c:a1e0::1/128")},
+			wantAddrs:   []netip.Prefix{netip.MustParsePrefix("fd7a:115c:a1e0::1/128")},
+		},
+		{
+			name:     "cap_keeps_advertised_subnet_route",
+			hasCap:   true,
+			approved: []netip.Prefix{subnet},
+			// AllowedIPs is sorted by netip.Prefix.Compare so IPv4
+			// sorts before IPv6.
+			wantAllowed: []netip.Prefix{
+				subnet,
+				netip.MustParsePrefix("fd7a:115c:a1e0::1/128"),
+			},
+			wantPrimary: []netip.Prefix{subnet},
+			wantAddrs:   []netip.Prefix{netip.MustParsePrefix("fd7a:115c:a1e0::1/128")},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			node := &types.Node{
+				GivenName: "ipv4-disabled-node",
+				IPv4:      v4,
+				IPv6:      v6,
+				Hostinfo: &tailcfg.Hostinfo{
+					RoutableIPs: tt.approved,
+				},
+				ApprovedRoutes: tt.approved,
+			}
+
+			var selfCaps tailcfg.NodeCapMap
+			if tt.hasCap {
+				selfCaps = tailcfg.NodeCapMap{NodeAttrDisableIPv4: nil}
+			}
+
+			got, err := node.View().TailNode(
+				0,
+				func(types.NodeID) []netip.Prefix {
+					return tt.approved
+				},
+				&types.Config{Taildrop: types.TaildropConfig{Enabled: true}},
+				selfCaps,
+			)
+			if err != nil {
+				t.Fatalf("TailNode: %v", err)
+			}
+
+			prefStrings := func(ps []netip.Prefix) []string {
+				out := make([]string, len(ps))
+				for i, p := range ps {
+					out[i] = p.String()
+				}
+
+				return out
+			}
+
+			if diff := cmp.Diff(prefStrings(tt.wantAddrs), prefStrings(got.Addresses), cmpopts.EquateEmpty()); diff != "" {
+				t.Errorf("Addresses (-want +got):\n%s", diff)
+			}
+
+			if diff := cmp.Diff(prefStrings(tt.wantAllowed), prefStrings(got.AllowedIPs), cmpopts.EquateEmpty()); diff != "" {
+				t.Errorf("AllowedIPs (-want +got):\n%s", diff)
+			}
+
+			if diff := cmp.Diff(prefStrings(tt.wantPrimary), prefStrings(got.PrimaryRoutes), cmpopts.EquateEmpty()); diff != "" {
+				t.Errorf("PrimaryRoutes (-want +got):\n%s", diff)
+			}
+		})
+	}
+}
+
 func TestNodeExpiry(t *testing.T) {
 	tp := func(t time.Time) *time.Time {
 		return &t
@@ -276,6 +492,7 @@ func TestNodeExpiry(t *testing.T) {
 					return []netip.Prefix{}
 				},
 				&types.Config{Taildrop: types.TaildropConfig{Enabled: true}},
+				nil,
 			)
 			if err != nil {
 				t.Fatalf("nodeExpiry() error = %v", err)