feat: add verify client config for embedded DERP (#2260)

* feat: add verify client config for embedded DERP

* refactor: embedded DERP no longer verify clients via HTTP

- register the `headscale://` protocol in `http.DefaultTransport` to intercept network requests
- update configuration to use a single boolean option `verify_clients`

* refactor: use `http.HandlerFunc` for type definition

* refactor: some renaming and restructuring

* chore: some renaming and fix lint

* test: fix TestDERPVerifyEndpoint

- `tailscale debug derp` use random node private key

* test: add verify clients integration test for embedded DERP server

* fix: apply code review suggestions

* chore: merge upstream changes

* fix: apply code review suggestions

---------

Co-authored-by: Kristoffer Dalby <kristoffer@dalby.cc>

hscontrol/app.go

@@ -226,6 +226,14 @@ func NewHeadscale(cfg *types.Config) (*Headscale, error) {
 			)
 		}
 
+		if cfg.DERP.ServerVerifyClients {
+			t := http.DefaultTransport.(*http.Transport) //nolint:forcetypeassert
+			t.RegisterProtocol(
+				derpServer.DerpVerifyScheme,
+				derpServer.NewDERPVerifyTransport(app.handleVerifyRequest),
+			)
+		}
+
 		embeddedDERPServer, err := derpServer.NewDERPServer(
 			cfg.ServerURL,
 			key.NodePrivate(*derpServerKey),

hscontrol/derp/server/derp_server.go

@@ -2,9 +2,11 @@ package server
 
 import (
 	"bufio"
+	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	"net"
 	"net/http"
 	"net/netip"
@@ -28,7 +30,10 @@ import (
 // server that the DERP HTTP client does not want the HTTP 101 response
 // headers and it will begin writing & reading the DERP protocol immediately
 // following its HTTP request.
-const fastStartHeader = "Derp-Fast-Start"
+const (
+	fastStartHeader  = "Derp-Fast-Start"
+	DerpVerifyScheme = "headscale-derp-verify"
+)
 
 type DERPServer struct {
 	serverURL     string
@@ -45,6 +50,11 @@ func NewDERPServer(
 	log.Trace().Caller().Msg("Creating new embedded DERP server")
 	server := derp.NewServer(derpKey, util.TSLogfWrapper()) // nolint // zerolinter complains
 
+	if cfg.ServerVerifyClients {
+		server.SetVerifyClientURL(DerpVerifyScheme + "://verify")
+		server.SetVerifyClientURLFailOpen(false)
+	}
+
 	return &DERPServer{
 		serverURL:     serverURL,
 		key:           derpKey,
@@ -360,3 +370,29 @@ func serverSTUNListener(ctx context.Context, packetConn *net.UDPConn) {
 		}
 	}
 }
+
+func NewDERPVerifyTransport(handleVerifyRequest func(*http.Request, io.Writer) error) *DERPVerifyTransport {
+	return &DERPVerifyTransport{
+		handleVerifyRequest: handleVerifyRequest,
+	}
+}
+
+type DERPVerifyTransport struct {
+	handleVerifyRequest func(*http.Request, io.Writer) error
+}
+
+func (t *DERPVerifyTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	buf := new(bytes.Buffer)
+	if err := t.handleVerifyRequest(req, buf); err != nil {
+		log.Error().Caller().Err(err).Msg("Failed to handle client verify request: ")
+
+		return nil, err
+	}
+
+	resp := &http.Response{
+		StatusCode: http.StatusOK,
+		Body:       io.NopCloser(buf),
+	}
+
+	return resp, nil
+}

hscontrol/handlers.go

@@ -81,28 +81,33 @@ func parseCabailityVersion(req *http.Request) (tailcfg.CapabilityVersion, error)
 	return tailcfg.CapabilityVersion(clientCapabilityVersion), nil
 }
 
-func (h *Headscale) derpRequestIsAllowed(
+func (h *Headscale) handleVerifyRequest(
 	req *http.Request,
-) (bool, error) {
+	writer io.Writer,
+) error {
 	body, err := io.ReadAll(req.Body)
 	if err != nil {
-		return false, fmt.Errorf("cannot read request body: %w", err)
+		return fmt.Errorf("cannot read request body: %w", err)
 	}
 
 	var derpAdmitClientRequest tailcfg.DERPAdmitClientRequest
 	if err := json.Unmarshal(body, &derpAdmitClientRequest); err != nil {
-		return false, fmt.Errorf("cannot parse derpAdmitClientRequest: %w", err)
+		return fmt.Errorf("cannot parse derpAdmitClientRequest: %w", err)
 	}
 
 	nodes, err := h.db.ListNodes()
 	if err != nil {
-		return false, fmt.Errorf("cannot list nodes: %w", err)
+		return fmt.Errorf("cannot list nodes: %w", err)
 	}
 
-	return nodes.ContainsNodeKey(derpAdmitClientRequest.NodePublic), nil
+	resp := &tailcfg.DERPAdmitClientResponse{
+		Allow: nodes.ContainsNodeKey(derpAdmitClientRequest.NodePublic),
+	}
+	return json.NewEncoder(writer).Encode(resp)
 }
 
-// see https://github.com/tailscale/tailscale/blob/964282d34f06ecc06ce644769c66b0b31d118340/derp/derp_server.go#L1159, Derp use verifyClientsURL to verify whether a client is allowed to connect to the DERP server.
+// VerifyHandler see https://github.com/tailscale/tailscale/blob/964282d34f06ecc06ce644769c66b0b31d118340/derp/derp_server.go#L1159
+// DERP use verifyClientsURL to verify whether a client is allowed to connect to the DERP server.
 func (h *Headscale) VerifyHandler(
 	writer http.ResponseWriter,
 	req *http.Request,
@@ -112,18 +117,12 @@ func (h *Headscale) VerifyHandler(
 		return
 	}
 
-	allow, err := h.derpRequestIsAllowed(req)
+	err := h.handleVerifyRequest(req, writer)
 	if err != nil {
 		httpError(writer, err)
 		return
 	}
-
-	resp := tailcfg.DERPAdmitClientResponse{
-		Allow: allow,
-	}
-
 	writer.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(writer).Encode(resp)
 }
 
 // KeyHandler provides the Headscale pub key

hscontrol/types/config.go

@@ -194,6 +194,7 @@ type DERPConfig struct {
 	ServerRegionCode                   string
 	ServerRegionName                   string
 	ServerPrivateKeyPath               string
+	ServerVerifyClients                bool
 	STUNAddr                           string
 	URLs                               []url.URL
 	Paths                              []string
@@ -458,6 +459,7 @@ func derpConfig() DERPConfig {
 	serverRegionID := viper.GetInt("derp.server.region_id")
 	serverRegionCode := viper.GetString("derp.server.region_code")
 	serverRegionName := viper.GetString("derp.server.region_name")
+	serverVerifyClients := viper.GetBool("derp.server.verify_clients")
 	stunAddr := viper.GetString("derp.server.stun_listen_addr")
 	privateKeyPath := util.AbsolutePathFromConfigPath(
 		viper.GetString("derp.server.private_key_path"),
@@ -502,6 +504,7 @@ func derpConfig() DERPConfig {
 		ServerRegionID:                     serverRegionID,
 		ServerRegionCode:                   serverRegionCode,
 		ServerRegionName:                   serverRegionName,
+		ServerVerifyClients:                serverVerifyClients,
 		ServerPrivateKeyPath:               privateKeyPath,
 		STUNAddr:                           stunAddr,
 		URLs:                               urls,