[management, client, proxy] add expose NetBird-only services over tunnel peers (#6226)

Adds a new "private" service mode for the reverse proxy: services reachable exclusively over the embedded WireGuard tunnel, gated by per-peer group membership instead of operator auth schemes. Wire contract - ProxyMapping.private (field 13): the proxy MUST call ValidateTunnelPeer and fail closed; operator schemes are bypassed. - ProxyCapabilities.private (4) + supports_private_service (5): capability gate. Management never streams private mappings to proxies that don't claim the capability; the broadcast path applies the same filter via filterMappingsForProxy. - ValidateTunnelPeer RPC: resolves an inbound tunnel IP to a peer, checks the peer's groups against service.AccessGroups, and mints a session JWT on success. checkPeerGroupAccess fails closed when a private service has empty AccessGroups. - ValidateSession/ValidateTunnelPeer responses now carry peer_group_ids + peer_group_names so the proxy can authorise policy-aware middlewares without an extra management round-trip. - ProxyInboundListener + SendStatusUpdate.inbound_listener: per-account inbound listener state surfaced to dashboards. - PathTargetOptions.direct_upstream (11): bypass the embedded NetBird client and dial the target via the proxy host's network stack for upstreams reachable without WireGuard. Data model - Service.Private (bool) + Service.AccessGroups ([]string, JSON- serialised). Validate() rejects bearer auth on private services. Copy() deep-copies AccessGroups. pgx getServices loads the columns. - DomainConfig.Private threaded into the proxy auth middleware. Request handler routes private services through forwardWithTunnelPeer and returns 403 on validation failure. - Account-level SynthesizePrivateServiceZones (synthetic DNS) and injectPrivateServicePolicies (synthetic ACL) gate on len(svc.AccessGroups) > 0. Proxy - /netbird proxy --private (embedded mode) flag; Config.Private in proxy/lifecycle.go. - Per-account inbound listener (proxy/inbound.go) binding HTTP/HTTPS on the embedded NetBird client's WireGuard tunnel netstack. - proxy/internal/auth/tunnel_cache: ValidateTunnelPeer response cache with single-flight de-duplication and per-account eviction. - Local peerstore short-circuit: when the inbound IP isn't in the account roster, deny fast without an RPC. - proxy/server.go reports SupportsPrivateService=true and redacts the full ProxyMapping JSON from info logs (auth_token + header-auth hashed values now only at debug level). Identity forwarding - ValidateSessionJWT returns user_id, email, method, groups, group_names. sessionkey.Claims carries Email + Groups + GroupNames so the proxy can stamp identity onto upstream requests without an extra management round-trip on every cookie-bearing request. - CapturedData carries userEmail / userGroups / userGroupNames; the proxy stamps X-NetBird-User and X-NetBird-Groups on r.Out from the authenticated identity (strips client-supplied values first to prevent spoofing). - AccessLog.UserGroups: access-log enrichment captures the user's group memberships at write time so the dashboard can render group context without reverse-resolving stale memberships. OpenAPI/dashboard surface - ReverseProxyService gains private + access_groups; ReverseProxyCluster gains private + supports_private. ReverseProxyTarget target_type enum gains "cluster". ServiceTargetOptions gains direct_upstream. ProxyAccessLog gains user_groups.
2026-07-21 07:51:29 +02:00 · 2026-05-25 17:41:50 +02:00
parent 0358be2313
commit 7aebdd69dd
84 changed files with 7810 additions and 933 deletions
--- a/proxy/internal/proxy/context.go
+++ b/proxy/internal/proxy/context.go
@@ -52,8 +52,15 @@ type CapturedData struct {
 	origin     ResponseOrigin
 	clientIP   netip.Addr
 	userID     string
-	authMethod string
-	metadata   map[string]string
+	userEmail  string
+	userGroups []string
+	// userGroupNames pairs positionally with userGroups; populated from
+	// the JWT's group_names claim or from ValidateSession/Tunnel
+	// responses. Slice may be shorter than userGroups for tokens minted
+	// before names were resolvable.
+	userGroupNames []string
+	authMethod     string
+	metadata       map[string]string
 }

 // NewCapturedData creates a CapturedData with the given request ID.
@@ -138,6 +145,81 @@ func (c *CapturedData) GetUserID() string {
 	return c.userID
 }

+// SetUserEmail records the authenticated user's email address. Used by
+// policy-aware middlewares to stamp identity onto upstream requests
+// (e.g. x-litellm-end-user-id) without a management round-trip.
+func (c *CapturedData) SetUserEmail(email string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.userEmail = email
+}
+
+// GetUserEmail returns the authenticated user's email address. Returns
+// the empty string when the auth path didn't carry an email (e.g.
+// non-OIDC schemes or legacy JWTs minted before the email claim).
+func (c *CapturedData) GetUserEmail() string {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return c.userEmail
+}
+
+// SetUserGroups records the authenticated user's group memberships so
+// downstream policy-aware middlewares can authorise the request without
+// an additional management round-trip. The auth middleware populates this
+// from ValidateSessionResponse / ValidateTunnelPeerResponse and from the
+// session JWT's groups claim on cookie-bearing requests.
+func (c *CapturedData) SetUserGroups(groups []string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if len(groups) == 0 {
+		c.userGroups = nil
+		return
+	}
+	c.userGroups = append(c.userGroups[:0], groups...)
+}
+
+// GetUserGroups returns a copy of the authenticated user's group
+// memberships.
+func (c *CapturedData) GetUserGroups() []string {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	if len(c.userGroups) == 0 {
+		return nil
+	}
+	out := make([]string, len(c.userGroups))
+	copy(out, c.userGroups)
+	return out
+}
+
+// SetUserGroupNames records the human-readable display names for the
+// user's groups, ordered identically to UserGroups (positional
+// pairing). Stamped onto upstream requests as X-NetBird-Groups so
+// downstream services can read names rather than opaque ids.
+func (c *CapturedData) SetUserGroupNames(names []string) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if len(names) == 0 {
+		c.userGroupNames = nil
+		return
+	}
+	c.userGroupNames = append(c.userGroupNames[:0], names...)
+}
+
+// GetUserGroupNames returns a copy of the authenticated user's group
+// display names. Position i pairs with UserGroups[i]. May be shorter
+// than UserGroups for tokens minted before names were resolvable; the
+// consumer should fall back to ids for missing positions.
+func (c *CapturedData) GetUserGroupNames() []string {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	if len(c.userGroupNames) == 0 {
+		return nil
+	}
+	out := make([]string, len(c.userGroupNames))
+	copy(out, c.userGroupNames)
+	return out
+}
+
 // SetAuthMethod sets the authentication method used.
 func (c *CapturedData) SetAuthMethod(method string) {
 	c.mu.Lock()
--- a/proxy/internal/proxy/reverseproxy.go
+++ b/proxy/internal/proxy/reverseproxy.go
@@ -86,6 +86,9 @@ func (p *ReverseProxy) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	if pt.RequestTimeout > 0 {
 		ctx = types.WithDialTimeout(ctx, pt.RequestTimeout)
 	}
+	if pt.DirectUpstream {
+		ctx = roundtrip.WithDirectUpstream(ctx)
+	}

 	rewriteMatchedPath := result.matchedPath
 	if pt.PathRewrite == PathRewritePreserve {
@@ -142,6 +145,8 @@ func (p *ReverseProxy) rewriteFunc(target *url.URL, matchedPath string, passHost
 			r.Out.Header.Set(k, v)
 		}

+		stampNetBirdIdentity(r)
+
 		clientIP := extractHostIP(r.In.RemoteAddr)

 		if isTrustedAddr(clientIP, p.trustedProxies) {
@@ -426,3 +431,70 @@ func opErrorContains(err error, substr string) bool {
 	}
 	return false
 }
+
+const (
+	// headerNetBirdUser carries the authenticated user's display identity
+	// (email when the peer is attached to a user, else peer name) onto
+	// upstream requests. Stripped from inbound requests before stamping
+	// so a client can't spoof identity by setting the header themselves.
+	headerNetBirdUser = "X-NetBird-User"
+	// headerNetBirdGroups carries the user's group display names as a
+	// comma-separated list. Falls back to group IDs at positions where a
+	// name wasn't available at session-mint time. Labels containing a
+	// comma or any non-printable byte are dropped at stamp time so the
+	// list is unambiguously splittable by consumers.
+	headerNetBirdGroups = "X-NetBird-Groups"
+)
+
+// isHeaderValueSafe reports whether v is a valid RFC 7230 field-value:
+// VCHAR (0x21-0x7E), SP (0x20), or HTAB (0x09). Empty values are
+// rejected; the caller decides whether to omit the header entirely.
+func isHeaderValueSafe(v string) bool {
+	if v == "" {
+		return false
+	}
+	for i := 0; i < len(v); i++ {
+		c := v[i]
+		if c == '\t' || (c >= 0x20 && c <= 0x7E) {
+			continue
+		}
+		return false
+	}
+	return true
+}
+
+// stampNetBirdIdentity injects authenticated identity onto outbound
+// requests as X-NetBird-User and X-NetBird-Groups. Always strips any
+// client-sent values first (anti-spoof). Skips when the request didn't
+// carry CapturedData (early-path errors, internal endpoints).
+func stampNetBirdIdentity(r *httputil.ProxyRequest) {
+	r.Out.Header.Del(headerNetBirdUser)
+	r.Out.Header.Del(headerNetBirdGroups)
+
+	cd := CapturedDataFromContext(r.In.Context())
+	if cd == nil {
+		return
+	}
+	if email := cd.GetUserEmail(); isHeaderValueSafe(email) {
+		r.Out.Header.Set(headerNetBirdUser, email)
+	}
+	groupIDs := cd.GetUserGroups()
+	if len(groupIDs) == 0 {
+		return
+	}
+	groupNames := cd.GetUserGroupNames()
+	labels := make([]string, 0, len(groupIDs))
+	for i, id := range groupIDs {
+		label := id
+		if i < len(groupNames) && groupNames[i] != "" {
+			label = groupNames[i]
+		}
+		if !isHeaderValueSafe(label) || strings.ContainsRune(label, ',') {
+			continue
+		}
+		labels = append(labels, label)
+	}
+	if len(labels) > 0 {
+		r.Out.Header.Set(headerNetBirdGroups, strings.Join(labels, ","))
+	}
+}
--- a/proxy/internal/proxy/reverseproxy_test.go
+++ b/proxy/internal/proxy/reverseproxy_test.go
@@ -1067,3 +1067,245 @@ func TestClassifyProxyError(t *testing.T) {
 		})
 	}
 }
