docs/oidc: warn about Authentik's built-in groups scope duplicating claims

Authentik 2025.8 ships a default 'groups' scope that emits the user's
ak_groups as the 'groups' claim automatically. Adding a custom scope
mapping with the same scope_name causes Authentik to concatenate
both emitters' output, producing duplicated group names in the
users.groups column.

Document the symptom and the fix, plus a sibling note that Keycloak
needs the opposite (explicit mapper required to emit anything).

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

@@ -51,6 +51,11 @@ jobs:
         with:
           name: tailscale-head-image
           path: /tmp/artifacts
+      - name: Download tailscale released images
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: tailscale-released-images
+          path: /tmp/artifacts
       - name: Download hi binary
         uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
@@ -86,6 +91,7 @@ jobs:
         run: |
           gunzip -c /tmp/artifacts/headscale-image.tar.gz | docker load
           gunzip -c /tmp/artifacts/tailscale-head-image.tar.gz | docker load
+          gunzip -c /tmp/artifacts/tailscale-released-images.tar.gz | docker load
           if [ -f /tmp/artifacts/postgres-image.tar.gz ]; then
             gunzip -c /tmp/artifacts/postgres-image.tar.gz | docker load
           fi

.github/workflows/test-integration.yaml

@@ -9,6 +9,9 @@ concurrency:
 jobs:
   # build: Builds binaries and Docker images once, uploads as artifacts for reuse.
   # build-postgres: Pulls postgres image separately to avoid Docker Hub rate limits.
+  # build-tailscale-released: Pre-pulls released Tailscale images from ghcr.io
+  # so fork PRs (no DOCKERHUB_USERNAME secret) don't hit Docker Hub rate
+  # limits at test time.
   # sqlite: Runs all integration tests with SQLite backend.
   # postgres: Runs a subset of tests with PostgreSQL to verify database compatibility.
   build:
@@ -150,9 +153,71 @@ jobs:
           name: postgres-image
           path: postgres-image.tar.gz
           retention-days: 10
-  sqlite:
+  build-tailscale-released:
+    runs-on: ubuntu-24.04-arm
     needs: build
     if: needs.build.outputs.files-changed == 'true'
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix', '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+      - name: Force overlay2 storage driver
+        run: |
+          sudo mkdir -p /etc/docker
+          echo '{"storage-driver":"overlay2"}' | sudo tee /etc/docker/daemon.json
+          sudo systemctl restart docker
+          docker version
+      - name: Login to Docker Hub
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_CI_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_CI_TOKEN }}
+        if: env.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
+      - name: List Tailscale versions to pre-pull
+        id: versions
+        run: |
+          versions=$(nix develop --command go run ./cmd/hi list-versions --set=must --exclude=head)
+          echo "versions=${versions}" >> "$GITHUB_OUTPUT"
+          echo "Pre-pulling: ${versions}"
+      - name: Pull Tailscale images
+        run: |
+          # Releases come from ghcr.io (anonymous, unmetered). The
+          # "unstable" floating tag on ghcr.io has been stale since 2022,
+          # so it still needs to come from Docker Hub. xargs -P 0 fans
+          # out one process per tag and returns non-zero if any pull
+          # fails.
+          refs=""
+          for v in ${{ steps.versions.outputs.versions }}; do
+            if [ "${v}" = "unstable" ]; then
+              refs="${refs} tailscale/tailscale:${v}"
+            else
+              refs="${refs} ghcr.io/tailscale/tailscale:${v}"
+            fi
+          done
+          echo "${refs}" | tr ' ' '\n' | grep -v '^$' \
+            | xargs -P 0 -I{} docker pull "{}"
+          echo "REFS=${refs}" >> "$GITHUB_ENV"
+      - name: Save Tailscale images to tarball
+        run: |
+          # Single docker save with all refs: one consistent snapshot, no
+          # parallel-daemon race.
+          docker save ${REFS} | gzip > tailscale-released-images.tar.gz
+          ls -lh tailscale-released-images.tar.gz
+      - name: Upload Tailscale released images
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: tailscale-released-images
+          path: tailscale-released-images.tar.gz
+          retention-days: 10
+  sqlite:
+    needs: [build, build-tailscale-released]
+    if: needs.build.outputs.files-changed == 'true'
     strategy:
       fail-fast: false
       matrix:
@@ -309,7 +374,7 @@ jobs:
       postgres_flag: "--postgres=0"
       database_name: "sqlite"
   postgres:
-    needs: [build, build-postgres]
+    needs: [build, build-postgres, build-tailscale-released]
     if: needs.build.outputs.files-changed == 'true'
     strategy:
       fail-fast: false

.golangci.yaml

@@ -13,6 +13,7 @@ linters:
     - gochecknoinits
     - gocognit
     - godox
+    - gomodguard
     - interfacebloat
     - ireturn
     - lll

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 0.29.0 (202x-xx-xx)
 
-**Minimum supported Tailscale client version: v1.76.0**
+**Minimum supported Tailscale client version: v1.80.0**
 
 ### Tailscale ACL compatibility improvements
 
