tstun,wgengine: add new datapath hooks for intercepting Connectors 2025

app connector packets

We introduce the Conn25PacketHooks interface to be used as a nil-able
field in userspaceEngine. The engine then plumbs through the functions
to the corresponding tstun.Wrapper intercepts.

The new intercepts run pre-filter when egressing toward WireGuard,
and post-filter when ingressing from WireGuard. This is preserve the
design invariant that the filter recognizes the traffic as interesting
app connector traffic.

This commit does not plumb through implementation of the interface, so
should be a functional no-op.

Fixes tailscale/corp#35985

Signed-off-by: Michael Ben-Ami <mzb@tailscale.com>

net/tstun/wrap.go

@@ -171,6 +171,9 @@ type Wrapper struct {
 	// PreFilterPacketInboundFromWireGuard is the inbound filter function that runs before the main filter
 	// and therefore sees the packets that may be later dropped by it.
 	PreFilterPacketInboundFromWireGuard FilterFunc
+	// PostFilterPacketInboundFromWireGuardAppConnector runs after the filter, but before PostFilterPacketInboundFromWireGuard.
+	// Non-app connector traffic is passed along. Invalid app connector traffic is dropped.
+	PostFilterPacketInboundFromWireGuardAppConnector FilterFunc
 	// PostFilterPacketInboundFromWireGuard is the inbound filter function that runs after the main filter.
 	PostFilterPacketInboundFromWireGuard GROFilterFunc
 	// PreFilterPacketOutboundToWireGuardNetstackIntercept is a filter function that runs before the main filter
@@ -183,6 +186,10 @@ type Wrapper struct {
 	// packets which it handles internally. If both this and PreFilterFromTunToNetstack
 	// filter functions are non-nil, this filter runs second.
 	PreFilterPacketOutboundToWireGuardEngineIntercept FilterFunc
+	// PreFilterPacketOutboundToWireGuardAppConnectorIntercept runs after PreFilterPacketOutboundToWireGuardEngineIntercept
+	// for app connector specific traffic. Non-app connector traffic is passed along. Invalid app connector traffic is
+	// dropped.
+	PreFilterPacketOutboundToWireGuardAppConnectorIntercept FilterFunc
 	// PostFilterPacketOutboundToWireGuard is the outbound filter function that runs after the main filter.
 	PostFilterPacketOutboundToWireGuard FilterFunc
 
@@ -872,6 +879,12 @@ func (t *Wrapper) filterPacketOutboundToWireGuard(p *packet.Parsed, pc *peerConf
 			return res, gro
 		}
 	}
+	if t.PreFilterPacketOutboundToWireGuardAppConnectorIntercept != nil {
+		if res := t.PreFilterPacketOutboundToWireGuardAppConnectorIntercept(p, t); res.IsDrop() {
+			// Handled by userspaceEngine's configured hook for Connectors 2025 app connectors.
+			return res, gro
+		}
+	}
 
 	// If the outbound packet is to a jailed peer, use our jailed peer
 	// packet filter.
@@ -1234,6 +1247,13 @@ func (t *Wrapper) filterPacketInboundFromWireGuard(p *packet.Parsed, captHook pa
 		return filter.Drop, gro
 	}
 
+	if t.PostFilterPacketInboundFromWireGuardAppConnector != nil {
+		if res := t.PostFilterPacketInboundFromWireGuardAppConnector(p, t); res.IsDrop() {
+			// Handled by userspaceEngine's configured hook for Connectors 2025 app connectors.
+			return res, gro
+		}
+	}
+
 	if t.PostFilterPacketInboundFromWireGuard != nil {
 		var res filter.Response
 		res, gro = t.PostFilterPacketInboundFromWireGuard(p, t, gro)

wgengine/userspace.go

@@ -143,8 +143,9 @@ type userspaceEngine struct {
 	trimmedNodes        map[key.NodePublic]bool   // set of node keys of peers currently excluded from wireguard config
 	sentActivityAt      map[netip.Addr]*mono.Time // value is accessed atomically
 	destIPActivityFuncs map[netip.Addr]func()
-	lastStatusPollTime  mono.Time    // last time we polled the engine status
-	reconfigureVPN      func() error // or nil
+	lastStatusPollTime  mono.Time         // last time we polled the engine status
+	reconfigureVPN      func() error      // or nil
+	conn25PacketHooks   Conn25PacketHooks // or nil
 
 	mu             sync.Mutex         // guards following; see lock order comment below
 	netMap         *netmap.NetworkMap // or nil
@@ -175,6 +176,19 @@ type BIRDClient interface {
 	Close() error
 }
 
+// Conn25PacketHooks are hooks for Connectors 2025 app connectors.
+// They are meant to be wired into to corresponding hooks in the
+// [tstun.Wrapper]. They may modify the packet (e.g., NAT), or drop
+// invalid app connector traffic.
+type Conn25PacketHooks interface {
+	// HandlePacketsFromTunDevice sends packets originating from the tun device
+	// for further Connectors 2025 app connectors processing.
+	HandlePacketsFromTunDevice(*packet.Parsed) filter.Response
+	// HandlePacketsFromWireguard sends packets originating from WireGuard
+	// for further Connectors 2025 app connectors processing.
+	HandlePacketsFromWireGuard(*packet.Parsed) filter.Response
+}
+
 // Config is the engine configuration.
 type Config struct {
 	// Tun is the device used by the Engine to exchange packets with
@@ -247,6 +261,10 @@ type Config struct {
 	// TODO(creachadair): As of 2025-03-19 this is optional, but is intended to
 	// become required non-nil.
 	EventBus *eventbus.Bus
+
+	// Conn25PacketHooks, if non-nil, is used to hook packets for Connectors 2025
+	// app connector handling logic.
+	Conn25PacketHooks Conn25PacketHooks
 }
 
 // NewFakeUserspaceEngine returns a new userspace engine for testing.
@@ -348,19 +366,20 @@ func NewUserspaceEngine(logf logger.Logf, conf Config) (_ Engine, reterr error)
 	}
 
 	e := &userspaceEngine{
-		eventBus:       conf.EventBus,
-		timeNow:        mono.Now,
-		logf:           logf,
-		reqCh:          make(chan struct{}, 1),
-		waitCh:         make(chan struct{}),
-		tundev:         tsTUNDev,
-		router:         rtr,
-		dialer:         conf.Dialer,
-		confListenPort: conf.ListenPort,
-		birdClient:     conf.BIRDClient,
-		controlKnobs:   conf.ControlKnobs,
-		reconfigureVPN: conf.ReconfigureVPN,
-		health:         conf.HealthTracker,
+		eventBus:          conf.EventBus,
+		timeNow:           mono.Now,
+		logf:              logf,
+		reqCh:             make(chan struct{}, 1),
+		waitCh:            make(chan struct{}),
+		tundev:            tsTUNDev,
+		router:            rtr,
+		dialer:            conf.Dialer,
+		confListenPort:    conf.ListenPort,
+		birdClient:        conf.BIRDClient,
+		controlKnobs:      conf.ControlKnobs,
+		reconfigureVPN:    conf.ReconfigureVPN,
+		health:            conf.HealthTracker,
+		conn25PacketHooks: conf.Conn25PacketHooks,
 	}
 
 	if e.birdClient != nil {
@@ -434,6 +453,16 @@ func NewUserspaceEngine(logf logger.Logf, conf Config) (_ Engine, reterr error)
 	}
 	e.tundev.PreFilterPacketOutboundToWireGuardEngineIntercept = e.handleLocalPackets
 
+	if e.conn25PacketHooks != nil {
+		e.tundev.PreFilterPacketOutboundToWireGuardAppConnectorIntercept = func(p *packet.Parsed, _ *tstun.Wrapper) filter.Response {
+			return e.conn25PacketHooks.HandlePacketsFromTunDevice(p)
+		}
+
+		e.tundev.PostFilterPacketInboundFromWireGuardAppConnector = func(p *packet.Parsed, _ *tstun.Wrapper) filter.Response {
+			return e.conn25PacketHooks.HandlePacketsFromWireGuard(p)
+		}
+	}
+
 	if buildfeatures.HasDebug && envknob.BoolDefaultTrue("TS_DEBUG_CONNECT_FAILURES") {
 		if e.tundev.PreFilterPacketInboundFromWireGuard != nil {
 			return nil, errors.New("unexpected PreFilterIn already set")