[proxy] Mirror LLM denials in the caller's provider error shape

A budget stop, a blocked model or an unroutable model all rendered as the
NetBird deny envelope alone. LLM clients only parse their own provider's
error shape, so the reason never reached the user: Claude Code showed an
unexplained API error where it could have shown the policy message.

Carry the resolved surface on the deny reason and add the vendor's error
object next to the existing fields. The body stays a superset of what it
was, so anything reading code, message, details or middleware is
unaffected. Status codes are unchanged here: mapping window caps to 429
needs the window reset plumbed through the limits response before a
correct Retry-After can be sent.

proxy/internal/middleware/builtin/llm_guardrail/middleware.go

@@ -84,8 +84,9 @@ func (m *Middleware) MutationsSupported() bool { return false }
 func (m *Middleware) Invoke(_ context.Context, in *middleware.Input) (*middleware.Output, error) {
 	model, modelPresent := lookupMetadata(in.Metadata, middleware.KeyLLMModel)
 	providerID, _ := lookupMetadata(in.Metadata, middleware.KeyLLMResolvedProviderID)
+	surface, _ := lookupMetadata(in.Metadata, middleware.KeyLLMProvider)
 
-	if denial := m.evaluateAllowlist(providerID, model, modelPresent); denial != nil {
+	if denial := m.evaluateAllowlist(providerID, surface, model, modelPresent); denial != nil {
 		return denial, nil
 	}
 
@@ -114,7 +115,7 @@ func (m *Middleware) Close() error { return nil }
 // evaluateAllowlist denies when the resolved provider's allowlist rejects the
 // model; nil means proceed. Scoped to the provider llm_router resolved, so an
 // unrestricted provider (absent from config) is never caught by another's list.
-func (m *Middleware) evaluateAllowlist(providerID, model string, modelPresent bool) *middleware.Output {
+func (m *Middleware) evaluateAllowlist(providerID, surface, model string, modelPresent bool) *middleware.Output {
 	if len(m.cfg.ProviderAllowlists) == 0 {
 		return nil
 	}
@@ -122,7 +123,7 @@ func (m *Middleware) evaluateAllowlist(providerID, model string, modelPresent bo
 	// if this request targets a restricted provider — fail closed. llm_router
 	// normally stamps the provider first, so this is a defensive guard.
 	if providerID == "" {
-		return denyModel("", denyCodeModelUnknown, denyMessageModelUnknown, denyReasonModelUnknown)
+		return denyModel(surface, "", denyCodeModelUnknown, denyMessageModelUnknown, denyReasonModelUnknown)
 	}
 	allowlist, restricted := m.cfg.ProviderAllowlists[providerID]
 	if !restricted {
@@ -134,17 +135,17 @@ func (m *Middleware) evaluateAllowlist(providerID, model string, modelPresent bo
 	// model the parser couldn't extract (absent/empty) is denied. This enforces
 	// the allowlist for path-routed providers (Bedrock, Vertex) with no body model.
 	if !modelPresent || normaliseModel(model) == "" {
-		return denyModel("", denyCodeModelUnknown, denyMessageModelUnknown, denyReasonModelUnknown)
+		return denyModel(surface, "", denyCodeModelUnknown, denyMessageModelUnknown, denyReasonModelUnknown)
 	}
 	if modelInAllowlist(allowlist, model) {
 		return nil
 	}
-	return denyModel(model, denyCodeModel, denyMessageModel, denyReasonModel)
+	return denyModel(surface, model, denyCodeModel, denyMessageModel, denyReasonModel)
 }
 
 // denyModel builds a 403 deny Output for a model-allowlist rejection. model is
 // included in the details only when non-empty.
-func denyModel(model, code, message, reason string) *middleware.Output {
+func denyModel(surface, model, code, message, reason string) *middleware.Output {
 	details := map[string]string{}
 	if model != "" {
 		details["model"] = model
@@ -156,6 +157,7 @@ func denyModel(model, code, message, reason string) *middleware.Output {
 			Code:    code,
 			Message: message,
 			Details: details,
+			Surface: surface,
 		},
 		Metadata: []middleware.KV{
 			{Key: middleware.KeyLLMPolicyDecision, Value: "deny"},

proxy/internal/middleware/builtin/llm_limit_check/middleware.go

@@ -126,7 +126,7 @@ func (m *Middleware) Invoke(ctx context.Context, in *middleware.Input) (*middlew
 	}
 
 	if resp.GetDecision() == "deny" {
-		return denyFromManagement(resp), nil
+		return denyFromManagement(resp, lookupKV(in.Metadata, middleware.KeyLLMProvider)), nil
 	}
 	return allowFromManagement(resp), nil
 }
@@ -170,7 +170,7 @@ func allowFromManagement(resp *proto.CheckLLMPolicyLimitsResponse) *middleware.O
 // envelope. The deny code surfaces verbatim through the framework's
 // fixed JSON template; arbitrary middleware bytes can't reach the
 // wire.
-func denyFromManagement(resp *proto.CheckLLMPolicyLimitsResponse) *middleware.Output {
+func denyFromManagement(resp *proto.CheckLLMPolicyLimitsResponse, surface string) *middleware.Output {
 	code := resp.GetDenyCode()
 	if code == "" {
 		code = "llm_policy.cap_exceeded"
@@ -185,6 +185,7 @@ func denyFromManagement(resp *proto.CheckLLMPolicyLimitsResponse) *middleware.Ou
 		DenyReason: &middleware.DenyReason{
 			Code:    code,
 			Message: denyMessageForCode(code),
+			Surface: surface,
 		},
 		Metadata: []middleware.KV{
 			{Key: middleware.KeyLLMPolicyDecision, Value: "deny"},

proxy/internal/middleware/builtin/llm_router/middleware.go

@@ -143,23 +143,26 @@ func (m *Middleware) Invoke(_ context.Context, in *middleware.Input) (*middlewar
 	// the model lookup so a model the parser extracted from the path can't be
 	// claimed by a same-vendor direct provider (e.g. claude-* on api.anthropic.com).
 	reqPath := requestPath(in.URL)
+	// The caller's API dialect, used to mirror a denial in the vendor's own
+	// error shape so the client can explain it to the user.
+	surface, _ := lookupMetadata(in.Metadata, middleware.KeyLLMProvider)
 	if isVertexPath(reqPath) {
 		model, _ := lookupMetadata(in.Metadata, middleware.KeyLLMModel)
 		// The request parser emits no llm.provider for a Vertex publisher it
 		// can't parse (e.g. google/gemini). Forwarding such a request would
 		// bypass token/budget metering, so deny it rather than serve it
 		// unmetered.
-		if vendor, _ := lookupMetadata(in.Metadata, middleware.KeyLLMProvider); vendor == "" {
-			return denyUnmeterable(), nil
+		if surface == "" {
+			return denyUnmeterable(surface), nil
 		}
 		route, outcome := m.matchVertex(reqPath, model, in.UserGroups)
 		switch outcome {
 		case matchOutcomeFound:
-			return m.allowWithRoute(route, in.UserGroups), nil
+			return m.allowWithRoute(route, surface, in.UserGroups), nil
 		case matchOutcomeUnauthorised:
-			return denyNoAuthorisedRoute(model), nil
+			return denyNoAuthorisedRoute(surface, model), nil
 		default:
-			return denyUnknownModel(model), nil
+			return denyUnknownModel(surface, model), nil
 		}
 	}
 
@@ -173,15 +176,15 @@ func (m *Middleware) Invoke(_ context.Context, in *middleware.Input) (*middlewar
 		route, outcome := m.matchBedrock(native, model, in.UserGroups)
 		switch outcome {
 		case matchOutcomeFound:
-			out := m.allowWithRoute(route, in.UserGroups)
+			out := m.allowWithRoute(route, surface, in.UserGroups)
 			if hadPrefix && out.Mutations != nil && out.Mutations.RewriteUpstream != nil {
 				out.Mutations.RewriteUpstream.StripPathPrefix = bedrockNamespacePrefix
 			}
 			return out, nil
 		case matchOutcomeUnauthorised:
-			return denyNoAuthorisedRoute(model), nil
+			return denyNoAuthorisedRoute(surface, model), nil
 		default:
-			return denyUnknownModel(model), nil
+			return denyUnknownModel(surface, model), nil
 		}
 	}
 
@@ -194,28 +197,27 @@ func (m *Middleware) Invoke(_ context.Context, in *middleware.Input) (*middlewar
 		route, outcome := m.matchModelless(requestPath(in.URL), in.UserGroups)
 		switch outcome {
 		case matchOutcomeFound:
-			out := m.allowWithRoute(route, in.UserGroups)
+			out := m.allowWithRoute(route, surface, in.UserGroups)
 			out.Metadata = append(out.Metadata, middleware.KV{Key: middleware.KeyLLMNonInference, Value: "true"})
 			return out, nil
 		case matchOutcomeUnauthorised:
 			// A recognised model-less endpoint exists but no provider
 			// authorises the caller — deny as an authorisation failure
 			// rather than masking it as a missing model.
-			return denyNoAuthorisedRoute(model), nil
+			return denyNoAuthorisedRoute(surface, model), nil
 		default:
-			return denyMissingModel(), nil
+			return denyMissingModel(surface), nil
 		}
 	}
 
-	vendor, _ := lookupMetadata(in.Metadata, middleware.KeyLLMProvider)
-	route, outcome := m.matchRoute(model, vendor, requestPath(in.URL), in.UserGroups)
+	route, outcome := m.matchRoute(model, surface, requestPath(in.URL), in.UserGroups)
 	switch outcome {
 	case matchOutcomeFound:
-		return m.allowWithRoute(route, in.UserGroups), nil
+		return m.allowWithRoute(route, surface, in.UserGroups), nil
 	case matchOutcomeUnauthorised:
-		return denyNoAuthorisedRoute(model), nil
+		return denyNoAuthorisedRoute(surface, model), nil
 	default:
-		return denyUnknownModel(model), nil
+		return denyUnknownModel(surface, model), nil
 	}
 }
 
@@ -621,7 +623,7 @@ func requestPath(raw string) string {
 // provider id so identity-stamping middlewares (llm_identity_inject)
 // tag the request with ONLY the groups that authorised this specific
 // route — not every group the peer happens to be in.
-func (m *Middleware) allowWithRoute(route ProviderRoute, userGroups []string) *middleware.Output {
+func (m *Middleware) allowWithRoute(route ProviderRoute, surface string, userGroups []string) *middleware.Output {
 	rewrite := &middleware.UpstreamRewrite{
 		Scheme: route.UpstreamScheme,
 		Host:   route.UpstreamHost,
@@ -643,7 +645,7 @@ func (m *Middleware) allowWithRoute(route ProviderRoute, userGroups []string) *m
 		// request time (cached + auto-refreshed) instead of a static value.
 		bearer, err := m.gcpBearer(route.GCPServiceAccountKeyB64)
 		if err != nil {
-			return denyUpstreamAuth()
+			return denyUpstreamAuth(surface)
 		}
 		authValue = bearer
 	}
@@ -713,11 +715,12 @@ func (m *Middleware) gcpTokenSource(saKeyB64 string) (oauth2.TokenSource, error)
 // denyUpstreamAuth is returned when the router cannot obtain the upstream
 // credential (e.g. a malformed service-account key or an unreachable token
 // endpoint). It surfaces as a 502 — an upstream problem, not a policy denial.
-func denyUpstreamAuth() *middleware.Output {
+func denyUpstreamAuth(surface string) *middleware.Output {
 	return &middleware.Output{
 		Decision:   middleware.DecisionDeny,
 		DenyStatus: 502,
 		DenyReason: &middleware.DenyReason{
+			Surface: surface,
 			Code:    denyCodeUpstreamAuth,
 			Message: "could not obtain upstream credential",
 		},
@@ -731,11 +734,12 @@ func denyUpstreamAuth() *middleware.Output {
 // denyUnmeterable returns the deny envelope for a path-routed request whose
 // publisher has no parser surface, so its usage can't be metered. Serving it
 // would bypass token/budget caps, so it is rejected with a 403.
-func denyUnmeterable() *middleware.Output {
+func denyUnmeterable(surface string) *middleware.Output {
 	return &middleware.Output{
 		Decision:   middleware.DecisionDeny,
 		DenyStatus: 403,
 		DenyReason: &middleware.DenyReason{
+			Surface: surface,
 			Code:    denyCodeUnmeterable,
 			Message: "request publisher is not supported for metering",
 		},
@@ -748,11 +752,12 @@ func denyUnmeterable() *middleware.Output {
 
 // denyMissingModel returns the deny envelope for a request whose
 // envelope has no llm.model metadata.
-func denyMissingModel() *middleware.Output {
+func denyMissingModel(surface string) *middleware.Output {
 	return &middleware.Output{
 		Decision:   middleware.DecisionDeny,
 		DenyStatus: 403,
 		DenyReason: &middleware.DenyReason{
+			Surface: surface,
 			Code:    denyCodeNotRoutable,
 			Message: "missing llm.model on request envelope",
 		},
@@ -765,11 +770,12 @@ func denyMissingModel() *middleware.Output {
 
 // denyUnknownModel returns the deny envelope for a model that no
 // configured provider claims.
-func denyUnknownModel(model string) *middleware.Output {
+func denyUnknownModel(surface, model string) *middleware.Output {
 	return &middleware.Output{
 		Decision:   middleware.DecisionDeny,
 		DenyStatus: 403,
 		DenyReason: &middleware.DenyReason{
+			Surface: surface,
 			Code:    denyCodeNotRoutable,
 			Message: fmt.Sprintf("no provider configured for model %s", model),
 			Details: map[string]string{"model": model},
@@ -784,11 +790,12 @@ func denyUnknownModel(model string) *middleware.Output {
 // denyNoAuthorisedRoute returns the deny envelope for a model that one
 // or more providers claim, but where no policy authorises the caller's
 // groups for any of those providers.
-func denyNoAuthorisedRoute(model string) *middleware.Output {
+func denyNoAuthorisedRoute(surface, model string) *middleware.Output {
 	return &middleware.Output{
 		Decision:   middleware.DecisionDeny,
 		DenyStatus: 403,
 		DenyReason: &middleware.DenyReason{
+			Surface: surface,
 			Code:    denyCodeNoAuthorisedRoute,
 			Message: fmt.Sprintf("no policy authorises model %s for the caller's groups", model),
 			Details: map[string]string{"model": model},