+
+func TestStampNetBirdIdentity_NoCapturedData_StripsOnly(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+	pr.In.Header.Set(headerNetBirdUser, "spoofed@evil.io")
+	pr.In.Header.Set(headerNetBirdGroups, "admin")
+	pr.Out.Header = pr.In.Header.Clone()
+
+	rewrite(pr)
+
+	assert.Empty(t, pr.Out.Header.Get(headerNetBirdUser),
+		"client-supplied X-NetBird-User must be stripped when no captured identity is present")
+	assert.Empty(t, pr.Out.Header.Get(headerNetBirdGroups),
+		"client-supplied X-NetBird-Groups must be stripped when no captured identity is present")
+}
+
+func TestStampNetBirdIdentity_StampsFromCapturedData(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+	pr.In.Header.Set(headerNetBirdUser, "spoofed@evil.io")
+	pr.Out.Header = pr.In.Header.Clone()
+
+	cd := NewCapturedData("req-1")
+	cd.SetUserEmail("alice@netbird.io")
+	cd.SetUserGroups([]string{"grp-eng", "grp-ops"})
+	cd.SetUserGroupNames([]string{"engineering", "operations"})
+
+	pr.In = pr.In.WithContext(WithCapturedData(pr.In.Context(), cd))
+
+	rewrite(pr)
+
+	assert.Equal(t, "alice@netbird.io", pr.Out.Header.Get(headerNetBirdUser),
+		"captured email must overwrite any spoofed value")
+	assert.Equal(t, "engineering,operations", pr.Out.Header.Get(headerNetBirdGroups),
+		"group display names must be CSV-joined in positional order")
+}
+
+// TestStampNetBirdIdentity_GroupsOnlyWhenEmailEmpty covers the
+// tunnel-peer-without-user case (machine agents, unattached proxy peers).
+// The proxy must still stamp the peer's groups so downstream services can
+// authorise, but X-NetBird-User stays unset — only its inbound stripping
+// must happen.
+func TestStampNetBirdIdentity_GroupsOnlyWhenEmailEmpty(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+	pr.In.Header.Set(headerNetBirdUser, "spoofed@evil.io")
+	pr.Out.Header = pr.In.Header.Clone()
+
+	cd := NewCapturedData("req-1")
+	cd.SetUserGroups([]string{"grp-machines"})
+	cd.SetUserGroupNames([]string{"machines"})
+
+	pr.In = pr.In.WithContext(WithCapturedData(pr.In.Context(), cd))
+
+	rewrite(pr)
+
+	assert.Empty(t, pr.Out.Header.Get(headerNetBirdUser),
+		"X-NetBird-User must remain unset when CapturedData carries no email")
+	assert.Equal(t, "machines", pr.Out.Header.Get(headerNetBirdGroups),
+		"groups must still be stamped for peers without a user identity")
+}
+
+// TestStampNetBirdIdentity_EmailOnlyWhenGroupsEmpty covers the symmetric
+// case: identity-resolved user without resolved group memberships.
+func TestStampNetBirdIdentity_EmailOnlyWhenGroupsEmpty(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+	pr.In.Header.Set(headerNetBirdGroups, "spoofed-admin")
+	pr.Out.Header = pr.In.Header.Clone()
+
+	cd := NewCapturedData("req-1")
+	cd.SetUserEmail("carol@netbird.io")
+
+	pr.In = pr.In.WithContext(WithCapturedData(pr.In.Context(), cd))
+
+	rewrite(pr)
+
+	assert.Equal(t, "carol@netbird.io", pr.Out.Header.Get(headerNetBirdUser),
+		"email must be stamped even when no groups are captured")
+	assert.Empty(t, pr.Out.Header.Get(headerNetBirdGroups),
+		"X-NetBird-Groups must remain unset when CapturedData carries no groups")
+}
+
+func TestStampNetBirdIdentity_FallsBackToGroupIDsWhenNameMissing(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+
+	cd := NewCapturedData("req-1")
+	cd.SetUserEmail("bob@netbird.io")
+	cd.SetUserGroups([]string{"grp-a", "grp-b", "grp-c"})
+	// "grp-b" gets an explicit empty-string display name (not just a
+	// shorter slice). Both gap shapes must fall back to the id.
+	cd.SetUserGroupNames([]string{"alpha", "", ""})
+
+	pr.In = pr.In.WithContext(WithCapturedData(pr.In.Context(), cd))
+
+	rewrite(pr)
+
+	assert.Equal(t, "alpha,grp-b,grp-c", pr.Out.Header.Get(headerNetBirdGroups),
+		"empty-string and out-of-range name slots must both fall back to the group id")
+}
+
+// TestStampNetBirdIdentity_DropsLabelsWithComma covers the
+// comma-separator constraint: a group display name that itself contains
+// a comma is dropped from the header (rather than corrupting the list),
+// and the remaining labels are stamped.
+func TestStampNetBirdIdentity_DropsLabelsWithComma(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+
+	cd := NewCapturedData("req-1")
+	cd.SetUserEmail("alice@netbird.io")
+	cd.SetUserGroups([]string{"grp-a", "grp-b", "grp-c"})
+	cd.SetUserGroupNames([]string{"engineering", "EU, EMEA", "operations"})
+
+	pr.In = pr.In.WithContext(WithCapturedData(pr.In.Context(), cd))
+
+	rewrite(pr)
+
+	assert.Equal(t, "engineering,operations", pr.Out.Header.Get(headerNetBirdGroups),
+		"group label with embedded comma must be dropped, remaining labels stamped")
+}
+
+// TestStampNetBirdIdentity_RejectsControlCharsInEmail covers the
+// header-injection defence: an email value containing CR/LF/control
+// chars is omitted entirely (not partially stamped) so the upstream
+// request stays well-formed and no header injection is possible.
+func TestStampNetBirdIdentity_RejectsControlCharsInEmail(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+	pr.In.Header.Set(headerNetBirdUser, "spoofed@evil.io")
+	pr.Out.Header = pr.In.Header.Clone()
+
+	cd := NewCapturedData("req-1")
+	cd.SetUserEmail("alice@netbird.io\r\nX-Admin: yes")
+	cd.SetUserGroups([]string{"grp-a"})
+	cd.SetUserGroupNames([]string{"engineering"})
+
+	pr.In = pr.In.WithContext(WithCapturedData(pr.In.Context(), cd))
+
+	rewrite(pr)
+
+	assert.Empty(t, pr.Out.Header.Get(headerNetBirdUser),
+		"email with CR/LF must be dropped, not partially stamped")
+	assert.Equal(t, "engineering", pr.Out.Header.Get(headerNetBirdGroups),
+		"groups remain stampable even when email is invalid")
+}
+
+// TestStampNetBirdIdentity_RejectsControlCharsInGroup covers the
+// per-label defence: a group name with a control char is silently
+// dropped, the rest are stamped.
+func TestStampNetBirdIdentity_RejectsControlCharsInGroup(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+
+	cd := NewCapturedData("req-1")
+	cd.SetUserEmail("alice@netbird.io")
+	cd.SetUserGroups([]string{"grp-a", "grp-b"})
+	cd.SetUserGroupNames([]string{"engineering\r\nsneaky", "operations"})
+
+	pr.In = pr.In.WithContext(WithCapturedData(pr.In.Context(), cd))
+
+	rewrite(pr)
+
+	assert.Equal(t, "operations", pr.Out.Header.Get(headerNetBirdGroups),
+		"group label with control char must be dropped, valid ones kept")
+}
+
+// TestStampNetBirdIdentity_OmitsGroupsHeaderWhenAllInvalid covers the
+// edge case where every group label is rejected: the header must not be
+// set at all (rather than set to an empty string).
+func TestStampNetBirdIdentity_OmitsGroupsHeaderWhenAllInvalid(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+	pr.In.Header.Set(headerNetBirdGroups, "spoofed-admin")
+	pr.Out.Header = pr.In.Header.Clone()
+
+	cd := NewCapturedData("req-1")
+	cd.SetUserEmail("alice@netbird.io")
+	cd.SetUserGroups([]string{"grp-a", "grp-b"})
+	cd.SetUserGroupNames([]string{"with,comma", "with\nbreak"})
+
+	pr.In = pr.In.WithContext(WithCapturedData(pr.In.Context(), cd))
+
+	rewrite(pr)
+
+	_, present := pr.Out.Header[http.CanonicalHeaderKey(headerNetBirdGroups)]
+	assert.False(t, present,
+		"X-NetBird-Groups must not be set when every group label is rejected")
+}
+
+// TestStampNetBirdIdentity_CapturedDataPresentButEmpty covers requests
+// that carry CapturedData with no identity fields populated (e.g. the
+// auth middleware ran but the request didn't authenticate). Both
+// headers must be cleared and neither stamped.
+func TestStampNetBirdIdentity_CapturedDataPresentButEmpty(t *testing.T) {
+	target, _ := url.Parse("http://backend.internal:8080")
+	p := &ReverseProxy{forwardedProto: "auto"}
+	rewrite := p.rewriteFunc(target, "", false, PathRewriteDefault, nil, nil)
+
+	pr := newProxyRequest(t, "http://example.com/", "203.0.113.50:9999")
+	pr.In.Header.Set(headerNetBirdUser, "spoofed@evil.io")
+	pr.In.Header.Set(headerNetBirdGroups, "spoofed-admin")
+	pr.Out.Header = pr.In.Header.Clone()
+
+	cd := NewCapturedData("req-1")
+	pr.In = pr.In.WithContext(WithCapturedData(pr.In.Context(), cd))
+
+	rewrite(pr)
+
+	assert.Empty(t, pr.Out.Header.Get(headerNetBirdUser),
+		"X-NetBird-User must be stripped when CapturedData has no email")
+	assert.Empty(t, pr.Out.Header.Get(headerNetBirdGroups),
+		"X-NetBird-Groups must be stripped when CapturedData has no groups")
+}
--- a/proxy/internal/proxy/servicemapping.go
+++ b/proxy/internal/proxy/servicemapping.go
@@ -28,6 +28,10 @@ type PathTarget struct {
 	RequestTimeout time.Duration
 	PathRewrite    PathRewriteMode
 	CustomHeaders  map[string]string
+	// DirectUpstream selects the stdlib HTTP transport (host network stack)
+	// over the embedded NetBird WireGuard client when forwarding requests
+	// to this target. Default false → embedded client (existing behaviour).
+	DirectUpstream bool
 }

 // Mapping describes how a domain is routed by the HTTP reverse proxy.