@@ -306,8 +306,8 @@ connected" routers that maintain their control session but cannot route packets.
 - Remove old migrations for the debian package [#3185](https://github.com/juanfont/headscale/pull/3185)
 - Install `config-example.yaml` as example for the debian package [#3186](https://github.com/juanfont/headscale/pull/3186)
 - Fix user-owned re-registration with zero client expiry and no default storing `0001-01-01 00:00:00` in the database instead of `NULL` [#3199](https://github.com/juanfont/headscale/pull/3199)
-  - Pre-existing rows with `0001-01-01 00:00:00` are not backfilled; they clear themselves the next time the node re-registers
 - Fix `tailscaled` restart on a node with no expiry resetting `NULL` to `0001-01-01 00:00:00` in the database, affecting both tagged and untagged nodes [#3197](https://github.com/juanfont/headscale/pull/3197)
+- Backfill `nodes.expiry` rows persisted by older versions as `0001-01-01 00:00:00` to `NULL`, so nodes upgraded from <0.28 stop reporting as expired [#3284](https://github.com/juanfont/headscale/issues/3284)
 
 ## 0.28.0 (2026-02-04)
 

DEPLOYMENT_GUIDE.md

@@ -1,314 +0,0 @@
-# OIDC Role Mapping Deployment Guide
-
-This guide provides step-by-step instructions for deploying the OIDC role mapping functionality to production environments.
-
-## Pre-Deployment Checklist
-
-### Prerequisites
-- [ ] Headscale 0.23.0+ installation
-- [ ] Headplane 0.6.1+ installation  
-- [ ] OIDC provider with group claims support
-- [ ] Database backup procedures in place
-- [ ] Monitoring and alerting configured
-
-### Compatibility Matrix
-| Component | Minimum Version | Recommended Version |
-|-----------|----------------|-------------------|
-| Headscale | 0.23.0 | Latest stable |
-| Headplane | 0.6.1 | Latest stable |
-| Go | 1.21+ | 1.22+ |
-| Node.js | 18+ | 22+ |
-
-## Phase 1: OIDC Provider Configuration
-
-### Keycloak Setup
-```bash
-# 1. Create new client for Headscale
-Client ID: headscale-client
-Client Protocol: openid-connect
-Access Type: confidential
-Valid Redirect URIs: https://your-headscale.com/oidc/callback
-
-# 2. Configure group mapper
-Name: groups
-Mapper Type: Group Membership
-Token Claim Name: groups
-Add to ID token: ON
-Add to access token: ON
-Add to userinfo: ON
-```
-
-### Azure AD Setup
-```bash
-# 1. App Registration
-Name: Headscale OIDC
-Redirect URI: https://your-headscale.com/oidc/callback
-ID tokens: Enabled
-
-# 2. API Permissions
-Microsoft Graph > GroupMember.Read.All
-Microsoft Graph > User.Read
-
-# 3. Token Configuration
-Add groups claim to ID tokens and access tokens
-```
-
-### Okta Setup
-```bash
-# 1. Application Creation
-Application Type: Web Application
-Grant Types: Authorization Code
-Redirect URIs: https://your-headscale.com/oidc/callback
-
-# 2. Claims Configuration
-Add "groups" claim to ID token and access token
-Filter: Regex .*
-```
-
-## Phase 2: Headscale Deployment
-
-### 1. Database Backup
-```bash
-# SQLite backup
-cp /var/lib/headscale/db.sqlite /var/lib/headscale/db.sqlite.backup.$(date +%Y%m%d)
-
-# PostgreSQL backup
-pg_dump headscale > headscale_backup_$(date +%Y%m%d).sql
-```
-
-### 2. Build with Groups Support
-```bash
-# Clone latest code with OIDC role mapping
-git clone https://github.com/juanfont/headscale.git
-cd headscale
-
-# Apply the OIDC role mapping patches
-# (These would be your committed changes)
-
-# Build binary
-go build -o headscale ./cmd/headscale
-```
-
-### 3. Configuration Update
-```yaml
-# /etc/headscale/config.yaml
-oidc:
-  issuer: "https://your-provider.com/realm"
-  client_id: "headscale-client"
-  client_secret: "your-secret"
-  scope: ["openid", "profile", "email", "groups"]  # Add groups scope
-  extra_params: {}
-  allowed_domains: []
-  allowed_groups: []  # Leave empty to allow all groups
-  allowed_users: []
-  expiry: 180d
-  use_expiry_from_token: false
-```
-
-### 4. Service Deployment
-```bash
-# Stop service
-sudo systemctl stop headscale
-
-# Replace binary
-sudo cp headscale /usr/local/bin/headscale
-sudo chmod +x /usr/local/bin/headscale
-
-# Run migration (automatic on startup)
-sudo systemctl start headscale
-
-# Verify migration completed
-sudo journalctl -u headscale -f | grep "migration"
-```
-
-### 5. Verification
-```bash
-# Check database schema
-sqlite3 /var/lib/headscale/db.sqlite ".schema users"
-# Should show 'groups' column
-
-# Test OIDC login
-headscale users list
-# Test with OIDC user login and verify groups are stored
-```
-
-## Phase 3: Headplane Deployment
-
-### 1. Database Migration
-```bash
-# For development/testing
-pnpm drizzle-kit push
-
-# For production - apply migration manually
-sqlite3 /path/to/headplane.db < drizzle/0003_add_groups_column.sql
-```
-
-### 2. Configuration Update
-```yaml
-# config.yaml
-oidc:
-  enabled: true
-  issuer_url: "https://your-provider.com/realm"
-  client_id: "headplane-client"
-  client_secret: "headplane-secret"
-  scope: "openid profile email groups"  # Add groups scope
-  redirect_uri: "https://your-headplane.com/admin/oidc/callback"
-
-# Optional: Custom role mappings
-role_mapping:
-  owner: ["company-owners", "cto-group"]
-  admin: ["it-admins", "platform-team"]
-  network_admin: ["network-team", "devops"]
-  it_admin: ["helpdesk", "support-team"]
-  auditor: ["compliance", "security-team"]
-```
-
-### 3. Build and Deploy
-```bash
-# Build with role mapping support
-pnpm build
-
-# Deploy (method depends on your setup)
-# Docker example:
-docker build -t headplane:latest .
-docker stop headplane
-docker run -d --name headplane headplane:latest
-```
-
-### 4. Verification
-```bash
-# Test role mapping
-curl -s "http://localhost:3000/admin" | grep -i "login"
-
-# Check logs for role assignments
-docker logs headplane | grep "role.*mapping"
-```
-
-## Phase 4: Testing & Validation
-
-### Automated Tests
-```bash
-# Run comprehensive test suite
-cd docker-dev
-docker compose -f docker-compose-oidc-test.yml up -d
-./test-oidc-roles.sh
-```
-
-### Manual Testing Checklist
-- [ ] Owner login assigns owner role with full capabilities
-- [ ] Admin login assigns admin role with administrative access
-- [ ] Network admin gets network-specific permissions
-- [ ] Auditor gets read-only access
-- [ ] Regular member gets zero capabilities (no UI access)
-- [ ] Group changes in OIDC provider reflect in next login
-- [ ] Existing CLI users continue to work normally
-
-### Monitoring Setup
-```bash
-# Add alerts for authentication failures
-# Monitor user login patterns
-# Track role assignment distributions
-# Alert on unexpected privilege escalations
-```
-
-## Rollback Procedures
-
-### Emergency Rollback
-```bash
-# 1. Stop services
-sudo systemctl stop headscale headplane
-
-# 2. Restore Headscale
-sudo cp /usr/local/bin/headscale.backup /usr/local/bin/headscale
-cp /var/lib/headscale/db.sqlite.backup.* /var/lib/headscale/db.sqlite
-
-# 3. Revert Headplane
-docker run -d --name headplane headplane:previous-version
-
-# 4. Update configs to remove groups scope
-# Edit config files to remove "groups" from OIDC scope
-
-# 5. Restart services
-sudo systemctl start headscale
-```
-
-### Staged Rollback (Recommended)
-```bash
-# 1. Disable OIDC role mapping in config
-role_mapping:
-  enabled: false  # Add this feature flag
-
-# 2. All users get default 'member' role
-# 3. Manually assign roles as needed
-# 4. Plan proper rollback during maintenance window
-```
-
-## Production Considerations
-
-### Security
-- Use strong client secrets for OIDC clients
-- Implement proper certificate management for HTTPS
-- Regular security updates for all components
-- Monitor for suspicious role assignments
-
-### Performance
-- Groups are cached in database to minimize OIDC calls
-- Consider connection pooling for high-traffic environments
-- Monitor database performance with new queries
-
-### Backup Strategy
-```bash
-# Automated backup script
-#!/bin/bash
-DATE=$(date +%Y%m%d_%H%M%S)
-
-# Headscale backup
-cp /var/lib/headscale/db.sqlite /backups/headscale_${DATE}.sqlite
-
-# Headplane backup  
-sqlite3 /var/lib/headplane/db.sqlite ".backup /backups/headplane_${DATE}.sqlite"
-
-# Retain 30 days of backups
-find /backups -name "*.sqlite" -mtime +30 -delete
-```
-
-### Monitoring Metrics
-- OIDC authentication success/failure rates
-- Role assignment distribution
-- Group membership changes
-- API call patterns by role
-- Database query performance
-
-## Troubleshooting
-
-### Common Issues
-
-**Groups not appearing in tokens**
-```bash
-# Check OIDC provider group mapping configuration
-# Verify groups scope is included in request
-# Test with OIDC debugging tools
-```
-
-**Wrong role assignments**
-```bash
-# Check group name mapping in Headplane config
-# Verify case sensitivity and exact matches
-# Review role hierarchy logic
-```
-
-**Database migration failures**
-```bash
-# Check disk space and permissions
-# Verify database isn't locked by other processes
-# Review migration logs for specific errors
-```
-
-**Performance issues**
-```bash
-# Monitor database query performance
-# Check for proper indexing on groups column
-# Review OIDC response times
-```
-
-This deployment guide ensures a smooth transition to OIDC role mapping while maintaining system stability and security.

Dockerfile.derper

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

Dockerfile.integration

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

Dockerfile.tailscale-HEAD

@@ -36,7 +36,7 @@ RUN GOARCH=$TARGETARCH go install -tags="${BUILD_TAGS}" -ldflags="\
       -X tailscale.com/version.gitCommitStamp=$VERSION_GIT_HASH" \
       -v ./cmd/tailscale ./cmd/tailscaled ./cmd/containerboot
 
-FROM alpine:3.22
+FROM alpine:3.23
 # Upstream: ca-certificates ip6tables iptables iproute2
 # Tests: curl python3 (traceroute via BusyBox)
 RUN apk add --no-cache ca-certificates curl ip6tables iptables iproute2 python3

Dockerfile.tailscale-rs

@@ -1,4 +1,4 @@
-FROM rust:1.94-bookworm AS builder
+FROM rust:1.95-trixie AS builder
 
 ARG TAILSCALE_RS_REPO=https://github.com/tailscale/tailscale-rs.git
 ARG TAILSCALE_RS_REF=main
@@ -15,7 +15,7 @@ RUN sed -i '/^axum = \["dep:axum"\]/a insecure-keyfetch = ["ts_control/insecure-
 
 RUN cargo build --release --features axum,insecure-keyfetch --example axum
 
-FROM debian:bookworm-slim
+FROM debian:trixie-slim
 
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \

IMPLEMENTATION_SUMMARY.md

@@ -1,237 +0,0 @@
-# OIDC Role Mapping Implementation Summary
-
-## 🎯 Project Completion Overview
-
-This document summarizes the complete OIDC role mapping implementation for Headscale and Headplane, delivering enterprise-grade role-based access control through OIDC group claims.
-
-## ✅ Implementation Status: COMPLETE
-
-All planned features have been successfully implemented, tested, and documented.
-
-## 🏗️ Architecture Implemented
-
-### Headscale Enhancements
-- **Groups Storage**: Added `groups` TEXT field to users table with JSON storage
-- **OIDC Integration**: Enhanced claims processing to extract and persist groups from OIDC tokens
-- **Helper Methods**: Added `GetGroups()` and `SetGroups()` methods for safe group management
-- **Migration**: Database migration `202509161200` with proper rollback support
-- **Automatic Updates**: Groups are refreshed on every OIDC login
-
-### Headplane Enhancements  
-- **Role Mapping Engine**: Sophisticated group-to-role mapping with configurable hierarchy
-- **Authentication Flow**: Enhanced OIDC callback to assign roles based on group membership
-- **Database Schema**: Added `groups` JSON field to users table
-- **Zero-Trust Security**: New users get `member` role with zero capabilities by default
-- **Dynamic Updates**: User roles and capabilities updated on every login
-
-## 📁 Files Created/Modified
-
-### Headscale Core Changes
-```
-hscontrol/types/users.go              # Added Groups field and helper methods
-hscontrol/db/db.go                    # Added migration for Groups column
-```
-
-### Headplane Core Changes
-```
-app/utils/oidc.ts                     # Enhanced FlowUser interface and group extraction
-app/server/web/roles.ts               # Added mapOidcGroupsToRole function
-app/routes/auth/oidc-callback.ts      # Updated authentication flow with role mapping
-app/server/db/schema.ts               # Added groups field to user schema
-drizzle/0003_add_groups_column.sql    # Database migration for groups column
-```
-
-### Testing Infrastructure
-```
-docker-dev/docker-compose-oidc-test.yml       # Complete test environment
-docker-dev/headscale-config-oidc.yaml         # Headscale OIDC configuration
-docker-dev/headplane-config-oidc.yaml         # Headplane OIDC configuration
-docker-dev/keycloak-config/realm-export.json  # Keycloak test realm
-docker-dev/test-oidc-roles.sh                 # Automated test suite
-docker-dev/validate-implementation.sh         # Implementation validator
-```
-
-### Documentation & Guides
-```
-OIDC_ROLE_MAPPING.md                  # Complete implementation documentation
-DEPLOYMENT_GUIDE.md                   # Production deployment instructions
-monitoring-config.yaml                # Monitoring and alerting configuration
-role-mapping-examples.yaml            # Organization-specific configurations
-IMPLEMENTATION_SUMMARY.md             # This summary document
-```
-
-## 🔐 Security Model Implemented
-
-### Zero-Trust Approach
-- **Default Deny**: New users get `member` role with zero capabilities
-- **Explicit Allow**: Only users with recognized groups get elevated privileges
-- **Dynamic Enforcement**: Role changes take effect immediately on next login
-
-### Role Hierarchy (Highest Privilege Wins)
-1. **Owner** (`owner` role) - Full system access including user management
-2. **Admin** (`admin` role) - Administrative access to all features
-3. **Network Admin** (`network_admin` role) - Network configuration and routing
-4. **IT Admin** (`it_admin` role) - Machine and user management
-5. **Auditor** (`auditor` role) - Read-only access for compliance
-6. **Member** (`member` role) - Zero capabilities (no UI access)
-
-### Group Mapping Examples
-```yaml
-role_mapping:
-  owner: ["ceo", "cto", "headscale-owner"]
-  admin: ["it-admin", "platform-admin", "headscale-admin"]
-  network_admin: ["network-team", "devops", "infrastructure"]
-  it_admin: ["helpdesk", "support-team", "it-staff"]
-  auditor: ["compliance", "audit-team", "security"]
-```
-
-## 🧪 Testing Capabilities
-
-### Automated Testing
-- **Docker Environment**: Complete test stack with Keycloak, Headscale, and Headplane
-- **Test Users**: Pre-configured users for each role level
-- **Validation Scripts**: Comprehensive implementation validation
-- **Integration Tests**: End-to-end OIDC flow testing
-
-### Manual Testing Scenarios
-- Owner login with full administrative access
-- Admin login with restricted owner capabilities
-- Network admin with specialized permissions
-- Auditor with read-only access
-- Regular member with zero UI access
-- Group membership changes reflecting in real-time
-
-## 🚀 Deployment Readiness
-
-### Production Requirements Met
-- **Database Migrations**: Safe, reversible schema changes
-- **Configuration Templates**: Ready-to-use configs for major OIDC providers
-- **Monitoring Setup**: Comprehensive metrics and alerting
-- **Documentation**: Complete deployment and operational guides
-- **Rollback Procedures**: Safe fallback mechanisms
-
-### Provider Compatibility
-- ✅ **Keycloak** - Fully tested with realm configuration
-- ✅ **Azure AD** - Group claims and role mapping ready
-- ✅ **Okta** - Compatible with group membership claims
-- ✅ **Generic OIDC** - Standards-compliant implementation
-
-## 📊 Key Features Delivered
-
-### Enterprise Integration
-- **SSO Compatibility**: Works with any OIDC-compliant identity provider
-- **Group Synchronization**: Automatic role updates based on identity provider changes
-- **Centralized Management**: User access controlled through existing identity systems
-- **Audit Trail**: Complete logging of role assignments and changes
-
-### Operational Excellence
-- **Zero Manual Work**: Automatic role assignment based on group membership
-- **Dynamic Access Control**: Permissions update immediately on login
-- **Consistent Enforcement**: Role-based access control across all features
-- **Graceful Degradation**: Fallback to manual role assignment if needed
-
-### Security Hardening
-- **Principle of Least Privilege**: Users get minimum required access
-- **Regular Re-validation**: Groups checked on every login
-- **Defense in Depth**: Multiple validation layers for role assignment
-- **Audit Compliance**: Comprehensive logging for regulatory requirements
-
-## 🔧 Technical Achievements
-
-### Code Quality
-- **Type Safety**: Full TypeScript support in Headplane
-- **Error Handling**: Robust error handling and graceful degradation
-- **Performance**: Efficient JSON storage and parsing for groups
-- **Maintainability**: Clear separation of concerns and modular design
-
-### Database Design
-- **Scalable Schema**: JSON storage for flexible group management
-- **Migration Safety**: Backward-compatible database changes
-- **Data Integrity**: Proper constraints and validation
-- **Performance**: Indexed queries for efficient lookups
-
-### Integration Patterns
-- **Standards Compliance**: Full OIDC specification adherence
-- **Provider Agnostic**: Works with any standards-compliant OIDC provider
-- **Extensible Design**: Easy to add new roles and capabilities
-- **Configuration Driven**: No code changes needed for new organizations
-
-## 🎯 Business Value Delivered
-
-### Security Improvements
-- **Reduced Attack Surface**: Automated privilege assignment reduces manual errors
-- **Compliance Ready**: Audit trails and role-based access for regulatory requirements
-- **Identity Integration**: Leverage existing security policies and procedures
-- **Centralized Control**: Single source of truth for user permissions
-
-### Operational Efficiency
-- **Reduced Admin Overhead**: Automatic user onboarding and role assignment
-- **Faster Onboarding**: New users get appropriate access immediately
-- **Consistent Enforcement**: No manual role assignment inconsistencies
-- **Simplified Management**: Use existing identity provider groups
-
-### Enterprise Readiness
-- **Scalable Architecture**: Supports large organizations with complex role structures
-- **Multi-Provider Support**: Not locked into specific identity provider
-- **Flexible Configuration**: Easily adapted to different organizational structures
-- **Production Monitoring**: Complete observability and alerting
-
-## 🚦 Current Status
-
-### ✅ COMPLETED
-- [x] Headscale Groups field implementation
-- [x] Database migrations for both systems
-- [x] OIDC group extraction and storage
-- [x] Headplane role mapping engine
-- [x] Authentication flow integration
-- [x] Comprehensive testing infrastructure
-- [x] Complete documentation suite
-- [x] Deployment guides and procedures
-- [x] Monitoring and alerting configuration
-- [x] Validation and testing scripts
-
-### 🎯 READY FOR
-- Production deployment to staging environment
-- Integration testing with organizational OIDC provider
-- User acceptance testing with real user groups
-- Performance testing under load
-- Security audit and penetration testing
-
-## 📋 Next Steps for Production
-
-1. **Staging Deployment**
-   - Deploy to staging environment
-   - Configure with organizational OIDC provider
-   - Test with real user groups and permissions
-
-2. **User Acceptance Testing**
-   - Validate role mappings with actual user groups
-   - Test edge cases and error scenarios
-   - Verify audit logging and compliance features
-
-3. **Production Rollout**
-   - Deploy during maintenance window
-   - Monitor authentication flows and role assignments
-   - Gradually migrate users from manual to automatic role assignment
-
-4. **Ongoing Optimization**
-   - Fine-tune role mappings based on usage patterns
-   - Optimize performance based on production metrics
-   - Enhance monitoring and alerting as needed
-
-## 🏆 Success Metrics
-
-The implementation successfully addresses the original security gap where OIDC users were receiving 'member' role with zero capabilities regardless of their authorization level. Now:
-
-- **100% Automated Role Assignment**: Users receive appropriate roles based on group membership
-- **Zero Trust Security**: New users get minimal access until proper groups are verified
-- **Enterprise Integration**: Seamless integration with existing identity providers
-- **Production Ready**: Complete testing, documentation, and deployment procedures
-
-This implementation transforms Headscale and Headplane from a basic VPN solution into an enterprise-grade, role-based access control system that integrates seamlessly with organizational identity management infrastructure.
-
----
-
-**Implementation Team**: Claude Code AI Assistant  
-**Completion Date**: September 16, 2025  
-**Status**: ✅ PRODUCTION READY

MIGRATION_COMPATIBILITY_PLAN.md

@@ -1,318 +0,0 @@
-# OIDC Groups Migration and Compatibility Plan
-
-## Overview
-
-This document outlines the migration strategy and backward compatibility considerations for the OIDC groups feature implementation.
-
-## Database Migration Strategy
-
-### Migration Details
-- **Migration ID**: `202509161200`
-- **Operation**: Add `groups` TEXT column to `users` table
-- **Default Value**: Empty string (`""`)
-- **Rollback Support**: Full rollback capability
-
-### Safety Measures
-
-#### Pre-Migration Validation
-```sql
--- Check current user count and table structure
-SELECT COUNT(*) FROM users;
-DESCRIBE users;
-```
-
-#### Migration Steps
-1. **Add Column**: `ALTER TABLE users ADD COLUMN groups TEXT DEFAULT '';`
-2. **Verify Addition**: Check column exists and has correct type
-3. **Index Creation**: No additional indexes needed initially
-4. **Data Validation**: Verify all existing users have empty groups field
-
-#### Rollback Procedure
-```sql
--- Safe rollback - removes groups column
-ALTER TABLE users DROP COLUMN groups;
-```
-
-### Migration Testing
-
-#### Unit Tests
-```go
-func TestGroupsMigration(t *testing.T) {
-    // Test migration up
-    // Test rollback  
-    // Test with existing data
-    // Test column constraints
-}
-```
-
-#### Integration Tests
-- Migration on database with existing users
-- Rollback with populated groups data
-- Performance impact measurement
-- Concurrent operation safety
-
-## Backward Compatibility Matrix
-
-### API Compatibility
-
-| Component | Before Groups | After Groups | Compatible |
-|-----------|---------------|--------------|------------|
-| User API Response | No groups field | Optional groups field | ✅ |
-| OIDC Login Flow | Standard flow | Groups extraction added | ✅ |
-| Database Schema | 10 columns | 11 columns | ✅ |
-| Configuration | No groups config | Optional groups config | ✅ |
-
-### Client Compatibility
-
-#### Existing Headscale Clients
-- ✅ **REST API Clients**: Groups field ignored if not expected
-- ✅ **gRPC Clients**: Protobuf backward compatibility maintained
-- ✅ **CLI Tools**: No impact on existing commands
-- ✅ **Terraform Provider**: Groups field optional in responses
-
-#### Management Interfaces
-- ✅ **Headplane**: Ready for groups integration
-- ✅ **Other UIs**: Groups field can be ignored safely
-- ✅ **Custom Dashboards**: No breaking changes to existing queries
-
-### Configuration Compatibility
-
-#### Existing Configurations
-```yaml
-# This continues to work unchanged
-oidc:
-  issuer: "https://your-provider.com"
-  client_id: "your-client-id"
-  client_secret: "your-secret"
-```
-
-#### Enhanced Configuration (Optional)
-```yaml
-# Groups extraction is entirely optional
-oidc:
-  issuer: "https://your-provider.com"
-  client_id: "your-client-id"
-  client_secret: "your-secret"
-  extra_params:
-    groups_claim: "groups"  # Optional groups extraction
-```
-
-## Deployment Strategy
-
-### Phase 1: Infrastructure Preparation
-1. **Database Backup**: Full backup before migration
-2. **Monitoring Setup**: Enhanced logging for migration tracking
-3. **Rollback Plan**: Tested rollback procedures
-4. **Staging Validation**: Full testing in staging environment
-
-### Phase 2: Migration Execution
-1. **Maintenance Window**: Schedule appropriate downtime
-2. **Migration Execution**: Run database migration
-3. **Verification**: Confirm migration success
-4. **Service Restart**: Restart Headscale with new code
-
-### Phase 3: Feature Activation
-1. **Configuration Update**: Add groups configuration if desired
-2. **OIDC Provider**: Configure groups claims
-3. **Testing**: Verify groups extraction working
-4. **Monitoring**: Watch for any issues
-
-### Phase 4: Validation
-1. **User Login Tests**: Verify existing users can still login
-2. **Groups Extraction**: Verify new logins extract groups
-3. **API Responses**: Verify API clients handle groups field
-4. **Performance**: Monitor for any performance impact
-
-## Rollback Procedures
-
-### Immediate Rollback (Same Session)
-If issues detected during migration:
-```bash
-# Rollback database migration
-headscale migration rollback 202509161200
-
-# Restart with previous code
-systemctl restart headscale
-```
-
-### Delayed Rollback (After Deployment)
-If issues detected after feature deployment:
-```bash
-# 1. Disable groups extraction in config
-# Remove or comment out groups_claim configuration
-
-# 2. Restart service
-systemctl restart headscale
-
-# 3. (Optional) Rollback database if needed
-headscale migration rollback 202509161200
-```
-
-### Emergency Rollback
-Critical issues requiring immediate fix:
-```bash
-# Emergency config to disable groups
-echo "HEADSCALE_DISABLE_GROUPS=true" >> /etc/headscale/env
-systemctl restart headscale
-
-# Full rollback when ready
-git checkout previous-version
-headscale migration rollback 202509161200
-```
-
-## Risk Mitigation
-
-### Low-Risk Design Decisions
-
-#### Optional Feature
-- Groups extraction only happens if configured
-- Existing OIDC flows continue unchanged
-- No impact on non-OIDC authentication
-
-#### Graceful Degradation
-```go
-// Groups parsing with error handling
-func (u *User) GetGroups() []string {
-    if u.Groups == "" {
-        return []string{}  // Safe empty default
-    }
-    
-    var groups []string
-    if err := json.Unmarshal([]byte(u.Groups), &groups); err != nil {
-        log.Error().Err(err).Msg("Failed to unmarshal user groups")
-        return []string{}  // Graceful failure
-    }
-    
-    return groups
-}
-```
-
-#### Database Safety
-- Column addition is non-destructive
-- Default values ensure consistency
-- No foreign key constraints
-- No unique constraints that could conflict
-
-### Medium-Risk Considerations
-
-#### Performance Impact
-- **Risk**: Additional JSON parsing on user operations
-- **Mitigation**: Lazy loading, caching, minimal parsing overhead
-- **Monitoring**: Response time metrics for user operations
-
-#### Storage Growth
-- **Risk**: Groups data increases user table size
-- **Mitigation**: JSON is compact, groups typically small
-- **Monitoring**: Database size growth tracking
-
-#### OIDC Provider Compatibility
-- **Risk**: Different providers return groups differently
-- **Mitigation**: Flexible claims configuration, error handling
-- **Testing**: Multi-provider integration tests
-
-### Risk Monitoring
-
-#### Key Metrics
-- Migration success/failure rates
-- User login success rates before/after
-- API response times
-- Groups extraction success rates
-- Database query performance
-
-#### Alert Conditions
-- Migration failures
-- Increased login failures
-- API response time degradation
-- Groups parsing errors above threshold
-
-## Testing Strategy
-
-### Pre-Migration Testing
-
-#### Unit Tests
-- Database migration up/down
-- Groups parsing/serialization
-- OIDC claims extraction
-- Error handling scenarios
-
-#### Integration Tests
-- Full OIDC flow with groups
-- Multiple provider compatibility
-- Migration with existing data
-- API responses with/without groups
-
-#### Performance Tests
-- User login latency impact
-- Database query performance
-- Memory usage with groups data
-- Concurrent operations
-
-### Post-Migration Testing
-
-#### Smoke Tests
-- Existing users can login
-- New users get groups extracted
-- API endpoints respond correctly
-- Admin operations work normally
-
-#### Regression Tests
-- All existing integration tests pass
-- No functional regressions
-- Configuration compatibility
-- CLI tool compatibility
-
-## Documentation Updates
-
-### Admin Documentation
-- Migration procedures
-- Rollback instructions
-- Troubleshooting guide
-- Configuration examples
-
-### API Documentation
-- Groups field in user responses
-- OIDC configuration options
-- Error conditions and handling
-- Migration impact notes
-
-### Deployment Documentation
-- Version compatibility matrix
-- Upgrade procedures
-- Monitoring recommendations
-- Security considerations
-
-## Success Criteria
-
-### Migration Success
-- ✅ Database migration completes without errors
-- ✅ All existing functionality preserved
-- ✅ No performance degradation > 5%
-- ✅ Groups extraction works when configured
-
-### Backward Compatibility Success
-- ✅ Existing OIDC configurations continue working
-- ✅ API clients handle responses correctly
-- ✅ No breaking changes to public interfaces
-- ✅ Rollback procedures tested and verified
-
-### Feature Success
-- ✅ Groups extracted from configured OIDC providers
-- ✅ Groups data stored and retrieved correctly
-- ✅ Integration with Headplane works as designed
-- ✅ Documentation complete and accurate
-
-## Long-term Maintenance
-
-### Ongoing Responsibilities
-- Monitor groups extraction accuracy
-- Update provider-specific documentation
-- Maintain test coverage for new providers
-- Address compatibility issues as they arise
-
-### Future Enhancements
-- Group hierarchy support
-- Custom claims mapping
-- Groups-based ACL rules
-- Performance optimizations
-
-This plan ensures the OIDC groups feature can be safely deployed with minimal risk to existing Headscale installations while providing a clear path forward for enhanced functionality.

OIDC_ROLE_MAPPING.md

@@ -1,204 +0,0 @@
-# OIDC Role Mapping Implementation
-
-This document describes the complete OIDC role mapping implementation for Headscale and Headplane, enabling enterprise-grade role-based access control through OIDC group claims.
-
-## Overview
-
-The implementation bridges OIDC group membership with Headplane role assignments, automatically mapping users to appropriate roles based on their group membership in the identity provider (e.g., Keycloak, Azure AD, Okta).
-
-## Architecture
-
-### 1. Headscale Changes
-
-#### Database Schema Updates
-- **New field**: `groups` column added to `users` table 
-- **Type**: `TEXT` field storing JSON array of group names
-- **Migration**: `202509161200` adds the column with proper rollback support
-
-#### OIDC Integration Enhancement
-- **Groups extraction**: Enhanced `FromClaim()` method to extract and store OIDC groups
-- **Claims processing**: Groups are extracted from both ID token and UserInfo endpoint
-- **Storage**: Groups are persisted as JSON in the database on every login
-
-#### Key Files Modified
-- `hscontrol/types/users.go`: Added Groups field and helper methods
-- `hscontrol/oidc.go`: Enhanced claims processing (groups already extracted)
-- `hscontrol/db/db.go`: Added database migration
-
-#### Helper Methods Added
-```go
-// GetGroups returns user's groups as a slice of strings
-func (u *User) GetGroups() []string
-
-// SetGroups stores user's groups as JSON in database  
-func (u *User) SetGroups(groups []string)
-```
-
-### 2. Headplane Changes
-
-#### Role Mapping System
-- **Function**: `mapOidcGroupsToRole()` maps OIDC groups to Headplane roles
-- **Hierarchy**: Roles are assigned based on highest privilege group membership
-- **Configurable**: Support for custom group-to-role mappings
-
-#### Database Schema Updates
-- **New field**: `groups` column added to `users` table (JSON array)
-- **Migration**: `0003_add_groups_column.sql` 
-
-#### Authentication Flow Enhancement
-- **Groups extraction**: Enhanced `FlowUser` interface to include groups
-- **Role assignment**: Automatic role assignment based on group mapping during login
-- **Persistence**: Groups and capabilities are updated on every login
-
-#### Key Files Modified
-- `app/utils/oidc.ts`: Enhanced FlowUser interface and group extraction
-- `app/server/web/roles.ts`: Added group-to-role mapping function
-- `app/routes/auth/oidc-callback.ts`: Updated authentication flow
-- `app/server/db/schema.ts`: Added groups field to schema
-
-#### Default Group Mappings
-| Group Pattern | Headplane Role | Capabilities |
-|---------------|----------------|--------------|
-| `owner`, `headplane-owner` | `owner` | Full system access |
-| `admin*`, `headplane-admin` | `admin` | Administrative access |
-| `network*`, `headplane-network` | `network_admin` | Network configuration |
-| `it*`, `headplane-it` | `it_admin` | IT operations |
-| `audit*`, `headplane-audit` | `auditor` | Read-only access |
-| Other groups | `member` | No UI access (zero capabilities) |
-
-## Configuration
-
-### Headscale OIDC Configuration
-```yaml
-oidc:
-  issuer: "https://your-provider.com/realm"
-  client_id: "headscale-client"
-  client_secret: "your-secret"
-  scope: ["openid", "profile", "email", "groups"]
-  # Groups will be automatically extracted and stored
-```
-
-### Headplane OIDC Configuration  
-```yaml
-oidc:
-  enabled: true
-  issuer_url: "https://your-provider.com/realm"
-  client_id: "headplane-client"
-  client_secret: "headplane-secret"
-  scope: "openid profile email groups"
-  
-# Optional: Custom group-to-role mappings
-role_mapping:
-  owner: ["company-owners", "headplane-owners"]
-  admin: ["company-admins", "it-admins"]
-  network_admin: ["network-team"]
-  auditor: ["audit-team", "compliance"]
-```
-
-## Testing Setup
-
-### Docker Compose Environment
-The implementation includes a complete testing environment with:
-
-- **Keycloak**: OIDC provider with preconfigured realm and test users
-- **PostgreSQL**: Database for Keycloak
-- **Headscale**: Built with OIDC groups support
-- **Headplane**: Configured for role mapping
-
-### Test Users
-| Email | Password | Groups | Expected Role |
-|-------|----------|--------|---------------|
-| `owner@example.com` | `password123` | `headscale-owner` | `owner` |
-| `admin@example.com` | `password123` | `headscale-admin` | `admin` |
-| `network@example.com` | `password123` | `headscale-network` | `network_admin` |
-| `auditor@example.com` | `password123` | `headscale-audit` | `auditor` |
-| `member@example.com` | `password123` | `headscale-member` | `member` |
-
-### Running Tests
-```bash
-cd docker-dev
-docker compose -f docker-compose-oidc-test.yml up -d
-./test-oidc-roles.sh
-```
-
-### Manual Testing
-1. **Keycloak Admin**: http://localhost:8280 (admin/admin)
-2. **Headplane UI**: http://localhost:3000/admin
-3. Test login with different users to verify role assignments
-
-## Security Considerations
-
-### Capabilities Model
-- **Zero-trust**: New users get `member` role with zero capabilities by default
-- **Explicit mapping**: Only users with recognized groups get elevated privileges
-- **Dynamic updates**: User roles are updated on every login based on current group membership
-
-### Group Validation
-- **Sanitization**: Groups are filtered to ensure they are strings
-- **Multiple sources**: Groups extracted from both ID token and UserInfo endpoint
-- **Fallback handling**: Graceful handling when no groups are provided
-
-### API Key Management
-- **Per-user keys**: Each OIDC user should have individual API keys (future enhancement)
-- **Shared key limitation**: Current implementation uses shared API key for simplicity
-
-## Migration Path
-
-### Existing Deployments
-1. **Backup databases**: Both Headscale and Headplane databases
-2. **Deploy Headscale changes**: Run migration `202509161200`
-3. **Deploy Headplane changes**: Run migration `0003_add_groups_column.sql`
-4. **Update configurations**: Add OIDC group scope and role mappings
-5. **Test with non-privileged user**: Verify role mapping works correctly
-
-### Rollback Procedure
-1. **Headscale**: Rollback migration removes groups column
-2. **Headplane**: Remove groups column and revert OIDC callback logic
-3. **Configuration**: Remove groups from OIDC scope
-
-## Benefits
-
-### Enterprise Integration
-- **SSO Compatibility**: Works with any OIDC-compliant provider
-- **Group Synchronization**: Automatic role updates based on identity provider changes
-- **Centralized Management**: User access controlled through existing identity systems
-
-### Operational Advantages
-- **Reduced Manual Work**: No manual role assignment required
-- **Dynamic Access**: User permissions update automatically on login
-- **Audit Trail**: Clear mapping between identity provider groups and system roles
-
-### Security Improvements
-- **Principle of Least Privilege**: Users get minimum required access
-- **Consistent Enforcement**: Role-based access control across all features
-- **Identity Provider Integration**: Leverage existing security policies
-
-## Future Enhancements
-
-### Planned Improvements
-1. **Individual API Keys**: Per-user API key generation and management
-2. **Group Hierarchies**: Support for nested group inheritance
-3. **Custom Capabilities**: Fine-grained permission customization per group
-4. **Audit Logging**: Enhanced logging of role assignments and changes
-5. **UI Role Management**: Administrative interface for role mapping configuration
-
-### Integration Opportunities
-1. **SCIM Support**: Automatic user provisioning and deprovisioning
-2. **Just-in-Time Access**: Temporary role elevation based on approval workflows
-3. **External Authorization**: Integration with external policy engines (OPA, etc.)
-
-## Troubleshooting
-
-### Common Issues
-1. **Missing Groups**: Ensure OIDC provider includes groups in claims
-2. **Wrong Roles**: Check group name matching and mapping configuration
-3. **No Access**: Verify user has at least one recognized group
-4. **Token Issues**: Check OIDC scope includes "groups"
-
-### Debug Steps
-1. **Check Headscale logs**: Verify groups are being extracted from OIDC claims
-2. **Inspect database**: Verify groups are stored in users table
-3. **Review Headplane logs**: Check role mapping function execution
-4. **Test OIDC flow**: Use OIDC debugging tools to inspect token claims
-
-This implementation provides a robust foundation for enterprise OIDC integration while maintaining security and operational efficiency.

PR_TEMPLATE_OIDC_GROUPS.md

@@ -1,185 +0,0 @@
-# Add OIDC Groups Support for Role-Based Access Control
-
-## Description
-
-This PR implements OIDC groups extraction and storage in Headscale, enabling role-based access control when integrated with management interfaces like Headplane.
-
-**Fixes #XXX** (issue number would go here after discussion)
-
-## Checklist
-
-- [x] have read the [CONTRIBUTING.md](./CONTRIBUTING.md) file
-- [x] raised a GitHub issue or discussed it on the projects chat beforehand
-- [x] added unit tests
-- [x] added integration tests  
-- [x] updated documentation if needed
-- [x] updated CHANGELOG.md
-
-## Changes Made
-
-### Core Implementation
-- **Database Schema**: Added `groups` TEXT field to `users` table with JSON storage
-- **OIDC Integration**: Enhanced `User.FromClaim()` to extract groups from OIDC tokens
-- **Helper Methods**: Added `GetGroups()` and `SetGroups()` for safe group management
-- **Migration**: Added migration `202509161200` with proper rollback support
-
-### Files Modified
-- `hscontrol/types/users.go` - Added Groups field and helper methods
-- `hscontrol/db/db.go` - Added database migration
-- `config-example.yaml` - Updated with groups claim configuration
-- `docs/ref/oidc.md` - Enhanced OIDC documentation
-
-### Files Added
-- `docs/ref/api-groups.md` - API documentation for groups functionality
-- `integration/oidc_groups_test.go` - Integration tests for groups extraction
-- Various deployment and monitoring documentation
-
-## Technical Details
-
-### Database Changes
-- **Non-breaking**: New `groups` column added with default empty value
-- **Backward Compatible**: Existing users continue to work without groups
-- **Rollback Support**: Migration includes proper rollback function
-- **Storage Format**: Groups stored as JSON array for flexibility
-
-### OIDC Integration
-- **Claims Extraction**: Groups extracted from both ID token and UserInfo endpoint
-- **Provider Support**: Works with Keycloak, Azure AD, Okta, and other OIDC providers
-- **Automatic Updates**: Groups refreshed on every OIDC login
-- **Error Handling**: Graceful fallback when groups claims are missing
-
-### API Changes
-- **New Methods**: `User.GetGroups()` and `User.SetGroups()`
-- **JSON Response**: Groups included in user API responses when present
-- **Backward Compatible**: No breaking changes to existing API endpoints
-
-## Testing
-
-### Unit Tests
-- [x] Groups JSON marshaling/unmarshaling
-- [x] Helper method functionality  
-- [x] Migration up/down operations
-- [x] OIDC claims processing with/without groups
-
-### Integration Tests
-- [x] End-to-end OIDC flow with groups extraction
-- [x] Database migration testing
-- [x] Multiple OIDC provider compatibility
-- [x] Groups persistence across login sessions
-
-### Test Coverage
-- Database operations: 100%
-- OIDC integration: 95%
-- Helper methods: 100%
-- Migration logic: 100%
-
-## Security Considerations
-
-### Data Protection
-- **Input Validation**: Groups claims validated before storage
-- **SQL Injection**: Using GORM parameterized queries
-- **JSON Security**: Safe JSON marshaling with error handling
-- **Size Limits**: Groups field has reasonable size constraints
-
-### Access Control
-- **Read-Only Storage**: Headscale only stores groups, doesn't interpret roles
-- **External Integration**: Role mapping handled by external systems (Headplane)
-- **Audit Trail**: Groups changes logged for security monitoring
-
-## Performance Impact
-
-### Database Performance
-- **Minimal Impact**: Single TEXT column addition
-- **Indexed Access**: No additional indexes needed for groups field
-- **Migration Speed**: Fast migration with no data transformation
-
-### Runtime Performance
-- **Login Overhead**: Minimal additional processing during OIDC flow
-- **Memory Usage**: Negligible increase per user
-- **API Response**: Small increase in response size when groups present
-
-## Backward Compatibility
-
-### Database Compatibility
-- ✅ **Existing Users**: Continue to work without groups
-- ✅ **API Responses**: Existing clients unaffected by new groups field
-- ✅ **Configuration**: OIDC continues to work without groups configuration
-- ✅ **Rollback**: Migration can be safely rolled back
-
-### Configuration Compatibility
-- ✅ **Optional Feature**: Groups extraction is optional
-- ✅ **Existing Configs**: Current OIDC configurations remain valid
-- ✅ **Provider Agnostic**: Works with or without groups claims
-
-## Documentation Updates
-
-### User Documentation
-- Updated OIDC configuration guide with groups setup
-- Added provider-specific configuration examples
-- Enhanced troubleshooting guide for groups issues
-
-### API Documentation
-- Documented new groups field in user responses
-- Added examples of groups data format
-- Updated OpenAPI specification
-
-### Deployment Documentation
-- Added production deployment considerations
-- Included monitoring and alerting recommendations
-- Provided rollback procedures
-
-## Future Considerations
-
-### Extensibility
-- **Role Mapping**: Foundation for future role-based features
-- **Group Hierarchies**: Schema supports nested group structures
-- **Custom Claims**: Extensible to other OIDC claims beyond groups
-
-### Integration Points
-- **Headplane Integration**: Ready for role-based access control
-- **API Extensions**: Groups can be exposed via REST API
-- **Webhook Support**: Groups changes can trigger webhooks
-
-## Monitoring and Observability
-
-### Metrics Added
-- `headscale_oidc_groups_extracted_total` - Groups extraction success/failure
-- `headscale_users_with_groups_total` - Users with group assignments
-- Migration metrics for deployment monitoring
-
-### Logging Enhancements
-- Groups extraction success/failure logging
-- Migration progress logging
-- Error logging for troubleshooting
-
-## Risk Assessment
-
-### Low Risk
-- **Backward Compatible**: No breaking changes
-- **Optional Feature**: Can be disabled if issues arise
-- **Rollback Ready**: Safe migration rollback available
-
-### Mitigation Strategies
-- **Staged Rollout**: Can be deployed incrementally
-- **Feature Flags**: Groups processing can be disabled via config
-- **Monitoring**: Comprehensive metrics for early issue detection
-
-## Maintenance Commitment
-
-The contributor commits to:
-- **Bug Fixes**: Address issues in groups functionality for 12 months
-- **Documentation**: Maintain and update documentation as needed
-- **Community Support**: Help users with groups configuration issues
-- **Testing**: Maintain and extend test coverage as Headscale evolves
-
-## Related Work
-
-### Upstream Compatibility
-- **Tailscale Protocol**: No changes to Tailscale protocol
-- **Client Compatibility**: No client-side changes required
-- **OIDC Standards**: Follows standard OIDC groups claim practices
-
-### External Integration
-- **Headplane Ready**: Implementation designed for Headplane integration
-- **Generic Design**: Can be used by other management interfaces
-- **API First**: Groups data available via standard Headscale APIs

cmd/hi/listversions.go

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

cmd/hi/main.go

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

docker-dev/Makefile

@@ -1,105 +0,0 @@
-# Makefile for Headscale Docker development environment
-
-.PHONY: help
-help: ## Show this help message
-	@echo "Headscale Docker Development Environment"
-	@echo ""
-	@echo "Usage: make [target]"
-	@echo ""
-	@echo "Targets:"
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-20s %s\n", $$1, $$2}'
-
-.PHONY: up
-up: ## Start all services
-	docker compose up -d
-	@echo "Waiting for Headscale to be healthy..."
-	@sleep 10
-	@make setup
-
-.PHONY: down
-down: ## Stop and remove all services
-	docker compose down
-
-.PHONY: clean
-clean: down ## Clean up everything including volumes
-	docker compose down -v
-	rm -f .env
-
-.PHONY: setup
-setup: ## Setup Headscale users and generate auth keys
-	./scripts/setup-headscale.sh
-
-.PHONY: restart-clients
-restart-clients: ## Restart Tailscale clients
-	docker compose restart tailscale-client1 tailscale-client2
-
-.PHONY: logs
-logs: ## Show logs from all services
-	docker compose logs -f
-
-.PHONY: logs-headscale
-logs-headscale: ## Show Headscale server logs
-	docker compose logs -f headscale
-
-.PHONY: logs-clients
-logs-clients: ## Show Tailscale client logs
-	docker compose logs -f tailscale-client1 tailscale-client2
-
-.PHONY: status
-status: ## Show status of all nodes
-	@echo "=== Headscale Node Status ==="
-	@docker exec headscale-server headscale nodes list || echo "No nodes registered yet"
-	@echo ""
-	@echo "=== Client1 Status ==="
-	@docker exec tailscale-client1 tailscale status 2>/dev/null || echo "Client1 not ready"
-	@echo ""
-	@echo "=== Client2 Status ==="
-	@docker exec tailscale-client2 tailscale status 2>/dev/null || echo "Client2 not ready"
-
-.PHONY: ping-test
-ping-test: ## Test connectivity between clients
-	@echo "Testing connectivity from Client1 to Client2..."
-	@docker exec tailscale-client1 tailscale ping client2 || echo "Ping failed - clients may not be connected yet"
-	@echo ""
-	@echo "Testing connectivity from Client2 to Client1..."
-	@docker exec tailscale-client2 tailscale ping client1 || echo "Ping failed - clients may not be connected yet"
-
-.PHONY: shell-headscale
-shell-headscale: ## Open shell in Headscale container
-	docker exec -it headscale-server /bin/sh
-
-.PHONY: shell-client1
-shell-client1: ## Open shell in Client1 container
-	docker exec -it tailscale-client1 /bin/sh
-
-.PHONY: shell-client2
-shell-client2: ## Open shell in Client2 container
-	docker exec -it tailscale-client2 /bin/sh
-
-.PHONY: build-local
-build-local: ## Build Headscale from local source
-	cd .. && docker build -t headscale:local -f Dockerfile .
-	@echo "To use local build, update docker-compose.yml:"
-	@echo "  image: headscale:local"
-
-.PHONY: register-manual
-register-manual: ## Show manual registration instructions
-	@echo "=== Manual Node Registration ==="
-	@echo ""
-	@echo "1. Get node key from client:"
-	@echo "   docker exec tailscale-client1 tailscale up --login-server=http://headscale:8080"
-	@echo ""
-	@echo "2. Register the node:"
-	@echo "   docker exec headscale-server headscale nodes register --user testuser --key <nodekey>"
-	@echo ""
-	@echo "3. Verify registration:"
-	@echo "   make status"
-
-.PHONY: test-web
-test-web: ## Test web server connectivity through Tailscale
-	@echo "Starting web server test..."
-	@echo "Creating test content..."
-	@mkdir -p www
-	@echo "<h1>Hello from Headscale Test Environment!</h1>" > www/index.html
-	@echo "Testing HTTP access from Client1 to web server..."
-	@docker exec tailscale-client1 wget -q -O- http://webserver || echo "Web test failed"

docker-dev/NETWORK-ARCHITECTURE.md

@@ -1,217 +0,0 @@
-# Network Architecture Documentation
-
-This document provides a detailed explanation of the networking setup in the Headscale Docker development environment.
-
-## Overview
-
-The setup uses **two distinct networking layers** that work together to provide a complete Tailscale network simulation:
-
-1. **Docker Bridge Network** - Infrastructure layer for container communication
-2. **Tailscale Overlay Network** - Encrypted VPN layer for secure data transmission
-
-## Layer 1: Docker Bridge Network
-
-### Network Configuration
-- **Subnet**: `10.99.0.0/24`
-- **Gateway**: `10.99.0.1`
-- **Network Name**: `headscale-dev_headscale-net`
-
-### Container IP Assignments
-| Container | IP Address | Role |
-|-----------|------------|------|
-| headscale-server | `10.99.0.10` | Control plane server |
-| tailscale-client1 | `10.99.0.21` | Tailscale node 1 |
-| tailscale-client2 | `10.99.0.22` | Tailscale node 2 |
-| test-webserver | `10.99.0.30` | HTTP test server |
-
-### Port Mappings
-
-#### Headscale Server
-| Host Port | Container Port | Service |
-|-----------|----------------|---------|
-| 8180 | 8080 | HTTP API |
-| 9090 | 9090 | Metrics |
-| 50443 | 50443 | gRPC |
-
-**Note**: Port 8180 is used on the host instead of 8080 to avoid conflicts with other services.
-
-#### Other Services
-| Container | Exposed Ports | Purpose |
-|-----------|---------------|---------|
-| test-webserver | 80 (internal only) | HTTP test content |
-| tailscale-client1 | None exposed | VPN endpoint |
-| tailscale-client2 | None exposed | VPN endpoint |
-
-## Layer 2: Tailscale Overlay Network
-
-### Network Configuration
-- **IPv4 Subnet**: `100.64.0.0/10` (Tailscale CGNAT range)
-- **IPv6 Subnet**: `fd7a:115c:a1e0::/48` (Tailscale IPv6 range)
-- **Allocation Strategy**: Sequential
-
-### Tailscale IP Assignments
-| Node | IPv4 Address | IPv6 Address | Hostname |
-|------|-------------|--------------|----------|
-| client1 | `100.64.0.1` | `fd7a:115c:a1e0::1` | client1 |
-| client2 | `100.64.0.2` | `fd7a:115c:a1e0::2` | client2 |
-
-## Network Communication Flow
-
-### 1. Control Plane Communication
-
-```
-Tailscale Client → Docker Network → Headscale Server
-      │                 │               │
-   100.64.0.1      10.99.0.21      10.99.0.10
-      │                 │               │
-      └─────── HTTP/GRPC over ──────────┘
-              headscale:8080
-```
-
-- Clients connect to Headscale using Docker's internal DNS (`headscale:8080`)
-- Authentication happens via pre-auth keys
-- Headscale assigns Tailscale IP addresses from the `100.64.0.0/10` range
-- Policy enforcement and network map distribution
-
-### 2. Data Plane Communication
-
-```
-Client1 ←→ Encrypted Tailscale Tunnel ←→ Client2
-  │                                        │
-100.64.0.1                              100.64.0.2
-  │                                        │
-10.99.0.21 ←── Docker Bridge Network ──→ 10.99.0.22
-```
-
-When `client1` pings `client2`:
-1. **Application layer**: Uses Tailscale IP `100.64.0.2`
-2. **Encryption layer**: Tailscale encrypts the packet using WireGuard
-3. **Transport layer**: Encrypted packet travels via Docker network `10.99.0.22:port`
-4. **Decryption layer**: `client2` decrypts and processes the packet
-
-**Key insight**: The ping result shows:
-```
-pong from client2 (100.64.0.2) via 10.99.0.22:49212 in 0s
-```
-This demonstrates how Tailscale IPs are used at the application level while Docker IPs handle the actual transport.
-
-## Security Architecture
-
-### 1. Noise Protocol (Tailscale v2)
-- **Purpose**: Encrypts control plane communication between clients and Headscale
-- **Key Storage**: `/var/lib/headscale/noise_private.key`
-- **Protocol**: Noise_IK_25519_ChaChaPoly_BLAKE2s
-
-### 2. WireGuard Encryption
-- **Purpose**: Encrypts data plane communication between Tailscale nodes
-- **Key Exchange**: Managed by Headscale control plane
-- **Cipher**: ChaCha20Poly1305
-
-### 3. Access Control Lists (ACL)
-```json
-{
-  "acls": [
-    {
-      "action": "accept",
-      "src": ["testuser@headscale"],
-      "dst": ["testuser@headscale:*"]
-    }
-  ]
-}
-```
-- Controls which nodes can communicate with each other
-- Applied at the Tailscale overlay network level
-- Independent of Docker network security
-
-## DNS Resolution
-
-### Docker Internal DNS
-- `headscale` → `10.99.0.10` (Control plane access)
-- `client1` → `10.99.0.21` (Container hostname)
-- `client2` → `10.99.0.22` (Container hostname)
-- `webserver` → `10.99.0.30` (Test web server)
-
-### Tailscale MagicDNS
-- `client1` → `100.64.0.1` (Tailscale hostname)
-- `client2` → `100.64.0.2` (Tailscale hostname)
-- Domain: `headscale.local` (configured in Headscale)
-
-## Network Isolation and Security
-
-### Container Isolation
-- Each container has its own network namespace
-- Containers can only communicate via the Docker bridge network
-- No direct host network access (except through port mappings)
-
-### Tailscale Overlay Isolation
-- Encrypted tunnels between authorized nodes only
-- ACL policies enforce access control
-- Zero-trust architecture: containers on same Docker network still use encrypted communication
-
-### Firewall Considerations
-- Docker bridge network: Internal communication only
-- Host ports: Only Headscale API (8180) exposed to host
-- Tailscale network: Controlled by ACL policies
-
-## Debugging Network Issues
-
-### Check Docker Network
-```bash
-# View network configuration
-docker network inspect headscale-dev_headscale-net
-
-# Test Docker-level connectivity
-docker exec tailscale-client1 ping headscale
-docker exec tailscale-client1 ping 10.99.0.22
-```
-
-### Check Tailscale Network
-```bash
-# View Tailscale status
-docker exec tailscale-client1 tailscale status
-
-# Test Tailscale connectivity
-docker exec tailscale-client1 tailscale ping client2
-docker exec tailscale-client1 ping 100.64.0.2
-```
-
-### Verify Control Plane
-```bash
-# Test Headscale API
-curl http://localhost:8180/health
-
-# View registered nodes
-docker exec headscale-server headscale nodes list
-```
-
-## Performance Characteristics
-
-### Latency
-- **Docker bridge**: Sub-millisecond latency (same host)
-- **Tailscale overlay**: Minimal additional latency due to encryption
-- **Control plane**: Periodic updates, not in data path
-
-### Throughput
-- **Limited by**: Docker bridge network bandwidth and CPU encryption
-- **Typical**: Near-native performance for local container communication
-- **Encryption overhead**: Minimal with modern ChaCha20 implementation
-
-### Scalability
-- **Current setup**: 2 clients, easily expandable
-- **Docker limitations**: Network MTU, container limits
-- **Headscale limitations**: Database backend (SQLite vs PostgreSQL)
-
-## Real-World Mapping
-
-This setup simulates real Tailscale deployments:
-
-| Docker Environment | Real World |
-|--------------------|------------|
-| Docker bridge network | Internet infrastructure |
-| Container IP addresses | Public/private IP addresses |
-| Headscale control server | Tailscale SaaS control plane |
-| ACL policies | Corporate network policies |
-| Pre-auth keys | Device enrollment tokens |
-| Encrypted tunnels | WireGuard VPN connections |
-
-The key difference is that in production, nodes are typically on different networks (home, office, cloud) rather than the same Docker host, but the Tailscale protocol behavior is identical.

docker-dev/README.md

@@ -1,303 +0,0 @@
-# Headscale Docker Development Environment
-
-This directory contains a complete Docker Compose setup for running Headscale with Tailscale clients in a local development environment.
-
-## Overview
-
-This setup includes:
-- **Headscale server**: The control plane server
-- **Two Tailscale clients**: Simulated nodes that connect through Headscale
-- **Test web server**: Optional nginx server for connectivity testing
-- **Helper scripts**: Automated setup and management tools
-
-## Architecture
-
-```
-┌─────────────────────────────────────────┐
-│         Docker Network (10.99.0.0/24)   │
-├─────────────────────────────────────────┤
-│                                         │
-│  ┌──────────────┐                      │
-│  │  Headscale   │ 10.99.0.10           │
-│  │   Server     │ :8080 (API)          │
-│  │              │ :9090 (Metrics)      │
-│  │              │ :50443 (gRPC)        │
-│  └──────┬───────┘                      │
-│         │                               │
-│    ┌────┴────┬─────────┐               │
-│    │         │         │               │
-│ ┌──▼───┐ ┌──▼───┐ ┌──▼───┐           │
-│ │Client│ │Client│ │ Web  │            │
-│ │  1   │ │  2   │ │Server│            │
-│ │.0.21 │ │.0.22 │ │.0.30 │            │
-│ └──────┘ └──────┘ └──────┘            │
-│                                         │
-│  Tailscale Network (100.64.0.0/16)     │
-└─────────────────────────────────────────┘
-```
-
-## Quick Start
-
-### 1. Start the environment
-
-```bash
-# Start all services and automatically set up users/keys
-make up
-
-# Or manually:
-docker compose up -d
-make setup
-```
-
-### 2. Check status
-
-```bash
-# View all nodes
-make status
-
-# Watch logs
-make logs
-```
-
-### 3. Test connectivity
-
-```bash
-# Test ping between clients
-make ping-test
-
-# Test web server access
-make test-web
-```
-
-## ✅ Verified Working Setup
-
-This environment has been tested and verified working with:
-- **Headscale**: `headscale/headscale:latest` (as of September 2024)
-- **Tailscale**: `tailscale/tailscale:latest`
-- **Network**: Docker bridge network `10.99.0.0/24` 
-- **Tailscale Network**: `100.64.0.0/10` with IPv6 `fd7a:115c:a1e0::/48`
-- **Port Mapping**: Host port `8180` → Container port `8080` (Headscale API)
-
-### Test Results
-- ✅ Headscale server starts and serves on port 8180
-- ✅ Both Tailscale clients register automatically with pre-auth keys
-- ✅ Clients receive IP addresses: `100.64.0.1` and `100.64.0.2`
-- ✅ Bidirectional ping works between clients
-- ✅ `tailscale status` shows both nodes online
-- ✅ Traffic flows through encrypted Tailscale tunnel
-
-### Key Insights from Testing
-
-**Network Architecture**: This setup demonstrates two distinct networking layers:
-1. **Docker Bridge Network** (`10.99.0.0/24`) - Physical layer for container communication
-2. **Tailscale Overlay Network** (`100.64.0.0/10`) - Encrypted VPN tunnel for secure communication
-
-When clients ping each other, the traffic uses Tailscale IPs (100.64.x.x) but actually travels through the Docker network infrastructure, demonstrating how Tailscale creates an encrypted overlay on top of existing network infrastructure.
-
-## Available Commands
-
-Run `make help` to see all available commands:
-
-- `make up` - Start all services with automatic setup
-- `make down` - Stop all services
-- `make clean` - Remove everything including volumes
-- `make status` - Show status of all nodes
-- `make logs` - Show logs from all services
-- `make ping-test` - Test connectivity between clients
-- `make shell-headscale` - Open shell in Headscale container
-- `make shell-client1` - Open shell in Client1 container
-- `make shell-client2` - Open shell in Client2 container
-
-## Manual Operations
-
-### Creating users
-
-```bash
-docker exec headscale-server headscale users create myuser
-```
-
-### Generating pre-auth keys
-
-```bash
-docker exec headscale-server headscale preauthkeys create \
-  --user myuser \
-  --reusable \
-  --expiration 24h
-```
-
-### Listing nodes
-
-```bash
-docker exec headscale-server headscale nodes list
-```
-
-### Manual node registration
-
-If automatic registration fails:
-
-1. Start the client registration:
-```bash
-docker exec tailscale-client1 tailscale up \
-  --login-server=http://headscale:8080
-```
-
-2. Copy the node key from the output
-
-3. Register the node:
-```bash
-docker exec headscale-server headscale nodes register \
-  --user testuser \
-  --key <nodekey>
-```
-
-## Configuration
-
-### Headscale Configuration
-
-Edit `headscale-config.yaml` to modify:
-- IP ranges for nodes
-- DNS settings
-- DERP server configuration
-- Logging levels
-
-### ACL Policy
-
-Edit `acl.hujson` to modify access control rules. Default policy allows all traffic between all nodes.
-
-### Environment Variables
-
-The `.env` file contains:
-- `COMPOSE_PROJECT_NAME`: Docker Compose project name
-- `TS_AUTHKEY_CLIENT1`: Pre-auth key for client 1
-- `TS_AUTHKEY_CLIENT2`: Pre-auth key for client 2
-
-## Testing Connectivity
-
-### Between Tailscale clients
-
-```bash
-# From client1 to client2
-docker exec tailscale-client1 tailscale ping client2
-
-# Using regular ping with Tailscale IPs
-docker exec tailscale-client1 ping -c 3 100.64.0.2
-```
-
-### Through the web server
-
-```bash
-# Access the test web server
-docker exec tailscale-client1 curl http://webserver
-```
-
-## Troubleshooting
-
-### Clients not connecting
-
-1. Check Headscale logs:
-```bash
-make logs-headscale
-```
-
-2. Check client logs:
-```bash
-make logs-clients
-```
-
-3. Verify pre-auth keys are set:
-```bash
-cat .env
-```
-
-4. Try manual registration:
-```bash
-make register-manual
-```
-
-### Network issues
-
-1. Verify Docker network:
-```bash
-docker network inspect headscale-dev_headscale-net
-```
-
-2. Check Tailscale status in clients:
-```bash
-docker exec tailscale-client1 tailscale status
-docker exec tailscale-client2 tailscale status
-```
-
-3. Test basic connectivity:
-```bash
-docker exec tailscale-client1 ping headscale
-```
-
-### Reset everything
-
-```bash
-make clean
-make up
-```
-
-## Development Workflow
-
-### Using local Headscale build
-
-1. Build Headscale from source:
-```bash
-make build-local
-```
-
-2. Update `docker-compose.yml`:
-```yaml
-headscale:
-  image: headscale:local  # Instead of headscale/headscale:latest
-```
-
-3. Restart:
-```bash
-make down
-make up
-```
-
-### Modifying ACL policies
-
-1. Edit `acl.hujson`
-2. Restart Headscale to apply changes:
-```bash
-docker compose restart headscale
-```
-
-### Adding more clients
-
-1. Copy the client service definition in `docker-compose.yml`
-2. Update the container name, hostname, and IP address
-3. Add a new auth key environment variable
-4. Run `make setup` to generate a new key
-5. Start the new client
-
-## Security Notes
-
-- This setup is for **development only**
-- Uses HTTP instead of HTTPS for simplicity
-- Pre-auth keys have 24-hour expiration by default
-- All traffic between nodes is allowed by default ACL
-
-## Clean Up
-
-To completely remove the environment:
-
-```bash
-make clean
-```
-
-This removes:
-- All containers
-- All volumes (including Headscale database)
-- Generated auth keys in `.env`
-
-## Related Documentation
-
-- [Headscale Documentation](https://headscale.net/)
-- [Tailscale Documentation](https://tailscale.com/kb/)
-- [Docker Compose Documentation](https://docs.docker.com/compose/)

docker-dev/SETUP-SUMMARY.md

@@ -1,153 +0,0 @@
-# Headscale Docker Environment - Setup Summary
-
-## 🎯 What We Built
-
-A complete, working Docker Compose environment that simulates a Tailscale network using the open-source Headscale control server. This setup provides:
-
-- **Self-hosted Tailscale control plane** using Headscale
-- **Two Tailscale client nodes** that communicate securely
-- **Encrypted mesh networking** with zero-configuration
-- **Real-world protocol behavior** in an isolated environment
-
-## 📁 Files Created
-
-| File | Purpose |
-|------|---------|
-| `docker-compose.yml` | Main orchestration file with all services |
-| `headscale-config.yaml` | Headscale server configuration |
-| `acl.hujson` | Access control policy (allows all communication) |
-| `Makefile` | Helper commands for easy management |
-| `.env` | Environment variables and pre-auth keys |
-| `scripts/setup-headscale.sh` | Automated user and key generation |
-| `scripts/client-init.sh` | Tailscale client initialization |
-| `www/index.html` | Test web content |
-| `README.md` | Complete user documentation |
-| `TROUBLESHOOTING.md` | Solutions for common issues |
-| `NETWORK-ARCHITECTURE.md` | Detailed networking explanation |
-| `TESTING-CHECKLIST.md` | Verification procedures |
-
-## 🌐 Network Architecture
-
-### Two-Layer Design
-1. **Docker Bridge Network** (`10.99.0.0/24`)
-   - Physical infrastructure layer
-   - Container-to-container communication
-   - Headscale control plane access
-
-2. **Tailscale Overlay Network** (`100.64.0.0/10`)
-   - Encrypted VPN tunnel layer
-   - Secure node-to-node communication
-   - WireGuard-based encryption
-
-### IP Assignments
-| Service | Docker IP | Tailscale IP | Role |
-|---------|-----------|--------------|------|
-| headscale-server | 10.99.0.10 | N/A | Control server |
-| tailscale-client1 | 10.99.0.21 | 100.64.0.1 | VPN node 1 |
-| tailscale-client2 | 10.99.0.22 | 100.64.0.2 | VPN node 2 |
-| test-webserver | 10.99.0.30 | N/A | HTTP test server |
-
-## ✅ Verified Working Features
-
-### Control Plane
-- ✅ Headscale server startup and configuration
-- ✅ User creation and management  
-- ✅ Pre-auth key generation and usage
-- ✅ Node registration and IP assignment
-- ✅ ACL policy enforcement
-
-### Data Plane
-- ✅ Encrypted tunnels between clients
-- ✅ Bidirectional connectivity testing
-- ✅ DNS resolution (Docker + MagicDNS)
-- ✅ HTTP traffic through VPN
-- ✅ Real-time status monitoring
-
-### Infrastructure
-- ✅ Docker networking and isolation
-- ✅ Port mapping and external access
-- ✅ Persistent storage for Headscale data
-- ✅ Health checks and dependency management
-- ✅ Graceful startup and shutdown
-
-## 🔧 Key Insights from Testing
-
-### Configuration Evolution
-Modern Headscale requires several configuration updates from older versions:
-- **Noise protocol**: Required for Tailscale v2 compatibility
-- **Prefix format**: Changed from `ip_prefixes` to structured `prefixes`
-- **User management**: CLI uses user IDs instead of usernames
-- **ACL syntax**: Stricter validation and email-format requirements
-
-### Network Behavior
-The setup demonstrates how Tailscale creates secure overlay networks:
-- **Encryption transparency**: Applications use Tailscale IPs, but traffic is encrypted
-- **Path optimization**: Direct communication when possible, relayed when necessary
-- **Zero-trust model**: Security doesn't rely on network boundaries
-
-### Practical Applications
-This environment is ideal for:
-- **Headscale development**: Testing changes before production deployment
-- **Network policy testing**: Experimenting with ACL configurations
-- **Integration testing**: Validating application behavior on Tailscale networks
-- **Education**: Understanding how modern VPN technologies work
-
-## 🚀 Quick Start Commands
-
-```bash
-# Navigate to the environment
-cd /home/rpm/claude/headscale/docker-dev
-
-# Start everything
-make up
-
-# Verify it's working
-make status
-make ping-test
-
-# Clean up when done
-make clean
-```
-
-## 📚 Documentation Structure
-
-1. **README.md** - Start here for basic usage
-2. **NETWORK-ARCHITECTURE.md** - Deep dive into networking
-3. **TROUBLESHOOTING.md** - Solutions for common problems
-4. **TESTING-CHECKLIST.md** - Systematic verification steps
-5. **SETUP-SUMMARY.md** - This overview document
-
-## 🎯 Next Steps
-
-### For Development
-- Modify ACL policies to test different network topologies
-- Add more clients to scale the network
-- Integrate with external services
-- Test route advertisement and exit nodes
-
-### For Production Use
-- Replace SQLite with PostgreSQL for scalability
-- Add TLS certificates for secure external access
-- Implement backup strategies for Headscale data
-- Configure monitoring and logging
-
-### For Learning
-- Study the network packet flows using `tcpdump`
-- Experiment with Headscale API endpoints
-- Try different client configurations
-- Explore the integration test patterns in the main Headscale repo
-
-## 🏆 Achievement Summary
-
-We successfully:
-1. ✅ **Built** a complete Tailscale network simulation
-2. ✅ **Tested** all core functionality with real traffic
-3. ✅ **Documented** the architecture and troubleshooting steps
-4. ✅ **Verified** networking behavior matches expectations
-5. ✅ **Created** reusable infrastructure for future development
-
-This environment provides a solid foundation for understanding, developing, and testing Tailscale-based networking solutions using the open-source Headscale project.
-
----
-
-**🎉 Congratulations! You now have a fully functional, well-documented Headscale development environment.**

docker-dev/TESTING-CHECKLIST.md

@@ -1,335 +0,0 @@
-# Testing Verification Checklist
-
-This checklist ensures the Headscale Docker environment is working correctly. Follow these steps to verify your setup.
-
-## ✅ Pre-Setup Verification
-
-### System Requirements
-- [ ] Docker installed and running
-- [ ] Docker Compose installed
-- [ ] Ports 8180, 9090, 50443 available on host
-- [ ] At least 2GB free disk space
-- [ ] Network subnet 10.99.0.0/24 not in use
-
-### Port Conflicts Check
-```bash
-# Check if required ports are free
-sudo lsof -i :8180 :9090 :50443
-# Should return no results if ports are free
-```
-
-### Network Conflicts Check
-```bash
-# Check for existing Docker networks using similar subnets
-docker network ls --format '{{.Name}}' | xargs -I {} sh -c 'echo "Network: {}"; docker network inspect {} 2>/dev/null | jq -r ".[0].IPAM.Config[0].Subnet // \"No subnet\""; echo' | grep -A1 "10.99"
-# Should return no results
-```
-
-## ✅ Initial Setup Verification
-
-### 1. Environment Startup
-```bash
-cd /path/to/headscale/docker-dev
-make up
-```
-
-**Expected results:**
-- [ ] All containers start without errors
-- [ ] Headscale container shows "listening and serving" messages
-- [ ] No port binding errors
-- [ ] User 'testuser' created successfully
-- [ ] Pre-auth keys generated and saved to .env
-
-### 2. Container Status Check
-```bash
-docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
-```
-
-**Expected results:**
-- [ ] `headscale-server` status: `Up X seconds`
-- [ ] `tailscale-client1` status: `Up X seconds`  
-- [ ] `tailscale-client2` status: `Up X seconds`
-- [ ] `test-webserver` status: `Up X seconds`
-- [ ] Port mappings visible: `0.0.0.0:8180->8080/tcp` etc.
-
-### 3. Network Creation Check
-```bash
-docker network inspect headscale-dev_headscale-net
-```
-
-**Expected results:**
-- [ ] Network exists with subnet `10.99.0.0/24`
-- [ ] Gateway at `10.99.0.1`
-- [ ] All 4 containers attached to network
-- [ ] Each container has assigned IP in correct range
-
-## ✅ Headscale Server Verification
-
-### 1. Health Check
-```bash
-curl -s http://localhost:8180/health
-```
-
-**Expected result:**
-- [ ] Returns: `{"status":"pass"}`
-
-### 2. User Management
-```bash
-docker exec headscale-server headscale users list
-```
-
-**Expected results:**
-- [ ] Shows user with ID 1
-- [ ] Username: `testuser`
-- [ ] Created timestamp present
-
-### 3. Pre-auth Keys
-```bash
-docker exec headscale-server headscale preauthkeys list --user 1
-```
-
-**Expected results:**
-- [ ] Shows 2 pre-auth keys
-- [ ] Both keys marked as `reusable: true`
-- [ ] Expiration set to 24h from creation
-- [ ] Keys not yet used
-
-### 4. Configuration Validation
-```bash
-docker exec headscale-server headscale configtest
-```
-
-**Expected result:**
-- [ ] Configuration validates successfully (if command exists)
-- [ ] Or server starts without configuration errors
-
-## ✅ Tailscale Client Verification
-
-### 1. Client Registration
-```bash
-docker exec headscale-server headscale nodes list
-```
-
-**Expected results:**
-- [ ] Shows 2 nodes (client1, client2)
-- [ ] Both nodes have status `online`
-- [ ] IP addresses: `100.64.0.1` and `100.64.0.2`
-- [ ] IPv6 addresses: `fd7a:115c:a1e0::1` and `fd7a:115c:a1e0::2`
-- [ ] Both nodes associated with `testuser`
-- [ ] No expired nodes
-
-### 2. Client Status
-```bash
-docker exec tailscale-client1 tailscale status
-docker exec tailscale-client2 tailscale status
-```
-
-**Expected results:**
-- [ ] Client1 shows itself at `100.64.0.1`
-- [ ] Client1 shows client2 at `100.64.0.2`
-- [ ] Client2 shows itself at `100.64.0.2`
-- [ ] Client2 shows client1 at `100.64.0.1`
-- [ ] Both show status as logged in to `testuser`
-
-### 3. Authentication Verification
-```bash
-cat .env | grep TS_AUTHKEY
-```
-
-**Expected results:**
-- [ ] Two auth keys present: `TS_AUTHKEY_CLIENT1` and `TS_AUTHKEY_CLIENT2`
-- [ ] Keys are non-empty 32-character hex strings
-- [ ] Keys are different from each other
-
-## ✅ Network Connectivity Testing
-
-### 1. Docker Network Connectivity
-```bash
-# Test basic Docker networking
-docker exec tailscale-client1 ping -c 3 headscale
-docker exec tailscale-client1 ping -c 3 10.99.0.22
-docker exec tailscale-client2 ping -c 3 10.99.0.21
-```
-
-**Expected results:**
-- [ ] All pings successful with 0% packet loss
-- [ ] Round trip times < 10ms (local network)
-- [ ] DNS resolution working (headscale resolves to 10.99.0.10)
-
-### 2. Tailscale Network Connectivity
-```bash
-# Test Tailscale VPN connectivity
-docker exec tailscale-client1 tailscale ping client2
-docker exec tailscale-client2 tailscale ping client1
-```
-
-**Expected results:**
-- [ ] Both pings return successful "pong" messages
-- [ ] Response shows Tailscale IP (100.64.0.x)
-- [ ] Response shows underlying transport (via 10.99.0.x:port)
-- [ ] Response time < 1s
-
-### 3. IP-level Connectivity
-```bash
-# Test direct IP ping through Tailscale
-docker exec tailscale-client1 ping -c 3 100.64.0.2
-docker exec tailscale-client2 ping -c 3 100.64.0.1
-```
-
-**Expected results:**
-- [ ] Pings successful through Tailscale tunnel
-- [ ] 0% packet loss
-- [ ] Consistent round trip times
-
-## ✅ Application Layer Testing
-
-### 1. Web Server Connectivity
-```bash
-# Test HTTP connectivity through Tailscale
-docker exec tailscale-client1 curl -s http://webserver | grep -i "hello"
-```
-
-**Expected results:**
-- [ ] Successfully retrieves web page
-- [ ] HTML content contains expected text
-- [ ] No connection errors
-
-### 2. Make Target Testing
-```bash
-# Test automation commands
-make status
-make ping-test
-```
-
-**Expected results:**
-- [ ] `make status` shows all nodes online
-- [ ] `make ping-test` reports successful connectivity
-- [ ] No error messages in output
-
-## ✅ Security Verification
-
-### 1. ACL Policy Check
-```bash
-docker exec headscale-server headscale policy get
-```
-
-**Expected results:**
-- [ ] Policy loaded successfully
-- [ ] Shows rule allowing testuser@headscale to communicate
-- [ ] No policy parsing errors
-
-### 2. Encryption Verification
-```bash
-# Check that traffic is encrypted (this is implicit in Tailscale)
-docker exec tailscale-client1 tailscale status --json | jq '.Peer[] | {Name: .HostName, Online: .Online, LastSeen: .LastSeen}'
-```
-
-**Expected results:**
-- [ ] Peers show as online
-- [ ] Recent LastSeen timestamps
-- [ ] Secure connections established
-
-### 3. Noise Protocol Verification
-```bash
-docker exec headscale-server ls -la /var/lib/headscale/noise_private.key
-```
-
-**Expected results:**
-- [ ] Noise private key file exists
-- [ ] File has appropriate permissions
-- [ ] Non-zero file size
-
-## ✅ Performance Testing
-
-### 1. Latency Test
-```bash
-# Test latency through Tailscale
-docker exec tailscale-client1 sh -c 'for i in {1..10}; do tailscale ping client2; done'
-```
-
-**Expected results:**
-- [ ] All pings successful
-- [ ] Consistent low latency (< 1s for local setup)
-- [ ] No timeout errors
-
-### 2. Throughput Test (Optional)
-```bash
-# Basic throughput test using nc (if available)
-docker exec tailscale-client2 nc -l 8888 > /dev/null &
-docker exec tailscale-client1 sh -c 'yes | head -c 1M | nc 100.64.0.2 8888'
-```
-
-**Expected results:**
-- [ ] Data transfer completes successfully
-- [ ] No connection refused errors
-
-## ✅ Log Analysis
-
-### 1. Check for Errors
-```bash
-# Check all container logs for errors
-docker logs headscale-server 2>&1 | grep -i error
-docker logs tailscale-client1 2>&1 | grep -i error  
-docker logs tailscale-client2 2>&1 | grep -i error
-```
-
-**Expected results:**
-- [ ] No critical errors in Headscale logs
-- [ ] No authentication failures
-- [ ] No network connectivity errors
-- [ ] Warning messages acceptable (non-blocking)
-
-### 2. Successful Operations
-```bash
-# Look for success indicators
-docker logs headscale-server 2>&1 | grep "listening and serving"
-```
-
-**Expected results:**
-- [ ] Headscale shows "listening and serving" for all ports
-- [ ] No startup failures
-- [ ] Database operations successful
-
-## ✅ Cleanup Verification
-
-### 1. Controlled Shutdown
-```bash
-make down
-```
-
-**Expected results:**
-- [ ] All containers stop gracefully
-- [ ] No force-kill required
-- [ ] Networks removed cleanly
-
-### 2. Complete Cleanup
-```bash
-make clean
-```
-
-**Expected results:**
-- [ ] All containers removed
-- [ ] All volumes removed  
-- [ ] Networks removed
-- [ ] .env file cleaned up
-
-## 🔧 Troubleshooting Failed Checks
-
-If any checks fail, refer to:
-- **TROUBLESHOOTING.md** - Common issues and solutions
-- **Container logs** - `docker logs <container-name>`
-- **Network inspection** - `docker network inspect <network-name>`
-- **Headscale CLI** - `docker exec headscale-server headscale --help`
-
-## 📊 Test Results Summary
-
-Create a test report with:
-- [ ] Test execution date/time
-- [ ] All checklist items marked as pass/fail
-- [ ] Any failures documented with error messages
-- [ ] Environment details (Docker version, OS, etc.)
-- [ ] Performance measurements if collected
-
----
-
-**✅ All checks passed? Congratulations! Your Headscale environment is fully functional.**

docker-dev/TROUBLESHOOTING.md

@@ -1,259 +0,0 @@
-# Troubleshooting Guide
-
-This guide covers common issues encountered when setting up and running the Headscale Docker development environment.
-
-## Configuration Issues
-
-### ❌ "headscale now requires a new `noise.private_key_path` field"
-
-**Symptom**: Headscale container fails to start with error about missing noise private key path.
-
-**Cause**: Newer versions of Headscale require the Noise protocol configuration for Tailscale v2.
-
-**Solution**: Add the noise configuration to `headscale-config.yaml`:
-```yaml
-noise:
-  private_key_path: /var/lib/headscale/noise_private.key
-```
-
-### ❌ "no IPv4 or IPv6 prefix configured"
-
-**Symptom**: Headscale fails with error about missing IP prefixes.
-
-**Cause**: Configuration format changed from `ip_prefixes` to `prefixes` with `v4`/`v6` subfields.
-
-**Solution**: Update the configuration format:
-```yaml
-# Old format (doesn't work)
-ip_prefixes:
-  - 100.64.0.0/16
-  - fd7a:115c:a1e0::/48
-
-# New format (works)
-prefixes:
-  v4: 100.64.0.0/10
-  v6: fd7a:115c:a1e0::/48
-  allocation: sequential
-```
-
-### ❌ "Username has to contain @, got: \"*\""
-
-**Symptom**: ACL policy fails to parse with username format error.
-
-**Cause**: Newer Headscale versions require usernames in email format.
-
-**Solution**: Use proper username format in ACL:
-```json
-{
-  "acls": [
-    {
-      "action": "accept",
-      "src": ["testuser@headscale"],
-      "dst": ["testuser@headscale:*"]
-    }
-  ]
-}
-```
-
-### ❌ "type *v2.Group not supported"
-
-**Symptom**: ACL fails with unsupported group type.
-
-**Cause**: Some ACL features might not be supported in newer versions.
-
-**Solution**: Simplify ACL policy to use direct user references instead of groups.
-
-## Network Conflicts
-
-### ❌ "Pool overlaps with other one on this address space"
-
-**Symptom**: Docker Compose fails to create network.
-
-**Cause**: The subnet conflicts with existing Docker networks.
-
-**Solution**: 
-1. Check existing networks: `docker network ls`
-2. Choose a different subnet in docker-compose.yml:
-```yaml
-networks:
-  headscale-net:
-    driver: bridge
-    ipam:
-      config:
-        - subnet: 10.99.0.0/24  # Use available subnet
-          gateway: 10.99.0.1
-```
-
-### ❌ "Bind for 0.0.0.0:8080 failed: port is already allocated"
-
-**Symptom**: Port conflict when starting Headscale.
-
-**Cause**: Port 8080 is already in use by another service.
-
-**Solution**: Map to a different host port:
-```yaml
-ports:
-  - "8180:8080"  # Use 8180 on host instead of 8080
-```
-
-## Authentication Issues
-
-### ❌ "invalid argument \"testuser\" for \"-u, --user\" flag"
-
-**Symptom**: Pre-auth key creation fails with user argument error.
-
-**Cause**: Newer Headscale uses user IDs instead of usernames.
-
-**Solution**: 
-1. Get user ID: `docker exec headscale-server headscale users list`
-2. Use ID in commands: `headscale preauthkeys create --user 1`
-
-### ❌ Clients not registering automatically
-
-**Symptom**: Tailscale clients don't register with pre-auth keys.
-
-**Troubleshooting**:
-1. Check if auth keys are set in `.env`:
-   ```bash
-   cat .env
-   ```
-2. Verify Headscale is reachable:
-   ```bash
-   docker exec tailscale-client1 wget -O- http://headscale:8080/health
-   ```
-3. Check client logs:
-   ```bash
-   docker logs tailscale-client1
-   ```
-
-## Health Check Issues
-
-### ❌ "unknown command \"health\" for \"headscale\""
-
-**Symptom**: Health check fails because command doesn't exist.
-
-**Cause**: The `headscale health` command doesn't exist in current versions.
-
-**Solution**: Use HTTP health check instead:
-```yaml
-healthcheck:
-  test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/health"]
-```
-
-Or remove health check dependency:
-```yaml
-depends_on:
-  - headscale  # Simple dependency without health check
-```
-
-## Connectivity Issues
-
-### ❌ Clients can't ping each other
-
-**Troubleshooting**:
-1. Check if nodes are registered:
-   ```bash
-   docker exec headscale-server headscale nodes list
-   ```
-2. Verify Tailscale status on clients:
-   ```bash
-   docker exec tailscale-client1 tailscale status
-   ```
-3. Check ACL policy allows communication:
-   ```bash
-   docker exec headscale-server headscale policy get
-   ```
-
-### ❌ "dependency failed to start: container headscale-server is unhealthy"
-
-**Symptom**: Clients won't start because Headscale health check fails.
-
-**Solution**: Either fix the health check or remove the health dependency:
-```yaml
-depends_on:
-  - headscale  # Remove health condition
-```
-
-## Container Issues
-
-### ❌ Permission denied with /dev/net/tun
-
-**Symptom**: Tailscale clients can't create TUN device.
-
-**Solution**: Ensure proper capabilities and device access:
-```yaml
-cap_add:
-  - NET_ADMIN
-  - SYS_MODULE
-volumes:
-  - /dev/net/tun:/dev/net/tun
-```
-
-### ❌ Clients keep restarting
-
-**Troubleshooting**:
-1. Check client logs for specific errors
-2. Verify Headscale is accessible
-3. Ensure auth keys are valid
-4. Check if TUN device is available
-
-## Debugging Commands
-
-### Check Service Status
-```bash
-# View all containers
-docker ps
-
-# Check specific service logs
-docker logs headscale-server
-docker logs tailscale-client1
-
-# Inspect network configuration
-docker network inspect headscale-dev_headscale-net
-```
-
-### Test Network Connectivity
-```bash
-# Test from client to Headscale
-docker exec tailscale-client1 ping headscale
-
-# Test Headscale API
-curl http://localhost:8180/health
-
-# Check Tailscale status
-docker exec tailscale-client1 tailscale status
-```
-
-### Verify Configuration
-```bash
-# Check Headscale users
-docker exec headscale-server headscale users list
-
-# List registered nodes
-docker exec headscale-server headscale nodes list
-
-# View pre-auth keys
-docker exec headscale-server headscale preauthkeys list --user 1
-```
-
-## Complete Reset
-
-If everything is broken, start fresh:
-```bash
-# Stop and remove everything
-make clean
-
-# Remove any conflicting networks manually if needed
-docker network prune
-
-# Start from scratch
-make up
-```
-
-## Getting Help
-
-1. **Check logs first**: Most issues are visible in container logs
-2. **Verify network connectivity**: Ensure Docker network is working
-3. **Test step by step**: Start with Headscale, then add clients
-4. **Use simple ACL**: Start with basic ACL and expand later
-5. **Check Headscale documentation**: https://headscale.net/

docker-dev/docker-compose-oidc-test.yml

@@ -1,152 +0,0 @@
-services:
-  # PostgreSQL database for Keycloak
-  postgres:
-    image: postgres:15-alpine
-    container_name: headscale-postgres
-    environment:
-      POSTGRES_DB: keycloak
-      POSTGRES_USER: keycloak
-      POSTGRES_PASSWORD: password
-    volumes:
-      - postgres-data:/var/lib/postgresql/data
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.5
-
-  # Keycloak OIDC provider
-  keycloak:
-    image: quay.io/keycloak/keycloak:23.0
-    container_name: headscale-keycloak
-    environment:
-      KEYCLOAK_ADMIN: admin
-      KEYCLOAK_ADMIN_PASSWORD: admin
-      KC_DB: postgres
-      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
-      KC_DB_USERNAME: keycloak
-      KC_DB_PASSWORD: password
-      KC_HOSTNAME_STRICT: false
-      KC_HOSTNAME_STRICT_HTTPS: false
-    ports:
-      - "8280:8080"  # Keycloak admin console
-    depends_on:
-      - postgres
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.6
-    command: start-dev
-    volumes:
-      - ./keycloak-config:/opt/keycloak/data/import:ro
-
-  # Build Headscale with our OIDC groups changes
-  headscale:
-    build:
-      context: ..
-      dockerfile: Dockerfile.debug
-    container_name: headscale-server
-    volumes:
-      - ./headscale-config-oidc.yaml:/etc/headscale/config.yaml
-      - ./acl.hujson:/etc/headscale/acl.hujson
-      - headscale-data:/var/lib/headscale
-    ports:
-      - "8180:8080"  # HTTP API
-      - "9090:9090"  # Metrics
-      - "50443:50443"  # gRPC
-    command: serve
-    restart: unless-stopped
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.10
-    depends_on:
-      - keycloak
-    healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/health"]
-      interval: 5s
-      timeout: 3s
-      retries: 5
-      start_period: 30s
-
-  # Headplane with OIDC configuration
-  headplane:
-    build:
-      context: ../../headplane
-      dockerfile: Dockerfile
-    container_name: headscale-headplane
-    ports:
-      - "3000:3000"  # Headplane UI
-    environment:
-      - HEADPLANE_CONFIG_PATH=/app/config.yaml
-    volumes:
-      - ./headplane-config-oidc.yaml:/app/config.yaml:ro
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.15
-    depends_on:
-      - headscale
-    restart: unless-stopped
-
-  # Test tailscale clients (unchanged)
-  tailscale-client1:
-    image: tailscale/tailscale:latest
-    container_name: tailscale-client1
-    hostname: client1
-    cap_add:
-      - NET_ADMIN
-      - SYS_MODULE
-    environment:
-      - TS_STATE_DIR=/var/lib/tailscale
-      - TS_EXTRA_ARGS=--login-server=http://headscale:8080
-      - TS_HOSTNAME=client1
-      - TS_AUTHKEY=${TS_AUTHKEY_CLIENT1:-}
-      - TS_ACCEPT_ROUTES=true
-      - TS_USERSPACE=false
-    volumes:
-      - tailscale-client1-state:/var/lib/tailscale
-      - /dev/net/tun:/dev/net/tun
-      - ./scripts/client-init.sh:/usr/local/bin/client-init.sh:ro
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.21
-    depends_on:
-      - headscale
-    restart: unless-stopped
-    command: sh -c "tailscaled --state=/var/lib/tailscale/tailscaled.state --socket=/var/run/tailscale/tailscaled.sock --tun=userspace-networking & sleep 5 && /usr/local/bin/client-init.sh client1 && wait"
-
-  tailscale-client2:
-    image: tailscale/tailscale:latest
-    container_name: tailscale-client2
-    hostname: client2
-    cap_add:
-      - NET_ADMIN
-      - SYS_MODULE
-    environment:
-      - TS_STATE_DIR=/var/lib/tailscale
-      - TS_EXTRA_ARGS=--login-server=http://headscale:8080
-      - TS_HOSTNAME=client2
-      - TS_AUTHKEY=${TS_AUTHKEY_CLIENT2:-}
-      - TS_ACCEPT_ROUTES=true
-      - TS_USERSPACE=false
-    volumes:
-      - tailscale-client2-state:/var/lib/tailscale
-      - /dev/net/tun:/dev/net/tun
-      - ./scripts/client-init.sh:/usr/local/bin/client-init.sh:ro
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.22
-    depends_on:
-      - headscale
-    restart: unless-stopped
-    command: sh -c "tailscaled --state=/var/lib/tailscale/tailscaled.state --socket=/var/run/tailscale/tailscaled.sock --tun=userspace-networking & sleep 5 && /usr/local/bin/client-init.sh client2 && wait"
-
-networks:
-  headscale-net:
-    driver: bridge
-    ipam:
-      config:
-        - subnet: 10.99.0.0/24
-          gateway: 10.99.0.1
-
-volumes:
-  headscale-data:
-  tailscale-client1-state:
-  tailscale-client2-state:
-  postgres-data:

docker-dev/docker-compose.yml

@@ -1,103 +0,0 @@
-services:
-  # Headscale control server
-  headscale:
-    image: headscale/headscale:latest
-    container_name: headscale-server
-    volumes:
-      - ./headscale-config.yaml:/etc/headscale/config.yaml
-      - ./acl.hujson:/etc/headscale/acl.hujson
-      - headscale-data:/var/lib/headscale
-    ports:
-      - "8180:8080"  # HTTP API
-      - "9090:9090"  # Metrics
-      - "50443:50443"  # gRPC
-    command: serve
-    restart: unless-stopped
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.10
-    healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/health"]
-      interval: 5s
-      timeout: 3s
-      retries: 5
-      start_period: 10s
-
-  # Tailscale client 1
-  tailscale-client1:
-    image: tailscale/tailscale:latest
-    container_name: tailscale-client1
-    hostname: client1
-    cap_add:
-      - NET_ADMIN
-      - SYS_MODULE
-    environment:
-      - TS_STATE_DIR=/var/lib/tailscale
-      - TS_EXTRA_ARGS=--login-server=http://headscale:8080
-      - TS_HOSTNAME=client1
-      - TS_AUTHKEY=${TS_AUTHKEY_CLIENT1:-}
-      - TS_ACCEPT_ROUTES=true
-      - TS_USERSPACE=false
-    volumes:
-      - tailscale-client1-state:/var/lib/tailscale
-      - /dev/net/tun:/dev/net/tun
-      - ./scripts/client-init.sh:/usr/local/bin/client-init.sh:ro
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.21
-    depends_on:
-      - headscale
-    restart: unless-stopped
-    command: sh -c "tailscaled --state=/var/lib/tailscale/tailscaled.state --socket=/var/run/tailscale/tailscaled.sock --tun=userspace-networking & sleep 5 && /usr/local/bin/client-init.sh client1 && wait"
-
-  # Tailscale client 2
-  tailscale-client2:
-    image: tailscale/tailscale:latest
-    container_name: tailscale-client2
-    hostname: client2
-    cap_add:
-      - NET_ADMIN
-      - SYS_MODULE
-    environment:
-      - TS_STATE_DIR=/var/lib/tailscale
-      - TS_EXTRA_ARGS=--login-server=http://headscale:8080
-      - TS_HOSTNAME=client2
-      - TS_AUTHKEY=${TS_AUTHKEY_CLIENT2:-}
-      - TS_ACCEPT_ROUTES=true
-      - TS_USERSPACE=false
-    volumes:
-      - tailscale-client2-state:/var/lib/tailscale
-      - /dev/net/tun:/dev/net/tun
-      - ./scripts/client-init.sh:/usr/local/bin/client-init.sh:ro
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.22
-    depends_on:
-      - headscale
-    restart: unless-stopped
-    command: sh -c "tailscaled --state=/var/lib/tailscale/tailscaled.state --socket=/var/run/tailscale/tailscaled.sock --tun=userspace-networking & sleep 5 && /usr/local/bin/client-init.sh client2 && wait"
-
-  # Optional: A simple web server for testing connectivity
-  test-webserver:
-    image: nginx:alpine
-    container_name: test-webserver
-    hostname: webserver
-    networks:
-      headscale-net:
-        ipv4_address: 10.99.0.30
-    volumes:
-      - ./www:/usr/share/nginx/html:ro
-    restart: unless-stopped
-
-networks:
-  headscale-net:
-    driver: bridge
-    ipam:
-      config:
-        - subnet: 10.99.0.0/24
-          gateway: 10.99.0.1
-
-volumes:
-  headscale-data:
-  tailscale-client1-state:
-  tailscale-client2-state:

docker-dev/headplane-config-oidc.yaml

@@ -1,31 +0,0 @@
-headscale:
-  url: "http://headscale:8080"
-  api_key: "headscale-api-key"
-
-oidc:
-  enabled: true
-  issuer_url: "http://keycloak:8080/realms/headscale"
-  client_id: "headplane-client"
-  client_secret: "headplane-client-secret"
-  scope: "openid profile email groups"
-  redirect_uri: "http://localhost:3000/admin/oidc/callback"
-  extra_params:
-    prompt: "select_account"
-  profile_picture_source: "oidc"
-  # For testing purposes, use the same API key for all users
-  # In production, you'd want proper API key management per user
-  headscale_api_key: "headscale-api-key"
-
-# Group to role mapping configuration
-role_mapping:
-  owner: ["headscale-owner", "owner"]
-  admin: ["headscale-admin", "admin", "administrators"]
-  network_admin: ["headscale-network", "network-admin"]
-  it_admin: ["headscale-it", "it-admin"]
-  auditor: ["headscale-audit", "auditor"]
-
-integration:
-  provider: "docker"
-
-log:
-  level: "info"

docker-dev/headscale-config-oidc.yaml

@@ -1,60 +0,0 @@
----
-# Headscale configuration with OIDC enabled for testing
-server_url: http://localhost:8180
-listen_addr: 0.0.0.0:8080
-metrics_listen_addr: 0.0.0.0:9090
-grpc_listen_addr: 0.0.0.0:50443
-grpc_allow_insecure: true
-
-# IP prefixes for the tailnet
-prefixes:
-  v4: 100.64.0.0/10
-  v6: fd7a:115c:a1e0::/48
-  
-ip_allocation: sequential
-
-# Database configuration
-database:
-  type: sqlite
-  sqlite:
-    path: /var/lib/headscale/db.sqlite
-
-# OIDC Configuration for testing with Keycloak
-oidc:
-  issuer: "http://keycloak:8080/realms/headscale"
-  client_id: "headscale-client"
-  client_secret: "your-client-secret"
-  scope: ["openid", "profile", "email", "groups"]
-  extra_params: {}
-  allowed_domains: []
-  allowed_groups: []
-  allowed_users: []
-  expiry: 180d
-  use_expiry_from_token: false
-  pkce:
-    enabled: true
-    method: "S256"
-
-# DNS Configuration
-dns:
-  override_local_dns: true
-  nameservers:
-    global: ["1.1.1.1", "1.0.0.1", "8.8.8.8"]
-  domains: []
-  extra_records: []
-  magic_dns: true
-  base_domain: headscale.net
-
-# TLS disabled for local testing
-disable_check_updates: true
-ephemeral_node_inactivity_timeout: 30m
-
-# Policy configuration
-policy:
-  mode: file
-  path: "/etc/headscale/acl.hujson"
-
-# Log configuration
-log:
-  format: text
-  level: info

docker-dev/headscale-config.yaml

@@ -1,70 +0,0 @@
-# Headscale configuration for Docker development environment
-server_url: http://headscale:8080
-listen_addr: 0.0.0.0:8080
-metrics_listen_addr: 0.0.0.0:9090
-grpc_listen_addr: 0.0.0.0:50443
-grpc_allow_insecure: true
-
-# Noise protocol private key for Tailscale v2
-noise:
-  private_key_path: /var/lib/headscale/noise_private.key
-
-# IP allocation for nodes
-prefixes:
-  v4: 100.64.0.0/10
-  v6: fd7a:115c:a1e0::/48
-  allocation: sequential
-
-# DERP server configuration
-derp:
-  server:
-    enabled: false
-  urls:
-    - https://controlplane.tailscale.com/derpmap/default
-  paths: []
-  auto_update_enabled: true
-  update_frequency: 24h
-
-# Disable real HTTPS in dev environment
-tls_cert_path: ""
-tls_key_path: ""
-
-# Database configuration
-database:
-  type: sqlite3
-  sqlite:
-    path: /var/lib/headscale/db.sqlite
-
-# Ephemeral node configuration
-ephemeral_node_inactivity_timeout: 30m
-
-# Node management
-node_update_check_interval: 10s
-
-# Logging
-log:
-  level: debug
-  format: text
-
-# DNS configuration
-dns:
-  magic_dns: true
-  base_domain: headscale.local
-  nameservers:
-    global:
-      - 1.1.1.1
-      - 8.8.8.8
-  search_domains: []
-
-# Policy configuration
-policy:
-  mode: file
-  path: /etc/headscale/acl.hujson
-
-# CLI configuration
-cli:
-  timeout: 5s
-  insecure: false
-
-# Disable random server_url check
-disable_check_updates: true

docker-dev/keycloak-config/realm-export.json

@@ -1,188 +0,0 @@
-{
-  "id": "headscale",
-  "realm": "headscale",
-  "displayName": "Headscale OIDC Test Realm",
-  "enabled": true,
-  "sslRequired": "external",
-  "registrationAllowed": false,
-  "loginWithEmailAllowed": true,
-  "duplicateEmailsAllowed": false,
-  "resetPasswordAllowed": true,
-  "editUsernameAllowed": true,
-  "bruteForceProtected": true,
-  "groups": [
-    {
-      "id": "headscale-owner",
-      "name": "headscale-owner",
-      "path": "/headscale-owner"
-    },
-    {
-      "id": "headscale-admin", 
-      "name": "headscale-admin",
-      "path": "/headscale-admin"
-    },
-    {
-      "id": "headscale-network",
-      "name": "headscale-network", 
-      "path": "/headscale-network"
-    },
-    {
-      "id": "headscale-it",
-      "name": "headscale-it",
-      "path": "/headscale-it"
-    },
-    {
-      "id": "headscale-audit", 
-      "name": "headscale-audit",
-      "path": "/headscale-audit"
-    },
-    {
-      "id": "headscale-member",
-      "name": "headscale-member",
-      "path": "/headscale-member"
-    }
-  ],
-  "users": [
-    {
-      "username": "owner@example.com",
-      "enabled": true,
-      "email": "owner@example.com",
-      "firstName": "Owner",
-      "lastName": "User", 
-      "credentials": [
-        {
-          "type": "password",
-          "value": "password123",
-          "temporary": false
-        }
-      ],
-      "groups": ["/headscale-owner"]
-    },
-    {
-      "username": "admin@example.com",
-      "enabled": true,
-      "email": "admin@example.com", 
-      "firstName": "Admin",
-      "lastName": "User",
-      "credentials": [
-        {
-          "type": "password",
-          "value": "password123",
-          "temporary": false
-        }
-      ],
-      "groups": ["/headscale-admin"]
-    },
-    {
-      "username": "network@example.com",
-      "enabled": true,
-      "email": "network@example.com",
-      "firstName": "Network",
-      "lastName": "Admin",
-      "credentials": [
-        {
-          "type": "password", 
-          "value": "password123",
-          "temporary": false
-        }
-      ],
-      "groups": ["/headscale-network"]
-    },
-    {
-      "username": "auditor@example.com",
-      "enabled": true,
-      "email": "auditor@example.com",
-      "firstName": "Auditor", 
-      "lastName": "User",
-      "credentials": [
-        {
-          "type": "password",
-          "value": "password123", 
-          "temporary": false
-        }
-      ],
-      "groups": ["/headscale-audit"]
-    },
-    {
-      "username": "member@example.com",
-      "enabled": true,
-      "email": "member@example.com",
-      "firstName": "Member",
-      "lastName": "User",
-      "credentials": [
-        {
-          "type": "password",
-          "value": "password123",
-          "temporary": false
-        }
-      ],
-      "groups": ["/headscale-member"]
-    }
-  ],
-  "clients": [
-    {
-      "clientId": "headscale-client",
-      "name": "Headscale OIDC Client",
-      "enabled": true,
-      "clientAuthenticatorType": "client-secret",
-      "secret": "your-client-secret",
-      "redirectUris": ["http://localhost:8180/oidc/callback"],
-      "webOrigins": ["http://localhost:8180"],
-      "standardFlowEnabled": true,
-      "implicitFlowEnabled": false,
-      "directAccessGrantsEnabled": false,
-      "serviceAccountsEnabled": false,
-      "publicClient": false,
-      "frontchannelLogout": true,
-      "protocol": "openid-connect",
-      "fullScopeAllowed": true,
-      "protocolMappers": [
-        {
-          "name": "groups",
-          "protocol": "openid-connect", 
-          "protocolMapper": "oidc-group-membership-mapper",
-          "consentRequired": false,
-          "config": {
-            "full.path": "false",
-            "id.token.claim": "true",
-            "access.token.claim": "true",
-            "claim.name": "groups",
-            "userinfo.token.claim": "true"
-          }
-        }
-      ]
-    },
-    {
-      "clientId": "headplane-client",
-      "name": "Headplane OIDC Client",
-      "enabled": true,
-      "clientAuthenticatorType": "client-secret",
-      "secret": "headplane-client-secret",
-      "redirectUris": ["http://localhost:3000/admin/oidc/callback"],
-      "webOrigins": ["http://localhost:3000"],
-      "standardFlowEnabled": true,
-      "implicitFlowEnabled": false,
-      "directAccessGrantsEnabled": false,
-      "serviceAccountsEnabled": false,
-      "publicClient": false,
-      "frontchannelLogout": true,
-      "protocol": "openid-connect",
-      "fullScopeAllowed": true,
-      "protocolMappers": [
-        {
-          "name": "groups",
-          "protocol": "openid-connect",
-          "protocolMapper": "oidc-group-membership-mapper",
-          "consentRequired": false,
-          "config": {
-            "full.path": "false",
-            "id.token.claim": "true",
-            "access.token.claim": "true",
-            "claim.name": "groups",
-            "userinfo.token.claim": "true"
-          }
-        }
-      ]
-    }
-  ]
-}

docker-dev/scripts/client-init.sh

@@ -1,38 +0,0 @@
-#!/bin/sh
-# Tailscale client initialization script
-
-CLIENT_NAME=$1
-HEADSCALE_URL="http://headscale:8080"
-
-echo "Initializing Tailscale client: $CLIENT_NAME"
-echo "Headscale server: $HEADSCALE_URL"
-
-# Wait for tailscaled to be ready
-sleep 5
-
-# Check if we have an auth key
-if [ -n "$TS_AUTHKEY" ]; then
-    echo "Using provided auth key to register..."
-    tailscale up \
-        --login-server=$HEADSCALE_URL \
-        --authkey=$TS_AUTHKEY \
-        --hostname=$CLIENT_NAME \
-        --accept-routes
-else
-    echo "No auth key provided. Manual registration required."
-    echo "To register this client:"
-    echo "1. Get the registration URL:"
-    echo "   docker exec $CLIENT_NAME tailscale up --login-server=$HEADSCALE_URL"
-    echo "2. In another terminal, approve the node:"
-    echo "   docker exec headscale-server headscale nodes register --user myuser --key <nodekey>"
-    
-    # Start tailscale in manual mode
-    tailscale up \
-        --login-server=$HEADSCALE_URL \
-        --hostname=$CLIENT_NAME \
-        --accept-routes
-fi
-
-# Keep the container running
-echo "Tailscale client $CLIENT_NAME is running..."
-tail -f /dev/null

docker-dev/scripts/setup-headscale.sh

@@ -1,54 +0,0 @@
-#!/bin/bash
-# Setup script for Headscale server
-# Creates users and generates pre-auth keys for Tailscale clients
-
-set -e
-
-echo "Waiting for Headscale to be ready..."
-sleep 5
-
-# Create a user for our test environment
-echo "Creating user 'testuser'..."
-docker exec headscale-server headscale users create testuser || echo "User might already exist"
-
-# Get the user ID (newer Headscale versions require user ID instead of username)
-echo "Getting user ID..."
-USER_ID=$(docker exec headscale-server headscale --output json users list | jq -r '.[] | select(.username=="testuser") | .id' 2>/dev/null)
-
-if [ -z "$USER_ID" ]; then
-    echo "Failed to get user ID. Trying alternative method..."
-    USER_ID=1  # Default to 1 for first user
-fi
-
-echo "Using user ID: $USER_ID"
-
-# Generate pre-auth keys for the clients using user ID
-echo "Generating pre-auth keys..."
-KEY1=$(docker exec headscale-server headscale --output json preauthkeys create --user $USER_ID --reusable --expiration 24h | jq -r '.key' 2>/dev/null || echo "")
-KEY2=$(docker exec headscale-server headscale --output json preauthkeys create --user $USER_ID --reusable --expiration 24h | jq -r '.key' 2>/dev/null || echo "")
-
-if [ -z "$KEY1" ] || [ -z "$KEY2" ]; then
-    echo "Failed to generate pre-auth keys automatically."
-    echo "You can create them manually with:"
-    echo "  docker exec headscale-server headscale preauthkeys create --user $USER_ID --reusable --expiration 24h"
-    echo ""
-    echo "Then add them to the .env file:"
-    echo "  TS_AUTHKEY_CLIENT1=<key1>"
-    echo "  TS_AUTHKEY_CLIENT2=<key2>"
-else
-    # Save the keys to .env file
-    cat > .env << EOF
-# Headscale pre-auth keys for Tailscale clients
-COMPOSE_PROJECT_NAME=headscale-dev
-TS_AUTHKEY_CLIENT1=$KEY1
-TS_AUTHKEY_CLIENT2=$KEY2
-EOF
-    
-    echo "Pre-auth keys saved to .env file:"
-    echo "  Client1: $KEY1"
-    echo "  Client2: $KEY2"
-fi
-
-echo ""
-echo "Setup complete! You can now restart the clients with:"
-echo "  docker compose restart tailscale-client1 tailscale-client2"

docker-dev/test-oidc-roles.sh

@@ -1,208 +0,0 @@
-#!/bin/bash
-
-# Test script for OIDC role mapping functionality
-# This script tests the complete flow from OIDC authentication to role assignment
-
-set -e
-
-echo "🚀 Starting OIDC Role Mapping Test Suite"
-echo "========================================"
-
-# Configuration
-KEYCLOAK_URL="http://localhost:8280"
-HEADSCALE_URL="http://localhost:8180"
-HEADPLANE_URL="http://localhost:3000"
-REALM="headscale"
-
-# Test users with different roles
-declare -A TEST_USERS=(
-    ["owner@example.com"]="owner"
-    ["admin@example.com"]="admin" 
-    ["network@example.com"]="network_admin"
-    ["auditor@example.com"]="auditor"
-    ["member@example.com"]="member"
-)
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-print_status() {
-    echo -e "${GREEN}✓${NC} $1"
-}
-
-print_warning() {
-    echo -e "${YELLOW}⚠${NC} $1"
-}
-
-print_error() {
-    echo -e "${RED}✗${NC} $1"
-}
-
-# Function to wait for service to be ready
-wait_for_service() {
-    local url=$1
-    local service_name=$2
-    local max_attempts=30
-    local attempt=1
-
-    echo "⏳ Waiting for $service_name to be ready..."
-    
-    while [ $attempt -le $max_attempts ]; do
-        if curl -sf "$url" > /dev/null 2>&1; then
-            print_status "$service_name is ready!"
-            return 0
-        fi
-        
-        echo "   Attempt $attempt/$max_attempts failed, retrying in 5 seconds..."
-        sleep 5
-        ((attempt++))
-    done
-    
-    print_error "$service_name failed to start after $max_attempts attempts"
-    return 1
-}
-
-# Function to get Keycloak admin token
-get_keycloak_token() {
-    echo "🔑 Getting Keycloak admin token..."
-    
-    local response=$(curl -sf \
-        -d "client_id=admin-cli" \
-        -d "username=admin" \
-        -d "password=admin" \
-        -d "grant_type=password" \
-        "$KEYCLOAK_URL/realms/master/protocol/openid-connect/token")
-    
-    if [ $? -eq 0 ]; then
-        echo "$response" | jq -r '.access_token'
-    else
-        print_error "Failed to get Keycloak admin token"
-        return 1
-    fi
-}
-
-# Function to import realm configuration
-import_realm() {
-    local token=$1
-    
-    echo "📥 Importing Headscale realm configuration..."
-    
-    local response=$(curl -sf \
-        -H "Authorization: Bearer $token" \
-        -H "Content-Type: application/json" \
-        -d @keycloak-config/realm-export.json \
-        "$KEYCLOAK_URL/admin/realms")
-    
-    if [ $? -eq 0 ]; then
-        print_status "Realm imported successfully"
-    else
-        print_warning "Realm import failed (may already exist)"
-    fi
-}
-
-# Function to test user authentication and role assignment
-test_user_role() {
-    local email=$1
-    local expected_role=$2
-    
-    echo "👤 Testing user: $email (expected role: $expected_role)"
-    
-    # In a real test, you would:
-    # 1. Simulate OIDC login flow
-    # 2. Extract tokens and groups from response
-    # 3. Verify Headscale user creation with correct groups
-    # 4. Verify Headplane role assignment
-    
-    # For now, we'll simulate the key parts:
-    echo "   - Simulating OIDC login flow..."
-    echo "   - Checking group membership in Keycloak..."
-    echo "   - Verifying role mapping in Headplane..."
-    
-    print_status "User $email test completed"
-}
-
-# Function to verify Headscale API
-test_headscale_api() {
-    echo "🔧 Testing Headscale API..."
-    
-    local response=$(curl -sf "$HEADSCALE_URL/health")
-    if [ $? -eq 0 ]; then
-        print_status "Headscale API is healthy"
-    else
-        print_error "Headscale API is not responding"
-        return 1
-    fi
-}
-
-# Function to verify Headplane UI
-test_headplane_ui() {
-    echo "🖥️  Testing Headplane UI..."
-    
-    local response=$(curl -sf "$HEADPLANE_URL/admin")
-    if [ $? -eq 0 ]; then
-        print_status "Headplane UI is accessible"
-    else
-        print_error "Headplane UI is not responding"
-        return 1
-    fi
-}
-
-# Main test execution
-main() {
-    echo "Starting services health check..."
-    
-    # Wait for all services to be ready
-    wait_for_service "$KEYCLOAK_URL/realms/master" "Keycloak"
-    wait_for_service "$HEADSCALE_URL/health" "Headscale"  
-    wait_for_service "$HEADPLANE_URL/admin" "Headplane"
-    
-    # Get Keycloak admin token and import realm
-    local token=$(get_keycloak_token)
-    if [ -n "$token" ]; then
-        import_realm "$token"
-    fi
-    
-    # Test individual services
-    test_headscale_api
-    test_headplane_ui
-    
-    echo ""
-    echo "🧪 Running user role mapping tests..."
-    echo "===================================="
-    
-    # Test each user role mapping
-    for email in "${!TEST_USERS[@]}"; do
-        test_user_role "$email" "${TEST_USERS[$email]}"
-        echo ""
-    done
-    
-    echo ""
-    echo "📋 Test Summary"
-    echo "==============="
-    echo "✅ OIDC provider (Keycloak) configured with test realm"
-    echo "✅ Headscale updated with Groups field and OIDC integration"
-    echo "✅ Headplane updated with role mapping functionality"
-    echo "✅ Test users created with different group memberships"
-    echo ""
-    echo "🎯 Manual Testing Steps:"
-    echo "1. Open Keycloak admin console: $KEYCLOAK_URL (admin/admin)"
-    echo "2. Open Headplane UI: $HEADPLANE_URL/admin"
-    echo "3. Test OIDC login with different users:"
-    for email in "${!TEST_USERS[@]}"; do
-        echo "   - $email (password: password123) -> Expected role: ${TEST_USERS[$email]}"
-    done
-    echo ""
-    echo "🔍 Verification Points:"
-    echo "- User groups are extracted from OIDC claims"
-    echo "- Groups are stored in Headscale user database"
-    echo "- Headplane maps groups to correct roles"
-    echo "- UI permissions reflect assigned roles"
-    
-    print_status "OIDC Role Mapping Test Suite completed!"
-}
-
-# Run the tests
-main "$@"

docker-dev/validate-implementation.sh

@@ -1,410 +0,0 @@
-#!/bin/bash
-
-# Comprehensive OIDC Role Mapping Implementation Validator
-# This script validates the complete implementation across both Headscale and Headplane
-
-set -e
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-print_header() {
-    echo -e "\n${BLUE}========================================${NC}"
-    echo -e "${BLUE}$1${NC}"
-    echo -e "${BLUE}========================================${NC}\n"
-}
-
-print_success() {
-    echo -e "${GREEN}✓${NC} $1"
-}
-
-print_warning() {
-    echo -e "${YELLOW}⚠${NC} $1"
-}
-
-print_error() {
-    echo -e "${RED}✗${NC} $1"
-}
-
-print_info() {
-    echo -e "${BLUE}ℹ${NC} $1"
-}
-
-# Test counters
-TESTS_PASSED=0
-TESTS_FAILED=0
-TESTS_TOTAL=0
-
-run_test() {
-    local test_name="$1"
-    local test_command="$2"
-    
-    ((TESTS_TOTAL++))
-    echo -n "Testing: $test_name... "
-    
-    if eval "$test_command" >/dev/null 2>&1; then
-        print_success "PASSED"
-        ((TESTS_PASSED++))
-    else
-        print_error "FAILED"
-        ((TESTS_FAILED++))
-        echo "  Command: $test_command"
-    fi
-}
-
-# Validate Headscale Implementation
-validate_headscale() {
-    print_header "Validating Headscale OIDC Groups Implementation"
-    
-    # Check if Headscale binary exists and is updated
-    run_test "Headscale binary exists" "which headscale"
-    
-    # Check database schema for groups column
-    if [ -f "/var/lib/headscale/db.sqlite" ]; then
-        run_test "Groups column exists in users table" \
-            "sqlite3 /var/lib/headscale/db.sqlite '.schema users' | grep -q 'groups'"
-    else
-        print_warning "Headscale database not found at expected location"
-    fi
-    
-    # Check source code for groups functionality
-    if [ -f "../hscontrol/types/users.go" ]; then
-        run_test "GetGroups method exists" \
-            "grep -q 'func.*GetGroups' ../hscontrol/types/users.go"
-        
-        run_test "SetGroups method exists" \
-            "grep -q 'func.*SetGroups' ../hscontrol/types/users.go"
-        
-        run_test "Groups field in User struct" \
-            "grep -q 'Groups.*string' ../hscontrol/types/users.go"
-    else
-        print_warning "Headscale source code not found"
-    fi
-    
-    # Check migration file exists
-    run_test "Groups migration file exists" \
-        "ls ../hscontrol/db/db.go | xargs grep -q '202509161200'"
-    
-    # Check OIDC integration for groups
-    if [ -f "../hscontrol/oidc.go" ]; then
-        run_test "OIDC groups extraction in FromClaim" \
-            "grep -q 'SetGroups.*claims.Groups' ../hscontrol/types/users.go"
-    fi
-}
-
-# Validate Headplane Implementation
-validate_headplane() {
-    print_header "Validating Headplane OIDC Role Mapping Implementation"
-    
-    # Check if we're in the right directory structure
-    if [ -d "../../headplane" ]; then
-        cd ../../headplane
-        
-        # Check TypeScript/JavaScript files for role mapping
-        run_test "FlowUser interface includes groups" \
-            "grep -q 'groups.*string\[\]' app/utils/oidc.ts"
-        
-        run_test "extractGroups function exists" \
-            "grep -q 'function extractGroups' app/utils/oidc.ts"
-        
-        run_test "mapOidcGroupsToRole function exists" \
-            "grep -q 'mapOidcGroupsToRole' app/server/web/roles.ts"
-        
-        run_test "Groups field in database schema" \
-            "grep -q 'groups.*json' app/server/db/schema.ts"
-        
-        run_test "OIDC callback uses role mapping" \
-            "grep -q 'mapOidcGroupsToRole' app/routes/auth/oidc-callback.ts"
-        
-        run_test "Migration file for groups column" \
-            "ls drizzle/0003_add_groups_column.sql"
-        
-        # Check for proper imports
-        run_test "Role mapping imported in callback" \
-            "grep -q 'mapOidcGroupsToRole' app/routes/auth/oidc-callback.ts"
-        
-        cd - >/dev/null
-    else
-        print_warning "Headplane directory not found"
-    fi
-}
-
-# Validate Configuration Files
-validate_configurations() {
-    print_header "Validating Configuration Files"
-    
-    # Check Headscale OIDC config
-    if [ -f "headscale-config-oidc.yaml" ]; then
-        run_test "Headscale OIDC config includes groups scope" \
-            "grep -q 'groups' headscale-config-oidc.yaml"
-    else
-        print_warning "Headscale OIDC config not found"
-    fi
-    
-    # Check Headplane OIDC config
-    if [ -f "headplane-config-oidc.yaml" ]; then
-        run_test "Headplane OIDC config includes groups scope" \
-            "grep -q 'groups' headplane-config-oidc.yaml"
-        
-        run_test "Headplane has role mapping configuration" \
-            "grep -q 'role_mapping' headplane-config-oidc.yaml"
-    else
-        print_warning "Headplane OIDC config not found"
-    fi
-    
-    # Check Keycloak realm configuration
-    if [ -f "keycloak-config/realm-export.json" ]; then
-        run_test "Keycloak realm has groups defined" \
-            "grep -q 'headscale-owner' keycloak-config/realm-export.json"
-        
-        run_test "Keycloak clients have group mappers" \
-            "grep -q 'oidc-group-membership-mapper' keycloak-config/realm-export.json"
-    else
-        print_warning "Keycloak realm config not found"
-    fi
-}
-
-# Validate Docker Setup
-validate_docker_setup() {
-    print_header "Validating Docker Test Environment"
-    
-    run_test "Docker Compose OIDC test file exists" \
-        "ls docker-compose-oidc-test.yml"
-    
-    run_test "Test script exists and is executable" \
-        "test -x test-oidc-roles.sh"
-    
-    # Check if Docker is available
-    run_test "Docker is available" \
-        "docker --version"
-    
-    run_test "Docker Compose is available" \
-        "docker compose version"
-}
-
-# Validate Dependencies
-validate_dependencies() {
-    print_header "Validating Dependencies and Versions"
-    
-    # Check Go version for Headscale
-    if command -v go >/dev/null 2>&1; then
-        GO_VERSION=$(go version | grep -o 'go[0-9]\+\.[0-9]\+' | sed 's/go//')
-        if [ "$(printf '%s\n' "1.21" "$GO_VERSION" | sort -V | head -n1)" = "1.21" ]; then
-            print_success "Go version $GO_VERSION is compatible"
-        else
-            print_warning "Go version $GO_VERSION may be too old (minimum 1.21)"
-        fi
-    else
-        print_warning "Go not found"
-    fi
-    
-    # Check Node.js version for Headplane
-    if command -v node >/dev/null 2>&1; then
-        NODE_VERSION=$(node --version | sed 's/v//')
-        NODE_MAJOR=$(echo $NODE_VERSION | cut -d. -f1)
-        if [ "$NODE_MAJOR" -ge 18 ]; then
-            print_success "Node.js version $NODE_VERSION is compatible"
-        else
-            print_warning "Node.js version $NODE_VERSION may be too old (minimum 18)"
-        fi
-    else
-        print_warning "Node.js not found"
-    fi
-    
-    # Check for required tools
-    run_test "jq is available" "command -v jq"
-    run_test "curl is available" "command -v curl"
-    run_test "sqlite3 is available" "command -v sqlite3"
-}
-
-# Validate Documentation
-validate_documentation() {
-    print_header "Validating Documentation"
-    
-    run_test "OIDC Role Mapping documentation exists" \
-        "ls ../OIDC_ROLE_MAPPING.md"
-    
-    run_test "Deployment guide exists" \
-        "ls ../DEPLOYMENT_GUIDE.md"
-    
-    run_test "Role mapping examples exist" \
-        "ls ../../headplane/role-mapping-examples.yaml"
-    
-    run_test "Monitoring configuration exists" \
-        "ls ../monitoring-config.yaml"
-}
-
-# Test Database Schema
-test_database_schema() {
-    print_header "Testing Database Schema Changes"
-    
-    # Create temporary test database for Headscale
-    TEMP_DB="/tmp/test_headscale.db"
-    rm -f "$TEMP_DB"
-    
-    # Simulate database schema with groups column
-    sqlite3 "$TEMP_DB" "CREATE TABLE users (
-        id INTEGER PRIMARY KEY,
-        name TEXT,
-        email TEXT,
-        groups TEXT
-    );"
-    
-    run_test "Can insert user with groups" \
-        "sqlite3 '$TEMP_DB' \"INSERT INTO users (name, email, groups) VALUES ('test', 'test@example.com', '[\"admin\", \"users\"]');\""
-    
-    run_test "Can query groups from database" \
-        "sqlite3 '$TEMP_DB' \"SELECT groups FROM users WHERE name='test';\" | grep -q admin"
-    
-    rm -f "$TEMP_DB"
-    
-    # Test Headplane schema if sqlite3 available
-    TEMP_HP_DB="/tmp/test_headplane.db"
-    rm -f "$TEMP_HP_DB"
-    
-    sqlite3 "$TEMP_HP_DB" "CREATE TABLE users (
-        id TEXT PRIMARY KEY,
-        sub TEXT NOT NULL UNIQUE,
-        caps INTEGER NOT NULL DEFAULT 0,
-        onboarded INTEGER NOT NULL DEFAULT false,
-        groups TEXT DEFAULT '[]'
-    );"
-    
-    run_test "Headplane users table accepts groups" \
-        "sqlite3 '$TEMP_HP_DB' \"INSERT INTO users (id, sub, groups) VALUES ('1', 'test', '[\"group1\"]');\""
-    
-    rm -f "$TEMP_HP_DB"
-}
-
-# Test Role Mapping Logic
-test_role_mapping() {
-    print_header "Testing Role Mapping Logic"
-    
-    # Create a simple test of the role mapping logic
-    cat > /tmp/test_role_mapping.js << 'EOF'
-const mapOidcGroupsToRole = (groups, config) => {
-    if (!groups || groups.length === 0) return 'member';
-    
-    const groupMapping = config || {
-        'owner': 'owner',
-        'admin': 'admin',
-        'headscale-admin': 'admin',
-        'network-admin': 'network_admin',
-        'auditor': 'auditor'
-    };
-    
-    const roleHierarchy = ['owner', 'admin', 'network_admin', 'it_admin', 'auditor', 'member'];
-    
-    for (const role of roleHierarchy) {
-        for (const group of groups) {
-            const normalizedGroup = group.toLowerCase().trim();
-            for (const [mappedGroup, mappedRole] of Object.entries(groupMapping)) {
-                if (mappedRole === role && normalizedGroup === mappedGroup.toLowerCase()) {
-                    return role;
-                }
-            }
-        }
-    }
-    return 'member';
-};
-
-// Test cases
-const tests = [
-    { groups: ['owner'], expected: 'owner' },
-    { groups: ['admin'], expected: 'admin' },
-    { groups: ['headscale-admin'], expected: 'admin' },
-    { groups: ['network-admin'], expected: 'network_admin' },
-    { groups: ['auditor'], expected: 'auditor' },
-    { groups: ['unknown'], expected: 'member' },
-    { groups: [], expected: 'member' },
-    { groups: ['admin', 'owner'], expected: 'owner' }
-];
-
-let passed = 0;
-tests.forEach((test, i) => {
-    const result = mapOidcGroupsToRole(test.groups);
-    if (result === test.expected) {
-        passed++;
-    } else {
-        console.log(`Test ${i+1} failed: groups=${JSON.stringify(test.groups)}, expected=${test.expected}, got=${result}`);
-    }
-});
-
-console.log(`${passed}/${tests.length} role mapping tests passed`);
-process.exit(passed === tests.length ? 0 : 1);
-EOF
-    
-    if command -v node >/dev/null 2>&1; then
-        run_test "Role mapping logic works correctly" \
-            "node /tmp/test_role_mapping.js"
-    else
-        print_warning "Node.js not available for role mapping tests"
-    fi
-    
-    rm -f /tmp/test_role_mapping.js
-}
-
-# Generate Implementation Report
-generate_report() {
-    print_header "Implementation Validation Report"
-    
-    echo "Test Results Summary:"
-    echo "  Total Tests: $TESTS_TOTAL"
-    echo "  Passed: $TESTS_PASSED"
-    echo "  Failed: $TESTS_FAILED"
-    echo "  Success Rate: $(( TESTS_PASSED * 100 / TESTS_TOTAL ))%"
-    echo ""
-    
-    if [ $TESTS_FAILED -eq 0 ]; then
-        print_success "All tests passed! Implementation appears to be complete."
-        echo ""
-        echo "Next Steps:"
-        echo "1. Run the full Docker test environment: docker compose -f docker-compose-oidc-test.yml up -d"
-        echo "2. Execute the role mapping tests: ./test-oidc-roles.sh"
-        echo "3. Test manual OIDC login with different user roles"
-        echo "4. Deploy to staging environment for integration testing"
-    else
-        print_warning "Some tests failed. Please review the failures above."
-        echo ""
-        echo "Common fixes:"
-        echo "- Ensure all source files have been modified correctly"
-        echo "- Check that migrations have been applied"
-        echo "- Verify configuration files are in place"
-        echo "- Confirm dependencies are installed"
-    fi
-    
-    echo ""
-    echo "Implementation Components Validated:"
-    echo "  ✓ Headscale OIDC groups extraction and storage"
-    echo "  ✓ Headplane role mapping from OIDC groups"
-    echo "  ✓ Database schema changes for both systems"
-    echo "  ✓ Configuration files for testing"
-    echo "  ✓ Docker test environment setup"
-    echo "  ✓ Documentation and deployment guides"
-    echo ""
-}
-
-# Main execution
-main() {
-    print_header "OIDC Role Mapping Implementation Validator"
-    print_info "This script validates the complete OIDC role mapping implementation"
-    print_info "across both Headscale and Headplane components."
-    
-    validate_dependencies
-    validate_headscale
-    validate_headplane
-    validate_configurations
-    validate_docker_setup
-    validate_documentation
-    test_database_schema
-    test_role_mapping
-    
-    generate_report
-}
-
-# Run validation
-main "$@"

docker-dev/www/index.html

@@ -1,65 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-    <title>Headscale Test Environment</title>
-    <style>
-        body {
-            font-family: system-ui, -apple-system, sans-serif;
-            max-width: 800px;
-            margin: 50px auto;
-            padding: 20px;
-            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-            min-height: 100vh;
-        }
-        .container {
-            background: white;
-            border-radius: 10px;
-            padding: 30px;
-            box-shadow: 0 20px 40px rgba(0,0,0,0.1);
-        }
-        h1 {
-            color: #333;
-            border-bottom: 3px solid #667eea;
-            padding-bottom: 10px;
-        }
-        .status {
-            background: #f0f9ff;
-            border-left: 4px solid #3b82f6;
-            padding: 15px;
-            margin: 20px 0;
-            border-radius: 5px;
-        }
-        code {
-            background: #f3f4f6;
-            padding: 2px 6px;
-            border-radius: 3px;
-            font-family: 'Courier New', monospace;
-        }
-    </style>
-</head>
-<body>
-    <div class="container">
-        <h1>🎉 Headscale Test Environment</h1>
-        <div class="status">
-            <strong>✅ Web Server is accessible!</strong>
-            <p>If you can see this page, the Tailscale network is working correctly.</p>
-        </div>
-        
-        <h2>Test Commands</h2>
-        <p>Try these commands from the Tailscale clients:</p>
-        <ul>
-            <li><code>curl http://webserver</code> - Access this page</li>
-            <li><code>tailscale ping client2</code> - Ping another client</li>
-            <li><code>tailscale status</code> - Check network status</li>
-        </ul>
-        
-        <h2>Network Information</h2>
-        <p>This server is running on the Headscale-managed Tailscale network.</p>
-        <ul>
-            <li>Docker Network: <code>10.99.0.30</code></li>
-            <li>Tailscale Network: <code>100.64.x.x</code></li>
-            <li>Hostname: <code>webserver</code></li>
-        </ul>
-    </div>
-</body>
-</html>

docs/ref/api-groups.md

@@ -1,309 +0,0 @@
-# API Reference: OIDC Groups
-
-This document describes the API changes related to OIDC group storage and management introduced in Headscale v0.24.0.
-
-## Overview
-
-Headscale now stores OIDC group membership information extracted from authentication claims. This enables external integrations to implement role-based access control based on a user's group membership.
-
-## User API Changes
-
-### User Object Schema
-
-The User object now includes group information when users authenticate via OIDC:
-
-```json
-{
-  "id": "1",
-  "name": "alice",
-  "createdAt": "2024-01-01T00:00:00Z",
-  "displayName": "Alice Smith",
-  "email": "alice@example.com",
-  "providerId": "https://provider.com/alice",
-  "provider": "oidc",
-  "profilePicUrl": "https://provider.com/avatar/alice.jpg",
-  "groups": ["admin", "developers", "security-team"]
-}
-```
-
-### Field Descriptions
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `groups` | `string[]` | Array of group names extracted from OIDC claims. Empty array for non-OIDC users. |
-
-## API Endpoints
-
-### List Users
-
-Returns all users including their group membership.
-
-**Request:**
-```http
-GET /api/v1/user
-Authorization: Bearer <api-key>
-```
-
-**Response:**
-```json
-{
-  "users": [
-    {
-      "id": "1",
-      "name": "alice",
-      "email": "alice@example.com",
-      "provider": "oidc",
-      "groups": ["admin", "developers"]
-    },
-    {
-      "id": "2", 
-      "name": "bob",
-      "email": "",
-      "provider": "cli",
-      "groups": []
-    }
-  ]
-}
-```
-
-### Get User
-
-Returns a specific user including group membership.
-
-**Request:**
-```http
-GET /api/v1/user/{name}
-Authorization: Bearer <api-key>
-```
-
-**Response:**
-```json
-{
-  "user": {
-    "id": "1",
-    "name": "alice",
-    "email": "alice@example.com",
-    "provider": "oidc",
-    "groups": ["admin", "developers", "security-team"]
-  }
-}
-```
-
-## Group Management
-
-### Automatic Group Updates
-
-Groups are automatically updated when OIDC users authenticate:
-
-1. User logs in via OIDC
-2. Groups are extracted from ID token and/or UserInfo endpoint
-3. User's group membership is updated in the database
-4. API responses include updated group information
-
-### Group Sources
-
-Groups can be extracted from multiple sources in OIDC claims:
-
-- **Standard `groups` claim**: Most common format
-- **`roles` claim**: Alternative role-based claim
-- **Provider-specific claims**: e.g., `cognito:groups` for AWS Cognito
-- **Nested claims**: e.g., `resource_access.client.roles` for Keycloak
-
-### Group Validation
-
-- Only string values are accepted as group names
-- Empty or null groups are filtered out
-- Group names are stored as-is (case-sensitive)
-- Maximum reasonable limit of groups per user (no strict limit enforced)
-
-## Integration Examples
-
-### Role-Based Access Control
-
-External applications can query user groups for access control:
-
-```bash
-# Get user groups via API
-curl -H "Authorization: Bearer $API_KEY" \
-  https://headscale.example.com/api/v1/user/alice | \
-  jq '.user.groups[]'
-
-# Check if user has admin group
-curl -H "Authorization: Bearer $API_KEY" \
-  https://headscale.example.com/api/v1/user/alice | \
-  jq '.user.groups | contains(["admin"])'
-```
-
-### Database Queries
-
-For direct database access:
-
-```sql
--- Get all users with their groups
-SELECT name, email, groups FROM users WHERE provider = 'oidc';
-
--- Find users in specific group
-SELECT name FROM users 
-WHERE provider = 'oidc' 
-AND JSON_EXTRACT(groups, '$') LIKE '%"admin"%';
-
--- Count users by group membership
-SELECT 
-  json_each.value as group_name,
-  COUNT(*) as user_count
-FROM users, json_each(users.groups)
-WHERE provider = 'oidc'
-GROUP BY json_each.value;
-```
-
-## WebUI Integration
-
-### Headplane Integration
-
-When using Headplane as a web interface, the groups information enables:
-
-- **Automatic Role Assignment**: Map OIDC groups to Headplane roles
-- **Dynamic Permissions**: Update user capabilities based on current group membership  
-- **Audit Trails**: Track role assignments based on group changes
-
-Example Headplane API usage:
-
-```javascript
-// Fetch user with groups
-const response = await fetch('/api/v1/user/alice', {
-  headers: { 'Authorization': `Bearer ${apiKey}` }
-});
-const user = await response.json();
-
-// Map groups to roles
-const roles = mapGroupsToRoles(user.groups);
-console.log(`User ${user.name} has roles:`, roles);
-```
-
-## Backward Compatibility
-
-### CLI Users
-
-- Users created via CLI (`headscale users create`) have empty groups array
-- No changes to existing CLI user management
-- Groups field is optional and defaults to empty array
-
-### API Compatibility
-
-- All existing API endpoints continue to work unchanged
-- New `groups` field is additive (doesn't break existing clients)
-- Clients can safely ignore the groups field if not needed
-
-### Migration
-
-- Existing OIDC users will have empty groups until next login
-- No database migration required for basic functionality
-- Groups are populated automatically on subsequent OIDC logins
-
-## Configuration
-
-### Headscale Configuration
-
-Ensure groups scope is included for group extraction:
-
-```yaml
-oidc:
-  issuer: "https://your-provider.com"
-  client_id: "headscale"
-  client_secret: "your-secret"
-  scope: ["openid", "profile", "email", "groups"]
-```
-
-### Provider-Specific Configuration
-
-=== "Keycloak"
-    ```yaml
-    # Keycloak automatically includes groups in standard format
-    oidc:
-      scope: ["openid", "profile", "email", "groups"]
-    ```
-
-=== "Azure AD"
-    ```yaml
-    # Azure AD requires group claims configuration
-    oidc:
-      scope: ["openid", "profile", "email"]
-      # Groups included via claims configuration in Azure AD
-    ```
-
-=== "Okta" 
-    ```yaml
-    # Okta supports groups in tokens
-    oidc:
-      scope: ["openid", "profile", "email", "groups"]
-    ```
-
-## Error Handling
-
-### Common Issues
-
-**Groups not appearing:**
-- Verify `groups` scope is included in OIDC configuration
-- Check identity provider group claim configuration
-- Ensure user is member of groups in identity provider
-
-**Invalid group data:**
-- Non-string group values are automatically filtered out
-- Empty arrays are valid (user has no groups)
-- Malformed JSON is handled gracefully with empty array fallback
-
-### Error Responses
-
-Standard HTTP error codes apply:
-
-- `401 Unauthorized`: Invalid or missing API key
-- `404 Not Found`: User does not exist  
-- `500 Internal Server Error`: Server-side processing error
-
-## Security Considerations
-
-### Access Control
-
-- Groups information is available to any client with valid API key
-- Consider creating read-only API keys for external integrations
-- Audit API key usage for compliance requirements
-
-### Data Privacy
-
-- Group names may contain sensitive organizational information
-- Consider data classification for group membership information
-- Implement appropriate access controls for group data
-
-### Token Security
-
-- Groups are extracted from verified OIDC tokens only
-- Token validation ensures groups cannot be spoofed
-- Groups are updated only during successful authentication
-
-## Monitoring and Observability
-
-### Metrics
-
-Monitor group extraction and updates:
-
-- Number of OIDC logins with groups extracted
-- Distribution of group membership across users
-- Failed group extractions or parsing errors
-
-### Logging
-
-Key log events to monitor:
-
-- Group extraction from OIDC claims
-- Group updates during user authentication
-- Group parsing errors or validation failures
-
-Example log entries:
-
-```
-INFO  Groups extracted from OIDC claims user=alice groups=["admin","developers"]
-WARN  Invalid group value filtered out user=bob value=123 type=number
-ERROR Failed to parse groups from OIDC claims user=charlie error="invalid JSON"
-```
-
-This API enhancement provides the foundation for implementing sophisticated role-based access control systems while maintaining backward compatibility with existing deployments.

docs/ref/oidc.md

@@ -274,6 +274,38 @@ oidc:
   scope: ["openid", "profile", "email", "groups"]
 ```
 
+### Identity provider configuration
+
+The `groups` scope is not part of the OpenID Connect core specification, so
+different identity providers handle it differently. Headscale stores whatever
+the provider emits, so misconfiguration on the IdP side shows up as garbage
+in the `users.groups` column.
+
+!!! warning "Authentik: do not attach a custom `groups` property mapping"
+
+    Authentik ships a built-in `groups` scope that emits the user's
+    `ak_groups.all()` as the `groups` claim automatically. If you also
+    attach a custom OAuth2 scope mapping with `scope_name: groups` to the
+    provider, Authentik runs *both* emitters and concatenates their outputs.
+    A user in groups `admins` and `users` ends up with
+    `["admins","users","admins","users"]` in the `users.groups` column.
+
+    The fix is to remove the custom mapping from the provider's property
+    mappings — the built-in `groups` scope alone produces exactly what
+    Headscale wants. Verified against Authentik 2025.8.
+
+!!! info "Keycloak and other providers"
+
+    Keycloak does not emit a `groups` claim by default. Create a "Group
+    Membership" mapper on the client scope `groups` (or directly on the
+    client) with token claim name `groups` and tick *Add to ID token*,
+    *Add to access token*, and *Add to userinfo*.
+
+    Other providers may need similar explicit configuration. If group
+    membership is missing from the stored `users.groups` column, check
+    the wire data first — the most common failure mode is "the provider
+    isn't emitting the claim", not "headscale isn't reading it".
+
 ### Headplane Integration
 When using [Headplane](https://github.com/tale/headplane) as a web interface for Headscale, OIDC groups enable automatic role-based access control:
 

flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1777270315,
-        "narHash": "sha256-yKB4G6cKsQsWN7M6rZGk6gkJPDNPIzT05y4qzRyCDlI=",
+        "lastModified": 1779351318,
+        "narHash": "sha256-f+JACbTqzZ+G92DSnXOUGRhGANb8Blh7CoeYOeBF8/U=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "6368eda62c9775c38ef7f714b2555a741c20c72d",
+        "rev": "4a29d733e8a7d5b824c3d8c958a946a9867b3eb2",
         "type": "github"
       },
       "original": {

flake.nix

@@ -62,16 +62,16 @@
 
           protoc-gen-grpc-gateway = buildGo rec {
             pname = "grpc-gateway";
-            version = "2.28.0";
+            version = "2.29.0";
 
             src = pkgs.fetchFromGitHub {
               owner = "grpc-ecosystem";
               repo = "grpc-gateway";
               rev = "v${version}";
-              sha256 = "sha256-93omvHb+b+S0w4D+FGEEwYYDjgumJFDAruc1P4elfvA=";
+              sha256 = "sha256-d9OIIGttyMBSNgpS6mbR5JEIm13qGu2gFHJazJAexdw=";
             };
 
-            vendorHash = "sha256-jVP5zfFPfHeAEApKNJzZwuZLA+DjKgkL7m2DFG72UNs=";
+            vendorHash = "sha256-p51yD+v8+rPs+ztlX7r0VQ4XlwUkxu+PxgknKEvH00k=";
 
             nativeBuildInputs = [ pkgs.installShellFiles ];
 
@@ -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.11.4";
+            version = "2.12.2";
 
             src = pkgs.fetchFromGitHub {
               owner = "golangci";
               repo = "golangci-lint";
               rev = "v${version}";
-              hash = "sha256-B19aLvfNRY9TOYw/71f2vpNUuSIz8OI4dL0ijGezsas=";
+              hash = "sha256-qR7fp1x2S+EwEAcplRHTvA3jWwLr/XSiYKSZtAwkrNU=";
             };
 
-            vendorHash = "sha256-xuoj4+U4tB5gpABKq4Dbp2cxnljxdYoBbO8A7DqPM5E=";
+            vendorHash = "sha256-AG5wtLwWLz55bdp1oi3cW+9O3yj1W1P7MV9zxym7Pb4=";
 
             subPackages = [ "cmd/golangci-lint" ];
 

flakehashes.json

@@ -1,6 +1,6 @@
 {
   "vendor": {
-    "goModSum": "sha256-nrTbTihH4NpnN817QxQEBZV5c7eneEcHl+AMMh8ehJY=",
-    "sri": "sha256-Y9f0Q2Kw07eB8bURLT0jce+YoSs2WoowEX7t8tkNDvw="
+    "goModSum": "sha256-xos6ixeJRMrEengGJaRiSsrm+3S3R0OEsnv1e85Sqhw=",
+    "sri": "sha256-bZod9sUUyQ67x/HzZrQ7SK+o5gAUxJhx7Rr6VdIUj1I="
   }
 }

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

@@ -1,6 +1,6 @@
 // Code generated by protoc-gen-go-grpc. DO NOT EDIT.
 // versions:
-// - protoc-gen-go-grpc v1.6.1
+// - protoc-gen-go-grpc v1.6.2
 // - protoc             (unknown)
 // source: headscale/v1/headscale.proto
 

go.mod

@@ -1,6 +1,6 @@
 module github.com/juanfont/headscale
 
-go 1.26.2
+go 1.26.3
 
 require (
 	github.com/arl/statsviz v0.8.0
@@ -8,20 +8,20 @@ require (
 	github.com/chasefleming/elem-go v0.31.0
 	github.com/coder/websocket v1.8.14
 	github.com/coreos/go-oidc/v3 v3.18.0
-	github.com/creachadair/command v0.2.2
-	github.com/creachadair/flax v0.0.5
+	github.com/creachadair/command v0.2.6
+	github.com/creachadair/flax v0.0.6
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc
 	github.com/docker/docker v28.5.2+incompatible
-	github.com/fsnotify/fsnotify v1.9.0
+	github.com/fsnotify/fsnotify v1.10.1
 	github.com/glebarez/sqlite v1.11.0
 	github.com/go-chi/chi/v5 v5.2.5
 	github.com/go-chi/metrics v0.1.1
 	github.com/go-gormigrate/gormigrate/v2 v2.1.5
-	github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433
+	github.com/go-json-experiment/json v0.0.0-20260520185125-572e7c383686
 	github.com/gofrs/uuid/v5 v5.4.0
 	github.com/google/go-cmp v0.7.0
 	github.com/gorilla/mux v1.8.1
-	github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0
 	github.com/hashicorp/golang-lru/v2 v2.0.7
 	github.com/jagottsicher/termcolor v1.0.2
 	github.com/oauth2-proxy/mockoidc v0.0.0-20240214162133-caebfff84d25
@@ -31,31 +31,32 @@ require (
 	github.com/prometheus/client_golang v1.23.2
 	github.com/prometheus/common v0.67.5
 	github.com/pterm/pterm v0.12.83
-	github.com/puzpuzpuz/xsync/v4 v4.4.0
-	github.com/rs/zerolog v1.35.0
+	github.com/puzpuzpuz/xsync/v4 v4.5.0
+	github.com/realclientip/realclientip-go v1.0.0
+	github.com/rs/zerolog v1.35.1
 	github.com/samber/lo v1.53.0
 	github.com/sasha-s/go-deadlock v0.3.9
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	github.com/stretchr/testify v1.11.1
 	github.com/tailscale/hujson v0.0.0-20260302212456-ecc657c15afd
-	github.com/tailscale/squibble v0.0.0-20260303070345-3ac5157f405e
-	github.com/tailscale/tailsql v0.0.0-20260322172246-3ab0c1744d9c
+	github.com/tailscale/squibble v0.0.0-20260411062017-141f5d618bc4
+	github.com/tailscale/tailsql v0.0.0-20260521144131-377d992d0d71
 	github.com/tcnksm/go-latest v0.0.0-20170313132115-e3007ae9052e
 	go4.org/netipx v0.0.0-20231129151722-fdeea329fbba
-	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/crypto v0.52.0
+	golang.org/x/exp v0.0.0-20260508232706-74f9aab9d74a
+	golang.org/x/net v0.55.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/genproto/googleapis/api v0.0.0-20260519071638-aa98bba5eb94
+	google.golang.org/grpc v1.81.1
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v3 v3.0.1
 	gorm.io/driver/postgres v1.6.0
 	gorm.io/gorm v1.31.1
-	pgregory.net/rapid v1.2.0
-	tailscale.com v1.97.0-pre.0.20260429005429-40088602c960
+	pgregory.net/rapid v1.3.0
+	tailscale.com v1.98.3
 	zombiezen.com/go/postgrestest v1.0.1
 )
 
@@ -77,10 +78,10 @@ require (
 // together, e.g:
 // go get modernc.org/libc@v1.55.3 modernc.org/sqlite@v1.33.1
 require (
-	modernc.org/libc v1.70.0 // indirect
+	modernc.org/libc v1.72.3 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
-	modernc.org/sqlite v1.48.2
+	modernc.org/sqlite v1.50.1
 )
 
 // NOTE: gvisor must be updated in lockstep with
@@ -129,7 +130,7 @@ require (
 	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.26.2 // indirect
+	github.com/creachadair/mds v0.28.0 // indirect
 	github.com/creachadair/msync v0.8.2 // indirect
 	github.com/dblohm7/wingoes v0.0.0-20250822163801-6d8e6105c62d // indirect
 	github.com/dgryski/go-metro v0.0.0-20250106013310-edb8663e5e33 // indirect
@@ -144,7 +145,7 @@ require (
 	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
 	github.com/gaissmai/bart v0.26.1 // indirect
 	github.com/glebarez/go-sqlite v1.22.0 // indirect
-	github.com/go-jose/go-jose/v3 v3.0.4 // indirect
+	github.com/go-jose/go-jose/v3 v3.0.5 // indirect
 	github.com/go-jose/go-jose/v4 v4.1.4 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
@@ -168,7 +169,7 @@ require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
-	github.com/jackc/pgx/v5 v5.8.0 // indirect
+	github.com/jackc/pgx/v5 v5.9.2 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
@@ -203,10 +204,8 @@ require (
 	github.com/pires/go-proxyproto v0.9.2 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
-	github.com/prometheus-community/pro-bing v0.7.0 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/prometheus/procfs v0.19.2 // indirect
-	github.com/realclientip/realclientip-go v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/safchain/ethtool v0.7.0 // indirect
 	github.com/sagikazarmark/locafero v0.12.0 // indirect
@@ -219,9 +218,9 @@ require (
 	github.com/tailscale/certstore v0.1.1-0.20260409135935-3638fb84b77d // indirect
 	github.com/tailscale/go-winio v0.0.0-20231025203758-c4f33415bf55 // indirect
 	github.com/tailscale/peercred v0.0.0-20250107143737-35a0c7bd7edc // indirect
-	github.com/tailscale/setec v0.0.0-20260115174028-19d190c5556d // indirect
+	github.com/tailscale/setec v0.0.0-20260310221408-dcd97e42f251 // indirect
 	github.com/tailscale/web-client-prebuilt v0.0.0-20251127225136-f19339b67368 // indirect
-	github.com/tailscale/wireguard-go v0.0.0-20260304043104-4184faf59e56 // indirect
+	github.com/tailscale/wireguard-go v0.0.0-20260427181203-e3ac4a0afb4e // 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
@@ -229,24 +228,24 @@ require (
 	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 // indirect
-	go.opentelemetry.io/otel v1.40.0 // indirect
-	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.40.0 // indirect
-	go.opentelemetry.io/otel/metric v1.40.0 // indirect
-	go.opentelemetry.io/otel/trace v1.40.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0 // indirect
+	go.opentelemetry.io/otel v1.43.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0 // indirect
+	go.opentelemetry.io/otel/metric v1.43.0 // indirect
+	go.opentelemetry.io/otel/trace v1.43.0 // indirect
 	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/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/image v0.40.0 // indirect
+	golang.org/x/mod v0.36.0 // indirect
+	golang.org/x/sys v0.45.0 // indirect
+	golang.org/x/term v0.43.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
-	golang.org/x/tools v0.44.0 // indirect
+	golang.org/x/tools v0.45.0 // indirect
 	golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 // indirect
 	golang.zx2c4.com/wireguard/windows v0.5.3 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260519071638-aa98bba5eb94 // 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

go.sum

@@ -129,12 +129,12 @@ github.com/coreos/go-iptables v0.7.1-0.20240112124308-65c67c9f46e6/go.mod h1:Qe8
 github.com/coreos/go-oidc/v3 v3.18.0 h1:V9orjXynvu5wiC9SemFTWnG4F45v403aIcjWo0d41+A=
 github.com/coreos/go-oidc/v3 v3.18.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4=
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
-github.com/creachadair/command v0.2.2 h1:4RGsUhqFf1imFC+vMWOOCiQdncThCdcdMJp0JNCjxxc=
-github.com/creachadair/command v0.2.2/go.mod h1:Z6Zp6CSJcnaWWR4wHgdqzODnFdxFJAaa/DrcVkeUu3E=
-github.com/creachadair/flax v0.0.5 h1:zt+CRuXQASxwQ68e9GHAOnEgAU29nF0zYMHOCrL5wzE=
-github.com/creachadair/flax v0.0.5/go.mod h1:F1PML0JZLXSNDMNiRGK2yjm5f+L9QCHchyHBldFymj8=
-github.com/creachadair/mds v0.26.2 h1:rCtvEV/bCRY0hGfwvvMg0p3yzKgBE8l/9OV4fjF9QQ8=
-github.com/creachadair/mds v0.26.2/go.mod h1:dMBTCSy3iS3dwh4Rb1zxeZz2d7K8+N24GCTsayWtQRI=
+github.com/creachadair/command v0.2.6 h1:+d4xUSZza5nqRVVsVRf5jDbix/0uKxVqFrc30F4uyRI=
+github.com/creachadair/command v0.2.6/go.mod h1:HWvS3zEpVakKlNXxT/j1U8tNoDaY7By7ORYQ+m1ha2U=
+github.com/creachadair/flax v0.0.6 h1:IFUdRdfKynNTyR5SRlrHMUGnxxMZZen8RVpwcDq/ftk=
+github.com/creachadair/flax v0.0.6/go.mod h1:F1PML0JZLXSNDMNiRGK2yjm5f+L9QCHchyHBldFymj8=
+github.com/creachadair/mds v0.28.0 h1:VS4JsBSlClsqBrHT8cYMTMqFHJdU0P/Z1ES6zjnSMXo=
+github.com/creachadair/mds v0.28.0/go.mod h1:dMBTCSy3iS3dwh4Rb1zxeZz2d7K8+N24GCTsayWtQRI=
 github.com/creachadair/msync v0.8.2 h1:ujvc/SVJPn+bFwmjUHucXNTTn3opVe2YbQ46mBCnP08=
 github.com/creachadair/msync v0.8.2/go.mod h1:LzxqD9kfIl/O3DczkwOgJplLPqwrTbIhINlf9bHIsEY=
 github.com/creachadair/taskgroup v0.13.2 h1:3KyqakBuFsm3KkXi/9XIb0QcA8tEzLHLgaoidf0MdVc=
@@ -174,8 +174,8 @@ github.com/fogleman/gg v1.3.0 h1:/7zJX8F6AaYQc57WQCyN9cAIz+4bCJGO9B+dyW29am8=
 github.com/fogleman/gg v1.3.0/go.mod h1:R/bRT+9gY/C5z7JzPU0zXsXHKM4/ayA+zqcVNZzPa1k=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
-github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
-github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
+github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
 github.com/fxamacker/cbor/v2 v2.9.0 h1:NpKPmjDBgUfBms6tr6JZkTHtfFGcMKsw3eGcmD/sapM=
 github.com/fxamacker/cbor/v2 v2.9.0/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=
 github.com/gaissmai/bart v0.26.1 h1:+w4rnLGNlA2GDVn382Tfe3jOsK5vOr5n4KmigJ9lbTo=
@@ -192,12 +192,12 @@ github.com/go-chi/metrics v0.1.1 h1:CXhbnkAVVjb0k73EBRQ6Z2YdWFnbXZgNtg1Mboguibk=
 github.com/go-chi/metrics v0.1.1/go.mod h1:mcGTM1pPalP7WCtb+akNYFO/lwNwBBLCuedepqjoPn4=
 github.com/go-gormigrate/gormigrate/v2 v2.1.5 h1:1OyorA5LtdQw12cyJDEHuTrEV3GiXiIhS4/QTTa/SM8=
 github.com/go-gormigrate/gormigrate/v2 v2.1.5/go.mod h1:mj9ekk/7CPF3VjopaFvWKN2v7fN3D9d3eEOAXRhi/+M=
-github.com/go-jose/go-jose/v3 v3.0.4 h1:Wp5HA7bLQcKnf6YYao/4kpRpVMp/yf6+pJKV8WFSaNY=
-github.com/go-jose/go-jose/v3 v3.0.4/go.mod h1:5b+7YgP7ZICgJDBdfjZaIt+H/9L9T/YQrVfLAMboGkQ=
+github.com/go-jose/go-jose/v3 v3.0.5 h1:BLLJWbC4nMZOfuPVxoZIxeYsn6Nl2r1fITaJ78UQlVQ=
+github.com/go-jose/go-jose/v3 v3.0.5/go.mod h1:5b+7YgP7ZICgJDBdfjZaIt+H/9L9T/YQrVfLAMboGkQ=
 github.com/go-jose/go-jose/v4 v4.1.4 h1:moDMcTHmvE6Groj34emNPLs/qtYXRVcd6S7NHbHz3kA=
 github.com/go-jose/go-jose/v4 v4.1.4/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
-github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/go-json-experiment/json v0.0.0-20260520185125-572e7c383686 h1:NZBJxCpbHS1gzS6xAmyxbJznosZIIPk9IB42v62UvKA=
+github.com/go-json-experiment/json v0.0.0-20260520185125-572e7c383686/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=
@@ -258,8 +258,8 @@ 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.28.0 h1:HWRh5R2+9EifMyIHV7ZV+MIZqgz+PMpZ14Jynv3O2Zs=
-github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0/go.mod h1:JfhWUomR1baixubs02l85lZYYOm7LV6om4ceouMv45c=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 h1:5VipnvEpbqr2gA2VbM+nYVbkIF28c5ZQfqCBQ5g2xfk=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0/go.mod h1:Hyl3n6Twe1hvtd9XUXDec4pTvgMSEixRuQKPTMH2bNs=
 github.com/hashicorp/go-version v1.8.0 h1:KAkNb1HAiZd1ukkxDFGmokVZe1Xy9HG6NUp+bPle2i4=
 github.com/hashicorp/go-version v1.8.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA=
 github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
@@ -280,8 +280,8 @@ github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsI
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
 github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
-github.com/jackc/pgx/v5 v5.8.0 h1:TYPDoleBBme0xGSAX3/+NujXXtpZn9HBONkQC7IEZSo=
-github.com/jackc/pgx/v5 v5.8.0/go.mod h1:QVeDInX2m9VyzvNeiCJVjCkNFqzsNb43204HshNSZKw=
+github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw=
+github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/jagottsicher/termcolor v1.0.2 h1:fo0c51pQSuLBN1+yVX2ZE+hE+P7ULb/TY8eRowJnrsM=
@@ -404,8 +404,6 @@ github.com/pkg/sftp v1.13.6/go.mod h1:tz1ryNURKu77RL+GuCzmoJYxQczL3wLNNpPWagdg4Q
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/prometheus-community/pro-bing v0.7.0 h1:KFYFbxC2f2Fp6c+TyxbCOEarf7rbnzr9Gw8eIb0RfZA=
-github.com/prometheus-community/pro-bing v0.7.0/go.mod h1:Moob9dvlY50Bfq6i88xIwfyw7xLFHH69LUgx9n5zqCE=
 github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
 github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
@@ -423,8 +421,8 @@ github.com/pterm/pterm v0.12.36/go.mod h1:NjiL09hFhT/vWjQHSj1athJpx6H8cjpHXNAK5b
 github.com/pterm/pterm v0.12.40/go.mod h1:ffwPLwlbXxP+rxT0GsgDTzS3y3rmpAO1NMjUkGTYf8s=
 github.com/pterm/pterm v0.12.83 h1:ie+YmGmA727VuhxBlyGr74Ks+7McV6kT99IB8EU80aA=
 github.com/pterm/pterm v0.12.83/go.mod h1:xlgc6bFWyJIMtmLJvGim+L7jhSReilOlOnodeIYe4Tk=
-github.com/puzpuzpuz/xsync/v4 v4.4.0 h1:vlSN6/CkEY0pY8KaB0yqo/pCLZvp9nhdbBdjipT4gWo=
-github.com/puzpuzpuz/xsync/v4 v4.4.0/go.mod h1:VJDmTCJMBt8igNxnkQd86r+8KUeN1quSfNKu5bLYFQo=
+github.com/puzpuzpuz/xsync/v4 v4.5.0 h1:vOSWu6b57/emh+L/Cw0BeQfvxa/cogFywXHeGUxQxAg=
+github.com/puzpuzpuz/xsync/v4 v4.5.0/go.mod h1:VJDmTCJMBt8igNxnkQd86r+8KUeN1quSfNKu5bLYFQo=
 github.com/realclientip/realclientip-go v1.0.0 h1:+yPxeC0mEaJzq1BfCt2h4BxlyrvIIBzR6suDc3BEF1U=
 github.com/realclientip/realclientip-go v1.0.0/go.mod h1:CXnUdVwFRcXFJIRb/dTYqbT7ud48+Pi2pFm80bxDmcI=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
@@ -432,8 +430,8 @@ 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/zerolog v1.35.0 h1:VD0ykx7HMiMJytqINBsKcbLS+BJ4WYjz+05us+LRTdI=
-github.com/rs/zerolog v1.35.0/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
+github.com/rs/zerolog v1.35.1 h1:m7xQeoiLIiV0BCEY4Hs+j2NG4Gp2o2KPKmhnnLiazKI=
+github.com/rs/zerolog v1.35.1/go.mod h1:EjML9kdfa/RMA7h/6z6pYmq1ykOuA8/mjWaEvGI+jcw=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/safchain/ethtool v0.7.0 h1:rlJzfDetsVvT61uz8x1YIcFn12akMfuPulHtZjtb7Is=
 github.com/safchain/ethtool v0.7.0/go.mod h1:MenQKEjXdfkjD3mp2QdCk8B/hwvkrlOTm/FD4gTpFxQ=
@@ -489,18 +487,18 @@ github.com/tailscale/netlink v1.1.1-0.20240822203006-4d49adab4de7 h1:uFsXVBE9Qr4
 github.com/tailscale/netlink v1.1.1-0.20240822203006-4d49adab4de7/go.mod h1:NzVQi3Mleb+qzq8VmcWpSkcSYxXIg0DkI6XDzpVkhJ0=
 github.com/tailscale/peercred v0.0.0-20250107143737-35a0c7bd7edc h1:24heQPtnFR+yfntqhI3oAu9i27nEojcQ4NuBQOo5ZFA=
 github.com/tailscale/peercred v0.0.0-20250107143737-35a0c7bd7edc/go.mod h1:f93CXfllFsO9ZQVq+Zocb1Gp4G5Fz0b0rXHLOzt/Djc=
-github.com/tailscale/setec v0.0.0-20260115174028-19d190c5556d h1:N+TtzIaGYREbLbKZB0WU0vVnMSfaqUkSf3qMEi03hwE=
-github.com/tailscale/setec v0.0.0-20260115174028-19d190c5556d/go.mod h1:6NU8H/GLPVX2TnXAY1duyy9ylLaHwFpr0X93UPiYmNI=
-github.com/tailscale/squibble v0.0.0-20260303070345-3ac5157f405e h1:4yfp5/YDr+TzbUME/PalYJVXAsp7zA2Gv2xQMZ9Qors=
-github.com/tailscale/squibble v0.0.0-20260303070345-3ac5157f405e/go.mod h1:xJkMmR3t+thnUQhA3Q4m2VSlS5pcOq+CIjmU/xfKKx4=
-github.com/tailscale/tailsql v0.0.0-20260322172246-3ab0c1744d9c h1:7lJQ/zycbk1E9e0nUiMuwIDYprFTLpWXUwiPdi+tRlI=
-github.com/tailscale/tailsql v0.0.0-20260322172246-3ab0c1744d9c/go.mod h1:bpNmZdvZKmBstrZunT+NXL6hmrFw5AsuT7MGiYS8sRc=
+github.com/tailscale/setec v0.0.0-20260310221408-dcd97e42f251 h1:kNnJlwxSzue+VRJuDdZ/yebcMM2q9KqFmK9xQqH1YRc=
+github.com/tailscale/setec v0.0.0-20260310221408-dcd97e42f251/go.mod h1:6NU8H/GLPVX2TnXAY1duyy9ylLaHwFpr0X93UPiYmNI=
+github.com/tailscale/squibble v0.0.0-20260411062017-141f5d618bc4 h1:1ghkd9YIC4J7umZuu9jZz8afWJSj1hCRSzfvdI2Q3Vo=
+github.com/tailscale/squibble v0.0.0-20260411062017-141f5d618bc4/go.mod h1:EVp9PDh7v69Do6aNzFfLvL0fdCph3XskGMi+WcS/uOM=
+github.com/tailscale/tailsql v0.0.0-20260521144131-377d992d0d71 h1:IXwFgoMvxnXLCmQldzyuOO+b8Ko1cxqeuz5o3oaMkj8=
+github.com/tailscale/tailsql v0.0.0-20260521144131-377d992d0d71/go.mod h1:N2Dm+UzRWz01zPMDl5XHkSVq91kNPWU13uUUibcOm+c=
 github.com/tailscale/web-client-prebuilt v0.0.0-20251127225136-f19339b67368 h1:0tpDdAj9sSfSZg4gMwNTdqMP592sBrq2Sm0w6ipnh7k=
 github.com/tailscale/web-client-prebuilt v0.0.0-20251127225136-f19339b67368/go.mod h1:agQPE6y6ldqCOui2gkIh7ZMztTkIQKH049tv8siLuNQ=
 github.com/tailscale/wf v0.0.0-20240214030419-6fbb0a674ee6 h1:l10Gi6w9jxvinoiq15g8OToDdASBni4CyJOdHY1Hr8M=
 github.com/tailscale/wf v0.0.0-20240214030419-6fbb0a674ee6/go.mod h1:ZXRML051h7o4OcI0d3AaILDIad/Xw0IkXaHM17dic1Y=
-github.com/tailscale/wireguard-go v0.0.0-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/wireguard-go v0.0.0-20260427181203-e3ac4a0afb4e h1:GexFR7ak1iz26fxg8HWCpOEqAOL8UEZJ7J3JxeCalDs=
+github.com/tailscale/wireguard-go v0.0.0-20260427181203-e3ac4a0afb4e/go.mod h1:6SerzcvHWQchKO2BfNdmquA77CHSECZuFl+D9fp4RnI=
 github.com/tailscale/xnet v0.0.0-20240729143630-8497ac4dab2e h1:zOGKqN5D5hHhiYUp091JqK7DPCqSARyUfduhGUY8Bek=
 github.com/tailscale/xnet v0.0.0-20240729143630-8497ac4dab2e/go.mod h1:orPd6JZXXRyuDusYilywte7k094d7dycXXU5YnWsrwg=
 github.com/tc-hib/winres v0.2.1 h1:YDE0FiP0VmtRaDn7+aaChp1KiF4owBiJa5l964l5ujA=
@@ -532,24 +530,24 @@ github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJu
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 h1:7iP2uCb7sGddAr30RRS6xjKy7AZ2JtTOPA3oolgVSw8=
-go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0/go.mod h1:c7hN3ddxs/z6q9xwvfLPk+UHlWRQyaeR1LdgfL/66l0=
-go.opentelemetry.io/otel v1.40.0 h1:oA5YeOcpRTXq6NN7frwmwFR0Cn3RhTVZvXsP4duvCms=
-go.opentelemetry.io/otel v1.40.0/go.mod h1:IMb+uXZUKkMXdPddhwAHm6UfOwJyh4ct1ybIlV14J0g=
-go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0 h1:QKdN8ly8zEMrByybbQgv8cWBcdAarwmIPZ6FThrWXJs=
-go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0/go.mod h1:bTdK1nhqF76qiPoCCdyFIV+N/sRHYXYCTQc+3VCi3MI=
-go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.40.0 h1:wVZXIWjQSeSmMoxF74LzAnpVQOAFDo3pPji9Y4SOFKc=
-go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.40.0/go.mod h1:khvBS2IggMFNwZK/6lEeHg/W57h/IX6J4URh57fuI40=
-go.opentelemetry.io/otel/metric v1.40.0 h1:rcZe317KPftE2rstWIBitCdVp89A2HqjkxR3c11+p9g=
-go.opentelemetry.io/otel/metric v1.40.0/go.mod h1:ib/crwQH7N3r5kfiBZQbwrTge743UDc7DTFVZrrXnqc=
-go.opentelemetry.io/otel/sdk v1.40.0 h1:KHW/jUzgo6wsPh9At46+h4upjtccTmuZCFAc9OJ71f8=
-go.opentelemetry.io/otel/sdk v1.40.0/go.mod h1:Ph7EFdYvxq72Y8Li9q8KebuYUr2KoeyHx0DRMKrYBUE=
-go.opentelemetry.io/otel/sdk/metric v1.40.0 h1:mtmdVqgQkeRxHgRv4qhyJduP3fYJRMX4AtAlbuWdCYw=
-go.opentelemetry.io/otel/sdk/metric v1.40.0/go.mod h1:4Z2bGMf0KSK3uRjlczMOeMhKU2rhUqdWNoKcYrtcBPg=
-go.opentelemetry.io/otel/trace v1.40.0 h1:WA4etStDttCSYuhwvEa8OP8I5EWu24lkOzp+ZYblVjw=
-go.opentelemetry.io/otel/trace v1.40.0/go.mod h1:zeAhriXecNGP/s2SEG3+Y8X9ujcJOTqQ5RgdEJcawiA=
-go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A=
-go.opentelemetry.io/proto/otlp v1.9.0/go.mod h1:xE+Cx5E/eEHw+ISFkwPLwCZefwVjY+pqKg1qcK03+/4=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0 h1:CqXxU8VOmDefoh0+ztfGaymYbhdB/tT3zs79QaZTNGY=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.68.0/go.mod h1:BuhAPThV8PBHBvg8ZzZ/Ok3idOdhWIodywz2xEcRbJo=
+go.opentelemetry.io/otel v1.43.0 h1:mYIM03dnh5zfN7HautFE4ieIig9amkNANT+xcVxAj9I=
+go.opentelemetry.io/otel v1.43.0/go.mod h1:JuG+u74mvjvcm8vj8pI5XiHy1zDeoCS2LB1spIq7Ay0=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0 h1:88Y4s2C8oTui1LGM6bTWkw0ICGcOLCAI5l6zsD1j20k=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.43.0/go.mod h1:Vl1/iaggsuRlrHf/hfPJPvVag77kKyvrLeD10kpMl+A=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0 h1:3iZJKlCZufyRzPzlQhUIWVmfltrXuGyfjREgGP3UUjc=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.43.0/go.mod h1:/G+nUPfhq2e+qiXMGxMwumDrP5jtzU+mWN7/sjT2rak=
+go.opentelemetry.io/otel/metric v1.43.0 h1:d7638QeInOnuwOONPp4JAOGfbCEpYb+K6DVWvdxGzgM=
+go.opentelemetry.io/otel/metric v1.43.0/go.mod h1:RDnPtIxvqlgO8GRW18W6Z/4P462ldprJtfxHxyKd2PY=
+go.opentelemetry.io/otel/sdk v1.43.0 h1:pi5mE86i5rTeLXqoF/hhiBtUNcrAGHLKQdhg4h4V9Dg=
+go.opentelemetry.io/otel/sdk v1.43.0/go.mod h1:P+IkVU3iWukmiit/Yf9AWvpyRDlUeBaRg6Y+C58QHzg=
+go.opentelemetry.io/otel/sdk/metric v1.43.0 h1:S88dyqXjJkuBNLeMcVPRFXpRw2fuwdvfCGLEo89fDkw=
+go.opentelemetry.io/otel/sdk/metric v1.43.0/go.mod h1:C/RJtwSEJ5hzTiUz5pXF1kILHStzb9zFlIEe85bhj6A=
+go.opentelemetry.io/otel/trace v1.43.0 h1:BkNrHpup+4k4w+ZZ86CZoHHEkohws8AY+WTX09nk+3A=
+go.opentelemetry.io/otel/trace v1.43.0/go.mod h1:/QJhyVBUUswCphDVxq+8mld+AvhXZLhe+8WVFxiFff0=
+go.opentelemetry.io/proto/otlp v1.10.0 h1:IQRWgT5srOCYfiWnpqUYz9CVmbO8bFmKcwYxpuCSL2g=
+go.opentelemetry.io/proto/otlp v1.10.0/go.mod h1:/CV4QoCR/S9yaPj8utp3lvQPoqMtxXdzn7ozvvozVqk=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=
@@ -563,25 +561,25 @@ 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.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/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
+golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
+golang.org/x/exp v0.0.0-20260508232706-74f9aab9d74a h1:+3jdDGGB8NGb1Zktc737jlt3/A5f6UlwSzmvqUuufxw=
+golang.org/x/exp v0.0.0-20260508232706-74f9aab9d74a/go.mod h1:d2fgXJLVs4dYDHUk5lwMIfzRzSrWCfGZb0ZqeLa/Vcw=
 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/image v0.40.0 h1:Tw4GyDXMo+daZN1znreBRC3VayR1aLFUyUEOLUdW1a8=
+golang.org/x/image v0.40.0/go.mod h1:uIc348UZMSvS5Z65CVZ7iDPaNobNFEPeJ4kbqTOszmA=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
-golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
-golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
+golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4=
+golang.org/x/mod v0.36.0/go.mod h1:moc6ELqsWcOw5Ef3xVprK5ul/MvtVvkIXLziUOICjUQ=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
 golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
 golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
-golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
-golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
+golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
+golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
 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=
@@ -607,8 +605,8 @@ golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
+golang.org/x/sys v0.45.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=
@@ -616,24 +614,24 @@ 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.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY=
-golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
 golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
-golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
-golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
 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.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
-golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
+golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8=
+golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 h1:B82qJJgjvYKsXS9jeunTOisW56dUokqW/FOteYJJ/yg=
 golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2/go.mod h1:deeaetjYA+DHMHg+sMSMI58GrEteJUUzzw7en6TJQcI=
@@ -641,12 +639,12 @@ golang.zx2c4.com/wireguard/windows v0.5.3 h1:On6j2Rpn3OEMXqBq00QEDC7bWSZrPIHKIus
 golang.zx2c4.com/wireguard/windows v0.5.3/go.mod h1:9TEe8TJmtwyQebdFwAkEWOPr3prrtqm+REGFifP60hI=
 gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
 gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E=
-google.golang.org/genproto/googleapis/api v0.0.0-20260406210006-6f92a3bedf2d h1:/aDRtSZJjyLQzm75d+a1wOJaqyKBMvIAfeQmoa3ORiI=
-google.golang.org/genproto/googleapis/api v0.0.0-20260406210006-6f92a3bedf2d/go.mod h1:etfGUgejTiadZAUaEP14NP97xi1RGeawqkjDARA/UOs=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9 h1:m8qni9SQFH0tJc1X0vmnpw/0t+AImlSvp30sEupozUg=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20260401024825-9d38bb4040a9/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
-google.golang.org/grpc v1.80.0 h1:Xr6m2WmWZLETvUNvIUmeD5OAagMw3FiKmMlTdViWsHM=
-google.golang.org/grpc v1.80.0/go.mod h1:ho/dLnxwi3EDJA4Zghp7k2Ec1+c2jqup0bFkw07bwF4=
+google.golang.org/genproto/googleapis/api v0.0.0-20260519071638-aa98bba5eb94 h1:DddG61lE5LkX6144z22i0gma9BMBs5aZ9B8lZLobxyw=
+google.golang.org/genproto/googleapis/api v0.0.0-20260519071638-aa98bba5eb94/go.mod h1:1dCETSCY2YKZNXQE3h4fun3TYwF5p8jejRKZgfWAgAY=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260519071638-aa98bba5eb94 h1:eZCjr/aAF8c5ccm5pb6T4EXgIei5MlAAPWPJk+5ArfY=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260519071638-aa98bba5eb94/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
+google.golang.org/grpc v1.81.1 h1:VnnIIZ88UzOOKLukQi+ImGz8O1Wdp8nAGGnvOfEIWQQ=
+google.golang.org/grpc v1.81.1/go.mod h1:xGH9GfzOyMTGIOXBJmXt+BX/V0kcdQbdcuwQ/zNw42I=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
@@ -676,10 +674,10 @@ 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.32.0 h1:hjG66bI/kqIPX1b2yT6fr/jt+QedtP2fqojG2VrFuVw=
-modernc.org/ccgo/v4 v4.32.0/go.mod h1:6F08EBCx5uQc38kMGl+0Nm0oWczoo1c7cgpzEry7Uc0=
+modernc.org/cc/v4 v4.28.2 h1:3tQ0lf2ADtoby2EtSP+J7IE2SHwEJdP8ioR59wx7XpY=
+modernc.org/cc/v4 v4.28.2/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/ccgo/v4 v4.34.0 h1:yRLPFZieg532OT4rp4JFNIVcquwalMX26G95WQDqwCQ=
+modernc.org/ccgo/v4 v4.34.0/go.mod h1:AS5WYMyBakQ+fhsHhtP8mWB82KTGPkNNJDGfGQCe0/A=
 modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
 modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
 modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
@@ -688,29 +686,29 @@ modernc.org/gc/v3 v3.1.2 h1:ZtDCnhonXSZexk/AYsegNRV1lJGgaNZJuKjJSWKyEqo=
 modernc.org/gc/v3 v3.1.2/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
 modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
 modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
-modernc.org/libc v1.70.0 h1:U58NawXqXbgpZ/dcdS9kMshu08aiA6b7gusEusqzNkw=
-modernc.org/libc v1.70.0/go.mod h1:OVmxFGP1CI/Z4L3E0Q3Mf1PDE0BucwMkcXjjLntvHJo=
+modernc.org/libc v1.72.3 h1:ZnDF4tXn4NBXFutMMQC4vtbTFSXhhKzR73fv0beZEAU=
+modernc.org/libc v1.72.3/go.mod h1:dn0dZNnnn1clLyvRxLxYExxiKRZIRENOfqQ8XEeg4Qs=
 modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
 modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
 modernc.org/memory v1.11.0 h1:o4QC8aMQzmcwCK3t3Ux/ZHmwFPzE6hf2Y5LbkRs+hbI=
 modernc.org/memory v1.11.0/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
-modernc.org/opt v0.1.4 h1:2kNGMRiUjrp4LcaPuLY2PzUfqM/w9N23quVwhKt5Qm8=
-modernc.org/opt v0.1.4/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
 modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
 modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
-modernc.org/sqlite v1.48.2 h1:5CnW4uP8joZtA0LedVqLbZV5GD7F/0x91AXeSyjoh5c=
-modernc.org/sqlite v1.48.2/go.mod h1:hWjRO6Tj/5Ik8ieqxQybiEOUXy0NJFNp2tpvVpKlvig=
+modernc.org/sqlite v1.50.1 h1:l+cQvn0sd0zJJtfygGHuQJ5AjlrwXmWPw4KP3ZMwr9w=
+modernc.org/sqlite v1.50.1/go.mod h1:tcNzv5p84E0skkmJn038y+hWJbLQXQqEnQfeh5r2JLM=
 modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
 modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
 modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
 modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
-pgregory.net/rapid v1.2.0 h1:keKAYRcjm+e1F0oAuU5F5+YPAWcyxNNRK2wud503Gnk=
-pgregory.net/rapid v1.2.0/go.mod h1:PY5XlDGj0+V1FCq0o192FdRhpKHGTRIWBgqjDBTrq04=
+pgregory.net/rapid v1.3.0 h1:vBvO0VSqti75J1jjYqpgPNBLKMd1+gxa9fYo7vk/Exc=
+pgregory.net/rapid v1.3.0/go.mod h1:dPlE4OBBxgXPqkP79flB6sJL1dx5azpI7HQ9MY9Z7uk=
 sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=
 sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=
 software.sslmate.com/src/go-pkcs12 v0.4.0 h1:H2g08FrTvSFKUj+D309j1DPfk5APnIdAQAB8aEykJ5k=
 software.sslmate.com/src/go-pkcs12 v0.4.0/go.mod h1:Qiz0EyvDRJjjxGyUQa2cCNZn/wMyzrRJ/qcDXOQazLI=
-tailscale.com v1.97.0-pre.0.20260429005429-40088602c960 h1:I56vAGia4DV24Dbv8N07F/Awtnguvmm7PAgWCxCIdqw=
-tailscale.com v1.97.0-pre.0.20260429005429-40088602c960/go.mod h1:8nwFkmNdNRtTIM2dkmr/DhbzSKeLmzusWOTacX1zVKk=
+tailscale.com v1.98.3 h1:caAbG4UfkKfKPE6b1fj5t4ep5qrwEis5AJu91ruvePw=
+tailscale.com v1.98.3/go.mod h1:U23ZwbZlKJMNU7CScy+lCVVlece/S5n09q0nyudncBI=
 zombiezen.com/go/postgrestest v1.0.1 h1:aXoADQAJmZDU3+xilYVut0pHhgc0sF8ZspPW9gFNwP4=
 zombiezen.com/go/postgrestest v1.0.1/go.mod h1:marlZezr+k2oSJrvXHnZUs1olHqpE9czlz8ZYkVxliQ=

hscontrol/capver/capver.go

@@ -12,24 +12,17 @@ import (
 	"tailscale.com/util/set"
 )
 
-const (
-	// minVersionParts is the minimum number of version parts needed for major.minor.
-	minVersionParts = 2
+// minVersionParts is the minimum number of version parts needed for major.minor.
+const minVersionParts = 2
 
-	// legacyDERPCapVer is the capability version when LegacyDERP can be cleaned up.
-	legacyDERPCapVer = 111
-)
-
-// CanOldCodeBeCleanedUp is intended to be called on startup to see if
-// there are old code that can ble cleaned up, entries should contain
-// a [tailcfg.CapabilityVersion] where something can be cleaned up and a panic if it can.
-// This is only intended to catch things in tests.
+// CanOldCodeBeCleanedUp is called at server startup to panic when
+// [MinSupportedCapabilityVersion] has crossed a threshold at which a
+// backwards-compat emit path can be deleted. Each entry pairs a
+// [tailcfg.CapabilityVersion] threshold with the message identifying
+// the code to remove; today there are none.
 //
-// All uses of Capability version checks should be listed here.
+// All capability-version-gated cleanups should be registered here.
 func CanOldCodeBeCleanedUp() {
-	if MinSupportedCapabilityVersion >= legacyDERPCapVer {
-		panic("LegacyDERP can be cleaned up in tail.go")
-	}
 }
 
 func tailscaleVersSorted() []string {

hscontrol/capver/capver_generated.go

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

hscontrol/capver/capver_test_data.go

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

hscontrol/db/db.go

@@ -744,6 +744,28 @@ WHERE tags IS NOT NULL AND tags != '[]' AND tags != '';
 				},
 				Rollback: func(db *gorm.DB) error { return nil },
 			},
+			{
+				// Clear zero-time node expiry values to NULL.
+				// Versions before 0.28 persisted a pointer to a zero
+				// time.Time as '0001-01-01 00:00:00+00:00' rather than
+				// NULL, which 0.29 reports as an expired node. This
+				// normalises the existing rows so the column once
+				// again means "no expiry" when unset.
+				ID: "202605221435-clear-zero-time-node-expiry",
+				Migrate: func(tx *gorm.DB) error {
+					err := tx.Exec(`
+UPDATE nodes
+SET expiry = NULL
+WHERE expiry IS NOT NULL AND expiry < '1900-01-01';
+						`).Error
+					if err != nil {
+						return fmt.Errorf("clearing zero-time node expiry: %w", err)
+					}
+
+					return nil
+				},
+				Rollback: func(db *gorm.DB) error { return nil },
+			},
 		},
 	)
 

hscontrol/db/db_test.go

@@ -144,6 +144,60 @@ func TestSQLiteMigrationAndDataValidation(t *testing.T) {
 				assert.NotContains(t, node7.Tags, "tag:forbidden", "node7 should NOT have tag:forbidden (unauthorized)")
 			},
 		},
+		// Test for the zero-time node expiry migration
+		// (202605221435-clear-zero-time-node-expiry). Pre-0.28 versions
+		// stored a zero time.Time as '0001-01-01 00:00:00+00:00' rather
+		// than NULL, which caused 0.29 to report those nodes as expired.
+		// Fixes: https://github.com/juanfont/headscale/issues/3284
+		{
+			dbPath: "testdata/sqlite/zero_time_expiry_migration_test.sql",
+			wantFunc: func(t *testing.T, hsdb *HSDatabase) {
+				t.Helper()
+
+				nodes, err := Read(hsdb.DB, func(rx *gorm.DB) (types.Nodes, error) {
+					return ListNodes(rx)
+				})
+				require.NoError(t, err)
+				require.Len(t, nodes, 5, "should have all 5 nodes")
+
+				byHostname := make(map[string]*types.Node, len(nodes))
+				for _, n := range nodes {
+					byHostname[n.Hostname] = n
+				}
+
+				// Node 1 had a zero-time expiry; should be cleared.
+				node1 := byHostname["node1"]
+				require.NotNil(t, node1, "node1 should exist")
+				assert.Nil(t, node1.Expiry, "node1 zero-time expiry should be cleared to NULL")
+				assert.False(t, node1.IsExpired(), "node1 should not be reported as expired")
+
+				// Node 2 already had NULL expiry; should still be NULL.
+				node2 := byHostname["node2"]
+				require.NotNil(t, node2, "node2 should exist")
+				assert.Nil(t, node2.Expiry, "node2 NULL expiry should be preserved")
+				assert.False(t, node2.IsExpired(), "node2 should not be reported as expired")
+
+				// Node 3 had a real future expiry; should be preserved.
+				node3 := byHostname["node3"]
+				require.NotNil(t, node3, "node3 should exist")
+				require.NotNil(t, node3.Expiry, "node3 future expiry should be preserved")
+				assert.Equal(t, 2099, node3.Expiry.UTC().Year(), "node3 expiry year should be 2099")
+				assert.False(t, node3.IsExpired(), "node3 with future expiry should not be expired")
+
+				// Node 4 had a real past expiry; should be preserved.
+				node4 := byHostname["node4"]
+				require.NotNil(t, node4, "node4 should exist")
+				require.NotNil(t, node4.Expiry, "node4 past expiry should be preserved")
+				assert.Equal(t, 2020, node4.Expiry.UTC().Year(), "node4 expiry year should be 2020")
+				assert.True(t, node4.IsExpired(), "node4 with past expiry should still be expired")
+
+				// Node 5 also had a zero-time expiry; should be cleared.
+				node5 := byHostname["node5"]
+				require.NotNil(t, node5, "node5 should exist")
+				assert.Nil(t, node5.Expiry, "node5 zero-time expiry should be cleared to NULL")
+				assert.False(t, node5.IsExpired(), "node5 should not be reported as expired")
+			},
+		},
 	}
 
 	for _, tt := range tests {

hscontrol/db/testdata/sqlite/zero_time_expiry_migration_test.sql

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

hscontrol/db/versioncheck.go

@@ -3,6 +3,7 @@ package db
 import (
 	"errors"
 	"fmt"
+	"regexp"
 	"strconv"
 	"strings"
 	"time"
@@ -139,10 +140,49 @@ func setDatabaseVersion(db *gorm.DB, version string) error {
 	return nil
 }
 
+// pseudoVersionTimeLayout is Go's pseudo-version timestamp layout
+// (golang.org/ref/mod#pseudo-versions): UTC yyyymmddhhmmss.
+const pseudoVersionTimeLayout = "20060102150405"
+
+// pseudoVersionSuffix matches the trailing "<sep><14 digits>-<12
+// lowercase hex>" of a Go module pseudo-version. The base form
+// (vX.0.0-<date>-<hash>) uses "-" before the timestamp; the
+// pre-release-ancestor and release-ancestor forms
+// (vX.Y.Z-pre.0.<date>-<hash> and vX.Y.(Z+1)-0.<date>-<hash>) use "."
+// because the digit-only "0" marker precedes the timestamp.
+var pseudoVersionSuffix = regexp.MustCompile(`[-.](\d{14})-[0-9a-f]{12}$`)
+
+// pseudoVersionTime returns the embedded commit time when v is a
+// syntactically and semantically valid Go module pseudo-version. The
+// timestamp must parse as a real UTC time; lookalikes with malformed
+// dates (e.g. month 13, day 30 in February) are rejected.
+func pseudoVersionTime(v string) (time.Time, bool) {
+	m := pseudoVersionSuffix.FindStringSubmatch(v)
+	if m == nil {
+		return time.Time{}, false
+	}
+
+	t, err := time.Parse(pseudoVersionTimeLayout, m[1])
+	if err != nil {
+		return time.Time{}, false
+	}
+
+	return t, true
+}
+
 // isDev reports whether a version string represents a development build
-// that should skip version checking.
+// that should skip version checking. Go module pseudo-versions (used by
+// untagged main-sha builds, where runtime/debug.BuildInfo falls back to
+// vX.Y.Z-<timestamp>-<commit>) are treated as dev to avoid poisoning
+// database_versions with synthetic baselines.
 func isDev(version string) bool {
-	return version == "" || version == "dev" || version == "(devel)"
+	if version == "" || version == "dev" || version == "(devel)" {
+		return true
+	}
+
+	_, ok := pseudoVersionTime(version)
+
+	return ok
 }
 
 // checkVersionUpgradePath verifies that the running headscale version

hscontrol/db/versioncheck_test.go

@@ -3,6 +3,7 @@ package db
 import (
 	"fmt"
 	"testing"
+	"time"
 
 	"github.com/glebarez/sqlite"
 	"github.com/stretchr/testify/assert"
@@ -56,12 +57,206 @@ func TestSemverString(t *testing.T) {
 	assert.Equal(t, "v0.28.3", s.String())
 }
 
+func TestPseudoVersionTime(t *testing.T) {
+	parseTS := func(s string) time.Time {
+		t.Helper()
+
+		ts, err := time.Parse(pseudoVersionTimeLayout, s)
+		require.NoError(t, err)
+
+		return ts
+	}
+
+	tests := []struct {
+		name     string
+		input    string
+		wantOK   bool
+		wantTime time.Time
+	}{
+		// Accept: all three Go pseudo-version shapes.
+		{
+			name:     "no ancestor tag (v0.0.0 base)",
+			input:    "v0.0.0-20260522092201-58a85b68b3d9",
+			wantOK:   true,
+			wantTime: parseTS("20260522092201"),
+		},
+		{
+			name:     "ancestor is pre-release tag",
+			input:    "v0.29.0-beta.1.0.20260522092201-58a85b68b3d9",
+			wantOK:   true,
+			wantTime: parseTS("20260522092201"),
+		},
+		{
+			name:     "ancestor is release tag",
+			input:    "v0.29.1-0.20260522092201-58a85b68b3d9",
+			wantOK:   true,
+			wantTime: parseTS("20260522092201"),
+		},
+		{
+			name:     "earliest realistic Go module date",
+			input:    "v0.0.0-20180101000000-000000000000",
+			wantOK:   true,
+			wantTime: parseTS("20180101000000"),
+		},
+
+		// Reject: real release tags must not look like pseudo-versions.
+		{name: "release tag", input: "v0.29.0"},
+		{name: "pre-release tag", input: "v0.29.0-beta.1"},
+		{name: "rc tag", input: "v0.29.0-rc1"},
+		{name: "tag with build metadata", input: "v0.29.0+build123"},
+
+		// Reject: literals handled elsewhere.
+		{name: "empty", input: ""},
+		{name: "dev literal", input: "dev"},
+		{name: "devel literal", input: "(devel)"},
+
+		// Reject: malformed hash.
+		{name: "hash too short", input: "v0.0.0-20260522092201-58a85b6"},
+		{name: "hash too long", input: "v0.0.0-20260522092201-58a85b68b3d9aa"},
+		{name: "hash uppercase hex", input: "v0.0.0-20260522092201-58A85B68B3D9"},
+		{name: "hash non-hex", input: "v0.0.0-20260522092201-zzzzzzzzzzzz"},
+
+		// Reject: malformed timestamp.
+		{name: "timestamp too short", input: "v0.0.0-2026052209220-58a85b68b3d9"},
+		{name: "timestamp too long", input: "v0.0.0-202605220922010-58a85b68b3d9"},
+		{name: "invalid month", input: "v0.0.0-20261322092201-58a85b68b3d9"},
+		{name: "invalid day", input: "v0.0.0-20260230092201-58a85b68b3d9"},
+		{name: "invalid hour", input: "v0.0.0-20260522252201-58a85b68b3d9"},
+		{name: "invalid minute", input: "v0.0.0-20260522096001-58a85b68b3d9"},
+		{name: "invalid second", input: "v0.0.0-20260522092260-58a85b68b3d9"},
+		{name: "leap day on non-leap year", input: "v0.0.0-20230229000000-58a85b68b3d9"},
+
+		// Reject: missing components.
+		{name: "missing date and hash", input: "v0.0.0-"},
+		{name: "missing hash", input: "v0.0.0-20260522092201-"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := pseudoVersionTime(tt.input)
+			assert.Equal(t, tt.wantOK, ok)
+
+			if tt.wantOK {
+				assert.True(t, got.Equal(tt.wantTime),
+					"want %s, got %s", tt.wantTime, got)
+			}
+		})
+	}
+}
+
 func TestIsDev(t *testing.T) {
-	assert.True(t, isDev(""))
-	assert.True(t, isDev("dev"))
-	assert.True(t, isDev("(devel)"))
-	assert.False(t, isDev("v0.28.0"))
-	assert.False(t, isDev("0.28.0"))
+	tests := []struct {
+		name  string
+		input string
+		want  bool
+	}{
+		// Existing literals.
+		{name: "empty", input: "", want: true},
+		{name: "dev", input: "dev", want: true},
+		{name: "devel", input: "(devel)", want: true},
+		{name: "release tag", input: "v0.28.0", want: false},
+		{name: "release tag no v", input: "0.28.0", want: false},
+		{name: "pre-release tag", input: "v0.29.0-beta.1", want: false},
+
+		// Go module pseudo-versions — all three shapes Go emits per
+		// golang.org/ref/mod#pseudo-versions. Untagged commits
+		// (such as main-sha docker builds) must be treated as dev
+		// so they neither poison database_versions nor trip the
+		// upgrade-path guard.
+		{
+			name:  "pseudo v0.0.0 base",
+			input: "v0.0.0-20260522092201-58a85b68b3d9",
+			want:  true,
+		},
+		{
+			name:  "pseudo from pre-release ancestor",
+			input: "v0.29.0-beta.1.0.20260522092201-58a85b68b3d9",
+			want:  true,
+		},
+		{
+			name:  "pseudo from release ancestor",
+			input: "v0.29.1-0.20260522092201-58a85b68b3d9",
+			want:  true,
+		},
+
+		// Malformed pseudo-version lookalikes must NOT be treated
+		// as dev — they fall through to the semver parser.
+		{
+			name:  "malformed timestamp not dev",
+			input: "v0.0.0-20261322092201-58a85b68b3d9",
+			want:  false,
+		},
+		{
+			name:  "hash wrong length not dev",
+			input: "v0.0.0-20260522092201-58a85b6",
+			want:  false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, isDev(tt.input))
+		})
+	}
+}
+
+// TestCheckVersionUpgradePath_StoredPseudoVersion exercises the
+// upgrade path when database_versions holds a Go module pseudo-version
+// written by an untagged main-sha build. Without dev handling, the
+// stored pseudo-version parses as v0.0.0 and the next real release
+// trips the multi-minor guard.
+func TestCheckVersionUpgradePath_StoredPseudoVersion(t *testing.T) {
+	tests := []struct {
+		name           string
+		stored         string
+		currentVersion string
+	}{
+		{
+			name:           "v0.0.0 base pseudo to real release",
+			stored:         "v0.0.0-20260520093041-e4e742c776ee",
+			currentVersion: "v0.29.0-beta.1",
+		},
+		{
+			name:           "pseudo from pre-release ancestor",
+			stored:         "v0.29.0-beta.1.0.20260520093041-e4e742c776ee",
+			currentVersion: "v0.29.0",
+		},
+		{
+			name:           "pseudo from release ancestor",
+			stored:         "v0.28.1-0.20260520093041-e4e742c776ee",
+			currentVersion: "v0.29.0",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			db := versionTestDB(t)
+			require.NoError(t, setDatabaseVersion(db, tt.stored))
+			err := checkVersionUpgradePathFromVersions(db, tt.currentVersion)
+			assert.NoError(t, err)
+		})
+	}
+}
+
+// TestCheckVersionUpgradePath_CurrentPseudoDoesNotPoison locks the
+// contract that a main-sha (pseudo-version) binary must preserve the
+// stored real release so the next real release can upgrade cleanly.
+// Mirrors the gating in db.go around setDatabaseVersion.
+func TestCheckVersionUpgradePath_CurrentPseudoDoesNotPoison(t *testing.T) {
+	db := versionTestDB(t)
+	require.NoError(t, setDatabaseVersion(db, "v0.28.0"))
+
+	current := "v0.0.0-20260522092201-58a85b68b3d9"
+	err := checkVersionUpgradePathFromVersions(db, current)
+	require.NoError(t, err)
+
+	// Mirror db.go: only write the current version when !isDev.
+	if !isDev(current) {
+		require.NoError(t, setDatabaseVersion(db, current))
+	}
+
+	stored, err := getDatabaseVersion(db)
+	require.NoError(t, err)
+	assert.Equal(t, "v0.28.0", stored,
+		"pseudo-version run must not overwrite stored release")
 }
 
 // versionTestDB creates an in-memory SQLite database with the

hscontrol/mapper/batcher.go

@@ -630,6 +630,9 @@ func (b *Batcher) processBatchedChanges() {
 			return true
 		}
 
+		// One policy recompute rebuilds the whole netmap; drop same-tick repeats.
+		pending = change.DedupePolicyChanges(pending)
+
 		// 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.

hscontrol/mapper/batcher_test.go

@@ -1104,6 +1104,72 @@ func TestBatcherWorkQueueBatching(t *testing.T) {
 	}
 }
 
+// TestBatcherCoalescesPolicyRecomputesPerTick proves that many identical
+// broadcast policy changes arriving in a single batcher tick collapse to one
+// runtime peer recompute per node. Without coalescing, each PolicyChange drives
+// a separate full netmap rebuild for every connected node (the reconnect-storm
+// fan-out); with it, a node sees at most one recompute per tick.
+func TestBatcherCoalescesPolicyRecomputesPerTick(t *testing.T) {
+	for _, bf := range allBatcherFunctions {
+		t.Run(bf.name, func(t *testing.T) {
+			const (
+				nodesPerUser         = 4
+				policyChangesPerTick = 8
+			)
+
+			testData, cleanup := setupBatcherWithTestData(t, bf.fn, 1, nodesPerUser, 100)
+			defer cleanup()
+
+			batcher := testData.Batcher
+			for i := range testData.Nodes {
+				n := &testData.Nodes[i]
+				require.NoError(t, batcher.AddNode(n.n.ID, n.ch, tailcfg.CapabilityVersion(100), nil))
+			}
+
+			// Many identical broadcast policy changes, then a DERP-map change as
+			// a sentinel. All land in one tick; the sentinel rides the same work
+			// item after the recompute(s), so its arrival marks the end of this
+			// tick's policy responses for a node.
+			for range policyChangesPerTick {
+				batcher.AddWork(change.PolicyChange())
+			}
+
+			batcher.AddWork(change.DERPMap())
+
+			for i := range testData.Nodes {
+				id := testData.Nodes[i].n.ID
+				ch := testData.Nodes[i].ch
+
+				policyResponses := 0
+				deadline := time.After(2 * time.Second)
+
+			drain:
+				for {
+					select {
+					case resp := <-ch:
+						switch {
+						case resp.DERPMap != nil && len(resp.Peers) == 0:
+							// Sentinel: every policy recompute for this tick has
+							// already been delivered to this node.
+							break drain
+						case len(resp.PacketFilters) > 0 && len(resp.Peers) == 0:
+							// A runtime peer recompute (policyChangeResponse):
+							// packet filters and incremental peers, no full list.
+							policyResponses++
+						}
+					case <-deadline:
+						t.Fatalf("node %d never received the DERP sentinel", id)
+					}
+				}
+
+				assert.LessOrEqualf(t, policyResponses, 1,
+					"node %d received %d policy recomputes in one tick; identical recomputes must coalesce to one",
+					id, policyResponses)
+			}
+		})
+	}
+}
+
 // TestBatcherWorkerChannelSafety tests that worker goroutines handle closed
 // channels safely without panicking when processing work items.
 //

hscontrol/mapper/tail_test.go

@@ -70,7 +70,6 @@ func TestTailNode(t *testing.T) {
 				Name:              "empty",
 				StableID:          "0",
 				HomeDERP:          0,
-				LegacyDERPString:  "127.3.3.40:0",
 				Hostinfo:          hiview(tailcfg.Hostinfo{}),
 				MachineAuthorized: true,
 
@@ -148,8 +147,7 @@ func TestTailNode(t *testing.T) {
 				PrimaryRoutes: []netip.Prefix{
 					netip.MustParsePrefix("192.168.0.0/24"),
 				},
-				HomeDERP:         0,
-				LegacyDERPString: "127.3.3.40:0",
+				HomeDERP: 0,
 				Hostinfo: hiview(tailcfg.Hostinfo{
 					RoutableIPs: []netip.Prefix{
 						tsaddr.AllIPv4(),
@@ -186,7 +184,6 @@ func TestTailNode(t *testing.T) {
 				Name:              "minimal.example.com.",
 				StableID:          "0",
 				HomeDERP:          0,
-				LegacyDERPString:  "127.3.3.40:0",
 				Hostinfo:          hiview(tailcfg.Hostinfo{}),
 				MachineAuthorized: true,
 

hscontrol/policy/pm.go

@@ -36,6 +36,14 @@ type PolicyManager interface {
 	// NodeCanApproveRoute reports whether the given node can approve the given route.
 	NodeCanApproveRoute(node types.NodeView, route netip.Prefix) bool
 
+	// NodeNeedsPeerRecompute reports whether peers must recompute their
+	// netmap when the node's online state changes. True for subnet
+	// routers, relay targets (tailscale.com/cap/relay), and via targets;
+	// false for ordinary nodes, which only need a lightweight online or
+	// offline peer patch. [State.Connect] and [State.Disconnect] use it to
+	// avoid a tailnet-wide recompute on every ordinary reconnect.
+	NodeNeedsPeerRecompute(node types.NodeView) bool
+
 	// ViaRoutesForPeer computes via grant effects for a viewer-peer pair.
 	// It returns which routes should be included (peer is via-designated for viewer)
 	// and excluded (steered to a different peer). When no via grants apply,

hscontrol/policy/v2/compiled.go

@@ -594,6 +594,58 @@ func hasPerNodeGrants(grants []compiledGrant) bool {
 	return false
 }
 
+// collectRelayTargetIPs returns the set of IPs that are destinations of a
+// tailscale.com/cap/relay grant. A node whose IP is in this set is a relay
+// target: when it goes offline, peers holding a PeerRelay allocation through
+// it must recompute their netmap to drop the now-dead allocation. The relay
+// cap is carried on each grant's [tailcfg.CapGrant] with Dsts set to the
+// resolved relay destinations (see [Policy.compileOtherDests]); the reversed
+// companion rule carries [tailcfg.PeerCapabilityRelayTarget] instead and is
+// intentionally skipped.
+func collectRelayTargetIPs(grants []compiledGrant) (*netipx.IPSet, error) {
+	var b netipx.IPSetBuilder
+
+	for i := range grants {
+		for _, rule := range grants[i].rules {
+			for _, cg := range rule.CapGrant {
+				if _, ok := cg.CapMap[tailcfg.PeerCapabilityRelay]; !ok {
+					continue
+				}
+
+				for _, dst := range cg.Dsts {
+					b.AddPrefix(dst)
+				}
+			}
+		}
+	}
+
+	return b.IPSet()
+}
+
+// collectViaTargetTags returns the set of tags used as via targets across all
+// grants. A node carrying any of these tags is a via target: peers steering
+// traffic through it must recompute when it goes offline. Returns nil when no
+// via grants exist.
+func collectViaTargetTags(grants []compiledGrant) map[Tag]struct{} {
+	var tags map[Tag]struct{}
+
+	for i := range grants {
+		if grants[i].via == nil {
+			continue
+		}
+
+		for _, t := range grants[i].via.viaTags {
+			if tags == nil {
+				tags = make(map[Tag]struct{})
+			}
+
+			tags[t] = struct{}{}
+		}
+	}
+
+	return tags
+}
+
 // globalFilterRules extracts global filter rules from [compiledGrant]s.
 // Via grants produce no global rules (they are per-node only); regular
 // grants contribute their full pre-compiled ruleset; self grants

hscontrol/policy/v2/node_recompute_test.go

@@ -0,0 +1,137 @@
+package v2
+
+import (
+	"net/netip"
+	"testing"
+
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+	"tailscale.com/tailcfg"
+)
+
+// TestNodeNeedsPeerRecompute pins which node roles force peers to recompute
+// their netmap when the node's online state changes. An ordinary node only
+// needs the lightweight online/offline peer patch; subnet routers, relay
+// targets, and via targets change what peers compute and therefore need a
+// full recompute. The predicate is keyed on the flipping node, so an ordinary
+// node in a tailnet that uses relay or via elsewhere must still be classified
+// as not needing a recompute.
+func TestNodeNeedsPeerRecompute(t *testing.T) {
+	users := types.Users{
+		{Model: gorm.Model{ID: 1}, Name: "user1", Email: "user1@headscale.net"},
+	}
+
+	const allowAll = `{"acls":[{"action":"accept","src":["*"],"dst":["*:*"]}]}`
+
+	relayPol := `{
+		"tagOwners": {"tag:relay": ["user1@"]},
+		"grants": [
+			{"src": ["*"], "dst": ["tag:relay"], "app": {"tailscale.com/cap/relay": [{}]}}
+		]
+	}`
+
+	viaPol := `{
+		"tagOwners": {"tag:via": ["user1@"]},
+		"grants": [
+			{"src": ["*"], "dst": ["10.0.0.0/24"], "ip": ["*"], "via": ["tag:via"]}
+		]
+	}`
+
+	taildrivePol := `{
+		"tagOwners": {"tag:drive": ["user1@"]},
+		"grants": [
+			{"src": ["*"], "dst": ["tag:drive"], "app": {"tailscale.com/cap/drive": [{}]}}
+		]
+	}`
+
+	ordinary := node("ordinary", "100.64.0.1", "fd7a:115c:a1e0::1", users[0])
+	ordinary.ID = 1
+
+	subnetRouter := node("subnet", "100.64.0.2", "fd7a:115c:a1e0::2", users[0])
+	subnetRouter.ID = 2
+	subnetRouter.Hostinfo = &tailcfg.Hostinfo{
+		RoutableIPs: []netip.Prefix{netip.MustParsePrefix("10.0.0.0/24")},
+	}
+	subnetRouter.ApprovedRoutes = []netip.Prefix{netip.MustParsePrefix("10.0.0.0/24")}
+
+	relayTarget := node("relay", "100.64.0.3", "fd7a:115c:a1e0::3", users[0])
+	relayTarget.ID = 3
+	relayTarget.Tags = []string{"tag:relay"}
+
+	viaTarget := node("via", "100.64.0.4", "fd7a:115c:a1e0::4", users[0])
+	viaTarget.ID = 4
+	viaTarget.Tags = []string{"tag:via"}
+
+	driveTarget := node("drive", "100.64.0.5", "fd7a:115c:a1e0::5", users[0])
+	driveTarget.ID = 5
+	driveTarget.Tags = []string{"tag:drive"}
+
+	tests := []struct {
+		name    string
+		pol     string
+		nodes   types.Nodes
+		subject *types.Node
+		want    bool
+	}{
+		{
+			name:    "ordinary node under allow-all does not need recompute",
+			pol:     allowAll,
+			nodes:   types.Nodes{ordinary},
+			subject: ordinary,
+			want:    false,
+		},
+		{
+			name:    "subnet router needs recompute",
+			pol:     allowAll,
+			nodes:   types.Nodes{subnetRouter},
+			subject: subnetRouter,
+			want:    true,
+		},
+		{
+			name:    "relay target needs recompute",
+			pol:     relayPol,
+			nodes:   types.Nodes{relayTarget, ordinary},
+			subject: relayTarget,
+			want:    true,
+		},
+		{
+			name:    "ordinary node in a relay-using tailnet does not need recompute",
+			pol:     relayPol,
+			nodes:   types.Nodes{relayTarget, ordinary},
+			subject: ordinary,
+			want:    false,
+		},
+		{
+			name:    "via target needs recompute",
+			pol:     viaPol,
+			nodes:   types.Nodes{viaTarget, ordinary},
+			subject: viaTarget,
+			want:    true,
+		},
+		{
+			name:    "ordinary node in a via-using tailnet does not need recompute",
+			pol:     viaPol,
+			nodes:   types.Nodes{viaTarget, ordinary},
+			subject: ordinary,
+			want:    false,
+		},
+		{
+			name:    "taildrive target does not need recompute",
+			pol:     taildrivePol,
+			nodes:   types.Nodes{driveTarget, ordinary},
+			subject: driveTarget,
+			want:    false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			pm, err := NewPolicyManager([]byte(tt.pol), users, tt.nodes.ViewSlice())
+			require.NoError(t, err)
+
+			got := pm.NodeNeedsPeerRecompute(tt.subject.View())
+			require.Equal(t, tt.want, got)
+		})
+	}
+}

hscontrol/policy/v2/policy.go

@@ -45,6 +45,15 @@ type PolicyManager struct {
 	autoApproveMapHash deephash.Sum
 	autoApproveMap     map[netip.Prefix]*netipx.IPSet
 
+	// relayTargetIPs holds the IPs of nodes that are destinations of a
+	// tailscale.com/cap/relay grant; viaTargetTags holds the tags used as
+	// via targets. A node matching either, or that is a subnet router,
+	// forces peers to recompute their netmap when its online state changes
+	// (see [PolicyManager.NodeNeedsPeerRecompute]). Recomputed from the
+	// compiled grants on every policy/user/node change.
+	relayTargetIPs *netipx.IPSet
+	viaTargetTags  map[Tag]struct{}
+
 	// Lazy map of SSH policies
 	sshPolicyMap map[types.NodeID]*tailcfg.SSHPolicy
 
@@ -223,6 +232,14 @@ func (pm *PolicyManager) updateLocked() (bool, error) {
 	pm.compiledGrants = pm.pol.compileGrants(pm.users, pm.nodes)
 	pm.userNodeIdx = buildUserNodeIndex(pm.nodes)
 	pm.needsPerNodeFilter = hasPerNodeGrants(pm.compiledGrants)
+	pm.viaTargetTags = collectViaTargetTags(pm.compiledGrants)
+
+	relayTargetIPs, err := collectRelayTargetIPs(pm.compiledGrants)
+	if err != nil {
+		return false, fmt.Errorf("collecting relay target IPs: %w", err)
+	}
+
+	pm.relayTargetIPs = relayTargetIPs
 
 	var filter []tailcfg.FilterRule
 	if pm.pol == nil || (pm.pol.ACLs == nil && pm.pol.Grants == nil) {
@@ -360,6 +377,45 @@ func (pm *PolicyManager) updateLocked() (bool, error) {
 	return true, nil
 }
 
+// NodeNeedsPeerRecompute reports whether peers must recompute their netmap
+// when node's online state changes. A plain node only needs the lightweight
+// online/offline peer patch; these roles change what peers compute when the
+// node goes up or down, so they require a full recompute:
+//   - subnet router: primary-route failover changes peers' AllowedIPs
+//   - relay target (tailscale.com/cap/relay): peers must drop a stale
+//     PeerRelay allocation
+//   - via target: peers steer traffic through this node
+//
+// The check is keyed on the node itself, so an ordinary node in a tailnet
+// that uses relay or via for other nodes is correctly classified as not
+// needing a recompute.
+func (pm *PolicyManager) NodeNeedsPeerRecompute(node types.NodeView) bool {
+	if !node.Valid() {
+		return false
+	}
+
+	// Subnet-router status is intrinsic to the node, so it needs no policy
+	// state and is checked without the lock.
+	if node.IsSubnetRouter() {
+		return true
+	}
+
+	pm.mu.Lock()
+	defer pm.mu.Unlock()
+
+	if pm.relayTargetIPs != nil && node.InIPSet(pm.relayTargetIPs) {
+		return true
+	}
+
+	for tag := range pm.viaTargetTags {
+		if node.HasTag(string(tag)) {
+			return true
+		}
+	}
+
+	return false
+}
+
 // SSHPolicy returns the [tailcfg.SSHPolicy] for node, compiling and
 // caching on first access. Rules use SessionDuration = 0 (no
 // auto-approval) and emit check URLs of the form
@@ -1299,13 +1355,18 @@ func (pm *PolicyManager) invalidateAutogroupSelfCache(oldNodes, newNodes views.S
 	// Tagged nodes don't participate in autogroup:self (identity is tag-based),
 	// so we skip them when collecting affected users, except when tag status changes
 	// (which affects the user's device set).
-	affectedUsers := make(map[uint]struct{})
+	//
+	// Ownership is keyed on TypedUserID (the UserID field), not the User
+	// association view: the NodeStore holds nodes by value with User as a
+	// *User pointer, and not every write path hydrates that association. A
+	// non-tagged node always has UserID set, so it is the reliable owner key.
+	affectedUsers := make(map[types.UserID]struct{})
 
 	// Check for removed nodes (only non-tagged nodes affect autogroup:self)
 	for nodeID, oldNode := range oldNodeMap {
 		if _, exists := newNodeMap[nodeID]; !exists {
 			if !oldNode.IsTagged() {
-				affectedUsers[oldNode.User().ID()] = struct{}{}
+				affectedUsers[oldNode.TypedUserID()] = struct{}{}
 			}
 		}
 	}
@@ -1314,7 +1375,7 @@ func (pm *PolicyManager) invalidateAutogroupSelfCache(oldNodes, newNodes views.S
 	for nodeID, newNode := range newNodeMap {
 		if _, exists := oldNodeMap[nodeID]; !exists {
 			if !newNode.IsTagged() {
-				affectedUsers[newNode.User().ID()] = struct{}{}
+				affectedUsers[newNode.TypedUserID()] = struct{}{}
 			}
 		}
 	}
@@ -1327,10 +1388,10 @@ func (pm *PolicyManager) invalidateAutogroupSelfCache(oldNodes, newNodes views.S
 			if oldNode.IsTagged() != newNode.IsTagged() {
 				if !oldNode.IsTagged() {
 					// Was untagged, now tagged: user lost a device
-					affectedUsers[oldNode.User().ID()] = struct{}{}
+					affectedUsers[oldNode.TypedUserID()] = struct{}{}
 				} else {
 					// Was tagged, now untagged: user gained a device
-					affectedUsers[newNode.User().ID()] = struct{}{}
+					affectedUsers[newNode.TypedUserID()] = struct{}{}
 				}
 
 				continue
@@ -1342,9 +1403,9 @@ func (pm *PolicyManager) invalidateAutogroupSelfCache(oldNodes, newNodes views.S
 			}
 
 			// Check if user changed (both versions are non-tagged here)
-			if oldNode.User().ID() != newNode.User().ID() {
-				affectedUsers[oldNode.User().ID()] = struct{}{}
-				affectedUsers[newNode.User().ID()] = struct{}{}
+			if oldNode.TypedUserID() != newNode.TypedUserID() {
+				affectedUsers[oldNode.TypedUserID()] = struct{}{}
+				affectedUsers[newNode.TypedUserID()] = struct{}{}
 			}
 
 			// Check if IPs changed (simple check - could be more sophisticated)
@@ -1352,12 +1413,12 @@ func (pm *PolicyManager) invalidateAutogroupSelfCache(oldNodes, newNodes views.S
 
 			newIPs := newNode.IPs()
 			if len(oldIPs) != len(newIPs) {
-				affectedUsers[newNode.User().ID()] = struct{}{}
+				affectedUsers[newNode.TypedUserID()] = struct{}{}
 			} else {
 				// Check if any IPs are different
 				for i, oldIP := range oldIPs {
 					if i >= len(newIPs) || oldIP != newIPs[i] {
-						affectedUsers[newNode.User().ID()] = struct{}{}
+						affectedUsers[newNode.TypedUserID()] = struct{}{}
 						break
 					}
 				}
@@ -1370,7 +1431,7 @@ func (pm *PolicyManager) invalidateAutogroupSelfCache(oldNodes, newNodes views.S
 	// because autogroup:self rules depend on the entire user's device set.
 	for nodeID := range pm.filterRulesMap {
 		// Find the user for this cached node
-		var nodeUserID uint
+		var nodeUserID types.UserID
 
 		found := false
 
@@ -1384,7 +1445,7 @@ func (pm *PolicyManager) invalidateAutogroupSelfCache(oldNodes, newNodes views.S
 					break
 				}
 
-				nodeUserID = node.User().ID()
+				nodeUserID = node.TypedUserID()
 				found = true
 
 				break
@@ -1400,7 +1461,7 @@ func (pm *PolicyManager) invalidateAutogroupSelfCache(oldNodes, newNodes views.S
 						break
 					}
 
-					nodeUserID = node.User().ID()
+					nodeUserID = node.TypedUserID()
 					found = true
 
 					break

hscontrol/policy/v2/policy_test.go

@@ -226,6 +226,72 @@ func TestInvalidateAutogroupSelfCache(t *testing.T) {
 	}
 }
 
+// TestSetNodesAutogroupSelfUnhydratedUser reproduces the panic seen on
+// /machine/map when an autogroup:self policy is active and a non-tagged
+// node reaches the policy manager with its UserID set but the User
+// association left unhydrated (User pointer nil). The NodeStore stores
+// nodes by value with User as a *User; not every write path hydrates the
+// association, so the autogroup:self cache invalidation must derive the
+// owning user from UserID, not from the User view.
+func TestSetNodesAutogroupSelfUnhydratedUser(t *testing.T) {
+	users := types.Users{
+		{Model: gorm.Model{ID: 1}, Name: "user1", Email: "user1@headscale.net"},
+		{Model: gorm.Model{ID: 2}, Name: "user2", Email: "user2@headscale.net"},
+	}
+
+	policy := `{
+		"acls": [
+			{
+				"action": "accept",
+				"src": ["autogroup:member"],
+				"dst": ["autogroup:self:*"]
+			}
+		]
+	}`
+
+	// unhydratedNode mirrors a NodeStore snapshot entry whose UserID is
+	// set (so it is unambiguously user-owned, not tagged) but whose User
+	// association was never loaded.
+	unhydratedNode := func(name, ipv4, ipv6 string, userID uint) *types.Node {
+		return &types.Node{
+			Hostname: name,
+			IPv4:     ap(ipv4),
+			IPv6:     ap(ipv6),
+			UserID:   new(userID),
+			User:     nil,
+		}
+	}
+
+	initialNodes := types.Nodes{
+		node("user1-node1", "100.64.0.1", "fd7a:115c:a1e0::1", users[0]),
+		node("user2-node1", "100.64.0.2", "fd7a:115c:a1e0::2", users[1]),
+	}
+	for i, n := range initialNodes {
+		n.ID = types.NodeID(i + 1) //nolint:gosec // safe conversion in test
+	}
+
+	pm, err := NewPolicyManager([]byte(policy), users, initialNodes.ViewSlice())
+	require.NoError(t, err)
+
+	require.False(t, initialNodes[0].IsTagged(), "node must be user-owned for autogroup:self")
+
+	// Simulate a node restarting tailscaled: the same node is pushed back
+	// into the policy manager, but the snapshot version has no hydrated
+	// User association. This is the exact shape that crashed beta.1.
+	updatedNodes := types.Nodes{
+		unhydratedNode("user1-node1", "100.64.0.1", "fd7a:115c:a1e0::1", users[0].ID),
+		node("user2-node1", "100.64.0.2", "fd7a:115c:a1e0::2", users[1]),
+	}
+	for i, n := range updatedNodes {
+		n.ID = types.NodeID(i + 1) //nolint:gosec // safe conversion in test
+	}
+
+	require.NotPanics(t, func() {
+		_, err = pm.SetNodes(updatedNodes.ViewSlice())
+	}, "SetNodes must not panic when a non-tagged node has an unhydrated User")
+	require.NoError(t, err)
+}
+
 // TestInvalidateGlobalPolicyCache tests the cache invalidation logic for global policies.
 func TestInvalidateGlobalPolicyCache(t *testing.T) {
 	mustIPPtr := func(s string) *netip.Addr {

hscontrol/state/connect_test.go

@@ -0,0 +1,216 @@
+package state
+
+import (
+	"net/netip"
+	"testing"
+
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/juanfont/headscale/hscontrol/types/change"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"tailscale.com/tailcfg"
+)
+
+// runtimePeerComputationReasons returns the Reason of every change in cs that
+// carries RequiresRuntimePeerComputation. Each such change makes the batcher
+// rebuild a full netmap (packet filters, SSH policy, peer serialization) for
+// every connected node, so it is the expensive fan-out the issue is about.
+func runtimePeerComputationReasons(cs []change.Change) []string {
+	var reasons []string
+
+	for _, c := range cs {
+		if c.RequiresRuntimePeerComputation {
+			reasons = append(reasons, c.Reason)
+		}
+	}
+
+	return reasons
+}
+
+// hasPeerPatch reports whether any change carries a lightweight PeerChange
+// patch (e.g. the online/offline indicator). This is the cheap notification a
+// reconnect should produce instead of a full runtime recompute.
+func hasPeerPatch(cs []change.Change) bool {
+	for _, c := range cs {
+		if len(c.PeerPatches) > 0 {
+			return true
+		}
+	}
+
+	return false
+}
+
+// forcesPeerRecompute reports whether any change makes peers rebuild a full
+// netmap, whether via a full update (subnet-router path) or a runtime peer
+// computation (relay/via path).
+func forcesPeerRecompute(cs []change.Change) bool {
+	for _, c := range cs {
+		if c.IsFull() || c.RequiresRuntimePeerComputation {
+			return true
+		}
+	}
+
+	return false
+}
+
+// TestConnectDisconnectOrdinaryNodeNoRuntimeRecompute asserts that an ordinary
+// node coming online or going offline only sends the lightweight online/offline
+// peer patch and does not trigger a runtime peer recompute.
+//
+// State.Connect and State.Disconnect gate change.PolicyChange() (which sets
+// RequiresRuntimePeerComputation, forcing the batcher to rebuild a full netmap
+// for every connected node) on NodeNeedsPeerRecompute. An ordinary node is
+// neither a subnet router, a relay target, nor a via target, so the gate is
+// false and no recompute is emitted.
+//
+// Emitting that recompute unconditionally turned each reconnect into O(N) full
+// netmap rebuilds (and a reconnect storm into O(N^2)), which saturated CPU
+// after the v0.28 -> v0.29 upgrade.
+func TestConnectDisconnectOrdinaryNodeNoRuntimeRecompute(t *testing.T) {
+	_, s, nodeID := persistTestSetup(t)
+	t.Cleanup(func() { _ = s.Close() })
+
+	t.Run("connect", func(t *testing.T) {
+		cs, epoch := s.Connect(nodeID)
+		require.NotZero(t, epoch, "Connect should return a session epoch")
+
+		assert.True(t, hasPeerPatch(cs),
+			"Connect should still emit a lightweight online peer patch")
+
+		reasons := runtimePeerComputationReasons(cs)
+		assert.Empty(t, reasons,
+			"ordinary node connect must not trigger a runtime peer recompute; "+
+				"got RequiresRuntimePeerComputation changes: %v", reasons)
+	})
+
+	t.Run("disconnect", func(t *testing.T) {
+		// Connect first so Disconnect's epoch check passes.
+		_, epoch := s.Connect(nodeID)
+
+		cs, err := s.Disconnect(nodeID, epoch)
+		require.NoError(t, err)
+
+		assert.True(t, hasPeerPatch(cs),
+			"Disconnect should still emit a lightweight offline peer patch")
+
+		reasons := runtimePeerComputationReasons(cs)
+		assert.Empty(t, reasons,
+			"ordinary node disconnect must not trigger a runtime peer recompute; "+
+				"got RequiresRuntimePeerComputation changes: %v", reasons)
+	})
+}
+
+// TestConnectDisconnectRelayTargetTriggersRecompute locks the cap/relay case:
+// a relay target is not a subnet router, so the only thing that makes its
+// connect/disconnect emit a runtime peer recompute is the
+// NodeNeedsPeerRecompute gate. Peers must still receive that recompute so they
+// drop a stale PeerRelay allocation when the relay goes offline.
+func TestConnectDisconnectRelayTargetTriggersRecompute(t *testing.T) {
+	_, s, nodeID := persistTestSetup(t)
+	t.Cleanup(func() { _ = s.Close() })
+
+	// A cap/relay grant whose destination resolves to the node's owning
+	// user makes the node a relay target without making it a subnet router.
+	relayPolicy := `{"grants":[{"src":["*"],"dst":["persist-user@"],"app":{"tailscale.com/cap/relay":[{}]}}]}`
+	_, err := s.SetPolicy([]byte(relayPolicy))
+	require.NoError(t, err)
+
+	t.Run("connect", func(t *testing.T) {
+		cs, epoch := s.Connect(nodeID)
+		require.NotZero(t, epoch)
+
+		assert.NotEmpty(t, runtimePeerComputationReasons(cs),
+			"relay-target node connect must trigger a runtime peer recompute")
+	})
+
+	t.Run("disconnect", func(t *testing.T) {
+		_, epoch := s.Connect(nodeID)
+
+		cs, err := s.Disconnect(nodeID, epoch)
+		require.NoError(t, err)
+
+		assert.NotEmpty(t, runtimePeerComputationReasons(cs),
+			"relay-target node disconnect must trigger a runtime peer recompute")
+	})
+}
+
+// TestConnectDisconnectSubnetRouterForcesRecompute guards that a subnet router
+// still forces peers to recompute on connect/disconnect (primary-route
+// failover changes their AllowedIPs), so the gate does not over-suppress.
+func TestConnectDisconnectSubnetRouterForcesRecompute(t *testing.T) {
+	_, s, nodeID := persistTestSetup(t)
+	t.Cleanup(func() { _ = s.Close() })
+
+	route := netip.MustParsePrefix("10.0.0.0/24")
+	_, ok := s.nodeStore.UpdateNode(nodeID, func(n *types.Node) {
+		n.Hostinfo = &tailcfg.Hostinfo{RoutableIPs: []netip.Prefix{route}}
+		n.ApprovedRoutes = []netip.Prefix{route}
+	})
+	require.True(t, ok)
+
+	t.Run("connect", func(t *testing.T) {
+		cs, epoch := s.Connect(nodeID)
+		require.NotZero(t, epoch)
+
+		assert.True(t, forcesPeerRecompute(cs),
+			"subnet router connect must force a peer recompute")
+	})
+
+	t.Run("disconnect", func(t *testing.T) {
+		_, epoch := s.Connect(nodeID)
+
+		cs, err := s.Disconnect(nodeID, epoch)
+		require.NoError(t, err)
+
+		assert.True(t, forcesPeerRecompute(cs),
+			"subnet router disconnect must force a peer recompute")
+	})
+}
+
+// TestConnectDisconnectSubnetRouterEmitsPolicyChangeNotFull pins how a subnet
+// router forces that recompute: through the gated change.PolicyChange() (a
+// runtime peer recompute) and the lightweight online/offline peer patch, not a
+// full update. policyChangeResponse is a strict subset of a full update yet
+// still carries primary-route failover, so the heavier FullUpdate that the
+// online/offline change once emitted for subnet routers is unnecessary.
+func TestConnectDisconnectSubnetRouterEmitsPolicyChangeNotFull(t *testing.T) {
+	_, s, nodeID := persistTestSetup(t)
+	t.Cleanup(func() { _ = s.Close() })
+
+	route := netip.MustParsePrefix("10.0.0.0/24")
+	_, ok := s.nodeStore.UpdateNode(nodeID, func(n *types.Node) {
+		n.Hostinfo = &tailcfg.Hostinfo{RoutableIPs: []netip.Prefix{route}}
+		n.ApprovedRoutes = []netip.Prefix{route}
+	})
+	require.True(t, ok)
+
+	assertRecomputeNotFull := func(t *testing.T, cs []change.Change) {
+		t.Helper()
+
+		assert.NotEmpty(t, runtimePeerComputationReasons(cs),
+			"subnet router must still drive a runtime peer recompute")
+		assert.True(t, hasPeerPatch(cs),
+			"subnet router should still emit the lightweight online/offline patch")
+
+		for _, c := range cs {
+			assert.Falsef(t, c.IsFull(),
+				"subnet router recompute must be a PolicyChange, not a full update: %q", c.Reason)
+		}
+	}
+
+	t.Run("connect", func(t *testing.T) {
+		cs, epoch := s.Connect(nodeID)
+		require.NotZero(t, epoch)
+
+		assertRecomputeNotFull(t, cs)
+	})
+
+	t.Run("disconnect", func(t *testing.T) {
+		_, epoch := s.Connect(nodeID)
+
+		cs, err := s.Disconnect(nodeID, epoch)
+		require.NoError(t, err)
+
+		assertRecomputeNotFull(t, cs)
+	})
+}

hscontrol/state/state.go

@@ -594,9 +594,14 @@ func (s *State) Connect(id types.NodeID) ([]change.Change, uint64) {
 		c = append(c, change.NodeAdded(id))
 	}
 
-	// Coming online may re-enable cap/relay grants and identity-based
-	// aliases targeting this node, so peers need a fresh netmap.
-	c = append(c, change.PolicyChange())
+	// Only a node whose online state changes what peers compute (a subnet
+	// router, relay target, or via target) needs a full peer recompute.
+	// An ordinary node coming online just sends the lightweight online
+	// patch above; emitting a PolicyChange for it would force every peer
+	// to rebuild its netmap on every reconnect.
+	if s.polMan.NodeNeedsPeerRecompute(node) {
+		c = append(c, change.PolicyChange())
+	}
 
 	return c, epoch
 }
@@ -648,13 +653,15 @@ func (s *State) Disconnect(id types.NodeID, epoch uint64) ([]change.Change, erro
 		c = change.Change{}
 	}
 
-	// Going offline can affect policy compilation beyond subnet routes
-	// (cap/relay grants, tag/group aliases, via routes), so peers need
-	// a fresh netmap regardless of whether the primary moved.
-	//
-	// TODO(kradalby): fires one full netmap recompute per peer on
-	// every connect/disconnect. Coalesce in mapper/batcher.go:addToBatch.
-	cs := []change.Change{change.NodeOfflineFor(node), c, change.PolicyChange()}
+	// Only a node whose online state changes what peers compute (a subnet
+	// router, relay target, or via target) needs a full peer recompute.
+	// An ordinary node going offline just sends the lightweight offline
+	// patch; emitting a PolicyChange for it would force every peer to
+	// rebuild its netmap on every disconnect.
+	cs := []change.Change{change.NodeOfflineFor(node), c}
+	if s.polMan.NodeNeedsPeerRecompute(node) {
+		cs = append(cs, change.PolicyChange())
+	}
 
 	return cs, nil
 }

hscontrol/types/change/change.go

@@ -250,6 +250,41 @@ func FilterForNode(nodeID types.NodeID, rs []Change) []Change {
 	return result
 }
 
+// IsBroadcastPolicyChange reports whether r is a tailnet-wide policy recompute
+// with no per-node payload. A recompute reads the current snapshot, so every
+// such change is interchangeable and same-tick duplicates are redundant. A
+// targeted or self-update ([Change.OriginNode]) recompute is per-node, so it is
+// not one of these.
+func (r Change) IsBroadcastPolicyChange() bool {
+	return r.RequiresRuntimePeerComputation && !r.IsTargetedToNode() && r.OriginNode == 0
+}
+
+// DedupePolicyChanges keeps the first broadcast policy change in a tick and
+// drops the rest: each rebuilds a node's whole netmap from the same snapshot, so
+// the repeats are wasted work. Order and all other changes are preserved.
+func DedupePolicyChanges(changes []Change) []Change {
+	if len(changes) < 2 {
+		return changes
+	}
+
+	out := make([]Change, 0, len(changes))
+	seen := false
+
+	for _, r := range changes {
+		if r.IsBroadcastPolicyChange() {
+			if seen {
+				continue
+			}
+
+			seen = true
+		}
+
+		out = append(out, r)
+	}
+
+	return out
+}
+
 func uniqueNodeIDs(ids []types.NodeID) []types.NodeID {
 	if len(ids) == 0 {
 		return nil
@@ -421,29 +456,19 @@ func NodeRemoved(id types.NodeID) Change {
 	return PeersRemoved(id)
 }
 
-// NodeOnlineFor returns a [Change] for when a node comes online.
-// If the node is a subnet router, a full update is sent instead of a patch.
+// NodeOnlineFor returns the [Change] for a node coming online: a lightweight
+// [NodeOnline] peer patch. Subnet routers, relay targets, and via targets get
+// their full peer recompute from the gated [PolicyChange] that State.Connect
+// emits, so no full update is needed here.
 func NodeOnlineFor(node types.NodeView) Change {
-	if node.IsSubnetRouter() {
-		c := FullUpdate()
-		c.Reason = "subnet router online"
-
-		return c
-	}
-
 	return NodeOnline(node.ID())
 }
 
-// NodeOfflineFor returns a [Change] for when a node goes offline.
-// If the node is a subnet router, a full update is sent instead of a patch.
+// NodeOfflineFor returns the [Change] for a node going offline: a lightweight
+// [NodeOffline] peer patch. As with [NodeOnlineFor], subnet routers and other
+// recompute-forcing nodes rely on the gated [PolicyChange] from State.Disconnect
+// for the peer recompute, so no full update is needed here.
 func NodeOfflineFor(node types.NodeView) Change {
-	if node.IsSubnetRouter() {
-		c := FullUpdate()
-		c.Reason = "subnet router offline"
-
-		return c
-	}
-
 	return NodeOffline(node.ID())
 }
 

hscontrol/types/change/change_test.go

@@ -1,11 +1,13 @@
 package change
 
 import (
+	"net/netip"
 	"reflect"
 	"testing"
 
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 	"tailscale.com/tailcfg"
 )
 
@@ -296,6 +298,99 @@ func TestChange_Merge(t *testing.T) {
 	}
 }
 
+func TestChange_IsBroadcastPolicyChange(t *testing.T) {
+	originUpdate := PolicyChange()
+	originUpdate.OriginNode = 7
+
+	targeted := PolicyChange()
+	targeted.TargetNode = 7
+
+	tests := []struct {
+		name string
+		c    Change
+		want bool
+	}{
+		{name: "policy change", c: PolicyChange(), want: true},
+		{name: "self-update recompute", c: originUpdate, want: false},
+		{name: "targeted recompute", c: targeted, want: false},
+		{name: "online patch", c: NodeOnline(1), want: false},
+		{name: "full update", c: FullUpdate(), want: false},
+		{name: "derp map", c: DERPMap(), want: false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, tt.c.IsBroadcastPolicyChange())
+		})
+	}
+}
+
+func TestDedupePolicyChanges(t *testing.T) {
+	// originRecompute is a runtime recompute carrying node-specific payload
+	// (OriginNode), so it is not the canonical broadcast PolicyChange and must
+	// never be coalesced away.
+	originRecompute := PolicyChange()
+	originRecompute.OriginNode = 7
+
+	tests := []struct {
+		name    string
+		changes []Change
+		want    []Change
+	}{
+		{
+			name:    "nil is a no-op",
+			changes: nil,
+			want:    nil,
+		},
+		{
+			name:    "single policy change is unchanged",
+			changes: []Change{PolicyChange()},
+			want:    []Change{PolicyChange()},
+		},
+		{
+			name:    "identical policy changes collapse to one",
+			changes: []Change{PolicyChange(), PolicyChange(), PolicyChange()},
+			want:    []Change{PolicyChange()},
+		},
+		{
+			name: "peer patches survive between collapsed policy changes",
+			changes: []Change{
+				NodeOnline(1), PolicyChange(), NodeOnline(2), PolicyChange(), NodeOffline(3),
+			},
+			want: []Change{
+				NodeOnline(1), PolicyChange(), NodeOnline(2), NodeOffline(3),
+			},
+		},
+		{
+			name:    "NodeAdded is preserved, not treated as a recompute",
+			changes: []Change{PolicyChange(), NodeAdded(5), PolicyChange()},
+			want:    []Change{PolicyChange(), NodeAdded(5)},
+		},
+		{
+			name:    "recompute carrying OriginNode is kept alongside the canonical one",
+			changes: []Change{PolicyChange(), originRecompute, PolicyChange()},
+			want:    []Change{PolicyChange(), originRecompute},
+		},
+		{
+			name:    "non-canonical recomputes are not collapsed",
+			changes: []Change{originRecompute, originRecompute},
+			want:    []Change{originRecompute, originRecompute},
+		},
+		{
+			name:    "changes without any recompute are unchanged",
+			changes: []Change{NodeOnline(1), DERPMap()},
+			want:    []Change{NodeOnline(1), DERPMap()},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := DedupePolicyChanges(tt.changes)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
 func TestChange_Constructors(t *testing.T) {
 	tests := []struct {
 		name        string
@@ -519,3 +614,42 @@ func TestUniqueNodeIDs(t *testing.T) {
 		})
 	}
 }
+
+func TestNodeOnlineOfflineForSubnetRouter(t *testing.T) {
+	route := netip.MustParsePrefix("10.0.0.0/24")
+	router := types.Node{
+		ID:             1,
+		Hostinfo:       &tailcfg.Hostinfo{RoutableIPs: []netip.Prefix{route}},
+		ApprovedRoutes: []netip.Prefix{route},
+	}
+	view := router.View()
+	require.True(t, view.IsSubnetRouter(), "test node must be a subnet router")
+
+	tests := []struct {
+		name       string
+		got        Change
+		wantOnline bool
+	}{
+		{name: "online", got: NodeOnlineFor(view), wantOnline: true},
+		{name: "offline", got: NodeOfflineFor(view), wantOnline: false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// A subnet router's online/offline transition rides the lightweight
+			// peer patch, not a full update: the gated PolicyChange that
+			// State.Connect/Disconnect emit owns the netmap recompute.
+			assert.False(t, tt.got.IsFull(),
+				"subnet router online/offline must be a peer patch, not a full update")
+
+			require.NotEmpty(t, tt.got.PeerPatches,
+				"expected an online/offline peer patch")
+
+			patch := tt.got.PeerPatches[0]
+			assert.Equal(t, view.ID().NodeID(), patch.NodeID)
+
+			require.NotNil(t, patch.Online)
+			assert.Equal(t, tt.wantOnline, *patch.Online)
+		})
+	}
+}

hscontrol/types/node.go

@@ -1185,11 +1185,7 @@ func (nv NodeView) TailNode(
 	}
 
 	var derp int
-	// TODO(kradalby): legacyDERP was removed in tailscale/tailscale@2fc4455e6dd9ab7f879d4e2f7cffc2be81f14077
-	// and should be removed after 111 is the minimum capver.
-	legacyDERP := "127.3.3.40:0" // Zero means disconnected or unknown.
 	if nv.Hostinfo().Valid() && nv.Hostinfo().NetInfo().Valid() {
-		legacyDERP = fmt.Sprintf("127.3.3.40:%d", nv.Hostinfo().NetInfo().PreferredDERP())
 		derp = nv.Hostinfo().NetInfo().PreferredDERP()
 	}
 
@@ -1266,16 +1262,15 @@ func (nv NodeView) TailNode(
 		Key:       nv.NodeKey(),
 		KeyExpiry: keyExpiry.UTC(),
 
-		Machine:          nv.MachineKey(),
-		DiscoKey:         nv.DiscoKey(),
-		Addresses:        addresses,
-		PrimaryRoutes:    primaryRoutes,
-		AllowedIPs:       allowedIPs,
-		Endpoints:        nv.Endpoints().AsSlice(),
-		HomeDERP:         derp,
-		LegacyDERPString: legacyDERP,
-		Hostinfo:         nv.Hostinfo(),
-		Created:          nv.CreatedAt().UTC(),
+		Machine:       nv.MachineKey(),
+		DiscoKey:      nv.DiscoKey(),
+		Addresses:     addresses,
+		PrimaryRoutes: primaryRoutes,
+		AllowedIPs:    allowedIPs,
+		Endpoints:     nv.Endpoints().AsSlice(),
+		HomeDERP:      derp,
+		Hostinfo:      nv.Hostinfo(),
+		Created:       nv.CreatedAt().UTC(),
 
 		Online: nv.IsOnline().Clone(),
 

integration/helpers.go

@@ -791,7 +791,6 @@ func assertValidNetmap(t *testing.T, client TailscaleClient) {
 		assert.Falsef(c, netmap.SelfNode.DiscoKey().IsZero(), "%q does not have a valid DiscoKey", client.Hostname())
 
 		for _, peer := range netmap.Peers {
-			assert.NotEqualf(c, "127.3.3.40:0", peer.LegacyDERPString(), "peer (%s) has no home DERP in %q's netmap, got: %s", peer.ComputedName(), client.Hostname(), peer.LegacyDERPString()) //nolint:staticcheck // SA1019: testing legacy field
 			assert.NotEqualf(c, 0, peer.HomeDERP(), "peer (%s) has no home DERP in %q's netmap, got: %d", peer.ComputedName(), client.Hostname(), peer.HomeDERP())
 
 			assert.Truef(c, peer.Hostinfo().Valid(), "peer (%s) of %q does not have Hostinfo", peer.ComputedName(), client.Hostname())

integration/tsic/tsic.go

@@ -522,6 +522,9 @@ func New(
 			}
 		}
 	case "unstable":
+		// ghcr.io/tailscale/tailscale:unstable is stale (last updated
+		// 2022); only tailscale/tailscale on Docker Hub publishes
+		// current unstable builds.
 		tailscaleOptions.Repository = "tailscale/tailscale"
 		tailscaleOptions.Tag = version
 
@@ -542,7 +545,7 @@ func New(
 			log.Printf("Docker run failed for %s (unstable), error: %v", hostname, err)
 		}
 	default:
-		tailscaleOptions.Repository = "tailscale/tailscale"
+		tailscaleOptions.Repository = "ghcr.io/tailscale/tailscale"
 		tailscaleOptions.Tag = "v" + version
 
 		err = dockertestutil.PullWithAuth(pool, tailscaleOptions.Repository+":"+tailscaleOptions.Tag)

monitoring-config.yaml

@@ -1,288 +0,0 @@
-# OIDC Role Mapping Monitoring Configuration
-# This file provides monitoring, alerting, and metrics configuration for production deployments
-
-# Prometheus Metrics
-prometheus_metrics:
-  # Headscale metrics to track
-  headscale_metrics:
-    - name: "headscale_oidc_logins_total"
-      description: "Total number of OIDC logins"
-      labels: ["result", "provider"]
-    
-    - name: "headscale_oidc_groups_extracted_total"
-      description: "Number of groups extracted from OIDC claims"
-      labels: ["user", "group_count"]
-    
-    - name: "headscale_users_with_groups_total"
-      description: "Total users with group assignments"
-      labels: ["group_name"]
-  
-  # Headplane metrics to track
-  headplane_metrics:
-    - name: "headplane_role_assignments_total"
-      description: "Total role assignments by type"
-      labels: ["role", "source"]
-    
-    - name: "headplane_oidc_role_mappings_total"
-      description: "OIDC group to role mappings"
-      labels: ["group", "role", "result"]
-    
-    - name: "headplane_capability_checks_total"
-      description: "Capability check results"
-      labels: ["capability", "result", "role"]
-
-# Grafana Dashboard Configuration
-grafana_dashboard:
-  title: "OIDC Role Mapping Dashboard"
-  
-  panels:
-    - title: "OIDC Login Success Rate"
-      type: "stat"
-      query: "rate(headscale_oidc_logins_total{result='success'}[5m])"
-      
-    - title: "Role Distribution"
-      type: "pie"
-      query: "sum by (role) (headplane_role_assignments_total)"
-      
-    - title: "Group Mapping Success Rate"
-      type: "graph"
-      query: "rate(headplane_oidc_role_mappings_total{result='success'}[5m])"
-      
-    - title: "Users by Group"
-      type: "table"
-      query: "headscale_users_with_groups_total"
-      
-    - title: "Failed Role Assignments"
-      type: "logs"
-      query: "headplane_oidc_role_mappings_total{result='failed'}"
-
-# Alerting Rules
-alerting_rules:
-  groups:
-    - name: "oidc_role_mapping"
-      rules:
-        - alert: "OIDCLoginFailureSpike"
-          expr: "rate(headscale_oidc_logins_total{result='failed'}[5m]) > 0.1"
-          for: "2m"
-          labels:
-            severity: "warning"
-          annotations:
-            summary: "High OIDC login failure rate"
-            description: "OIDC login failures have exceeded 10% over the last 5 minutes"
-        
-        - alert: "RoleMappingFailures"
-          expr: "rate(headplane_oidc_role_mappings_total{result='failed'}[5m]) > 0"
-          for: "1m"
-          labels:
-            severity: "critical"
-          annotations:
-            summary: "Role mapping failures detected"
-            description: "Users are failing to get assigned proper roles from OIDC groups"
-        
-        - alert: "UnexpectedOwnerRoleAssignments"
-          expr: "increase(headplane_role_assignments_total{role='owner'}[1h]) > 1"
-          for: "0m"
-          labels:
-            severity: "critical"
-          annotations:
-            summary: "Multiple owner role assignments detected"
-            description: "More than one owner role has been assigned in the last hour"
-        
-        - alert: "NoGroupsInOIDCTokens"
-          expr: "rate(headscale_oidc_groups_extracted_total{group_count='0'}[10m]) > 0.5"
-          for: "5m"
-          labels:
-            severity: "warning"
-          annotations:
-            summary: "OIDC tokens missing group claims"
-            description: "Over 50% of OIDC logins are not receiving group information"
-
-# Log Monitoring Configuration
-log_monitoring:
-  # Headscale log patterns to monitor
-  headscale_patterns:
-    - pattern: "Failed to unmarshal user groups"
-      severity: "error"
-      action: "alert"
-      
-    - pattern: "Groups extracted from OIDC"
-      severity: "info"
-      action: "metric"
-      
-    - pattern: "OIDC callback.*groups.*empty"
-      severity: "warning"
-      action: "alert"
-  
-  # Headplane log patterns to monitor
-  headplane_patterns:
-    - pattern: "Role mapping.*failed"
-      severity: "error"
-      action: "alert"
-      
-    - pattern: "User.*assigned role.*owner"
-      severity: "info"
-      action: "audit_log"
-      
-    - pattern: "Groups.*not found in mapping"
-      severity: "warning"
-      action: "metric"
-
-# Security Monitoring
-security_monitoring:
-  # Track privilege escalation attempts
-  privilege_escalation:
-    - monitor: "Role changes from member to admin+"
-      threshold: 1
-      window: "1h"
-      
-    - monitor: "Direct database role modifications"
-      threshold: 0
-      window: "5m"
-  
-  # Monitor suspicious group assignments
-  suspicious_groups:
-    - pattern: "groups containing 'admin' assigned to new users"
-      threshold: 5
-      window: "1h"
-      
-    - pattern: "owner role assigned outside business hours"
-      threshold: 0
-      window: "24h"
-
-# Health Checks
-health_checks:
-  oidc_provider:
-    - name: "OIDC Issuer Reachability"
-      url: "${OIDC_ISSUER}/.well-known/openid-configuration"
-      interval: "30s"
-      timeout: "5s"
-      
-    - name: "OIDC Token Endpoint"
-      url: "${OIDC_ISSUER}/protocol/openid-connect/token"
-      interval: "60s"
-      timeout: "10s"
-  
-  headscale:
-    - name: "Headscale Health"
-      url: "${HEADSCALE_URL}/health"
-      interval: "10s"
-      timeout: "3s"
-      
-    - name: "Headscale OIDC Endpoint"
-      url: "${HEADSCALE_URL}/oidc/callback"
-      interval: "60s"
-      timeout: "5s"
-  
-  headplane:
-    - name: "Headplane UI"
-      url: "${HEADPLANE_URL}/admin"
-      interval: "30s"
-      timeout: "5s"
-      
-    - name: "Headplane OIDC Callback"
-      url: "${HEADPLANE_URL}/admin/oidc/callback"
-      interval: "60s"
-      timeout: "5s"
-
-# Audit Trail Configuration
-audit_trail:
-  # Events to log for compliance
-  critical_events:
-    - "Owner role assignments"
-    - "Role mapping configuration changes"
-    - "OIDC provider configuration updates"
-    - "Database schema migrations"
-    - "Manual role overrides"
-  
-  # Log format for audit events
-  log_format:
-    timestamp: "ISO8601"
-    user_id: "OIDC subject"
-    action: "Role assignment/change"
-    old_value: "Previous role"
-    new_value: "New role"
-    source: "OIDC/Manual"
-    ip_address: "Client IP"
-    user_agent: "Browser/Client info"
-
-# Performance Monitoring
-performance_monitoring:
-  # Database performance
-  database_metrics:
-    - "Query execution time for user lookups"
-    - "Groups JSON parsing performance"
-    - "Database connection pool usage"
-    - "Migration execution time"
-  
-  # OIDC performance
-  oidc_metrics:
-    - "Token exchange response time"
-    - "UserInfo endpoint response time"
-    - "Groups claim extraction time"
-    - "Role mapping calculation time"
-
-# Incident Response Runbook
-incident_response:
-  scenarios:
-    - name: "OIDC Provider Outage"
-      steps:
-        1. "Check OIDC provider status page"
-        2. "Verify network connectivity"
-        3. "Enable fallback authentication if available"
-        4. "Communicate to users about temporary limitations"
-        5. "Monitor provider restoration"
-    
-    - name: "Mass Role Assignment Failures"
-      steps:
-        1. "Check OIDC provider group claim configuration"
-        2. "Verify role mapping configuration"
-        3. "Check for recent configuration changes"
-        4. "Test with known working user account"
-        5. "Consider temporary manual role assignments"
-    
-    - name: "Unexpected Owner Role Assignments"
-      steps:
-        1. "Immediately review audit logs"
-        2. "Verify OIDC group membership in provider"
-        3. "Check for compromised accounts"
-        4. "Review role mapping configuration"
-        5. "Consider temporary role restrictions"
-
-# Backup and Recovery Monitoring
-backup_monitoring:
-  # Monitor backup processes
-  backup_checks:
-    - name: "Headscale Database Backup"
-      frequency: "daily"
-      retention: "30 days"
-      verification: "restore test monthly"
-      
-    - name: "Headplane Database Backup"
-      frequency: "daily"
-      retention: "30 days"
-      verification: "restore test monthly"
-      
-    - name: "Configuration Backup"
-      frequency: "on change"
-      retention: "90 days"
-      verification: "syntax check"
-
-# Compliance Reporting
-compliance_reporting:
-  # Generate reports for auditors
-  reports:
-    - name: "Monthly Role Assignment Report"
-      frequency: "monthly"
-      includes:
-        - "New role assignments"
-        - "Role changes"
-        - "Group membership changes"
-        - "Failed authentication attempts"
-    
-    - name: "Quarterly Access Review"
-      frequency: "quarterly"
-      includes:
-        - "All users and their assigned roles"
-        - "Group to role mapping effectiveness"
-        - "Orphaned accounts"
-        - "Privilege escalation events"