From bb4c66398bdc2315629232d10de4ea81f6dd1e34 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:19:28 +0100 Subject: [PATCH 01/14] feat(registry): declare per-user upstream headers on MCP targets An MCP target can now declare upstream headers whose value belongs to each caller (user_headers), next to the shared headers map. A declaration names the header, whether it is required or secret, and an optional scheme. Validation rejects reserved and gateway-owned names, duplicates, a header that is also shared, and the header the auth mode already writes. Values are bounded and refuse CR, LF, NUL and non-ASCII. Values are keyed in the vault by registry instance and header, so PRE and PRO keep separate values. Refs ENG-3243 --- pkg/domain/registry/mcp_target.go | 7 + pkg/domain/registry/mcp_user_headers.go | 210 +++++++++++++++++++ pkg/domain/registry/mcp_user_headers_test.go | 153 ++++++++++++++ 3 files changed, 370 insertions(+) create mode 100644 pkg/domain/registry/mcp_user_headers.go create mode 100644 pkg/domain/registry/mcp_user_headers_test.go diff --git a/pkg/domain/registry/mcp_target.go b/pkg/domain/registry/mcp_target.go index 99721bce6..19d962c0b 100644 --- a/pkg/domain/registry/mcp_target.go +++ b/pkg/domain/registry/mcp_target.go @@ -183,6 +183,10 @@ type MCPTarget struct { // without re-reading the catalog. Empty for servers whose URL is fully // determined (the common case). See ResolveURL. URLVariables []MCPURLVariable `json:"url_variables,omitempty"` + // UserHeaders declares the upstream headers whose value is each caller's + // own, read from the vault per request (see MCPUserHeader). Headers stays + // the shared map: one admin-set value for every caller. + UserHeaders []MCPUserHeader `json:"user_headers,omitempty"` // InstanceConfig carries one instance's resolved plain URL-variable values when // the Store scoper exposes several instances of the same catalog code for a // principal (e.g. two Snowflake schemas). It is a request-scoped overlay set on @@ -393,6 +397,9 @@ func (t *MCPTarget) Validate() error { return fmt.Errorf("%w: header %q looks masked; send the full value or the masked value unchanged", ErrInvalidMCPTarget, name) } + if err := t.validateUserHeaders(); err != nil { + return err + } if t.Auth != nil { if err := t.Auth.Validate(); err != nil { return err diff --git a/pkg/domain/registry/mcp_user_headers.go b/pkg/domain/registry/mcp_user_headers.go new file mode 100644 index 000000000..689878796 --- /dev/null +++ b/pkg/domain/registry/mcp_user_headers.go @@ -0,0 +1,210 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package registry + +import ( + "fmt" + "net/http" + "regexp" + "strings" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" +) + +// MCPUserHeader declares one upstream header whose value belongs to each +// caller rather than to the registry. The admin declares the header; every +// person enrolls their own value once, through the connect link, and the +// gateway sends the calling person's value on each request to the upstream. +// Values live in the vault under the registry instance and the caller's +// principal (UserHeaderVaultProvider), never on the registry row. +type MCPUserHeader struct { + // Name is the HTTP header sent upstream, e.g. X-API-Key. + Name string `json:"name"` + // Description is the help shown when a person enters their value. + Description string `json:"description,omitempty"` + // Required makes a call fail with a connect link until the caller has a + // value. An optional header is simply left out when the caller has none. + Required bool `json:"required,omitempty"` + // Secret hides the value once entered: the connect page shows it masked + // and it is never echoed back. A non-secret value (an account id, a + // tenant) is shown back to its owner so it can be checked and edited. + // Both are stored encrypted in the vault. + Secret bool `json:"secret,omitempty"` + // Scheme is written before the value with one space, e.g. "Bearer" sends + // "Bearer ". Empty sends the value as entered. + Scheme string `json:"scheme,omitempty"` +} + +// MaxUserHeaderValueLen bounds one per-user header value. An API key or a +// token fits comfortably; anything longer is not a credential a person typed. +const MaxUserHeaderValueLen = 4096 + +// maxUserHeaders bounds how many per-user headers one registry declares. +const maxUserHeaders = 16 + +// userHeaderVaultPrefix namespaces per-user header values in the vault, apart +// from forwarded OAuth credentials and secret URL variables. +const userHeaderVaultPrefix = "uhdr:" + +// httpToken is an RFC 9110 token: what a header name and an auth scheme are. +var httpToken = regexp.MustCompile("^[!#$%&'*+.^_`|~0-9A-Za-z-]+$") + +// reservedUpstreamHeaders are names a per-user value may never set: the +// transport owns them, the MCP protocol owns them, or a hop strips them. +var reservedUpstreamHeaders = []string{ + "Host", "Content-Length", "Content-Type", "Content-Encoding", "Transfer-Encoding", + "Connection", "Keep-Alive", "Proxy-Authenticate", "Proxy-Authorization", + "Proxy-Connection", "TE", "Trailer", "Upgrade", "Cookie", "Accept", + "Mcp-Session-Id", "Mcp-Protocol-Version", "Last-Event-ID", +} + +// reservedUpstreamHeaderPrefix is the gateway's own header namespace. +const reservedUpstreamHeaderPrefix = "x-neuraltrust-" + +// UserHeaderVaultProvider is the vault "provider" key a person's value for one +// per-user header of one registry instance is stored under. It is keyed by the +// registry, not by the catalog code, so two instances of the same upstream +// (PRE and PRO) hold separate values while one instance bound to several +// applications reads the same value. The header name is canonicalised so the +// writer and the reader agree whatever case the admin typed. +func UserHeaderVaultProvider(registryID ids.RegistryID, header string) string { + return userHeaderVaultPrefix + registryID.String() + ":" + http.CanonicalHeaderKey(strings.TrimSpace(header)) +} + +// UserHeaderVaultPrefix is the vault provider prefix every per-user header of +// one registry shares, for listing or resetting all of them at once. +func UserHeaderVaultPrefix(registryID ids.RegistryID) string { + return userHeaderVaultPrefix + registryID.String() + ":" +} + +// HasUserHeaders reports whether any upstream header of this target is +// resolved per caller. +func (t *MCPTarget) HasUserHeaders() bool { + return t != nil && len(t.UserHeaders) > 0 +} + +// UserHeader returns the declared per-user header with this name, matched +// case-insensitively as HTTP header names are. +func (t *MCPTarget) UserHeader(name string) (MCPUserHeader, bool) { + if t == nil { + return MCPUserHeader{}, false + } + for _, h := range t.UserHeaders { + if strings.EqualFold(strings.TrimSpace(h.Name), strings.TrimSpace(name)) { + return h, true + } + } + return MCPUserHeader{}, false +} + +// FormatValue is the header value sent upstream for a person's stored value. +func (h MCPUserHeader) FormatValue(value string) string { + if scheme := strings.TrimSpace(h.Scheme); scheme != "" { + return scheme + " " + value + } + return value +} + +// ValidateUserHeaderValue checks a value a person enters for a per-user +// header. It never echoes the value: the error names the header only. +func ValidateUserHeaderValue(h MCPUserHeader, value string) error { + if strings.TrimSpace(value) == "" { + return fmt.Errorf("%w: header %q needs a value", ErrInvalidMCPTarget, h.Name) + } + if len(value) > MaxUserHeaderValueLen { + return fmt.Errorf("%w: header %q value is too long (max %d characters)", ErrInvalidMCPTarget, h.Name, MaxUserHeaderValueLen) + } + for _, r := range value { + // Visible ASCII and space/tab only: CR, LF and NUL would split the + // request, and anything else is not a value an HTTP header carries + // reliably. + if r == '\t' || (r >= 0x20 && r < 0x7f) { + continue + } + return fmt.Errorf("%w: header %q value has characters an HTTP header cannot carry", ErrInvalidMCPTarget, h.Name) + } + return nil +} + +// validateUserHeaders checks the per-user header declarations against each +// other, against the shared headers and against whatever the auth mode sends. +func (t *MCPTarget) validateUserHeaders() error { + if len(t.UserHeaders) == 0 { + return nil + } + if len(t.UserHeaders) > maxUserHeaders { + return fmt.Errorf("%w: at most %d per-user headers", ErrInvalidMCPTarget, maxUserHeaders) + } + authHeader := t.authSetsHeader() + seen := make(map[string]struct{}, len(t.UserHeaders)) + for _, h := range t.UserHeaders { + name := strings.TrimSpace(h.Name) + if name == "" || !httpToken.MatchString(name) { + return fmt.Errorf("%w: per-user header name %q is not a valid HTTP header name", ErrInvalidMCPTarget, h.Name) + } + if IsReservedUpstreamHeader(name) { + return fmt.Errorf("%w: header %q is reserved and cannot be set per user", ErrInvalidMCPTarget, name) + } + key := strings.ToLower(name) + if _, dup := seen[key]; dup { + return fmt.Errorf("%w: per-user header %q is declared twice", ErrInvalidMCPTarget, name) + } + seen[key] = struct{}{} + if _, shared := storedHeader(t.Headers, name); shared { + return fmt.Errorf("%w: header %q is both shared and per-user; pick one", ErrInvalidMCPTarget, name) + } + if authHeader != "" && strings.EqualFold(authHeader, name) { + return fmt.Errorf("%w: header %q is already set by auth mode %q", ErrInvalidMCPTarget, name, t.Auth.Mode) + } + if scheme := strings.TrimSpace(h.Scheme); scheme != "" && !httpToken.MatchString(scheme) { + return fmt.Errorf("%w: per-user header %q scheme %q is not a valid token", ErrInvalidMCPTarget, name, h.Scheme) + } + if len(h.Description) > 512 { + return fmt.Errorf("%w: per-user header %q description is too long", ErrInvalidMCPTarget, name) + } + } + return nil +} + +// authSetsHeader names the header the auth mode writes on every upstream +// call, or "" when it writes none. +func (t *MCPTarget) authSetsHeader() string { + if t.Auth == nil { + return "" + } + switch t.Auth.Mode { + case MCPAuthModeStatic: + return strings.TrimSpace(t.Auth.Header) + case MCPAuthModePassthrough, MCPAuthModeExchange, MCPAuthModeForwarded, MCPAuthModeClientCredentials: + return "Authorization" + default: + return "" + } +} + +// IsReservedUpstreamHeader reports whether name is a header the gateway, the +// transport or the MCP protocol owns, so no per-user value may set it. +func IsReservedUpstreamHeader(name string) bool { + name = strings.TrimSpace(name) + if strings.HasPrefix(strings.ToLower(name), reservedUpstreamHeaderPrefix) { + return true + } + for _, r := range reservedUpstreamHeaders { + if strings.EqualFold(r, name) { + return true + } + } + return false +} diff --git a/pkg/domain/registry/mcp_user_headers_test.go b/pkg/domain/registry/mcp_user_headers_test.go new file mode 100644 index 000000000..ce841b278 --- /dev/null +++ b/pkg/domain/registry/mcp_user_headers_test.go @@ -0,0 +1,153 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package registry + +import ( + "errors" + "strings" + "testing" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" +) + +func TestMCPTarget_UserHeadersValidate(t *testing.T) { + t.Parallel() + cases := []struct { + name string + mutate func(*MCPTarget) + wantErr string + }{ + {name: "one api key header with no auth", mutate: func(tg *MCPTarget) { + tg.Auth = &MCPAuth{Mode: MCPAuthModeNone} + tg.UserHeaders = []MCPUserHeader{{Name: "X-API-Key", Required: true, Secret: true}} + }}, + {name: "combined with shared header and static auth on another name", mutate: func(tg *MCPTarget) { + tg.Headers = map[string]string{"X-Tenant": "acme"} + tg.UserHeaders = []MCPUserHeader{{Name: "X-API-Key", Secret: true}, {Name: "X-Account", Scheme: "Id"}} + }}, + {name: "per-user Authorization with no auth mode", mutate: func(tg *MCPTarget) { + tg.Auth = &MCPAuth{Mode: MCPAuthModeNone} + tg.UserHeaders = []MCPUserHeader{{Name: "Authorization", Scheme: "Bearer", Secret: true}} + }}, + {name: "per-user Authorization when static auth sets it", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "authorization"}} + }, wantErr: "already set by auth mode"}, + {name: "per-user Authorization when forwarded sets it", mutate: func(tg *MCPTarget) { + tg.Auth = &MCPAuth{Mode: MCPAuthModeForwarded, Provider: "p", Registration: RegistrationAuto} + tg.UserHeaders = []MCPUserHeader{{Name: "Authorization"}} + }, wantErr: "already set by auth mode"}, + {name: "static auth on a custom header collides", mutate: func(tg *MCPTarget) { + tg.Auth = &MCPAuth{Mode: MCPAuthModeStatic, Header: "X-API-Key", Value: "k"} + tg.UserHeaders = []MCPUserHeader{{Name: "x-api-key"}} + }, wantErr: "already set by auth mode"}, + {name: "shared and per-user at once", mutate: func(tg *MCPTarget) { + tg.Headers = map[string]string{"x-api-key": "shared"} + tg.UserHeaders = []MCPUserHeader{{Name: "X-API-Key"}} + }, wantErr: "both shared and per-user"}, + {name: "duplicate", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "X-Key"}, {Name: "x-key"}} + }, wantErr: "declared twice"}, + {name: "reserved host", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "Host"}} + }, wantErr: "reserved"}, + {name: "reserved session id", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "mcp-session-id"}} + }, wantErr: "reserved"}, + {name: "reserved gateway namespace", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "X-NeuralTrust-End-User"}} + }, wantErr: "reserved"}, + {name: "invalid name", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "X Key"}} + }, wantErr: "not a valid HTTP header name"}, + {name: "empty name", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: " "}} + }, wantErr: "not a valid HTTP header name"}, + {name: "invalid scheme", mutate: func(tg *MCPTarget) { + tg.UserHeaders = []MCPUserHeader{{Name: "X-Key", Scheme: "Bear er"}} + }, wantErr: "not a valid token"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + tg := validMCPTarget() + tc.mutate(tg) + err := tg.Validate() + if tc.wantErr == "" { + if err != nil { + t.Fatalf("Validate() = %v, want nil", err) + } + return + } + if err == nil || !errors.Is(err, ErrInvalidMCPTarget) || !strings.Contains(err.Error(), tc.wantErr) { + t.Fatalf("Validate() = %v, want ErrInvalidMCPTarget containing %q", err, tc.wantErr) + } + }) + } +} + +func TestValidateUserHeaderValue(t *testing.T) { + t.Parallel() + h := MCPUserHeader{Name: "X-API-Key"} + cases := []struct { + name string + value string + ok bool + }{ + {"plain key", "sk-live_abc.123", true}, + {"with space", "abc def", true}, + {"empty", " ", false}, + {"crlf injection", "abc\r\nX-Evil: 1", false}, + {"lf", "abc\nd", false}, + {"nul", "abc\x00", false}, + {"non ascii", "clé", false}, + {"too long", strings.Repeat("a", MaxUserHeaderValueLen+1), false}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + err := ValidateUserHeaderValue(h, tc.value) + if tc.ok != (err == nil) { + t.Fatalf("ValidateUserHeaderValue() = %v, want ok=%v", err, tc.ok) + } + if err != nil && strings.Contains(err.Error(), "abc") { + t.Fatalf("error echoes the value: %v", err) + } + }) + } +} + +func TestUserHeaderVaultProvider(t *testing.T) { + t.Parallel() + pre, pro := ids.New[ids.RegistryKind](), ids.New[ids.RegistryKind]() + if UserHeaderVaultProvider(pre, "x-api-key") != UserHeaderVaultProvider(pre, " X-API-KEY ") { + t.Fatal("header case must not change the vault key") + } + if UserHeaderVaultProvider(pre, "X-API-Key") == UserHeaderVaultProvider(pro, "X-API-Key") { + t.Fatal("two instances must not share a value") + } + if !strings.HasPrefix(UserHeaderVaultProvider(pre, "X-API-Key"), UserHeaderVaultPrefix(pre)) { + t.Fatal("per-header key must sit under the registry prefix") + } +} + +func TestMCPUserHeader_FormatValue(t *testing.T) { + t.Parallel() + if got := (MCPUserHeader{Scheme: "Bearer"}).FormatValue("tok"); got != "Bearer tok" { + t.Fatalf("got %q", got) + } + if got := (MCPUserHeader{}).FormatValue("tok"); got != "tok" { + t.Fatalf("got %q", got) + } +} From 2c8509990877b9dd2f6c97d4efa28c25a6c876e8 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:19:28 +0100 Subject: [PATCH 02/14] feat(mcp): send each caller's own per-user upstream header values The credential resolver now reads the calling principal's value for every per-user header a registry declares and sets it after the shared headers and the auth mode. A required header without a value refuses the call with a connect link (-32003); an optional one is left out. The application itself and group keys are refused before the vault is read. Upstream sessions, the discovery cache and introspection are scoped per principal, and the pin key carries a digest of the values so a replaced key dials a new session. An upstream 401 on a registry whose only per-caller credential is its headers marks the values refused and asks the caller to enter them again, without retrying. Refs ENG-3243 --- pkg/app/mcp/credentials.go | 9 +- pkg/app/mcp/discovery.go | 2 +- pkg/app/mcp/introspector.go | 2 +- pkg/app/mcp/target.go | 2 +- pkg/app/mcp/user_headers.go | 199 ++++++++++++++++++++++++ pkg/app/mcp/user_headers_test.go | 251 +++++++++++++++++++++++++++++++ 6 files changed, 461 insertions(+), 4 deletions(-) create mode 100644 pkg/app/mcp/user_headers.go create mode 100644 pkg/app/mcp/user_headers_test.go diff --git a/pkg/app/mcp/credentials.go b/pkg/app/mcp/credentials.go index daed5dbd2..4aacc52e8 100644 --- a/pkg/app/mcp/credentials.go +++ b/pkg/app/mcp/credentials.go @@ -173,6 +173,13 @@ const rejectedCredentialRefreshCooldown = 30 * time.Second const deadGrantRetryInterval = 15 * time.Minute func (r *credentialResolver) Apply(ctx context.Context, rc *appconsumer.RoutableConsumer, reg *registrydomain.Registry, target *Target) error { + if err := r.applyAuth(ctx, rc, reg, target); err != nil { + return err + } + return r.applyUserHeaders(ctx, rc, reg, target) +} + +func (r *credentialResolver) applyAuth(ctx context.Context, rc *appconsumer.RoutableConsumer, reg *registrydomain.Registry, target *Target) error { cfg := reg.MCPTarget.Auth if cfg == nil { return nil @@ -290,7 +297,7 @@ func (r *credentialResolver) Refresh( ) error { cfg := reg.MCPTarget.Auth if cfg == nil || cfg.Mode != registrydomain.MCPAuthModeForwarded { - return errCredentialRefreshUnsupported + return r.refuseRejectedUserHeaders(ctx, rc, reg) } principal := identity.PrincipalFromContext(ctx) if principal == nil { diff --git a/pkg/app/mcp/discovery.go b/pkg/app/mcp/discovery.go index 84593799f..20c140ad9 100644 --- a/pkg/app/mcp/discovery.go +++ b/pkg/app/mcp/discovery.go @@ -434,7 +434,7 @@ func isContextError(err error) bool { func discoveryKey(ctx context.Context, reg *registrydomain.Registry, kind string) (string, bool) { key := kind + ":" + reg.ID.String() + ":" + reg.UpdatedAt.UTC().Format("20060102150405.000") perPrincipal := perPrincipalAuth(reg) || - (reg.MCPTarget != nil && reg.MCPTarget.HasURLVariables()) + (reg.MCPTarget != nil && (reg.MCPTarget.HasURLVariables() || reg.MCPTarget.HasUserHeaders())) if !perPrincipal { return key, true } diff --git a/pkg/app/mcp/introspector.go b/pkg/app/mcp/introspector.go index 56f0e49b9..1a6ca80a0 100644 --- a/pkg/app/mcp/introspector.go +++ b/pkg/app/mcp/introspector.go @@ -63,5 +63,5 @@ func (i *introspector) ListRegistryTools(ctx context.Context, gatewayID ids.Gate // notIntrospectable reports whether dialing this registry needs a principal. func notIntrospectable(reg *registrydomain.Registry) bool { - return perPrincipalAuth(reg) || reg.MCPTarget.HasURLVariables() + return perPrincipalAuth(reg) || reg.MCPTarget.HasURLVariables() || reg.MCPTarget.HasUserHeaders() } diff --git a/pkg/app/mcp/target.go b/pkg/app/mcp/target.go index 5b7f84769..35b3c636b 100644 --- a/pkg/app/mcp/target.go +++ b/pkg/app/mcp/target.go @@ -88,7 +88,7 @@ func targetFor(ctx context.Context, rc *appconsumer.RoutableConsumer, reg *regis t := StaticTarget(reg) if rc != nil && rc.Consumer != nil { t.PinKey = fmt.Sprintf("%s:%s:%s", rc.Consumer.GatewayID, rc.Consumer.ID, reg.ID) - if perPrincipalAuth(reg) { + if perPrincipalAuth(reg) || reg.MCPTarget.HasUserHeaders() { if p := identity.PrincipalFromContext(ctx); p != nil { t.PinKey += ":" + p.Subject } diff --git a/pkg/app/mcp/user_headers.go b/pkg/app/mcp/user_headers.go new file mode 100644 index 000000000..0a31c7278 --- /dev/null +++ b/pkg/app/mcp/user_headers.go @@ -0,0 +1,199 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package mcp + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "errors" + "sort" + "time" + + appconsumer "github.com/NeuralTrust/TrustGate/pkg/app/consumer" + "github.com/NeuralTrust/TrustGate/pkg/common/logref" + consumerdomain "github.com/NeuralTrust/TrustGate/pkg/domain/consumer" + "github.com/NeuralTrust/TrustGate/pkg/domain/identity" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + registrydomain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" +) + +// Cause codes for a call refused because a per-user header has no usable value. +const ( + // ConsentCauseUserHeaderMissing: the caller never entered a value. + ConsentCauseUserHeaderMissing = "user_header_missing" + // ConsentCauseUserHeaderRejected: the upstream answered 401 with the value + // this caller entered, so it has to be entered again. + ConsentCauseUserHeaderRejected = "user_header_rejected" +) + +// applyUserHeaders sets the calling person's own value for every per-user +// header the registry declares. A required header without a usable value +// refuses the call with a connect link; an optional one is left out. +// +// A caller with no individual identity is refused before the vault is read: +// the application itself, or a group key whose owner's value would otherwise +// be sent on behalf of everyone holding the key. +func (r *credentialResolver) applyUserHeaders( + ctx context.Context, + rc *appconsumer.RoutableConsumer, + reg *registrydomain.Registry, + target *Target, +) error { + if reg == nil || !reg.MCPTarget.HasUserHeaders() { + return nil + } + principal := identity.PrincipalFromContext(ctx) + if principal == nil || principal.Subject == "" { + return ErrNoPrincipal + } + label := registryLabelFor(reg) + if principal.KeyGroup() != "" || principal.Subject == consumerdomain.AppSubject(rc.Consumer.ID) { + return &ApplicationNotConnectedError{Provider: label, Registry: label} + } + gatewayID := rc.Consumer.GatewayID + if target.Headers == nil { + target.Headers = map[string]string{} + } + resolved := make([]string, 0, len(reg.MCPTarget.UserHeaders)) + for _, h := range reg.MCPTarget.UserHeaders { + value, cause, err := r.userHeaderValue(ctx, gatewayID, principal.Subject, reg, h) + if err != nil { + return err + } + if cause != "" { + if !h.Required { + continue + } + return r.consentRequired(ctx, rc, reg, label, principal.Subject, cause, + "no usable value for a per-user upstream header", "header", h.Name) + } + target.Headers[h.Name] = h.FormatValue(value) + resolved = append(resolved, h.Name+"\x00"+value) + } + // One person's upstream session is never reused for another, and a value + // the person replaced dials a fresh session instead of riding the old one. + sort.Strings(resolved) + sum := sha256.New() + sum.Write([]byte(principal.Issuer + "\x00" + principal.Subject)) + for _, v := range resolved { + sum.Write([]byte{0}) + sum.Write([]byte(v)) + } + target.PinKey += ":h:" + hex.EncodeToString(sum.Sum(nil)[:8]) + return nil +} + +// userHeaderValue reads one person's value for one header. A non-empty cause +// means there is no usable value and says why; err is a vault failure. +func (r *credentialResolver) userHeaderValue( + ctx context.Context, + gatewayID ids.GatewayID, + subject string, + reg *registrydomain.Registry, + h registrydomain.MCPUserHeader, +) (value, cause string, err error) { + if r.vault == nil { + return "", ConsentCauseUserHeaderMissing, nil + } + cred, err := r.vault.Find(ctx, gatewayID, subject, registrydomain.UserHeaderVaultProvider(reg.ID, h.Name)) + switch { + case errors.Is(err, vaultdomain.ErrNotFound): + return "", ConsentCauseUserHeaderMissing, nil + case errors.Is(err, vaultdomain.ErrUndecryptable): + return "", ConsentCauseUndecryptable, nil + case err != nil: + return "", "", err + } + if cred == nil || cred.AccessToken == "" { + return "", ConsentCauseUserHeaderMissing, nil + } + if UserHeaderRejected(cred) { + return "", ConsentCauseUserHeaderRejected, nil + } + return cred.AccessToken, "", nil +} + +// UserHeaderRejected reports whether a stored per-user header value was +// refused by the upstream. A value carries no expiry of its own; the vault's +// reconnect mark (an expiry set to the moment of the refusal) is what records +// that the upstream answered 401 with it. +func UserHeaderRejected(cred *vaultdomain.Credential) bool { + return cred != nil && !cred.ExpiresAt.IsZero() && !cred.ExpiresAt.After(time.Now()) +} + +// rejectUserHeaders marks every per-user header value the caller sent to this +// registry as refused, after the upstream answered 401. It reports whether a +// value was marked, so the caller can tell the person to enter it again rather +// than retry with the same key. +func (r *credentialResolver) rejectUserHeaders( + ctx context.Context, + rc *appconsumer.RoutableConsumer, + reg *registrydomain.Registry, +) bool { + if r.vault == nil || reg == nil || !reg.MCPTarget.HasUserHeaders() { + return false + } + principal := identity.PrincipalFromContext(ctx) + if principal == nil || principal.Subject == "" { + return false + } + requirer, ok := r.vault.(vaultdomain.ReconnectRequirer) + if !ok { + return false + } + gatewayID := rc.Consumer.GatewayID + marked := false + for _, h := range reg.MCPTarget.UserHeaders { + provider := registrydomain.UserHeaderVaultProvider(reg.ID, h.Name) + cred, err := r.vault.Find(ctx, gatewayID, principal.Subject, provider) + if err != nil || cred == nil || UserHeaderRejected(cred) { + continue + } + if err := requirer.RequireReconnect(ctx, cred); err != nil && !errors.Is(err, vaultdomain.ErrCredentialChanged) { + r.logger.Warn("mcp user headers: could not mark a rejected value", + "gateway_id", gatewayID.String(), "registry_id", reg.ID.String(), + "principal_ref", logref.Opaque(principal.Subject), "header", h.Name, "error", err) + continue + } + marked = true + r.logger.Info("security audit", + "event", "mcp_user_header_rejected", + "gateway_id", gatewayID.String(), "registry_id", reg.ID.String(), + "principal_ref", logref.Opaque(principal.Subject), "header", h.Name) + } + return marked +} + +// refuseRejectedUserHeaders answers an upstream 401 on a registry whose only +// per-caller credential is its per-user headers: the values are marked +// refused and the caller gets a connect link to enter them again. The call is +// not retried, since the same values would be refused again. A registry that +// also forwards an OAuth credential refreshes that one instead: a 401 does not +// say which credential failed, and the token is the one that expires. +func (r *credentialResolver) refuseRejectedUserHeaders( + ctx context.Context, + rc *appconsumer.RoutableConsumer, + reg *registrydomain.Registry, +) error { + if !r.rejectUserHeaders(ctx, rc, reg) { + return errCredentialRefreshUnsupported + } + principal := identity.PrincipalFromContext(ctx) + label := registryLabelFor(reg) + return r.consentRequired(ctx, rc, reg, label, principal.Subject, ConsentCauseUserHeaderRejected, + "the upstream refused this caller's per-user header value") +} diff --git a/pkg/app/mcp/user_headers_test.go b/pkg/app/mcp/user_headers_test.go new file mode 100644 index 000000000..a320c5ecd --- /dev/null +++ b/pkg/app/mcp/user_headers_test.go @@ -0,0 +1,251 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package mcp + +import ( + "context" + "errors" + "strings" + "testing" + "time" + + consumerdomain "github.com/NeuralTrust/TrustGate/pkg/domain/consumer" + "github.com/NeuralTrust/TrustGate/pkg/domain/identity" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + registrydomain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" +) + +// userHeaderVault is a memVault that can mark a credential refused, as the +// Postgres and Redis vaults do. +type userHeaderVault struct{ *memVault } + +func (v userHeaderVault) RequireReconnect(_ context.Context, c *vaultdomain.Credential) error { + stored := v.creds[v.key(c.GatewayID, c.PrincipalSub, c.Provider)] + if stored == nil { + return vaultdomain.ErrCredentialChanged + } + stored.ExpiresAt = time.Now().Add(-time.Second) + return nil +} + +func regWithUserHeaders(gw ids.GatewayID, headers ...registrydomain.MCPUserHeader) *registrydomain.Registry { + reg, err := registrydomain.NewMCPRegistry(gw, "keyed", "", ®istrydomain.MCPTarget{ + URL: "https://keyed.example.com/mcp", + Auth: ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeNone}, + Headers: map[string]string{"X-Tenant": "acme"}, + UserHeaders: headers, + }) + if err != nil { + panic(err) + } + return reg +} + +func storeUserHeader(t *testing.T, v *memVault, gw ids.GatewayID, sub string, reg *registrydomain.Registry, header, value string) { + t.Helper() + cred, err := vaultdomain.NewCredential(gw, sub, registrydomain.UserHeaderVaultProvider(reg.ID, header), "", value, "", nil, time.Time{}) + if err != nil { + t.Fatal(err) + } + if err := v.Upsert(context.Background(), cred); err != nil { + t.Fatal(err) + } +} + +func TestApplyUserHeaders_EachCallerSendsTheirOwnValue(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := &memVault{} + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true, Secret: true}) + storeUserHeader(t, vault, gw, "ana", reg, "x-api-key", "ana-key") + storeUserHeader(t, vault, gw, "bruno", reg, "X-API-Key", "bruno-key") + r := NewCredentialResolver(nil, vault, &stubConnect{ticket: "t"}, nil, discardLogger()) + rc := mcpConsumer(gw) + + targets := map[string]Target{} + for _, sub := range []string{"ana", "bruno"} { + ctx := principalCtx(&identity.Principal{Subject: sub, Method: identity.MethodOAuth}) + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatalf("%s: Apply() = %v", sub, err) + } + targets[sub] = target + } + if got := targets["ana"].Headers["X-API-Key"]; got != "ana-key" { + t.Fatalf("ana sent %q", got) + } + if got := targets["bruno"].Headers["X-API-Key"]; got != "bruno-key" { + t.Fatalf("bruno sent %q", got) + } + if targets["ana"].Headers["X-Tenant"] != "acme" { + t.Fatal("shared header dropped") + } + if targets["ana"].PinKey == targets["bruno"].PinKey { + t.Fatal("two callers share an upstream session") + } + for _, tg := range targets { + if strings.Contains(tg.PinKey, "key") { + t.Fatalf("pin key carries the value: %s", tg.PinKey) + } + } +} + +func TestApplyUserHeaders_SchemeAndRotation(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := &memVault{} + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "Authorization", Scheme: "Bearer", Required: true}) + storeUserHeader(t, vault, gw, "ana", reg, "Authorization", "one") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()) + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + first := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &first); err != nil { + t.Fatal(err) + } + if first.Headers["Authorization"] != "Bearer one" { + t.Fatalf("got %q", first.Headers["Authorization"]) + } + storeUserHeader(t, vault, gw, "ana", reg, "Authorization", "two") + second := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &second); err != nil { + t.Fatal(err) + } + if first.PinKey == second.PinKey { + t.Fatal("a replaced value must dial a new session") + } +} + +func TestApplyUserHeaders_MissingValue(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + t.Run("required asks for consent", func(t *testing.T) { + t.Parallel() + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + r := NewCredentialResolver(nil, &memVault{}, &stubConnect{ticket: "tk"}, nil, discardLogger()) + target := targetFor(ctx, rc, reg) + err := r.Apply(ctx, rc, reg, &target) + var consent *ConsentRequiredError + if !errors.As(err, &consent) || consent.Cause != ConsentCauseUserHeaderMissing || consent.Ticket != "tk" { + t.Fatalf("Apply() = %v, want consent with ticket", err) + } + }) + t.Run("optional is left out", func(t *testing.T) { + t.Parallel() + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-Account"}) + r := NewCredentialResolver(nil, &memVault{}, &stubConnect{}, nil, discardLogger()) + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatal(err) + } + if _, ok := target.Headers["X-Account"]; ok { + t.Fatal("optional header without a value was sent") + } + }) +} + +func TestApplyUserHeaders_CallerWithoutIndividualIdentity(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := &memVault{} + rc := mcpConsumer(gw) + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + storeUserHeader(t, vault, gw, "owner", reg, "X-API-Key", "owner-key") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()) + + cases := map[string]*identity.Principal{ + "application itself": {Subject: consumerdomain.AppSubject(rc.Consumer.ID), Method: identity.MethodAPIKey}, + "group key": {Subject: "owner", Method: identity.MethodPersonalKey, + Claims: map[string]any{identity.ClaimKeyGroup: "engineering"}}, + } + for name, p := range cases { + t.Run(name, func(t *testing.T) { + t.Parallel() + ctx := principalCtx(p) + target := targetFor(ctx, rc, reg) + err := r.Apply(ctx, rc, reg, &target) + var notConnected *ApplicationNotConnectedError + if !errors.As(err, ¬Connected) { + t.Fatalf("Apply() = %v, want ApplicationNotConnectedError", err) + } + if _, sent := target.Headers["X-API-Key"]; sent { + t.Fatal("a value was sent for a caller with no individual identity") + } + }) + } + t.Run("no principal", func(t *testing.T) { + t.Parallel() + target := targetFor(context.Background(), rc, reg) + if err := r.Apply(context.Background(), rc, reg, &target); !errors.Is(err, ErrNoPrincipal) { + t.Fatalf("Apply() = %v, want ErrNoPrincipal", err) + } + }) +} + +func TestApplyUserHeaders_InstancesHoldSeparateValues(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := &memVault{} + pre := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + pro := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + storeUserHeader(t, vault, gw, "ana", pre, "X-API-Key", "pre-key") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()) + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + target := targetFor(ctx, rc, pro) + var consent *ConsentRequiredError + if err := r.Apply(ctx, rc, pro, &target); !errors.As(err, &consent) { + t.Fatalf("PRO reused PRE's value: %v", err) + } +} + +func TestRefresh_UpstreamRejectsUserHeader(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + vault := userHeaderVault{&memVault{}} + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + storeUserHeader(t, vault.memVault, gw, "ana", reg, "X-API-Key", "stale") + r := NewCredentialResolver(nil, vault, &stubConnect{ticket: "tk"}, nil, discardLogger()).(*credentialResolver) + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatal(err) + } + var consent *ConsentRequiredError + if err := r.Refresh(ctx, rc, reg, &target); !errors.As(err, &consent) || consent.Cause != ConsentCauseUserHeaderRejected { + t.Fatalf("Refresh() = %v, want consent with rejected cause", err) + } + next := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &next); !errors.As(err, &consent) || consent.Cause != ConsentCauseUserHeaderRejected { + t.Fatalf("Apply() after a 401 = %v, want the rejected value refused before dialing", err) + } + + t.Run("a registry without user headers keeps refusing to refresh", func(t *testing.T) { + t.Parallel() + plain := regWithAuth(gw, ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeNone}) + tg := targetFor(ctx, rc, plain) + if err := r.Refresh(ctx, rc, plain, &tg); !errors.Is(err, errCredentialRefreshUnsupported) { + t.Fatalf("Refresh() = %v, want unsupported", err) + } + }) +} From 86581a7982f33193013c8136929fcd44b19640c4 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:21:03 +0100 Subject: [PATCH 03/14] feat(registry): accept per-user header declarations on the admin API mcp_target.user_headers is read on create and update and returned on read. An update that omits it keeps the stored declarations and an empty list removes them. A catalog row with per-user headers counts as customized, so a catalog reapply never rewrites it and drops them. Refs ENG-3243 --- .../request/create_registry_request.go | 40 ++++++++++++++---- .../http/registry/request/mcp_account_test.go | 17 ++++++++ .../registry/response/registry_response.go | 31 ++++++++++---- pkg/app/registry/updater.go | 3 ++ pkg/app/registry/updater_test.go | 42 +++++++++++++++++++ pkg/app/store/catalog_reapply.go | 2 +- 6 files changed, 120 insertions(+), 15 deletions(-) diff --git a/pkg/api/handler/http/registry/request/create_registry_request.go b/pkg/api/handler/http/registry/request/create_registry_request.go index 4f34d5661..1fb062c08 100644 --- a/pkg/api/handler/http/registry/request/create_registry_request.go +++ b/pkg/api/handler/http/registry/request/create_registry_request.go @@ -53,13 +53,31 @@ type PriceOverrideRequest struct { } type MCPTargetRequest struct { - Code string `json:"code,omitempty"` - Source string `json:"source,omitempty"` - URL string `json:"url,omitempty"` - Transport string `json:"transport,omitempty"` - Headers map[string]string `json:"headers,omitempty"` - Auth *MCPAuthRequest `json:"auth,omitempty"` - OpenAPI *OpenAPITargetRequest `json:"openapi,omitempty"` + Code string `json:"code,omitempty"` + Source string `json:"source,omitempty"` + URL string `json:"url,omitempty"` + Transport string `json:"transport,omitempty"` + Headers map[string]string `json:"headers,omitempty"` + // UserHeaders declares the upstream headers each caller fills with their + // own value. Omitted on update, the stored declarations are kept; an empty + // list removes them all. + UserHeaders *[]MCPUserHeaderRequest `json:"user_headers,omitempty"` + Auth *MCPAuthRequest `json:"auth,omitempty"` + OpenAPI *OpenAPITargetRequest `json:"openapi,omitempty"` +} + +// MCPUserHeaderRequest declares one per-user upstream header. +type MCPUserHeaderRequest struct { + // Name is the HTTP header sent upstream, e.g. X-API-Key. + Name string `json:"name"` + // Description is the help shown to a person entering their value. + Description string `json:"description,omitempty"` + // Required refuses a call with a connect link until the caller has a value. + Required bool `json:"required,omitempty"` + // Secret keeps the value masked once entered. + Secret bool `json:"secret,omitempty"` + // Scheme is written before the value, e.g. Bearer. Empty sends it raw. + Scheme string `json:"scheme,omitempty"` } type OpenAPITargetRequest struct { @@ -269,6 +287,14 @@ func (t *MCPTargetRequest) ToDomain() *domain.MCPTarget { Transport: domain.MCPTransport(t.Transport), Headers: t.Headers, } + if t.UserHeaders != nil { + out.UserHeaders = make([]domain.MCPUserHeader, 0, len(*t.UserHeaders)) + for _, h := range *t.UserHeaders { + out.UserHeaders = append(out.UserHeaders, domain.MCPUserHeader{ + Name: h.Name, Description: h.Description, Required: h.Required, Secret: h.Secret, Scheme: h.Scheme, + }) + } + } if t.OpenAPI != nil { out.OpenAPI = &domain.OpenAPITarget{SpecURL: t.OpenAPI.SpecURL} } diff --git a/pkg/api/handler/http/registry/request/mcp_account_test.go b/pkg/api/handler/http/registry/request/mcp_account_test.go index f0887eece..508dce97e 100644 --- a/pkg/api/handler/http/registry/request/mcp_account_test.go +++ b/pkg/api/handler/http/registry/request/mcp_account_test.go @@ -68,3 +68,20 @@ func TestCreateRegistryRequest_NoAccountIsTheCallersOwn(t *testing.T) { require.Empty(t, string(target.Auth.Account)) require.False(t, target.Auth.Shared()) } + +// A per-user header that does not survive the wire would be dropped silently +// and every caller would dial without it. +func TestMCPTargetRequest_UserHeaders(t *testing.T) { + var omitted, cleared, set MCPTargetRequest + require.NoError(t, json.Unmarshal([]byte(`{"url":"https://x.example.com/mcp"}`), &omitted)) + require.NoError(t, json.Unmarshal([]byte(`{"url":"https://x.example.com/mcp","user_headers":[]}`), &cleared)) + require.NoError(t, json.Unmarshal([]byte(`{"url":"https://x.example.com/mcp","user_headers":[ + {"name":"X-API-Key","description":"Your key","required":true,"secret":true,"scheme":"Token"}]}`), &set)) + + require.Nil(t, omitted.ToDomain().UserHeaders) + require.NotNil(t, cleared.ToDomain().UserHeaders) + require.Empty(t, cleared.ToDomain().UserHeaders) + require.Equal(t, []domain.MCPUserHeader{{ + Name: "X-API-Key", Description: "Your key", Required: true, Secret: true, Scheme: "Token", + }}, set.ToDomain().UserHeaders) +} diff --git a/pkg/api/handler/http/registry/response/registry_response.go b/pkg/api/handler/http/registry/response/registry_response.go index 6cd377fac..58f2b6f2d 100644 --- a/pkg/api/handler/http/registry/response/registry_response.go +++ b/pkg/api/handler/http/registry/response/registry_response.go @@ -132,13 +132,25 @@ type MCPTargetResponse struct { Code string `json:"code,omitempty"` // Origin is "store" when the gateway materialised this registry from the // catalog itself (self-service install, approval, consumer binding). - Origin string `json:"origin,omitempty"` - Source string `json:"source,omitempty"` - URL string `json:"url,omitempty"` - Transport string `json:"transport,omitempty"` - Headers map[string]string `json:"headers,omitempty"` - Auth *MCPAuthResponse `json:"auth,omitempty"` - OpenAPI *OpenAPITargetResponse `json:"openapi,omitempty"` + Origin string `json:"origin,omitempty"` + Source string `json:"source,omitempty"` + URL string `json:"url,omitempty"` + Transport string `json:"transport,omitempty"` + Headers map[string]string `json:"headers,omitempty"` + // UserHeaders are the upstream headers each caller fills with their own + // value. Only the declarations: values live per person in the vault. + UserHeaders []MCPUserHeaderResponse `json:"user_headers,omitempty"` + Auth *MCPAuthResponse `json:"auth,omitempty"` + OpenAPI *OpenAPITargetResponse `json:"openapi,omitempty"` +} + +// MCPUserHeaderResponse is one declared per-user upstream header. +type MCPUserHeaderResponse struct { + Name string `json:"name"` + Description string `json:"description,omitempty"` + Required bool `json:"required,omitempty"` + Secret bool `json:"secret,omitempty"` + Scheme string `json:"scheme,omitempty"` } type OpenAPITargetResponse struct { @@ -310,6 +322,11 @@ func fromMCPTarget(t *domain.MCPTarget) *MCPTargetResponse { Transport: string(t.Transport), Headers: maskHeaders(t.Headers), } + for _, h := range t.UserHeaders { + out.UserHeaders = append(out.UserHeaders, MCPUserHeaderResponse{ + Name: h.Name, Description: h.Description, Required: h.Required, Secret: h.Secret, Scheme: h.Scheme, + }) + } if t.OpenAPI != nil { out.OpenAPI = &OpenAPITargetResponse{SpecURL: t.OpenAPI.SpecURL} } diff --git a/pkg/app/registry/updater.go b/pkg/app/registry/updater.go index 307238260..27f06e3ca 100644 --- a/pkg/app/registry/updater.go +++ b/pkg/app/registry/updater.go @@ -248,6 +248,9 @@ func applyMCPTargetUpdate( if incoming.Headers == nil { incoming.Headers = prev.Headers } + if incoming.UserHeaders == nil { + incoming.UserHeaders = prev.UserHeaders + } if incoming.Auth == nil { incoming.Auth = prev.Auth } diff --git a/pkg/app/registry/updater_test.go b/pkg/app/registry/updater_test.go index 45ceb6a36..13dfb8bb0 100644 --- a/pkg/app/registry/updater_test.go +++ b/pkg/app/registry/updater_test.go @@ -780,3 +780,45 @@ func TestUpdater_Update_RestoresMaskedProviderOptionHeader(t *testing.T) { t.Fatalf("Update: %v", err) } } + +func TestUpdater_Update_UserHeadersKeptWhenOmittedAndClearedWhenEmpty(t *testing.T) { + t.Parallel() + declared := []domain.MCPUserHeader{{Name: "X-API-Key", Required: true, Secret: true}} + cases := []struct { + name string + incoming []domain.MCPUserHeader + want int + }{ + {name: "omitted keeps the declarations", incoming: nil, want: 1}, + {name: "empty list removes them", incoming: []domain.MCPUserHeader{}, want: 0}, + {name: "a new list replaces them", incoming: []domain.MCPUserHeader{{Name: "X-Account"}, {Name: "X-Key"}}, want: 2}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + repo := repomocks.NewRepository(t) + existing, err := domain.NewMCPRegistry(ids.New[ids.GatewayKind](), "keyed", "", &domain.MCPTarget{ + URL: "https://keyed.example.com/mcp", + UserHeaders: declared, + }) + if err != nil { + t.Fatalf("NewMCPRegistry error: %v", err) + } + repo.EXPECT().FindByID(mock.Anything, existing.ID).Return(existing, nil).Once() + repo.EXPECT().Update(mock.Anything, mock.Anything).Return(nil).Once() + publisher := cachemocks.NewEventPublisher(t) + publisher.EXPECT().Publish(mock.Anything, mock.Anything).Return(nil).Once() + updater := appregistry.NewUpdater(repo, newCacheManager(), publisher, newTestLogger(), nil, nil) + got, err := updater.Update(context.Background(), appregistry.UpdateInput{ + ID: existing.ID, + MCPTarget: &domain.MCPTarget{UserHeaders: tc.incoming}, + }) + if err != nil { + t.Fatalf("Update error: %v", err) + } + if len(got.MCPTarget.UserHeaders) != tc.want { + t.Fatalf("user headers = %+v, want %d", got.MCPTarget.UserHeaders, tc.want) + } + }) + } +} diff --git a/pkg/app/store/catalog_reapply.go b/pkg/app/store/catalog_reapply.go index 081023e7f..e1d7c94f9 100644 --- a/pkg/app/store/catalog_reapply.go +++ b/pkg/app/store/catalog_reapply.go @@ -317,7 +317,7 @@ func catalogCustomized(target *registrydomain.MCPTarget) bool { if target.Source != "" && target.Source != registrydomain.MCPSourceRemote { return true } - if len(target.Headers) > 0 || len(target.UnreadableHeaders) > 0 { + if len(target.Headers) > 0 || len(target.UnreadableHeaders) > 0 || len(target.UserHeaders) > 0 { return true } auth := target.Auth From cd9bc1fb0f4e8d5da1ea88c469581f45dd98e011 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:25:06 +0100 Subject: [PATCH 04/14] feat(oauth): enter per-user header values on the connect page The connect page lists every server of the consumer whose upstream needs the person's own header values, with a form to enter, replace or remove them. A secret value is never written back into the page, and leaving its field empty keeps what is stored. Every value is validated before any is written. An application's ticket shows no such server, and a ticket pinned to one instance reaches only that instance. Writes are accepted only from the gateway's own page, like the OAuth start, and each change is audited with the header name and an opaque principal reference, never the value. Refs ENG-3243 --- .../oauth/connect_user_headers_handler.go | 108 +++++++ .../connect_user_headers_handler_test.go | 109 +++++++ pkg/api/handler/http/oauth/page_assets.go | 28 +- pkg/api/handler/http/oauth/pages.go | 18 +- pkg/app/oauth/connect.go | 5 + pkg/app/oauth/connect_types.go | 3 + pkg/app/oauth/connect_user_headers.go | 285 ++++++++++++++++++ pkg/app/oauth/connect_user_headers_test.go | 175 +++++++++++ pkg/server/router/mcp_router.go | 2 + 9 files changed, 726 insertions(+), 7 deletions(-) create mode 100644 pkg/api/handler/http/oauth/connect_user_headers_handler.go create mode 100644 pkg/api/handler/http/oauth/connect_user_headers_handler_test.go create mode 100644 pkg/app/oauth/connect_user_headers.go create mode 100644 pkg/app/oauth/connect_user_headers_test.go diff --git a/pkg/api/handler/http/oauth/connect_user_headers_handler.go b/pkg/api/handler/http/oauth/connect_user_headers_handler.go new file mode 100644 index 000000000..19d93c716 --- /dev/null +++ b/pkg/api/handler/http/oauth/connect_user_headers_handler.go @@ -0,0 +1,108 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package oauth + +import ( + "errors" + "net/url" + "strings" + + appoauth "github.com/NeuralTrust/TrustGate/pkg/app/oauth" + "github.com/gofiber/fiber/v2" +) + +const ( + // UserHeadersSavePath is where the connect page posts a person's header + // values for one server instance. + UserHeadersSavePath = "/oauth/user-headers/:instance" + // UserHeadersRemovePath is where it posts to remove them. + UserHeadersRemovePath = "/oauth/user-headers-remove/:instance" +) + +// maxUserHeaderFormBytes bounds the form a person posts with their keys. +const maxUserHeaderFormBytes = 64 << 10 + +// SaveUserHeaders stores the header values a person entered on the connect +// page, then shows the page again with what is now stored. +func (h *ConnectHandler) SaveUserHeaders(c *fiber.Ctx) error { + enroll, err := h.userHeaderEnrollment(c) + if err != nil { + return err + } + if !isFormURLEncoded(c.Get(fiber.HeaderContentType)) { + return fiber.NewError(fiber.StatusUnsupportedMediaType, "expected application/x-www-form-urlencoded") + } + if len(c.Body()) > maxUserHeaderFormBytes { + return fiber.NewError(fiber.StatusRequestEntityTooLarge, "form too large") + } + form, err := url.ParseQuery(string(c.Body())) + if err != nil { + return fiber.NewError(fiber.StatusBadRequest, "malformed form") + } + values := make(map[string]string, len(form)) + for name, vs := range form { + if len(vs) > 0 { + values[name] = vs[0] + } + } + ticket := c.Query("ticket") + if err := enroll.SaveUserHeaders(c.UserContext(), ticket, c.Params("instance"), values); err != nil { + return h.userHeaderError(c, ticket, err) + } + return h.showPage(c, ticket, "") +} + +// RemoveUserHeaders deletes the header values a person holds for one server. +func (h *ConnectHandler) RemoveUserHeaders(c *fiber.Ctx) error { + enroll, err := h.userHeaderEnrollment(c) + if err != nil { + return err + } + ticket := c.Query("ticket") + if err := enroll.RemoveUserHeaders(c.UserContext(), ticket, c.Params("instance")); err != nil { + return h.userHeaderError(c, ticket, err) + } + return h.showPage(c, ticket, "") +} + +// userHeaderEnrollment refuses a write that did not come from the gateway's +// own page, and one this plane's connect service cannot serve. +func (h *ConnectHandler) userHeaderEnrollment(c *fiber.Ctx) (appoauth.UserHeaderEnrollment, error) { + c.Set(fiber.HeaderCacheControl, "no-store") + if !sentFromOwnPage(c) { + return nil, h.pageError(c, errConnectNotFromPage) + } + enroll, ok := h.connect.(appoauth.UserHeaderEnrollment) + if !ok { + return nil, fiber.NewError(fiber.StatusNotFound, "per-user keys are not available here") + } + if strings.TrimSpace(c.Query("ticket")) == "" { + return nil, fiber.NewError(fiber.StatusUnauthorized, "missing ticket: re-run the tool call to get a fresh connect link") + } + return enroll, nil +} + +func (h *ConnectHandler) userHeaderError(c *fiber.Ctx, ticket string, err error) error { + switch { + case errors.Is(err, appoauth.ErrUserHeaderInvalid): + // The message names the header, never the value; the person fixes it + // on the same page. + return h.showPage(c, ticket, err.Error()) + case errors.Is(err, appoauth.ErrUserHeaderServerNotFound): + return fiber.NewError(fiber.StatusNotFound, err.Error()) + default: + return h.pageError(c, err) + } +} diff --git a/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go b/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go new file mode 100644 index 000000000..9ee6401ba --- /dev/null +++ b/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go @@ -0,0 +1,109 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package oauth + +import ( + "context" + "net/http/httptest" + "strings" + "testing" + + appoauth "github.com/NeuralTrust/TrustGate/pkg/app/oauth" + "github.com/gofiber/fiber/v2" +) + +// enrollingConnectService is a connect service that also takes header values. +type enrollingConnectService struct { + *stubConnectService + saved map[string]string + removed bool +} + +func (s *enrollingConnectService) SaveUserHeaders(_ context.Context, _, _ string, values map[string]string) error { + s.saved = values + return nil +} + +func (s *enrollingConnectService) RemoveUserHeaders(context.Context, string, string) error { + s.removed = true + return nil +} + +func userHeaderPage(code string) *appoauth.ConnectPage { + return &appoauth.ConnectPage{ + ConsumerPath: "/dev/mcp", + Code: code, + Principal: appoauth.ConnectPrincipal{Subject: "ana", Email: "ana@acme.test"}, + UserHeaders: []appoauth.UserHeaderServer{{ + Registry: "Keyed API", Instance: "inst-1", + Fields: []appoauth.UserHeaderField{ + {Name: "X-API-Key", Required: true, Secret: true, Set: true}, + {Name: "X-Account", Value: "acct-visible", Set: true}, + }, + }}, + } +} + +func TestConnectPage_ShowsPerUserHeaderForms(t *testing.T) { + t.Parallel() + for name, code := range map[string]string{"grid": "", "focused on a header-only server": "com.keyed/mcp"} { + h := newTestConnectHandler(&stubConnectService{page: userHeaderPage(code)}, nil, "") + h.holdFor = 0 + _, body := send(t, connectFlowApp(h), httptest.NewRequest(fiber.MethodGet, "/dev/mcp/connect?ticket=abc", nil)) + if !strings.Contains(body, `action="/oauth/user-headers/inst-1?ticket=abc"`) { + t.Fatalf("%s: no save form: %s", name, body) + } + if !strings.Contains(body, `type="password"`) || !strings.Contains(body, "acct-visible") { + t.Fatalf("%s: secret must be a password field and the plain value shown: %s", name, body) + } + if strings.Contains(body, "No third-party providers") { + t.Fatalf("%s: a page with header servers says there is nothing to connect", name) + } + } +} + +func TestSaveUserHeaders_OnlyFromTheGatewaysOwnPage(t *testing.T) { + t.Parallel() + svc := &enrollingConnectService{stubConnectService: &stubConnectService{page: userHeaderPage("")}} + h := newTestConnectHandler(svc, nil, "") + h.holdFor = 0 + app := fiber.New() + app.Post(UserHeadersSavePath, h.SaveUserHeaders) + app.Post(UserHeadersRemovePath, h.RemoveUserHeaders) + + cross := httptest.NewRequest(fiber.MethodPost, "/oauth/user-headers/inst-1?ticket=abc", strings.NewReader("X-API-Key=k")) + cross.Header.Set(fiber.HeaderContentType, fiber.MIMEApplicationForm) + cross.Header.Set("Sec-Fetch-Site", "cross-site") + if res, _ := send(t, app, cross); res.StatusCode == fiber.StatusOK || svc.saved != nil { + t.Fatalf("a cross-site post was accepted (status %d)", res.StatusCode) + } + + own := httptest.NewRequest(fiber.MethodPost, "/oauth/user-headers/inst-1?ticket=abc", strings.NewReader("X-API-Key=k&X-Account=a")) + own.Header.Set(fiber.HeaderContentType, fiber.MIMEApplicationForm) + own.Header.Set("Sec-Fetch-Site", "same-origin") + res, body := send(t, app, own) + if res.StatusCode != fiber.StatusOK || svc.saved["X-API-Key"] != "k" { + t.Fatalf("own-page save failed: %d %v", res.StatusCode, svc.saved) + } + if strings.Contains(body, `value="k"`) { + t.Fatal("the saved secret was echoed into the page") + } + + remove := httptest.NewRequest(fiber.MethodPost, "/oauth/user-headers-remove/inst-1?ticket=abc", nil) + remove.Header.Set("Sec-Fetch-Site", "same-origin") + if res, _ := send(t, app, remove); res.StatusCode != fiber.StatusOK || !svc.removed { + t.Fatalf("remove failed: %d", res.StatusCode) + } +} diff --git a/pkg/api/handler/http/oauth/page_assets.go b/pkg/api/handler/http/oauth/page_assets.go index 4be6164a2..871dd116d 100644 --- a/pkg/api/handler/http/oauth/page_assets.go +++ b/pkg/api/handler/http/oauth/page_assets.go @@ -370,6 +370,30 @@ const alertGlyph = `` +// userHeadersSection lists the servers whose upstream needs the person's own +// header values, with a form to enter, replace or remove them. A secret value +// is never written back into the page: its field stays empty, and leaving it +// empty keeps what is stored. +const userHeadersSection = `{{if .UserHeaders}}
+

Your keys

+

These servers authenticate each person with their own key. Enter yours once: it is stored encrypted in the gateway vault, sent only on your calls, and never shown to the agent.

+{{range .UserHeaders}}
+
+

{{.Registry}}

+ {{if .Missing}}Needs your key{{else}}` + badgeCheck + `Saved{{end}} +
+
+ {{range .Fields}}
+ + + {{if .Description}}

{{.Description}}

{{end}} +
{{end}} +
+
+
+
{{end}} +
{{end}}` + var connectPageTmpl = template.Must(template.New("connect").Parse(` ` + pageFonts + ` @@ -386,7 +410,7 @@ var connectPageTmpl = template.Must(template.New("connect").Parse(`
{{len .Providers}} of {{len .Providers}}
{{end}} -{{if not .Providers}}

No third-party providers are configured for this virtual MCP.

{{end}} +{{if and (not .Providers) (not .UserHeaders)}}

No third-party providers are configured for this virtual MCP.

{{end}}
{{range .Providers}}
@@ -409,6 +433,7 @@ var connectPageTmpl = template.Must(template.New("connect").Parse(` {{end}}
{{end}}
+` + userHeadersSection + ` {{if .ResumeURL}}
Done connecting?
Return to your application to finish signing in.
Continue @@ -509,6 +534,7 @@ var singleConnectPageTmpl = template.Must(template.New("single-connect").Parse(` {{if and .Owner.Name (not .AwaitingAdmin)}}
Linked to{{.Owner.Name}}{{if .Owner.Detail}}{{.Owner.Detail}}{{end}}
{{end}}

` + lockGlyph + `Credentials are encrypted in the gateway vault. The agent never sees the token.

{{end}} +` + userHeadersSection + `
{{if .Found}} diff --git a/pkg/api/handler/http/oauth/pages.go b/pkg/api/handler/http/oauth/pages.go index 85e52a6d8..4e22dc93b 100644 --- a/pkg/api/handler/http/oauth/pages.go +++ b/pkg/api/handler/http/oauth/pages.go @@ -53,6 +53,7 @@ type connectPageView struct { Providers []providerView ResumeURL template.URL Owner ownerView + UserHeaders []appoauth.UserHeaderServer } // ownerView is who an account connected from a page is linked to: Name is @@ -115,7 +116,9 @@ func renderConnectPageAfter(c *fiber.Ctx, page *appoauth.ConnectPage, ticket, fl connectPageReferrerPolicy(c) // A ticket minted for one server (e.g. a Store install) shows the focused // single-server page instead of the full provider grid. - if strings.TrimSpace(page.Code) != "" { + // A server whose only per-person credential is its header keys has no + // account row to focus on: the page lists the keys instead. + if strings.TrimSpace(page.Code) != "" && (len(page.UserHeaders) == 0 || len(providerRowsForPage(page)) > 0) { return renderSingleConnectPage(c, page, ticket, flash, justConnected, catalog) } return renderHTML(c, connectPageTmpl, connectPageView{ @@ -125,6 +128,7 @@ func renderConnectPageAfter(c *fiber.Ctx, page *appoauth.ConnectPage, ticket, fl Providers: decorateProviders(catalog, page.Providers), ResumeURL: template.URL(page.ResumeURL), // #nosec G203 -- the registered redirect_uri, or an https URL checked by NormalizeResumeURL Owner: ownerOf(page.Principal), + UserHeaders: page.UserHeaders, }) } @@ -185,6 +189,7 @@ type singleConnectView struct { Items []string ItemsMore int Owner ownerView + UserHeaders []appoauth.UserHeaderServer } // providerRowsForPage narrows a page's rows to the server it is scoped to: the @@ -214,11 +219,12 @@ func providerRowsForPage(page *appoauth.ConnectPage) []appoauth.ProviderStatus { // no connection (or is not on this consumer) and the page says so. func renderSingleConnectPage(c *fiber.Ctx, page *appoauth.ConnectPage, ticket, flash string, justConnected bool, catalog appcatalog.MCPServerCatalog) error { view := singleConnectView{ - Ticket: ticket, - Flash: flash, - ResumeURL: template.URL(page.ResumeURL), // #nosec G203 -- the registered redirect_uri, or an https URL checked by NormalizeResumeURL - Owner: ownerOf(page.Principal), - AppName: page.ClientName, + Ticket: ticket, + Flash: flash, + ResumeURL: template.URL(page.ResumeURL), // #nosec G203 -- the registered redirect_uri, or an https URL checked by NormalizeResumeURL + Owner: ownerOf(page.Principal), + AppName: page.ClientName, + UserHeaders: page.UserHeaders, } var granted []string for _, p := range providerRowsForPage(page) { diff --git a/pkg/app/oauth/connect.go b/pkg/app/oauth/connect.go index 38830185c..243e1bd4c 100644 --- a/pkg/app/oauth/connect.go +++ b/pkg/app/oauth/connect.go @@ -318,7 +318,12 @@ func (s *connectService) Page(ctx context.Context, ticketID string) (*ConnectPag if err != nil { return nil, err } + userHeaders, err := s.userHeaderServers(ctx, gatewayID, ticket, data, rc) + if err != nil { + return nil, err + } page := &ConnectPage{ + UserHeaders: userHeaders, ConsumerPath: ticket.ConsumerPath, ResumeURL: ticket.ResumeURL, Providers: providers, diff --git a/pkg/app/oauth/connect_types.go b/pkg/app/oauth/connect_types.go index 500d8aea8..a6d9c33fd 100644 --- a/pkg/app/oauth/connect_types.go +++ b/pkg/app/oauth/connect_types.go @@ -219,6 +219,9 @@ type ConnectPage struct { Principal ConnectPrincipal // ClientName is the app the link came from, empty when unknown. ClientName string + // UserHeaders are the servers whose upstream needs this person's own + // header values (an API key), each with what is stored. + UserHeaders []UserHeaderServer } //go:generate mockery --name=ConnectService --dir=. --output=./mocks --filename=oauth_connect_service_mock.go --case=underscore --with-expecter diff --git a/pkg/app/oauth/connect_user_headers.go b/pkg/app/oauth/connect_user_headers.go new file mode 100644 index 000000000..a39343135 --- /dev/null +++ b/pkg/app/oauth/connect_user_headers.go @@ -0,0 +1,285 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package oauth + +import ( + "context" + "errors" + "fmt" + "log/slog" + "strings" + "time" + + appconsumer "github.com/NeuralTrust/TrustGate/pkg/app/consumer" + "github.com/NeuralTrust/TrustGate/pkg/common/logref" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + registrydomain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" +) + +var ( + // ErrUserHeaderServerNotFound: the ticket cannot act on a server with + // per-user headers by that instance id. + ErrUserHeaderServerNotFound = errors.New("oauth connect: no server with per-user headers by that id on this link") + // ErrUserHeaderInvalid wraps a value or field the form cannot accept. The + // text names the header, never the value. + ErrUserHeaderInvalid = errors.New("oauth connect: invalid per-user header value") +) + +// Audit events for per-user header values. They carry the header name and an +// opaque principal reference, never the value. +const ( + UserHeaderAuditSet = "mcp_user_header_set" + UserHeaderAuditRemoved = "mcp_user_header_removed" + UserHeaderAuditReset = "mcp_user_header_reset" + UserHeaderAuditImported = "mcp_user_header_imported" +) + +// UserHeaderField is one per-user header as the connect page shows it to the +// person whose value it is. +type UserHeaderField struct { + Name string + Description string + Required bool + Secret bool + // Set reports whether the person has a value stored. + Set bool + // Rejected reports whether the upstream refused the stored value, so it + // has to be entered again. + Rejected bool + // Value is the stored value of a non-secret header, shown so the person + // can check and edit it. Always empty for a secret header. + Value string + // UpdatedAt is when the value was last written; zero when unset. + UpdatedAt time.Time +} + +// UserHeaderServer is one registry instance whose upstream needs the +// person's own header values. +type UserHeaderServer struct { + Registry string + Instance string + Code string + Fields []UserHeaderField +} + +// Missing reports whether a required header has no usable value, so a call +// to this server is refused until the person enters it. +func (s UserHeaderServer) Missing() bool { + for _, f := range s.Fields { + if f.Required && (!f.Set || f.Rejected) { + return true + } + } + return false +} + +// UserHeaderEnrollment writes and removes a person's per-user header values +// through the connect link they were handed. The link is the authority, as it +// is for connecting an OAuth account: it names the principal the values are +// stored for. +type UserHeaderEnrollment interface { + // SaveUserHeaders stores the values entered for one instance. A secret + // field sent empty keeps the stored value; unknown fields are refused. + SaveUserHeaders(ctx context.Context, ticketID, instanceID string, values map[string]string) error + // RemoveUserHeaders deletes every value the person holds for one instance. + RemoveUserHeaders(ctx context.Context, ticketID, instanceID string) error +} + +var _ UserHeaderEnrollment = (*connectService)(nil) + +// userHeaderServers lists the instances this ticket can enter header values +// for. An application's ticket has none: an application has no individual +// identity to hold a person's key, and the runtime refuses it before reading +// one. +func (s *connectService) userHeaderServers( + ctx context.Context, + gatewayID ids.GatewayID, + ticket *ConnectTicket, + data *appconsumer.Data, + rc *appconsumer.RoutableConsumer, +) ([]UserHeaderServer, error) { + if ticket.Providers != nil || strings.TrimSpace(ticket.PrincipalSub) == "" { + return nil, nil + } + var out []UserHeaderServer + for _, reg := range data.EffectiveRegistries(rc) { + if !userHeaderRegistryAllowed(ticket, reg) { + continue + } + server := UserHeaderServer{Registry: reg.Name, Instance: reg.ID.String(), Code: reg.MCPTarget.Code} + for _, h := range reg.MCPTarget.UserHeaders { + field := UserHeaderField{Name: h.Name, Description: h.Description, Required: h.Required, Secret: h.Secret} + cred, err := s.vault.Find(ctx, gatewayID, ticket.PrincipalSub, registrydomain.UserHeaderVaultProvider(reg.ID, h.Name)) + switch { + case err == nil && cred != nil && cred.AccessToken != "": + field.Set = true + field.Rejected = !cred.ExpiresAt.IsZero() && !cred.ExpiresAt.After(time.Now()) + field.UpdatedAt = cred.UpdatedAt + if !h.Secret { + field.Value = cred.AccessToken + } + case errors.Is(err, vaultdomain.ErrUndecryptable): + field.Set = true + field.Rejected = true + case err != nil && !errors.Is(err, vaultdomain.ErrNotFound): + return nil, fmt.Errorf("oauth connect: read per-user header: %w", err) + } + server.Fields = append(server.Fields, field) + } + out = append(out, server) + } + return out, nil +} + +// userHeaderRegistryAllowed reports whether a person's ticket may show and +// write header values for reg. A ticket pinned to an instance reaches that +// instance only; one pinned to an OAuth provider reaches no header server. +func userHeaderRegistryAllowed(ticket *ConnectTicket, reg *registrydomain.Registry) bool { + if reg == nil || !reg.Enabled || !reg.IsMCP() || !reg.MCPTarget.HasUserHeaders() { + return false + } + if pinned := strings.TrimSpace(ticket.InstanceID); pinned != "" { + return pinned == reg.ID.String() + } + if code := strings.TrimSpace(ticket.Code); code != "" { + return code == strings.TrimSpace(reg.MCPTarget.Code) + } + return strings.TrimSpace(ticket.Provider) == "" +} + +func (s *connectService) userHeaderRegistry( + ctx context.Context, + ticketID, instanceID string, +) (*ConnectTicket, ids.GatewayID, *registrydomain.Registry, error) { + ticket, gatewayID, data, rc, err := s.resolve(ctx, ticketID) + if err != nil { + return nil, ids.GatewayID{}, nil, err + } + if ticket.Providers != nil || strings.TrimSpace(ticket.PrincipalSub) == "" { + return nil, ids.GatewayID{}, nil, ErrUserHeaderServerNotFound + } + for _, reg := range data.EffectiveRegistries(rc) { + if reg != nil && reg.ID.String() == instanceID && userHeaderRegistryAllowed(ticket, reg) { + return ticket, gatewayID, reg, nil + } + } + return nil, ids.GatewayID{}, nil, ErrUserHeaderServerNotFound +} + +func (s *connectService) SaveUserHeaders(ctx context.Context, ticketID, instanceID string, values map[string]string) error { + ticket, gatewayID, reg, err := s.userHeaderRegistry(ctx, ticketID, instanceID) + if err != nil { + return err + } + for name := range values { + if _, ok := reg.MCPTarget.UserHeader(name); !ok { + return fmt.Errorf("%w: %q is not a header of this server", ErrUserHeaderInvalid, name) + } + } + // Every value is checked before any is written, so a bad field never + // leaves the person half enrolled. + writes := make(map[string]string, len(values)) + for _, h := range reg.MCPTarget.UserHeaders { + value, sent := lookupFold(values, h.Name) + value = strings.TrimSpace(value) + if !sent || value == "" { + if !h.Required { + continue + } + if _, err := s.vault.Find(ctx, gatewayID, ticket.PrincipalSub, registrydomain.UserHeaderVaultProvider(reg.ID, h.Name)); err == nil { + continue + } + return fmt.Errorf("%w: header %q needs a value", ErrUserHeaderInvalid, h.Name) + } + if err := registrydomain.ValidateUserHeaderValue(h, value); err != nil { + return fmt.Errorf("%w: %w", ErrUserHeaderInvalid, err) + } + writes[h.Name] = value + } + for name, value := range writes { + if err := WriteUserHeaderValue(ctx, s.vault, gatewayID, ticket.PrincipalSub, reg.ID, name, value); err != nil { + return err + } + AuditUserHeader(ctx, UserHeaderAuditSet, gatewayID, reg.ID, ticket.PrincipalSub, name, "self") + } + return nil +} + +func (s *connectService) RemoveUserHeaders(ctx context.Context, ticketID, instanceID string) error { + ticket, gatewayID, reg, err := s.userHeaderRegistry(ctx, ticketID, instanceID) + if err != nil { + return err + } + for _, h := range reg.MCPTarget.UserHeaders { + err := s.vault.Delete(ctx, gatewayID, ticket.PrincipalSub, registrydomain.UserHeaderVaultProvider(reg.ID, h.Name)) + if err != nil && !errors.Is(err, vaultdomain.ErrNotFound) { + return err + } + if err == nil { + AuditUserHeader(ctx, UserHeaderAuditRemoved, gatewayID, reg.ID, ticket.PrincipalSub, h.Name, "self") + } + } + return nil +} + +// WriteUserHeaderValue stores one person's value for one header of one +// registry instance. Writing clears a refusal mark: the value is new. +func WriteUserHeaderValue( + ctx context.Context, + vault vaultdomain.Repository, + gatewayID ids.GatewayID, + principalSub string, + registryID ids.RegistryID, + header, value string, +) error { + cred, err := vaultdomain.NewCredential(gatewayID, principalSub, + registrydomain.UserHeaderVaultProvider(registryID, header), "", value, "", nil, time.Time{}) + if err != nil { + return err + } + return vault.Upsert(ctx, cred) +} + +// AuditUserHeader records a change to a person's header value, without it. +// actor says who made it: "self", "admin" or "upstream". +func AuditUserHeader( + ctx context.Context, + event string, + gatewayID ids.GatewayID, + registryID ids.RegistryID, + principalSub, header, actor string, +) { + slog.InfoContext(ctx, "security audit", + slog.String("event", event), + slog.String("gateway_id", gatewayID.String()), + slog.String("registry_id", registryID.String()), + slog.String("principal_ref", logref.Opaque(principalSub)), + slog.String("header", header), + slog.String("actor", actor), + ) +} + +func lookupFold(values map[string]string, name string) (string, bool) { + if v, ok := values[name]; ok { + return v, true + } + for k, v := range values { + if strings.EqualFold(k, name) { + return v, true + } + } + return "", false +} diff --git a/pkg/app/oauth/connect_user_headers_test.go b/pkg/app/oauth/connect_user_headers_test.go new file mode 100644 index 000000000..ca2e143d3 --- /dev/null +++ b/pkg/app/oauth/connect_user_headers_test.go @@ -0,0 +1,175 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package oauth_test + +import ( + "context" + "errors" + "testing" + + appconsumer "github.com/NeuralTrust/TrustGate/pkg/app/consumer" + "github.com/NeuralTrust/TrustGate/pkg/app/oauth" + consumerdomain "github.com/NeuralTrust/TrustGate/pkg/domain/consumer" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + registrydomain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" + infraoauth "github.com/NeuralTrust/TrustGate/pkg/infra/oauth" + "github.com/stretchr/testify/require" +) + +type userHeaderFixture struct { + service oauth.ConnectService + enroll oauth.UserHeaderEnrollment + store *memConnectStore + vault *memVaultRepo + gatewayID ids.GatewayID + keyed *registrydomain.Registry + other *registrydomain.Registry +} + +func newUserHeaderFixture(t *testing.T) userHeaderFixture { + t.Helper() + gatewayID := ids.New[ids.GatewayKind]() + keyed, err := registrydomain.NewMCPRegistry(gatewayID, "Keyed API", "", ®istrydomain.MCPTarget{ + URL: "https://keyed.example/mcp", + Auth: ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeNone}, + UserHeaders: []registrydomain.MCPUserHeader{ + {Name: "X-API-Key", Required: true, Secret: true, Description: "Your personal key"}, + {Name: "X-Account", Description: "Account id"}, + }, + }) + require.NoError(t, err) + other, err := registrydomain.NewMCPRegistry(gatewayID, "Plain", "", ®istrydomain.MCPTarget{ + URL: "https://plain.example/mcp", + Auth: ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeNone}, + }) + require.NoError(t, err) + data := appconsumer.NewData(gatewayID, []appconsumer.RoutableConsumer{{ + Consumer: &consumerdomain.Consumer{ + ID: ids.New[ids.ConsumerKind](), GatewayID: gatewayID, + Type: consumerdomain.TypeMCP, Slug: "dev", Active: true, + }, + Registries: []*registrydomain.Registry{keyed, other}, + }}) + store := newMemConnectStore() + vault := &memVaultRepo{} + service := oauth.NewConnectService(store, vault, &stubDataFinder{data: data}, + infraoauth.NewProviderClient(nil), infraoauth.NewUpstreamRegistrar(store, nil), + oauth.NewConnectAuditor(nil), nil, nil, nil, nil) + enroll, ok := service.(oauth.UserHeaderEnrollment) + require.True(t, ok, "the connect service serves per-user header enrollment") + return userHeaderFixture{service: service, enroll: enroll, store: store, vault: vault, + gatewayID: gatewayID, keyed: keyed, other: other} +} + +func (f userHeaderFixture) ticketFor(t *testing.T, sub string) string { + t.Helper() + ticket, err := f.service.CreateTicket(context.Background(), f.gatewayID, sub, "/dev/mcp") + require.NoError(t, err) + return ticket +} + +func TestUserHeaders_PageListsOnlyServersWithHeaders(t *testing.T) { + f := newUserHeaderFixture(t) + page, err := f.service.Page(context.Background(), f.ticketFor(t, "ana")) + require.NoError(t, err) + require.Len(t, page.UserHeaders, 1) + server := page.UserHeaders[0] + require.Equal(t, f.keyed.ID.String(), server.Instance) + require.True(t, server.Missing()) + require.Len(t, server.Fields, 2) + require.False(t, server.Fields[0].Set) +} + +func TestUserHeaders_SaveStoresPerPrincipalAndNeverShowsSecrets(t *testing.T) { + f := newUserHeaderFixture(t) + ctx := context.Background() + ana := f.ticketFor(t, "ana") + require.NoError(t, f.enroll.SaveUserHeaders(ctx, ana, f.keyed.ID.String(), + map[string]string{"x-api-key": "ana-secret", "X-Account": "acct-1"})) + + cred, err := f.vault.Find(ctx, f.gatewayID, "ana", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.NoError(t, err) + require.Equal(t, "ana-secret", cred.AccessToken) + _, err = f.vault.Find(ctx, f.gatewayID, "bruno", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.ErrorIs(t, err, vaultdomain.ErrNotFound) + + page, err := f.service.Page(ctx, ana) + require.NoError(t, err) + fields := page.UserHeaders[0].Fields + require.True(t, fields[0].Set) + require.Empty(t, fields[0].Value, "a secret is never written back into the page") + require.Equal(t, "acct-1", fields[1].Value) + require.False(t, page.UserHeaders[0].Missing()) + + // An empty secret keeps the stored value: the page never sends it back. + require.NoError(t, f.enroll.SaveUserHeaders(ctx, ana, f.keyed.ID.String(), + map[string]string{"X-API-Key": "", "X-Account": "acct-2"})) + cred, err = f.vault.Find(ctx, f.gatewayID, "ana", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.NoError(t, err) + require.Equal(t, "ana-secret", cred.AccessToken) +} + +func TestUserHeaders_SaveRefusesBadInputBeforeWriting(t *testing.T) { + f := newUserHeaderFixture(t) + ctx := context.Background() + ana := f.ticketFor(t, "ana") + cases := map[string]map[string]string{ + "required missing": {"X-Account": "acct"}, + "crlf": {"X-API-Key": "k\r\nX-Evil: 1", "X-Account": "acct"}, + "unknown header": {"X-API-Key": "k", "X-Other": "v"}, + } + for name, values := range cases { + t.Run(name, func(t *testing.T) { + err := f.enroll.SaveUserHeaders(ctx, ana, f.keyed.ID.String(), values) + require.ErrorIs(t, err, oauth.ErrUserHeaderInvalid) + require.NotContains(t, err.Error(), "X-Evil") + _, err = f.vault.Find(ctx, f.gatewayID, "ana", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-Account")) + require.ErrorIs(t, err, vaultdomain.ErrNotFound, "nothing is written when one field is refused") + }) + } +} + +func TestUserHeaders_ScopeOfTheTicket(t *testing.T) { + f := newUserHeaderFixture(t) + ctx := context.Background() + ana := f.ticketFor(t, "ana") + + err := f.enroll.SaveUserHeaders(ctx, ana, f.other.ID.String(), map[string]string{"X-API-Key": "k"}) + require.ErrorIs(t, err, oauth.ErrUserHeaderServerNotFound) + err = f.enroll.SaveUserHeaders(ctx, "no-such-ticket", f.keyed.ID.String(), map[string]string{"X-API-Key": "k"}) + require.True(t, errors.Is(err, oauth.ErrTicketNotFound)) + + pinned, err := f.service.CreateServerTicket(ctx, f.gatewayID, "ana", "/dev/mcp", "", f.other.ID.String()) + require.NoError(t, err) + err = f.enroll.SaveUserHeaders(ctx, pinned, f.keyed.ID.String(), map[string]string{"X-API-Key": "k"}) + require.ErrorIs(t, err, oauth.ErrUserHeaderServerNotFound, "a ticket pinned to another instance cannot write here") +} + +func TestUserHeaders_RemoveDeletesOnlyThisPersonsValues(t *testing.T) { + f := newUserHeaderFixture(t) + ctx := context.Background() + ana, bruno := f.ticketFor(t, "ana"), f.ticketFor(t, "bruno") + require.NoError(t, f.enroll.SaveUserHeaders(ctx, ana, f.keyed.ID.String(), map[string]string{"X-API-Key": "a"})) + require.NoError(t, f.enroll.SaveUserHeaders(ctx, bruno, f.keyed.ID.String(), map[string]string{"X-API-Key": "b"})) + + require.NoError(t, f.enroll.RemoveUserHeaders(ctx, ana, f.keyed.ID.String())) + + _, err := f.vault.Find(ctx, f.gatewayID, "ana", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.ErrorIs(t, err, vaultdomain.ErrNotFound) + cred, err := f.vault.Find(ctx, f.gatewayID, "bruno", registrydomain.UserHeaderVaultProvider(f.keyed.ID, "X-API-Key")) + require.NoError(t, err) + require.Equal(t, "b", cred.AccessToken) +} diff --git a/pkg/server/router/mcp_router.go b/pkg/server/router/mcp_router.go index d8e9ba62c..276f9001f 100644 --- a/pkg/server/router/mcp_router.go +++ b/pkg/server/router/mcp_router.go @@ -155,6 +155,8 @@ func (r *mcpRouter) BuildRoutes(app *fiber.App) error { app.Get(oauthhttp.ConnectStartPath, r.connectHandler.Confirm) app.Get(oauthhttp.ConnectCallbackPath, r.connectHandler.Callback) app.Post(oauthhttp.DisconnectPath, r.connectHandler.Disconnect) + app.Post(oauthhttp.UserHeadersSavePath, r.connectHandler.SaveUserHeaders) + app.Post(oauthhttp.UserHeadersRemovePath, r.connectHandler.RemoveUserHeaders) if r.endUserConnectionsHandler != nil { app.Post("/:slug/connections/links", r.endUserConnectionsHandler.Link) app.Get("/:slug/connections", r.endUserConnectionsHandler.List) From 3aea354e11a4dd26b0b69e1af6b5c93d0d042423 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:30:42 +0100 Subject: [PATCH 05/14] feat(registry): administer per-user header values Admins can now list who holds a value for an instance's per-user headers (when it was written and whether the upstream refused it, never the value), reset one person's values or everyone's, load values in bulk (up to 1000 rows, all validated before any is written) and issue one person the connect link that enters their own values. Values an admin writes on the control plane go to both vault stores, since the MCP data plane reads only the shared Redis. Deleting a registry removes every value entered for it. The vault gains listing and deletion by provider prefix across principals for Postgres, Redis and the fallback composition. The self-service connect page writes through the same path and audit. Refs ENG-3243 --- .../registry/request/user_headers_request.go | 41 ++ .../response/user_headers_response.go | 76 ++++ .../http/registry/user_headers_handler.go | 153 +++++++ pkg/app/oauth/connect_user_headers.go | 60 +-- pkg/app/registry/user_headers.go | 405 ++++++++++++++++++ pkg/app/registry/user_headers_test.go | 221 ++++++++++ pkg/container/modules/mcp.go | 17 + pkg/container/modules/registry.go | 7 + pkg/container/modules/server_admin.go | 3 + pkg/domain/vault/provider_prefix.go | 51 +++ pkg/infra/repository/vault/provider_prefix.go | 229 ++++++++++ .../repository/vault/provider_prefix_test.go | 97 +++++ pkg/server/router/admin_router.go | 9 + 13 files changed, 1318 insertions(+), 51 deletions(-) create mode 100644 pkg/api/handler/http/registry/request/user_headers_request.go create mode 100644 pkg/api/handler/http/registry/response/user_headers_response.go create mode 100644 pkg/api/handler/http/registry/user_headers_handler.go create mode 100644 pkg/app/registry/user_headers.go create mode 100644 pkg/app/registry/user_headers_test.go create mode 100644 pkg/domain/vault/provider_prefix.go create mode 100644 pkg/infra/repository/vault/provider_prefix.go create mode 100644 pkg/infra/repository/vault/provider_prefix_test.go diff --git a/pkg/api/handler/http/registry/request/user_headers_request.go b/pkg/api/handler/http/registry/request/user_headers_request.go new file mode 100644 index 000000000..95d1d9b64 --- /dev/null +++ b/pkg/api/handler/http/registry/request/user_headers_request.go @@ -0,0 +1,41 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package request + +// UserHeaderLinkRequest asks for the connect page one person walks to enter +// their own header values. +type UserHeaderLinkRequest struct { + // PrincipalSub is the person: the subject their token carries, or + // app:: for an end user an application names. + PrincipalSub string `json:"principal_sub"` + // ConsumerPath is the virtual MCP the person reaches the server through. + // Empty uses the MCP Store. + ConsumerPath string `json:"consumer_path,omitempty"` + // ResumeURL is where the page sends the person once they are done. + ResumeURL string `json:"resume_url,omitempty"` +} + +// UserHeaderImportRequest loads values for many people at once. +type UserHeaderImportRequest struct { + Values []UserHeaderImportValue `json:"values"` +} + +// UserHeaderImportValue is one person's value for one header. +type UserHeaderImportValue struct { + PrincipalSub string `json:"principal_sub"` + Header string `json:"header"` + // Value is the person's own value, stored encrypted and never returned. + Value string `json:"value"` +} diff --git a/pkg/api/handler/http/registry/response/user_headers_response.go b/pkg/api/handler/http/registry/response/user_headers_response.go new file mode 100644 index 000000000..c02578ba8 --- /dev/null +++ b/pkg/api/handler/http/registry/response/user_headers_response.go @@ -0,0 +1,76 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package response + +import ( + "time" + + appregistry "github.com/NeuralTrust/TrustGate/pkg/app/registry" +) + +// UserHeaderHoldersResponse lists who holds a value for an instance's +// per-user headers. Values are never returned. +type UserHeaderHoldersResponse struct { + Holders []UserHeaderHolderResponse `json:"holders"` +} + +type UserHeaderHolderResponse struct { + PrincipalSub string `json:"principal_sub"` + Values []UserHeaderValueResponse `json:"values"` + // Missing lists the required headers this person has no usable value for. + Missing []string `json:"missing,omitempty"` +} + +type UserHeaderValueResponse struct { + Header string `json:"header"` + UpdatedAt time.Time `json:"updated_at"` + // RejectedAt is set when the upstream refused the value with a 401. + RejectedAt *time.Time `json:"rejected_at,omitempty"` +} + +// UserHeaderCountResponse reports how many values a reset or import touched. +type UserHeaderCountResponse struct { + Count int `json:"count"` +} + +// UserHeaderLinkResponse is the connect page one person walks. +type UserHeaderLinkResponse struct { + Ticket string `json:"ticket"` + ConsumerPath string `json:"consumer_path"` +} + +func FromUserHeaderHolders(holders []appregistry.UserHeaderHolder) UserHeaderHoldersResponse { + out := UserHeaderHoldersResponse{Holders: make([]UserHeaderHolderResponse, 0, len(holders))} + for _, h := range holders { + row := UserHeaderHolderResponse{PrincipalSub: h.PrincipalSub, Missing: h.Missing} + for _, v := range h.Values { + value := UserHeaderValueResponse{Header: v.Header, UpdatedAt: v.UpdatedAt} + if !v.RejectedAt.IsZero() { + rejected := v.RejectedAt + value.RejectedAt = &rejected + } + row.Values = append(row.Values, value) + } + out.Holders = append(out.Holders, row) + } + return out +} + +func FromUserHeaderLink(l *appregistry.UserHeaderLink) UserHeaderLinkResponse { + if l == nil { + return UserHeaderLinkResponse{} + } + return UserHeaderLinkResponse{Ticket: l.Ticket, ConsumerPath: l.ConsumerPath} +} diff --git a/pkg/api/handler/http/registry/user_headers_handler.go b/pkg/api/handler/http/registry/user_headers_handler.go new file mode 100644 index 000000000..e51bd2b7d --- /dev/null +++ b/pkg/api/handler/http/registry/user_headers_handler.go @@ -0,0 +1,153 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package registry + +import ( + "fmt" + "strings" + + "github.com/NeuralTrust/TrustGate/pkg/api/handler/http/httpio" + "github.com/NeuralTrust/TrustGate/pkg/api/handler/http/registry/request" + "github.com/NeuralTrust/TrustGate/pkg/api/handler/http/registry/response" + appregistry "github.com/NeuralTrust/TrustGate/pkg/app/registry" + commonerrors "github.com/NeuralTrust/TrustGate/pkg/common/errors" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + "github.com/gofiber/fiber/v2" +) + +// UserHeadersHandler serves the per-user header values of an MCP instance as +// an admin sees them: who holds one, resetting them, loading them in bulk and +// handing one person their link. Values are written, never read back. +type UserHeadersHandler struct { + admin appregistry.UserHeaderAdmin +} + +func NewUserHeadersHandler(admin appregistry.UserHeaderAdmin) *UserHeadersHandler { + return &UserHeadersHandler{admin: admin} +} + +// List godoc +// @Summary List who holds per-user header values +// @Description Lists every person holding a value for this MCP instance's per-user headers, when each was written and whether the upstream refused it. Values are never returned. +// @Tags registries +// @Produce json +// @Security BearerAuth +// @Param gateway_id path string true "Gateway id" format(uuid) +// @Param id path string true "Registry id" format(uuid) +// @Success 200 {object} response.UserHeaderHoldersResponse +// @Failure 404 {object} httpio.ErrorBody +// @Failure 409 {object} httpio.ErrorBody +// @Router /v1/gateways/{gateway_id}/registries/{id}/user-headers [get] +func (h *UserHeadersHandler) List(c *fiber.Ctx) error { + gatewayID, id, err := httpio.ParseGatewayScopedID[ids.RegistryKind](c) + if err != nil { + return httpio.WriteError(c, err) + } + holders, err := h.admin.Holders(c.UserContext(), gatewayID, id) + if err != nil { + return httpio.WriteError(c, err) + } + return httpio.WriteOK(c, response.FromUserHeaderHolders(holders)) +} + +// Reset godoc +// @Summary Reset per-user header values +// @Description Removes the values one person holds for this instance (principal_sub), or every person's when principal_sub is omitted. The next call of each affected person answers with a connect link. +// @Tags registries +// @Produce json +// @Security BearerAuth +// @Param gateway_id path string true "Gateway id" format(uuid) +// @Param id path string true "Registry id" format(uuid) +// @Param principal_sub query string false "One person; omitted resets everyone" +// @Success 200 {object} response.UserHeaderCountResponse +// @Failure 404 {object} httpio.ErrorBody +// @Router /v1/gateways/{gateway_id}/registries/{id}/user-headers/values [delete] +func (h *UserHeadersHandler) Reset(c *fiber.Ctx) error { + gatewayID, id, err := httpio.ParseGatewayScopedID[ids.RegistryKind](c) + if err != nil { + return httpio.WriteError(c, err) + } + n, err := h.admin.Reset(c.UserContext(), gatewayID, id, strings.TrimSpace(c.Query("principal_sub"))) + if err != nil { + return httpio.WriteError(c, err) + } + return httpio.WriteOK(c, response.UserHeaderCountResponse{Count: n}) +} + +// Import godoc +// @Summary Load per-user header values in bulk +// @Description Stores values for many people at once (up to 1000 rows). Every row is validated before any is written; values are encrypted and never returned. +// @Tags registries +// @Accept json +// @Produce json +// @Security BearerAuth +// @Param gateway_id path string true "Gateway id" format(uuid) +// @Param id path string true "Registry id" format(uuid) +// @Param body body request.UserHeaderImportRequest true "Values to load" +// @Success 200 {object} response.UserHeaderCountResponse +// @Failure 404 {object} httpio.ErrorBody +// @Failure 409 {object} httpio.ErrorBody +// @Failure 422 {object} httpio.ErrorBody +// @Router /v1/gateways/{gateway_id}/registries/{id}/user-headers/values [put] +func (h *UserHeadersHandler) Import(c *fiber.Ctx) error { + gatewayID, id, err := httpio.ParseGatewayScopedID[ids.RegistryKind](c) + if err != nil { + return httpio.WriteError(c, err) + } + var req request.UserHeaderImportRequest + if err := c.BodyParser(&req); err != nil { + return httpio.WriteError(c, fmt.Errorf("invalid request body: %w", commonerrors.ErrValidation)) + } + rows := make([]appregistry.UserHeaderImportRow, 0, len(req.Values)) + for _, v := range req.Values { + rows = append(rows, appregistry.UserHeaderImportRow{PrincipalSub: v.PrincipalSub, Header: v.Header, Value: v.Value}) + } + n, err := h.admin.Import(c.UserContext(), gatewayID, id, rows) + if err != nil { + return httpio.WriteError(c, err) + } + return httpio.WriteOK(c, response.UserHeaderCountResponse{Count: n}) +} + +// Link godoc +// @Summary Issue one person's link to enter their header values +// @Description Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. +// @Tags registries +// @Accept json +// @Produce json +// @Security BearerAuth +// @Param gateway_id path string true "Gateway id" format(uuid) +// @Param id path string true "Registry id" format(uuid) +// @Param body body request.UserHeaderLinkRequest true "Whose link" +// @Success 200 {object} response.UserHeaderLinkResponse +// @Failure 404 {object} httpio.ErrorBody +// @Failure 409 {object} httpio.ErrorBody +// @Failure 422 {object} httpio.ErrorBody +// @Router /v1/gateways/{gateway_id}/registries/{id}/user-headers/links [post] +func (h *UserHeadersHandler) Link(c *fiber.Ctx) error { + gatewayID, id, err := httpio.ParseGatewayScopedID[ids.RegistryKind](c) + if err != nil { + return httpio.WriteError(c, err) + } + var req request.UserHeaderLinkRequest + if err := c.BodyParser(&req); err != nil { + return httpio.WriteError(c, fmt.Errorf("invalid request body: %w", commonerrors.ErrValidation)) + } + link, err := h.admin.Link(c.UserContext(), gatewayID, id, req.PrincipalSub, req.ConsumerPath, req.ResumeURL) + if err != nil { + return httpio.WriteError(c, err) + } + return httpio.WriteOK(c, response.FromUserHeaderLink(link)) +} diff --git a/pkg/app/oauth/connect_user_headers.go b/pkg/app/oauth/connect_user_headers.go index a39343135..e3d968a7b 100644 --- a/pkg/app/oauth/connect_user_headers.go +++ b/pkg/app/oauth/connect_user_headers.go @@ -18,12 +18,11 @@ import ( "context" "errors" "fmt" - "log/slog" "strings" "time" appconsumer "github.com/NeuralTrust/TrustGate/pkg/app/consumer" - "github.com/NeuralTrust/TrustGate/pkg/common/logref" + appregistry "github.com/NeuralTrust/TrustGate/pkg/app/registry" "github.com/NeuralTrust/TrustGate/pkg/domain/ids" registrydomain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" @@ -38,15 +37,6 @@ var ( ErrUserHeaderInvalid = errors.New("oauth connect: invalid per-user header value") ) -// Audit events for per-user header values. They carry the header name and an -// opaque principal reference, never the value. -const ( - UserHeaderAuditSet = "mcp_user_header_set" - UserHeaderAuditRemoved = "mcp_user_header_removed" - UserHeaderAuditReset = "mcp_user_header_reset" - UserHeaderAuditImported = "mcp_user_header_imported" -) - // UserHeaderField is one per-user header as the connect page shows it to the // person whose value it is. type UserHeaderField struct { @@ -210,10 +200,15 @@ func (s *connectService) SaveUserHeaders(ctx context.Context, ticketID, instance writes[h.Name] = value } for name, value := range writes { - if err := WriteUserHeaderValue(ctx, s.vault, gatewayID, ticket.PrincipalSub, reg.ID, name, value); err != nil { + cred, err := vaultdomain.NewCredential(gatewayID, ticket.PrincipalSub, + registrydomain.UserHeaderVaultProvider(reg.ID, name), "", value, "", nil, time.Time{}) + if err != nil { + return err + } + if err := appregistry.WriteUserHeaderCredential(ctx, s.vault, cred); err != nil { return err } - AuditUserHeader(ctx, UserHeaderAuditSet, gatewayID, reg.ID, ticket.PrincipalSub, name, "self") + appregistry.AuditUserHeader(ctx, nil, appregistry.UserHeaderAuditSet, gatewayID, reg.ID, ticket.PrincipalSub, name, "self") } return nil } @@ -229,49 +224,12 @@ func (s *connectService) RemoveUserHeaders(ctx context.Context, ticketID, instan return err } if err == nil { - AuditUserHeader(ctx, UserHeaderAuditRemoved, gatewayID, reg.ID, ticket.PrincipalSub, h.Name, "self") + appregistry.AuditUserHeader(ctx, nil, appregistry.UserHeaderAuditRemoved, gatewayID, reg.ID, ticket.PrincipalSub, h.Name, "self") } } return nil } -// WriteUserHeaderValue stores one person's value for one header of one -// registry instance. Writing clears a refusal mark: the value is new. -func WriteUserHeaderValue( - ctx context.Context, - vault vaultdomain.Repository, - gatewayID ids.GatewayID, - principalSub string, - registryID ids.RegistryID, - header, value string, -) error { - cred, err := vaultdomain.NewCredential(gatewayID, principalSub, - registrydomain.UserHeaderVaultProvider(registryID, header), "", value, "", nil, time.Time{}) - if err != nil { - return err - } - return vault.Upsert(ctx, cred) -} - -// AuditUserHeader records a change to a person's header value, without it. -// actor says who made it: "self", "admin" or "upstream". -func AuditUserHeader( - ctx context.Context, - event string, - gatewayID ids.GatewayID, - registryID ids.RegistryID, - principalSub, header, actor string, -) { - slog.InfoContext(ctx, "security audit", - slog.String("event", event), - slog.String("gateway_id", gatewayID.String()), - slog.String("registry_id", registryID.String()), - slog.String("principal_ref", logref.Opaque(principalSub)), - slog.String("header", header), - slog.String("actor", actor), - ) -} - func lookupFold(values map[string]string, name string) (string, bool) { if v, ok := values[name]; ok { return v, true diff --git a/pkg/app/registry/user_headers.go b/pkg/app/registry/user_headers.go new file mode 100644 index 000000000..4b199920b --- /dev/null +++ b/pkg/app/registry/user_headers.go @@ -0,0 +1,405 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package registry + +import ( + "context" + "errors" + "fmt" + "log/slog" + "sort" + "strings" + "time" + + appconsumer "github.com/NeuralTrust/TrustGate/pkg/app/consumer" + commonerrors "github.com/NeuralTrust/TrustGate/pkg/common/errors" + "github.com/NeuralTrust/TrustGate/pkg/common/logref" + consumerdomain "github.com/NeuralTrust/TrustGate/pkg/domain/consumer" + "github.com/NeuralTrust/TrustGate/pkg/domain/identity" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + domain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" +) + +// Audit events for per-user header values. They carry the header name and an +// opaque principal reference, never the value. +const ( + UserHeaderAuditSet = "mcp_user_header_set" + UserHeaderAuditRemoved = "mcp_user_header_removed" + UserHeaderAuditReset = "mcp_user_header_reset" + UserHeaderAuditImported = "mcp_user_header_imported" + UserHeaderAuditLink = "mcp_user_header_link_issued" +) + +// MaxUserHeaderImportRows bounds one bulk import request. +const MaxUserHeaderImportRows = 1000 + +var ( + // ErrNoUserHeaders is a registry that declares no per-user header. + ErrNoUserHeaders = fmt.Errorf("registry: this server declares no per-user headers: %w", commonerrors.ErrConflict) + // ErrUserHeaderImportInvalid wraps a row the import refuses. The text names + // the row and the header, never the value. + ErrUserHeaderImportInvalid = fmt.Errorf("registry: invalid per-user header import: %w", commonerrors.ErrValidation) + // ErrUserHeaderAdminUnavailable is a plane whose vault cannot list or + // reset values across people. + ErrUserHeaderAdminUnavailable = fmt.Errorf("registry: per-user header administration is not available here: %w", commonerrors.ErrNotFound) +) + +// UserHeaderValueState is what an admin sees of one person's value for one +// header: whether it exists and when it was written or refused. Never the value. +type UserHeaderValueState struct { + Header string + UpdatedAt time.Time + // RejectedAt is when the upstream refused the value with a 401; zero when + // it has not. + RejectedAt time.Time +} + +// UserHeaderHolder is one person and the values they hold for an instance. +type UserHeaderHolder struct { + PrincipalSub string + Values []UserHeaderValueState + // Missing lists the required headers this person has no usable value for. + Missing []string +} + +// UserHeaderImportRow is one value an admin loads for one person. +type UserHeaderImportRow struct { + PrincipalSub string + Header string + Value string +} + +// UserHeaderLink is a connect page an admin hands one person to enter their +// own values. +type UserHeaderLink struct { + Ticket string + ConsumerPath string +} + +type UserHeaderAdmin interface { + // Holders lists every person holding a value for the instance. + Holders(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID) ([]UserHeaderHolder, error) + // Reset removes the values of one person, or of everyone when + // principalSub is empty, and reports how many it removed. + Reset(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, principalSub string) (int, error) + // Import stores values for many people at once. Every row is checked + // before any is written. + Import(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, rows []UserHeaderImportRow) (int, error) + // Link mints the connect page for one person. consumerPath is the virtual + // MCP the person reaches the server through; empty uses the Store. + Link(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, principalSub, consumerPath, resumeURL string) (*UserHeaderLink, error) +} + +type userHeaderAdmin struct { + registries Finder + vault vaultdomain.Repository + tickets ServerTicketMinter + logger *slog.Logger +} + +func NewUserHeaderAdmin(registries Finder, vault vaultdomain.Repository, tickets ServerTicketMinter, logger *slog.Logger) UserHeaderAdmin { + if logger == nil { + logger = slog.Default() + } + return &userHeaderAdmin{registries: registries, vault: vault, tickets: tickets, logger: logger} +} + +func (s *userHeaderAdmin) registry(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID) (*domain.Registry, error) { + reg, err := s.registries.FindByID(ctx, gatewayID, registryID) + if err != nil { + return nil, err + } + if !reg.IsMCP() || !reg.MCPTarget.HasUserHeaders() { + return nil, ErrNoUserHeaders + } + return reg, nil +} + +func (s *userHeaderAdmin) prefixStore() (vaultdomain.ProviderPrefixStore, error) { + store, ok := s.vault.(vaultdomain.ProviderPrefixStore) + if !ok { + return nil, ErrUserHeaderAdminUnavailable + } + return store, nil +} + +func (s *userHeaderAdmin) Holders(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID) ([]UserHeaderHolder, error) { + reg, err := s.registry(ctx, gatewayID, registryID) + if err != nil { + return nil, err + } + store, err := s.prefixStore() + if err != nil { + return nil, err + } + summaries, err := store.ListByProviderPrefix(ctx, gatewayID, domain.UserHeaderVaultPrefix(reg.ID)) + if err != nil { + return nil, err + } + byName := map[string]string{} + for _, h := range reg.MCPTarget.UserHeaders { + byName[domain.UserHeaderVaultProvider(reg.ID, h.Name)] = h.Name + } + holders := map[string]*UserHeaderHolder{} + now := time.Now() + for _, sum := range summaries { + name, declared := byName[sum.Provider] + if !declared { + // A value for a header the admin has since removed is not used; + // it is not shown either. + continue + } + holder := holders[sum.PrincipalSub] + if holder == nil { + holder = &UserHeaderHolder{PrincipalSub: sum.PrincipalSub} + holders[sum.PrincipalSub] = holder + } + state := UserHeaderValueState{Header: name, UpdatedAt: sum.UpdatedAt} + if !sum.ExpiresAt.IsZero() && !sum.ExpiresAt.After(now) { + state.RejectedAt = sum.ExpiresAt + } + holder.Values = append(holder.Values, state) + } + out := make([]UserHeaderHolder, 0, len(holders)) + for _, holder := range holders { + usable := map[string]bool{} + for _, v := range holder.Values { + usable[strings.ToLower(v.Header)] = v.RejectedAt.IsZero() + } + for _, h := range reg.MCPTarget.UserHeaders { + if h.Required && !usable[strings.ToLower(h.Name)] { + holder.Missing = append(holder.Missing, h.Name) + } + } + out = append(out, *holder) + } + sort.Slice(out, func(i, j int) bool { return out[i].PrincipalSub < out[j].PrincipalSub }) + return out, nil +} + +func (s *userHeaderAdmin) Reset(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, principalSub string) (int, error) { + reg, err := s.registries.FindByID(ctx, gatewayID, registryID) + if err != nil { + return 0, err + } + principalSub = strings.TrimSpace(principalSub) + if principalSub == "" { + store, err := s.prefixStore() + if err != nil { + return 0, err + } + n, err := store.DeleteByProviderPrefix(ctx, gatewayID, domain.UserHeaderVaultPrefix(reg.ID)) + if err != nil { + return 0, err + } + s.audit(ctx, UserHeaderAuditReset, gatewayID, reg.ID, "*", "*") + return n, nil + } + removed := 0 + var headers []domain.MCPUserHeader + if reg.MCPTarget != nil { + headers = reg.MCPTarget.UserHeaders + } + for _, h := range headers { + err := s.vault.Delete(ctx, gatewayID, principalSub, domain.UserHeaderVaultProvider(reg.ID, h.Name)) + switch { + case err == nil: + removed++ + s.audit(ctx, UserHeaderAuditReset, gatewayID, reg.ID, principalSub, h.Name) + case !errors.Is(err, vaultdomain.ErrNotFound): + return removed, err + } + } + return removed, nil +} + +func (s *userHeaderAdmin) Import(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID, rows []UserHeaderImportRow) (int, error) { + reg, err := s.registry(ctx, gatewayID, registryID) + if err != nil { + return 0, err + } + if len(rows) == 0 { + return 0, fmt.Errorf("%w: no rows", ErrUserHeaderImportInvalid) + } + if len(rows) > MaxUserHeaderImportRows { + return 0, fmt.Errorf("%w: at most %d rows per request", ErrUserHeaderImportInvalid, MaxUserHeaderImportRows) + } + creds := make([]*vaultdomain.Credential, 0, len(rows)) + seen := map[string]int{} + for i, row := range rows { + sub := strings.TrimSpace(row.PrincipalSub) + if sub == "" { + return 0, fmt.Errorf("%w: row %d has no principal", ErrUserHeaderImportInvalid, i+1) + } + if !personSubject(sub) { + return 0, fmt.Errorf("%w: row %d names an application or an instance, not a person", ErrUserHeaderImportInvalid, i+1) + } + h, ok := reg.MCPTarget.UserHeader(row.Header) + if !ok { + return 0, fmt.Errorf("%w: row %d: %q is not a header of this server", ErrUserHeaderImportInvalid, i+1, row.Header) + } + value := strings.TrimSpace(row.Value) + if err := domain.ValidateUserHeaderValue(h, value); err != nil { + return 0, fmt.Errorf("%w: row %d: %w", ErrUserHeaderImportInvalid, i+1, err) + } + key := sub + "\x00" + strings.ToLower(h.Name) + if prev, dup := seen[key]; dup { + return 0, fmt.Errorf("%w: rows %d and %d set the same header for the same principal", ErrUserHeaderImportInvalid, prev, i+1) + } + seen[key] = i + 1 + cred, err := vaultdomain.NewCredential(gatewayID, sub, domain.UserHeaderVaultProvider(reg.ID, h.Name), "", value, "", nil, time.Time{}) + if err != nil { + return 0, fmt.Errorf("%w: row %d: %w", ErrUserHeaderImportInvalid, i+1, err) + } + creds = append(creds, cred) + } + written := 0 + for _, cred := range creds { + if err := WriteUserHeaderCredential(ctx, s.vault, cred); err != nil { + return written, err + } + written++ + s.audit(ctx, UserHeaderAuditImported, gatewayID, reg.ID, cred.PrincipalSub, headerOfProvider(cred.Provider)) + } + return written, nil +} + +func (s *userHeaderAdmin) Link( + ctx context.Context, + gatewayID ids.GatewayID, + registryID ids.RegistryID, + principalSub, consumerPath, resumeURL string, +) (*UserHeaderLink, error) { + reg, err := s.registry(ctx, gatewayID, registryID) + if err != nil { + return nil, err + } + principalSub = strings.TrimSpace(principalSub) + if principalSub == "" || !personSubject(principalSub) { + return nil, fmt.Errorf("%w: a person's principal is required", ErrUserHeaderImportInvalid) + } + if s.tickets == nil { + return nil, fmt.Errorf("registry: connect is not available: %w", commonerrors.ErrNotFound) + } + consumerPath = strings.TrimSpace(consumerPath) + if consumerPath == "" { + consumerPath = appconsumer.MCPPath(consumerdomain.StoreSlug) + } + ticket, err := s.tickets.CreateResumableServerTicket( + ctx, gatewayID, principalSub, consumerPath, reg.MCPTarget.Code, reg.ID.String(), strings.TrimSpace(resumeURL), + ) + if err != nil { + return nil, err + } + s.audit(ctx, UserHeaderAuditLink, gatewayID, reg.ID, principalSub, "*") + return &UserHeaderLink{Ticket: ticket, ConsumerPath: consumerPath}, nil +} + +func (s *userHeaderAdmin) audit(ctx context.Context, event string, gatewayID ids.GatewayID, registryID ids.RegistryID, principalSub, header string) { + AuditUserHeader(ctx, s.logger, event, gatewayID, registryID, principalSub, header, "admin") +} + +// WriteUserHeaderCredential stores a per-user header value where the MCP data +// plane reads it. A control-plane vault writes Postgres and reads the shared +// Redis behind it; the data plane reads only that Redis, so the write goes to +// both. Writing clears a refusal mark: the value is new. +func WriteUserHeaderCredential(ctx context.Context, vault vaultdomain.Repository, cred *vaultdomain.Credential) error { + if replicated, ok := vault.(vaultdomain.ReplicatedUpserter); ok { + return replicated.UpsertReplicated(ctx, cred) + } + return vault.Upsert(ctx, cred) +} + +// AuditUserHeader records a change to a person's header value, without it. +// actor says who made it: "self", "admin" or "upstream". +func AuditUserHeader( + ctx context.Context, + logger *slog.Logger, + event string, + gatewayID ids.GatewayID, + registryID ids.RegistryID, + principalSub, header, actor string, +) { + if logger == nil { + logger = slog.Default() + } + ref := principalSub + if principalSub != "*" { + ref = logref.Opaque(principalSub) + } + logger.InfoContext(ctx, "security audit", + slog.String("event", event), + slog.String("gateway_id", gatewayID.String()), + slog.String("registry_id", registryID.String()), + slog.String("principal_ref", ref), + slog.String("header", header), + slog.String("actor", actor), + ) +} + +func headerOfProvider(provider string) string { + if i := strings.LastIndex(provider, ":"); i >= 0 { + return provider[i+1:] + } + return provider +} + +// personSubject reports whether sub can hold a person's values: any subject a +// token carries, or an end user an application named (app::). +// The application itself and an instance's own account are nobody. +func personSubject(sub string) bool { + lowered := strings.ToLower(strings.TrimSpace(sub)) + switch { + case lowered == "": + return false + case strings.HasPrefix(lowered, identity.InstanceSubjectPrefix): + return false + case strings.HasPrefix(lowered, identity.AppSubjectPrefix): + rest := strings.TrimPrefix(lowered, identity.AppSubjectPrefix) + consumer, endUser, ok := strings.Cut(rest, ":") + return ok && consumer != "" && strings.TrimSpace(endUser) != "" + default: + return true + } +} + +// userHeaderValuesCleaner removes every person's header values for a registry +// once it is deleted, so no value outlives the server it was entered for. +type userHeaderValuesCleaner struct { + store vaultdomain.ProviderPrefixStore + logger *slog.Logger +} + +// NewUserHeaderValuesCleaner returns the registry-delete cleanup for per-user +// header values, or nil when the vault cannot remove values across people. +func NewUserHeaderValuesCleaner(vault vaultdomain.Repository, logger *slog.Logger) DependentCleaner { + store, ok := vault.(vaultdomain.ProviderPrefixStore) + if !ok { + return nil + } + return &userHeaderValuesCleaner{store: store, logger: logger} +} + +func (c *userHeaderValuesCleaner) DeleteByRegistry(ctx context.Context, gatewayID ids.GatewayID, registryID ids.RegistryID) error { + n, err := c.store.DeleteByProviderPrefix(ctx, gatewayID, domain.UserHeaderVaultPrefix(registryID)) + if err != nil { + return err + } + if n > 0 { + AuditUserHeader(ctx, c.logger, UserHeaderAuditReset, gatewayID, registryID, "*", "*", "registry_deleted") + } + return nil +} diff --git a/pkg/app/registry/user_headers_test.go b/pkg/app/registry/user_headers_test.go new file mode 100644 index 000000000..378649c77 --- /dev/null +++ b/pkg/app/registry/user_headers_test.go @@ -0,0 +1,221 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package registry_test + +import ( + "context" + "strings" + "sync" + "testing" + "time" + + appregistry "github.com/NeuralTrust/TrustGate/pkg/app/registry" + appmocks "github.com/NeuralTrust/TrustGate/pkg/app/registry/mocks" + commonerrors "github.com/NeuralTrust/TrustGate/pkg/common/errors" + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + domain "github.com/NeuralTrust/TrustGate/pkg/domain/registry" + vaultdomain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" + "github.com/stretchr/testify/mock" + "github.com/stretchr/testify/require" +) + +// prefixVault is an in-memory vault with the admin prefix operations and a +// replicated write, recording which path a write took. +type prefixVault struct { + mu sync.Mutex + creds map[string]*vaultdomain.Credential + replicated int +} + +func newPrefixVault() *prefixVault { return &prefixVault{creds: map[string]*vaultdomain.Credential{}} } + +func vkey(gw ids.GatewayID, sub, provider string) string { + return gw.String() + "\x00" + sub + "\x00" + provider +} + +func (v *prefixVault) Upsert(_ context.Context, c *vaultdomain.Credential) error { + v.mu.Lock() + defer v.mu.Unlock() + cp := *c + cp.UpdatedAt = time.Now() + v.creds[vkey(c.GatewayID, c.PrincipalSub, c.Provider)] = &cp + return nil +} + +func (v *prefixVault) UpsertReplicated(ctx context.Context, c *vaultdomain.Credential) error { + v.replicated++ + return v.Upsert(ctx, c) +} + +func (v *prefixVault) Find(_ context.Context, gw ids.GatewayID, sub, provider string) (*vaultdomain.Credential, error) { + v.mu.Lock() + defer v.mu.Unlock() + c, ok := v.creds[vkey(gw, sub, provider)] + if !ok { + return nil, vaultdomain.ErrNotFound + } + return c, nil +} + +func (v *prefixVault) ListByPrincipal(context.Context, ids.GatewayID, string) ([]*vaultdomain.Credential, error) { + return nil, nil +} + +func (v *prefixVault) Delete(_ context.Context, gw ids.GatewayID, sub, provider string) error { + v.mu.Lock() + defer v.mu.Unlock() + k := vkey(gw, sub, provider) + if _, ok := v.creds[k]; !ok { + return vaultdomain.ErrNotFound + } + delete(v.creds, k) + return nil +} + +func (v *prefixVault) ListByProviderPrefix(_ context.Context, gw ids.GatewayID, prefix string) ([]vaultdomain.CredentialSummary, error) { + v.mu.Lock() + defer v.mu.Unlock() + var out []vaultdomain.CredentialSummary + for _, c := range v.creds { + if c.GatewayID == gw && strings.HasPrefix(c.Provider, prefix) { + out = append(out, vaultdomain.CredentialSummary{ + PrincipalSub: c.PrincipalSub, Provider: c.Provider, ExpiresAt: c.ExpiresAt, UpdatedAt: c.UpdatedAt, + }) + } + } + return out, nil +} + +func (v *prefixVault) DeleteByProviderPrefix(_ context.Context, gw ids.GatewayID, prefix string) (int, error) { + v.mu.Lock() + defer v.mu.Unlock() + n := 0 + for k, c := range v.creds { + if c.GatewayID == gw && strings.HasPrefix(c.Provider, prefix) { + delete(v.creds, k) + n++ + } + } + return n, nil +} + +func keyedRegistry(t *testing.T, gw ids.GatewayID) *domain.Registry { + t.Helper() + reg, err := domain.NewMCPRegistry(gw, "keyed", "", &domain.MCPTarget{ + URL: "https://keyed.example.com/mcp", + Auth: &domain.MCPAuth{Mode: domain.MCPAuthModeNone}, + UserHeaders: []domain.MCPUserHeader{ + {Name: "X-API-Key", Required: true, Secret: true}, + {Name: "X-Account"}, + }, + }) + require.NoError(t, err) + return reg +} + +func TestUserHeaderAdmin_ImportListReset(t *testing.T) { + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + reg := keyedRegistry(t, gw) + finder := appmocks.NewFinder(t) + finder.EXPECT().FindByID(mock.Anything, gw, reg.ID).Return(reg, nil) + vault := newPrefixVault() + admin := appregistry.NewUserHeaderAdmin(finder, vault, &ticketRecorder{}, nil) + + n, err := admin.Import(ctx, gw, reg.ID, []appregistry.UserHeaderImportRow{ + {PrincipalSub: "ana", Header: "x-api-key", Value: "ana-key"}, + {PrincipalSub: "app:c1:bruno", Header: "X-API-Key", Value: "bruno-key"}, + {PrincipalSub: "bruno-oauth", Header: "X-Account", Value: "acct"}, + }) + require.NoError(t, err) + require.Equal(t, 3, n) + require.Equal(t, 3, vault.replicated, "admin writes must reach the data plane's store") + + holders, err := admin.Holders(ctx, gw, reg.ID) + require.NoError(t, err) + require.Len(t, holders, 3) + require.Equal(t, "ana", holders[0].PrincipalSub) + require.Empty(t, holders[0].Missing) + require.Equal(t, "bruno-oauth", holders[2].PrincipalSub) + require.Equal(t, []string{"X-API-Key"}, holders[2].Missing) + + removed, err := admin.Reset(ctx, gw, reg.ID, "ana") + require.NoError(t, err) + require.Equal(t, 1, removed) + removed, err = admin.Reset(ctx, gw, reg.ID, "") + require.NoError(t, err) + require.Equal(t, 2, removed) + holders, err = admin.Holders(ctx, gw, reg.ID) + require.NoError(t, err) + require.Empty(t, holders) +} + +func TestUserHeaderAdmin_ImportRefusesBadRowsBeforeWriting(t *testing.T) { + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + reg := keyedRegistry(t, gw) + finder := appmocks.NewFinder(t) + finder.EXPECT().FindByID(mock.Anything, gw, reg.ID).Return(reg, nil) + cases := map[string][]appregistry.UserHeaderImportRow{ + "unknown header": {{PrincipalSub: "ana", Header: "X-API-Key", Value: "ok"}, {PrincipalSub: "ana", Header: "X-Nope", Value: "v"}}, + "crlf": {{PrincipalSub: "ana", Header: "X-API-Key", Value: "v\r\nX: 1"}}, + "application itself": {{PrincipalSub: "app:c1", Header: "X-API-Key", Value: "v"}}, + "instance subject": {{PrincipalSub: "instance:" + reg.ID.String(), Header: "X-API-Key", Value: "v"}}, + "duplicate": {{PrincipalSub: "ana", Header: "X-API-Key", Value: "a"}, {PrincipalSub: "ana", Header: "x-api-key", Value: "b"}}, + "empty": {}, + } + for name, rows := range cases { + t.Run(name, func(t *testing.T) { + vault := newPrefixVault() + admin := appregistry.NewUserHeaderAdmin(finder, vault, &ticketRecorder{}, nil) + _, err := admin.Import(ctx, gw, reg.ID, rows) + require.ErrorIs(t, err, commonerrors.ErrValidation) + require.NotContains(t, err.Error(), "X: 1", "the error must not echo a value") + require.Empty(t, vault.creds, "nothing is written when one row is refused") + }) + } +} + +func TestUserHeaderAdmin_LinkActsAsThePerson(t *testing.T) { + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + reg := keyedRegistry(t, gw) + finder := appmocks.NewFinder(t) + finder.EXPECT().FindByID(mock.Anything, gw, reg.ID).Return(reg, nil) + tickets := &ticketRecorder{} + admin := appregistry.NewUserHeaderAdmin(finder, newPrefixVault(), tickets, nil) + + link, err := admin.Link(ctx, gw, reg.ID, "ana", "/dev/mcp", "") + require.NoError(t, err) + require.Equal(t, "tk", link.Ticket) + require.Equal(t, "ana", tickets.last.principalSub) + require.Equal(t, reg.ID.String(), tickets.last.instanceID) + require.Equal(t, "/dev/mcp", tickets.last.consumerPath) + + _, err = admin.Link(ctx, gw, reg.ID, "app:c1", "", "") + require.ErrorIs(t, err, commonerrors.ErrValidation) +} + +func TestUserHeaderAdmin_RegistryWithoutUserHeaders(t *testing.T) { + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + reg, err := domain.NewMCPRegistry(gw, "plain", "", &domain.MCPTarget{URL: "https://p.example.com/mcp"}) + require.NoError(t, err) + finder := appmocks.NewFinder(t) + finder.EXPECT().FindByID(mock.Anything, gw, reg.ID).Return(reg, nil) + admin := appregistry.NewUserHeaderAdmin(finder, newPrefixVault(), &ticketRecorder{}, nil) + _, err = admin.Holders(ctx, gw, reg.ID) + require.ErrorIs(t, err, commonerrors.ErrConflict) +} diff --git a/pkg/container/modules/mcp.go b/pkg/container/modules/mcp.go index 20fd9f94c..3e5be240c 100644 --- a/pkg/container/modules/mcp.go +++ b/pkg/container/modules/mcp.go @@ -165,6 +165,12 @@ func MCP(c *container.Container) error { if err := c.Provide(registryhttp.NewSharedAccountHandler); err != nil { return err } + if err := c.Provide(provideRegistryUserHeaders); err != nil { + return err + } + if err := c.Provide(registryhttp.NewUserHeadersHandler); err != nil { + return err + } if err := c.Provide(appmcp.NewPluginRunner); err != nil { return err } @@ -652,6 +658,17 @@ func MCPVaultRedis(c *container.Container) error { }) } +// provideRegistryUserHeaders serves an admin's view of the per-user header +// values people hold for an instance. +func provideRegistryUserHeaders( + registries appregistry.Finder, + vault vaultdomain.Repository, + connect appoauth.ConnectService, + logger *slog.Logger, +) appregistry.UserHeaderAdmin { + return appregistry.NewUserHeaderAdmin(registries, vault, connect, logger) +} + // provideRegistrySharedAccounts serves the account an MCP instance holds for // every caller. It is the connect service the runtime already uses, minting the // ticket for the instance instead of for whoever is calling. diff --git a/pkg/container/modules/registry.go b/pkg/container/modules/registry.go index 3ce144463..a05177047 100644 --- a/pkg/container/modules/registry.go +++ b/pkg/container/modules/registry.go @@ -113,6 +113,8 @@ type registryDeleterCleaners struct { Grants storeaccessdomain.Repository `optional:"true"` Everyone storeaccessdomain.EveryoneRepository `optional:"true"` Installs installationdomain.Repository `optional:"true"` + // Vault holds per-user header values, removed with their registry. + Vault vaultdomain.Repository `optional:"true"` } func (p registryDeleterCleaners) options(logger *slog.Logger) []appregistry.DeleterOption { @@ -123,6 +125,11 @@ func (p registryDeleterCleaners) options(logger *slog.Logger) []appregistry.Dele if p.Everyone != nil { opts = append(opts, appregistry.WithAfterDeleteCleaner(appstore.NewEveryoneRegistryCleaner(p.Everyone))) } + if p.Vault != nil { + if cleaner := appregistry.NewUserHeaderValuesCleaner(p.Vault, logger); cleaner != nil { + opts = append(opts, appregistry.WithAfterDeleteCleaner(cleaner)) + } + } if denier, ok := p.Installs.(installationdomain.PendingDenier); ok { opts = append(opts, appregistry.WithDependentCleaner(appstore.NewDeletedServerRequests(denier, logger))) } diff --git a/pkg/container/modules/server_admin.go b/pkg/container/modules/server_admin.go index 6d2db67be..22a5ed121 100644 --- a/pkg/container/modules/server_admin.go +++ b/pkg/container/modules/server_admin.go @@ -90,6 +90,8 @@ type adminRouterParams struct { ListRegistryTools *registryhttp.ListRegistryToolsHandler // RegistrySharedAccount is absent on planes without the connect service. RegistrySharedAccount *registryhttp.SharedAccountHandler `optional:"true"` + // RegistryUserHeaders is absent on planes without the connect service. + RegistryUserHeaders *registryhttp.UserHeadersHandler `optional:"true"` CreatePolicy *policyhttp.CreatePolicyHandler GetPolicy *policyhttp.GetPolicyHandler @@ -194,6 +196,7 @@ func ServerAdmin(c *container.Container) error { AgentCard: p.AgentCard, ListRegistryTools: p.ListRegistryTools, RegistrySharedAccount: p.RegistrySharedAccount, + RegistryUserHeaders: p.RegistryUserHeaders, CreatePolicy: p.CreatePolicy, GetPolicy: p.GetPolicy, ListPolicy: p.ListPolicy, diff --git a/pkg/domain/vault/provider_prefix.go b/pkg/domain/vault/provider_prefix.go new file mode 100644 index 000000000..ddf9d653b --- /dev/null +++ b/pkg/domain/vault/provider_prefix.go @@ -0,0 +1,51 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package vault + +import ( + "context" + "time" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" +) + +// CredentialSummary is a stored credential without its secrets: who holds it, +// under which provider key, and when it was written or refused. +type CredentialSummary struct { + PrincipalSub string + Provider string + // ExpiresAt is zero for a credential that does not expire. For a value + // with no expiry of its own, a past ExpiresAt is the refusal mark. + ExpiresAt time.Time + CreatedAt time.Time + UpdatedAt time.Time +} + +// ProviderPrefixStore lists and removes credentials of every principal whose +// provider key starts with a prefix: the values every person holds for one +// registry instance, for an admin roster or reset. +type ProviderPrefixStore interface { + ListByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) ([]CredentialSummary, error) + // DeleteByProviderPrefix removes them and reports how many it removed. + DeleteByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) (int, error) +} + +// ReplicatedUpserter is a store that can write a credential everywhere it is +// read from. A control-plane write meant for the MCP data plane uses it: the +// control plane writes to Postgres, and the data plane reads the shared Redis +// vault only. +type ReplicatedUpserter interface { + UpsertReplicated(ctx context.Context, c *Credential) error +} diff --git a/pkg/infra/repository/vault/provider_prefix.go b/pkg/infra/repository/vault/provider_prefix.go new file mode 100644 index 000000000..ff71b6898 --- /dev/null +++ b/pkg/infra/repository/vault/provider_prefix.go @@ -0,0 +1,229 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package vault + +import ( + "context" + "errors" + "fmt" + "sort" + "strings" + "time" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + domain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" + "github.com/NeuralTrust/TrustGate/pkg/infra/cache" + "github.com/NeuralTrust/TrustGate/pkg/infra/database" + "github.com/jackc/pgx/v5" +) + +var ( + _ domain.ProviderPrefixStore = (*Repository)(nil) + _ domain.ProviderPrefixStore = (*redisRepository)(nil) + _ domain.ProviderPrefixStore = (*fallbackRepository)(nil) + _ domain.ReplicatedUpserter = (*fallbackRepository)(nil) +) + +// errEmptyProviderPrefix refuses a prefix that would match every credential. +var errEmptyProviderPrefix = errors.New("vault repository: provider prefix is required") + +func (r *Repository) ListByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) ([]domain.CredentialSummary, error) { + if strings.TrimSpace(prefix) == "" { + return nil, errEmptyProviderPrefix + } + const query = ` + SELECT principal_sub, provider, expires_at, created_at, updated_at + FROM vault_credentials + WHERE gateway_id = $1 AND provider LIKE $2 ESCAPE '\' + ORDER BY principal_sub, provider` + rows, err := r.conn.Pool.Query(ctx, query, gatewayID, likePrefix(prefix)) + if err != nil { + return nil, fmt.Errorf("vault repository: list by provider prefix: %w", err) + } + defer rows.Close() + var out []domain.CredentialSummary + for rows.Next() { + var s domain.CredentialSummary + var expires *time.Time + if err := rows.Scan(&s.PrincipalSub, &s.Provider, &expires, &s.CreatedAt, &s.UpdatedAt); err != nil { + return nil, fmt.Errorf("vault repository: scan summary: %w", err) + } + if expires != nil { + s.ExpiresAt = *expires + } + out = append(out, s) + } + return out, rows.Err() +} + +func (r *Repository) DeleteByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) (int, error) { + if strings.TrimSpace(prefix) == "" { + return 0, errEmptyProviderPrefix + } + const query = `DELETE FROM vault_credentials WHERE gateway_id = $1 AND provider LIKE $2 ESCAPE '\'` + deleted := 0 + err := database.WithTx(ctx, r.conn, func(tx pgx.Tx) error { + tag, err := tx.Exec(ctx, query, gatewayID, likePrefix(prefix)) + if err != nil { + return err + } + deleted = int(tag.RowsAffected()) + return nil + }) + if err != nil { + return 0, fmt.Errorf("vault repository: delete by provider prefix: %w", err) + } + return deleted, nil +} + +// scanProviderPrefix walks every credential of the gateway and hands the ones +// under prefix to visit. Keys cannot be split back into principal and provider +// (either may contain ':'), so each record is read; this is an admin path. +func (r *redisRepository) scanProviderPrefix( + ctx context.Context, + gatewayID ids.GatewayID, + prefix string, + visit func(key string, stored *storedCredential) error, +) error { + if r == nil || r.rc == nil { + return errors.New("vault repository: redis unavailable") + } + if strings.TrimSpace(prefix) == "" { + return errEmptyProviderPrefix + } + match := fmt.Sprintf("%s:%s:*", redisKeyPrefix, escapeGlob(gatewayID.String())) + return cache.ScanKeys(ctx, r.rc, match, redisScanBatchSize, func(ctx context.Context, keys []string) error { + for _, key := range keys { + stored, err := r.load(ctx, key) + if err != nil { + if errors.Is(err, domain.ErrNotFound) { + continue + } + return err + } + if stored.GatewayID != gatewayID || !strings.HasPrefix(stored.Provider, prefix) { + continue + } + if err := visit(key, stored); err != nil { + return err + } + } + return nil + }) +} + +func (r *redisRepository) ListByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) ([]domain.CredentialSummary, error) { + var out []domain.CredentialSummary + err := r.scanProviderPrefix(ctx, gatewayID, prefix, func(_ string, stored *storedCredential) error { + s := domain.CredentialSummary{ + PrincipalSub: stored.PrincipalSub, + Provider: stored.Provider, + CreatedAt: stored.CreatedAt, + UpdatedAt: stored.UpdatedAt, + } + if stored.ExpiresAt != nil { + s.ExpiresAt = *stored.ExpiresAt + } + out = append(out, s) + return nil + }) + if err != nil { + return nil, fmt.Errorf("vault repository: list by provider prefix: %w", err) + } + sortSummaries(out) + return out, nil +} + +func (r *redisRepository) DeleteByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) (int, error) { + var keys []string + err := r.scanProviderPrefix(ctx, gatewayID, prefix, func(key string, _ *storedCredential) error { + keys = append(keys, key) + return nil + }) + if err != nil { + return 0, fmt.Errorf("vault repository: delete by provider prefix: %w", err) + } + if len(keys) == 0 { + return 0, nil + } + n, err := r.rc.Del(ctx, keys...).Result() + if err != nil { + return 0, fmt.Errorf("vault repository: delete by provider prefix: %w", err) + } + return int(n), nil +} + +func (r *fallbackRepository) ListByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) ([]domain.CredentialSummary, error) { + merged := map[string]domain.CredentialSummary{} + for _, store := range []domain.Repository{r.primary, r.fallback} { + lister, ok := store.(domain.ProviderPrefixStore) + if !ok { + continue + } + list, err := lister.ListByProviderPrefix(ctx, gatewayID, prefix) + if err != nil { + return nil, err + } + for _, s := range list { + key := s.PrincipalSub + "\x00" + s.Provider + // The same value written to both stores is one value: keep the + // newer write, which is what a reader sees. + if prev, ok := merged[key]; ok && !s.UpdatedAt.After(prev.UpdatedAt) { + continue + } + merged[key] = s + } + } + out := make([]domain.CredentialSummary, 0, len(merged)) + for _, s := range merged { + out = append(out, s) + } + sortSummaries(out) + return out, nil +} + +func (r *fallbackRepository) DeleteByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) (int, error) { + total := 0 + for _, store := range []domain.Repository{r.primary, r.fallback} { + deleter, ok := store.(domain.ProviderPrefixStore) + if !ok { + continue + } + n, err := deleter.DeleteByProviderPrefix(ctx, gatewayID, prefix) + if err != nil { + return total, err + } + total = max(total, n) + } + return total, nil +} + +// UpsertReplicated writes to both stores, so a value an admin sets on the +// control plane is read by the data plane, which only reads the shared Redis. +func (r *fallbackRepository) UpsertReplicated(ctx context.Context, c *domain.Credential) error { + if err := r.primary.Upsert(ctx, c); err != nil { + return err + } + return r.fallback.Upsert(ctx, c) +} + +func sortSummaries(out []domain.CredentialSummary) { + sort.Slice(out, func(i, j int) bool { + if out[i].PrincipalSub != out[j].PrincipalSub { + return out[i].PrincipalSub < out[j].PrincipalSub + } + return out[i].Provider < out[j].Provider + }) +} diff --git a/pkg/infra/repository/vault/provider_prefix_test.go b/pkg/infra/repository/vault/provider_prefix_test.go new file mode 100644 index 000000000..cffea1802 --- /dev/null +++ b/pkg/infra/repository/vault/provider_prefix_test.go @@ -0,0 +1,97 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package vault_test + +import ( + "context" + "testing" + + "github.com/NeuralTrust/TrustGate/pkg/domain/ids" + domain "github.com/NeuralTrust/TrustGate/pkg/domain/vault" + vaultrepo "github.com/NeuralTrust/TrustGate/pkg/infra/repository/vault" +) + +func TestRedisRepository_ProviderPrefixListsAndDeletesEveryPrincipal(t *testing.T) { + repo, _, _ := newRedisVaultRepo(t) + store, ok := repo.(domain.ProviderPrefixStore) + if !ok { + t.Fatal("redis vault does not implement ProviderPrefixStore") + } + ctx := context.Background() + gw, other := ids.New[ids.GatewayKind](), ids.New[ids.GatewayKind]() + const prefix = "uhdr:reg-1:" + for _, c := range []*domain.Credential{ + newTestCredential(t, gw, "ana", prefix+"X-Api-Key", "a", ""), + newTestCredential(t, gw, "app:c1:bruno", prefix+"X-Api-Key", "b", ""), + newTestCredential(t, gw, "ana", "uhdr:reg-10:X-Api-Key", "c", ""), + newTestCredential(t, gw, "ana", "com.linear/mcp|abcd", "d", "r"), + newTestCredential(t, other, "ana", prefix+"X-Api-Key", "e", ""), + } { + if err := repo.Upsert(ctx, c); err != nil { + t.Fatal(err) + } + } + list, err := store.ListByProviderPrefix(ctx, gw, prefix) + if err != nil { + t.Fatal(err) + } + if len(list) != 2 || list[0].PrincipalSub != "ana" || list[1].PrincipalSub != "app:c1:bruno" { + t.Fatalf("list = %+v, want ana and app:c1:bruno only", list) + } + n, err := store.DeleteByProviderPrefix(ctx, gw, prefix) + if err != nil || n != 2 { + t.Fatalf("deleted %d, err %v; want 2", n, err) + } + if _, err := repo.Find(ctx, gw, "ana", "uhdr:reg-10:X-Api-Key"); err != nil { + t.Fatalf("a sibling registry's value was deleted: %v", err) + } + if _, err := repo.Find(ctx, other, "ana", prefix+"X-Api-Key"); err != nil { + t.Fatalf("another gateway's value was deleted: %v", err) + } + if _, err := store.ListByProviderPrefix(ctx, gw, ""); err == nil { + t.Fatal("an empty prefix must be refused") + } +} + +func TestFallbackRepository_ReplicatedWriteReachesBothStores(t *testing.T) { + primary, _, _ := newRedisVaultRepo(t) + secondary, _, _ := newRedisVaultRepo(t) + repo := vaultrepo.NewFallbackRepository(primary, secondary) + ctx := context.Background() + gw := ids.New[ids.GatewayKind]() + writer, ok := repo.(domain.ReplicatedUpserter) + if !ok { + t.Fatal("fallback vault does not implement ReplicatedUpserter") + } + if err := writer.UpsertReplicated(ctx, newTestCredential(t, gw, "ana", "uhdr:r:X-Api-Key", "v", "")); err != nil { + t.Fatal(err) + } + for name, store := range map[string]domain.Repository{"primary": primary, "secondary": secondary} { + if _, err := store.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err != nil { + t.Fatalf("%s does not hold the value: %v", name, err) + } + } + lister := repo.(domain.ProviderPrefixStore) + list, err := lister.ListByProviderPrefix(ctx, gw, "uhdr:r:") + if err != nil || len(list) != 1 { + t.Fatalf("merged list = %+v err %v; want one entry", list, err) + } + if n, err := lister.DeleteByProviderPrefix(ctx, gw, "uhdr:r:"); err != nil || n != 1 { + t.Fatalf("deleted %d err %v", n, err) + } + if _, err := secondary.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err == nil { + t.Fatal("reset left a live copy on the data plane store") + } +} diff --git a/pkg/server/router/admin_router.go b/pkg/server/router/admin_router.go index 7967b787c..da162d15f 100644 --- a/pkg/server/router/admin_router.go +++ b/pkg/server/router/admin_router.go @@ -87,6 +87,9 @@ type AdminRouterDeps struct { // RegistrySharedAccount serves the upstream account an MCP instance holds // for every caller. Absent on planes without the connect service. RegistrySharedAccount *registryhttp.SharedAccountHandler + // RegistryUserHeaders serves the per-user header values of an MCP + // instance: roster, reset, bulk import and per-person links. + RegistryUserHeaders *registryhttp.UserHeadersHandler CreatePolicy *policyhttp.CreatePolicyHandler GetPolicy *policyhttp.GetPolicyHandler @@ -211,6 +214,12 @@ func (r *adminRouter) BuildRoutes(app *fiber.App) error { registries.Post("/:id/shared-account/connect-link", r.deps.RegistrySharedAccount.ConnectLink) registries.Delete("/:id/shared-account", r.deps.RegistrySharedAccount.Disconnect) } + if r.deps.RegistryUserHeaders != nil { + registries.Get("/:id/user-headers", r.deps.RegistryUserHeaders.List) + registries.Put("/:id/user-headers/values", r.deps.RegistryUserHeaders.Import) + registries.Delete("/:id/user-headers/values", r.deps.RegistryUserHeaders.Reset) + registries.Post("/:id/user-headers/links", r.deps.RegistryUserHeaders.Link) + } registries.Post("/:id/agent-card/refresh", r.deps.AgentCard.Refresh) registries.Post("/:id/agent-card/approve", r.deps.AgentCard.Approve) registries.Put("/:id", r.deps.UpdateRegistry.Handle) From 4d24a4e9f8b54b29a1a83ae04437554d44bf69c7 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:31:11 +0100 Subject: [PATCH 06/14] docs(api): regenerate OpenAPI for per-user upstream headers Adds mcp_target.user_headers and the registry user-headers routes. The regeneration also picks up the A2A agent locator fields already on develop that were not regenerated there. Refs ENG-3243 --- docs/docs.go | 479 ++++++++++++++++++++++++++++++++++++++++- docs/openapi.json | 535 +++++++++++++++++++++++++++++++++++++++++++++- docs/swagger.json | 479 ++++++++++++++++++++++++++++++++++++++++- docs/swagger.yaml | 335 +++++++++++++++++++++++++++++ 4 files changed, 1822 insertions(+), 6 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index 7409fd5ce..ab31d7cf7 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -4040,6 +4040,260 @@ const docTemplate = `{ ] } }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers": { + "get": { + "description": "Lists every person holding a value for this MCP instance's per-user headers, when each was written and whether the upstream refused it. Values are never returned.", + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "List who holds per-user header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/links": { + "post": { + "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Issue one person's link to enter their header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Whose link", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "422": { + "description": "Unprocessable Entity", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/values": { + "put": { + "description": "Stores values for many people at once (up to 1000 rows). Every row is validated before any is written; values are encrypted and never returned.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Load per-user header values in bulk", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Values to load", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "422": { + "description": "Unprocessable Entity", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "description": "Removes the values one person holds for this instance (principal_sub), or every person's when principal_sub is omitted. The next call of each affected person answers with a connect link.", + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Reset per-user header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "One person; omitted resets everyone", + "name": "principal_sub", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, "/v1/gateways/{gateway_id}/store/access-policies": { "get": { "description": "Returns every per-principal Store access level (open | curated | none) set on the gateway, for users and groups.", @@ -9194,6 +9448,9 @@ const docTemplate = `{ "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ATargetRequest": { "type": "object", "properties": { + "agentcore_harness": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator" + }, "allowed_methods": { "type": "array", "items": { @@ -9223,6 +9480,9 @@ const docTemplate = `{ "cloud_auth": { "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ACloudAuthRequest" }, + "databricks_agent": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator" + }, "headers": { "type": "object", "additionalProperties": { @@ -9242,7 +9502,9 @@ const docTemplate = `{ "generic", "bedrock_agentcore", "azure_foundry", - "vertex_agent_engine" + "vertex_agent_engine", + "agentcore_harness", + "databricks_agent" ] }, "url": { @@ -9499,6 +9761,38 @@ const docTemplate = `{ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders declares the upstream headers each caller fills with their\nown value. Omitted on update, the stored declarations are kept; an empty\nlist removes them all.", + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest": { + "type": "object", + "properties": { + "description": { + "description": "Description is the help shown to a person entering their value.", + "type": "string" + }, + "name": { + "description": "Name is the HTTP header sent upstream, e.g. X-API-Key.", + "type": "string" + }, + "required": { + "description": "Required refuses a call with a connect link until the caller has a value.", + "type": "boolean" + }, + "scheme": { + "description": "Scheme is written before the value, e.g. Bearer. Empty sends it raw.", + "type": "string" + }, + "secret": { + "description": "Secret keeps the value masked once entered.", + "type": "boolean" } } }, @@ -9513,6 +9807,9 @@ const docTemplate = `{ "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.PreviewAgentCardRequest": { "type": "object", "properties": { + "agentcore_harness": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator" + }, "allowed_methods": { "type": "array", "items": { @@ -9542,6 +9839,9 @@ const docTemplate = `{ "cloud_auth": { "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ACloudAuthRequest" }, + "databricks_agent": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator" + }, "headers": { "type": "object", "additionalProperties": { @@ -9561,7 +9861,9 @@ const docTemplate = `{ "generic", "bedrock_agentcore", "azure_foundry", - "vertex_agent_engine" + "vertex_agent_engine", + "agentcore_harness", + "databricks_agent" ] }, "url": { @@ -9748,6 +10050,49 @@ const docTemplate = `{ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest": { + "type": "object", + "properties": { + "values": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "principal_sub": { + "type": "string" + }, + "value": { + "description": "Value is the person's own value, stored encrypted and never returned.", + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest": { + "type": "object", + "properties": { + "consumer_path": { + "description": "ConsumerPath is the virtual MCP the person reaches the server through.\nEmpty uses the MCP Store.", + "type": "string" + }, + "principal_sub": { + "description": "PrincipalSub is the person: the subject their token carries, or\napp:\u003cconsumer_id\u003e:\u003cend_user\u003e for an end user an application names.", + "type": "string" + }, + "resume_url": { + "description": "ResumeURL is where the page sends the person once they are done.", + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2AAWSAuthResponse": { "type": "object", "properties": { @@ -9805,6 +10150,9 @@ const docTemplate = `{ "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2ATargetResponse": { "type": "object", "properties": { + "agentcore_harness": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator" + }, "allowed_methods": { "type": "array", "items": { @@ -9838,6 +10186,9 @@ const docTemplate = `{ "cloud_auth": { "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2ACloudAuthResponse" }, + "databricks_agent": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator" + }, "endpoint": { "type": "string" }, @@ -10133,6 +10484,33 @@ const docTemplate = `{ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders are the upstream headers each caller fills with their own\nvalue. Only the declarations: values live per person in the vault.", + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "required": { + "type": "boolean" + }, + "scheme": { + "type": "string" + }, + "secret": { + "type": "boolean" } } }, @@ -10424,6 +10802,72 @@ const docTemplate = `{ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse": { + "type": "object", + "properties": { + "missing": { + "description": "Missing lists the required headers this person has no usable value for.", + "type": "array", + "items": { + "type": "string" + } + }, + "principal_sub": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse": { + "type": "object", + "properties": { + "holders": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse": { + "type": "object", + "properties": { + "consumer_path": { + "type": "string" + }, + "ticket": { + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "rejected_at": { + "description": "RejectedAt is set when the upstream refused the value with a 401.", + "type": "string" + }, + "updated_at": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_store_request.ConfigureLink": { "type": "object", "properties": { @@ -11670,6 +12114,20 @@ const docTemplate = `{ } } }, + "github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator": { + "type": "object", + "properties": { + "app_url": { + "type": "string" + }, + "serving_endpoint": { + "type": "string" + }, + "workspace_url": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_domain_registry.FoundryLocator": { "type": "object", "properties": { @@ -11681,6 +12139,17 @@ const docTemplate = `{ } } }, + "github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator": { + "type": "object", + "properties": { + "harness_arn": { + "type": "string" + }, + "qualifier": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_domain_registry.VertexLocator": { "type": "object", "properties": { @@ -11785,12 +12254,18 @@ const docTemplate = `{ "identity_subject_kind": { "type": "string" }, + "input_tokens": { + "type": "integer" + }, "method": { "type": "string" }, "outcome": { "type": "string" }, + "output_tokens": { + "type": "integer" + }, "protocol_version": { "type": "string" }, diff --git a/docs/openapi.json b/docs/openapi.json index 7f3f9ce2d..aef4d3700 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -5114,6 +5114,316 @@ ] } }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers": { + "get": { + "description": "Lists every person holding a value for this MCP instance's per-user headers, when each was written and whether the upstream refused it. Values are never returned.", + "tags": [ + "registries" + ], + "summary": "List who holds per-user header values", + "parameters": [ + { + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "Registry id", + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/links": { + "post": { + "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them.", + "tags": [ + "registries" + ], + "summary": "Issue one person's link to enter their header values", + "parameters": [ + { + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "Registry id", + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest" + } + } + }, + "description": "Whose link", + "required": true + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "422": { + "description": "Unprocessable Entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/values": { + "put": { + "description": "Stores values for many people at once (up to 1000 rows). Every row is validated before any is written; values are encrypted and never returned.", + "tags": [ + "registries" + ], + "summary": "Load per-user header values in bulk", + "parameters": [ + { + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "Registry id", + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest" + } + } + }, + "description": "Values to load", + "required": true + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + }, + "422": { + "description": "Unprocessable Entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "description": "Removes the values one person holds for this instance (principal_sub), or every person's when principal_sub is omitted. The next call of each affected person answers with a connect link.", + "tags": [ + "registries" + ], + "summary": "Reset per-user header values", + "parameters": [ + { + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "Registry id", + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "description": "One person; omitted resets everyone", + "name": "principal_sub", + "in": "query", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + } + } + }, + "404": { + "description": "Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, "/v1/gateways/{gateway_id}/store/access-policies": { "get": { "description": "Returns every per-principal Store access level (open | curated | none) set on the gateway, for users and groups.", @@ -11088,6 +11398,9 @@ "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ATargetRequest": { "type": "object", "properties": { + "agentcore_harness": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator" + }, "allowed_methods": { "type": "array", "items": { @@ -11117,6 +11430,9 @@ "cloud_auth": { "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ACloudAuthRequest" }, + "databricks_agent": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator" + }, "headers": { "type": "object", "additionalProperties": { @@ -11136,7 +11452,9 @@ "generic", "bedrock_agentcore", "azure_foundry", - "vertex_agent_engine" + "vertex_agent_engine", + "agentcore_harness", + "databricks_agent" ] }, "url": { @@ -11393,6 +11711,38 @@ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders declares the upstream headers each caller fills with their\nown value. Omitted on update, the stored declarations are kept; an empty\nlist removes them all.", + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest": { + "type": "object", + "properties": { + "description": { + "description": "Description is the help shown to a person entering their value.", + "type": "string" + }, + "name": { + "description": "Name is the HTTP header sent upstream, e.g. X-API-Key.", + "type": "string" + }, + "required": { + "description": "Required refuses a call with a connect link until the caller has a value.", + "type": "boolean" + }, + "scheme": { + "description": "Scheme is written before the value, e.g. Bearer. Empty sends it raw.", + "type": "string" + }, + "secret": { + "description": "Secret keeps the value masked once entered.", + "type": "boolean" } } }, @@ -11407,6 +11757,9 @@ "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.PreviewAgentCardRequest": { "type": "object", "properties": { + "agentcore_harness": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator" + }, "allowed_methods": { "type": "array", "items": { @@ -11436,6 +11789,9 @@ "cloud_auth": { "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ACloudAuthRequest" }, + "databricks_agent": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator" + }, "headers": { "type": "object", "additionalProperties": { @@ -11455,7 +11811,9 @@ "generic", "bedrock_agentcore", "azure_foundry", - "vertex_agent_engine" + "vertex_agent_engine", + "agentcore_harness", + "databricks_agent" ] }, "url": { @@ -11642,6 +12000,49 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest": { + "type": "object", + "properties": { + "values": { + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "principal_sub": { + "type": "string" + }, + "value": { + "description": "Value is the person's own value, stored encrypted and never returned.", + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest": { + "type": "object", + "properties": { + "consumer_path": { + "description": "ConsumerPath is the virtual MCP the person reaches the server through.\nEmpty uses the MCP Store.", + "type": "string" + }, + "principal_sub": { + "description": "PrincipalSub is the person: the subject their token carries, or\napp:: for an end user an application names.", + "type": "string" + }, + "resume_url": { + "description": "ResumeURL is where the page sends the person once they are done.", + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2AAWSAuthResponse": { "type": "object", "properties": { @@ -11699,6 +12100,9 @@ "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2ATargetResponse": { "type": "object", "properties": { + "agentcore_harness": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator" + }, "allowed_methods": { "type": "array", "items": { @@ -11732,6 +12136,9 @@ "cloud_auth": { "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2ACloudAuthResponse" }, + "databricks_agent": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator" + }, "endpoint": { "type": "string" }, @@ -12027,6 +12434,33 @@ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders are the upstream headers each caller fills with their own\nvalue. Only the declarations: values live per person in the vault.", + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "required": { + "type": "boolean" + }, + "scheme": { + "type": "string" + }, + "secret": { + "type": "boolean" } } }, @@ -12318,6 +12752,72 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse": { + "type": "object", + "properties": { + "missing": { + "description": "Missing lists the required headers this person has no usable value for.", + "type": "array", + "items": { + "type": "string" + } + }, + "principal_sub": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse": { + "type": "object", + "properties": { + "holders": { + "type": "array", + "items": { + "$ref": "#/components/schemas/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse": { + "type": "object", + "properties": { + "consumer_path": { + "type": "string" + }, + "ticket": { + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "rejected_at": { + "description": "RejectedAt is set when the upstream refused the value with a 401.", + "type": "string" + }, + "updated_at": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_store_request.ConfigureLink": { "type": "object", "properties": { @@ -13564,6 +14064,20 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator": { + "type": "object", + "properties": { + "app_url": { + "type": "string" + }, + "serving_endpoint": { + "type": "string" + }, + "workspace_url": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_domain_registry.FoundryLocator": { "type": "object", "properties": { @@ -13575,6 +14089,17 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator": { + "type": "object", + "properties": { + "harness_arn": { + "type": "string" + }, + "qualifier": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_domain_registry.VertexLocator": { "type": "object", "properties": { @@ -13679,12 +14204,18 @@ "identity_subject_kind": { "type": "string" }, + "input_tokens": { + "type": "integer" + }, "method": { "type": "string" }, "outcome": { "type": "string" }, + "output_tokens": { + "type": "integer" + }, "protocol_version": { "type": "string" }, diff --git a/docs/swagger.json b/docs/swagger.json index 71e6743f1..e6989e896 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -4033,6 +4033,260 @@ ] } }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers": { + "get": { + "description": "Lists every person holding a value for this MCP instance's per-user headers, when each was written and whether the upstream refused it. Values are never returned.", + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "List who holds per-user header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/links": { + "post": { + "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Issue one person's link to enter their header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Whose link", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "422": { + "description": "Unprocessable Entity", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, + "/v1/gateways/{gateway_id}/registries/{id}/user-headers/values": { + "put": { + "description": "Stores values for many people at once (up to 1000 rows). Every row is validated before any is written; values are encrypted and never returned.", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Load per-user header values in bulk", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "description": "Values to load", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "409": { + "description": "Conflict", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + }, + "422": { + "description": "Unprocessable Entity", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + }, + "delete": { + "description": "Removes the values one person holds for this instance (principal_sub), or every person's when principal_sub is omitted. The next call of each affected person answers with a connect link.", + "produces": [ + "application/json" + ], + "tags": [ + "registries" + ], + "summary": "Reset per-user header values", + "parameters": [ + { + "type": "string", + "format": "uuid", + "description": "Gateway id", + "name": "gateway_id", + "in": "path", + "required": true + }, + { + "type": "string", + "format": "uuid", + "description": "Registry id", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "One person; omitted resets everyone", + "name": "principal_sub", + "in": "query" + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody" + } + } + }, + "security": [ + { + "BearerAuth": [] + } + ] + } + }, "/v1/gateways/{gateway_id}/store/access-policies": { "get": { "description": "Returns every per-principal Store access level (open | curated | none) set on the gateway, for users and groups.", @@ -9187,6 +9441,9 @@ "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ATargetRequest": { "type": "object", "properties": { + "agentcore_harness": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator" + }, "allowed_methods": { "type": "array", "items": { @@ -9216,6 +9473,9 @@ "cloud_auth": { "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ACloudAuthRequest" }, + "databricks_agent": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator" + }, "headers": { "type": "object", "additionalProperties": { @@ -9235,7 +9495,9 @@ "generic", "bedrock_agentcore", "azure_foundry", - "vertex_agent_engine" + "vertex_agent_engine", + "agentcore_harness", + "databricks_agent" ] }, "url": { @@ -9492,6 +9754,38 @@ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders declares the upstream headers each caller fills with their\nown value. Omitted on update, the stored declarations are kept; an empty\nlist removes them all.", + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest": { + "type": "object", + "properties": { + "description": { + "description": "Description is the help shown to a person entering their value.", + "type": "string" + }, + "name": { + "description": "Name is the HTTP header sent upstream, e.g. X-API-Key.", + "type": "string" + }, + "required": { + "description": "Required refuses a call with a connect link until the caller has a value.", + "type": "boolean" + }, + "scheme": { + "description": "Scheme is written before the value, e.g. Bearer. Empty sends it raw.", + "type": "string" + }, + "secret": { + "description": "Secret keeps the value masked once entered.", + "type": "boolean" } } }, @@ -9506,6 +9800,9 @@ "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.PreviewAgentCardRequest": { "type": "object", "properties": { + "agentcore_harness": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator" + }, "allowed_methods": { "type": "array", "items": { @@ -9535,6 +9832,9 @@ "cloud_auth": { "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ACloudAuthRequest" }, + "databricks_agent": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator" + }, "headers": { "type": "object", "additionalProperties": { @@ -9554,7 +9854,9 @@ "generic", "bedrock_agentcore", "azure_foundry", - "vertex_agent_engine" + "vertex_agent_engine", + "agentcore_harness", + "databricks_agent" ] }, "url": { @@ -9741,6 +10043,49 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest": { + "type": "object", + "properties": { + "values": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "principal_sub": { + "type": "string" + }, + "value": { + "description": "Value is the person's own value, stored encrypted and never returned.", + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest": { + "type": "object", + "properties": { + "consumer_path": { + "description": "ConsumerPath is the virtual MCP the person reaches the server through.\nEmpty uses the MCP Store.", + "type": "string" + }, + "principal_sub": { + "description": "PrincipalSub is the person: the subject their token carries, or\napp:\u003cconsumer_id\u003e:\u003cend_user\u003e for an end user an application names.", + "type": "string" + }, + "resume_url": { + "description": "ResumeURL is where the page sends the person once they are done.", + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2AAWSAuthResponse": { "type": "object", "properties": { @@ -9798,6 +10143,9 @@ "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2ATargetResponse": { "type": "object", "properties": { + "agentcore_harness": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator" + }, "allowed_methods": { "type": "array", "items": { @@ -9831,6 +10179,9 @@ "cloud_auth": { "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2ACloudAuthResponse" }, + "databricks_agent": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator" + }, "endpoint": { "type": "string" }, @@ -10126,6 +10477,33 @@ }, "url": { "type": "string" + }, + "user_headers": { + "description": "UserHeaders are the upstream headers each caller fills with their own\nvalue. Only the declarations: values live per person in the vault.", + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "name": { + "type": "string" + }, + "required": { + "type": "boolean" + }, + "scheme": { + "type": "string" + }, + "secret": { + "type": "boolean" } } }, @@ -10417,6 +10795,72 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse": { + "type": "object", + "properties": { + "missing": { + "description": "Missing lists the required headers this person has no usable value for.", + "type": "array", + "items": { + "type": "string" + } + }, + "principal_sub": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse": { + "type": "object", + "properties": { + "holders": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse" + } + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse": { + "type": "object", + "properties": { + "consumer_path": { + "type": "string" + }, + "ticket": { + "type": "string" + } + } + }, + "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse": { + "type": "object", + "properties": { + "header": { + "type": "string" + }, + "rejected_at": { + "description": "RejectedAt is set when the upstream refused the value with a 401.", + "type": "string" + }, + "updated_at": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_api_handler_http_store_request.ConfigureLink": { "type": "object", "properties": { @@ -11663,6 +12107,20 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator": { + "type": "object", + "properties": { + "app_url": { + "type": "string" + }, + "serving_endpoint": { + "type": "string" + }, + "workspace_url": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_domain_registry.FoundryLocator": { "type": "object", "properties": { @@ -11674,6 +12132,17 @@ } } }, + "github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator": { + "type": "object", + "properties": { + "harness_arn": { + "type": "string" + }, + "qualifier": { + "type": "string" + } + } + }, "github_com_NeuralTrust_TrustGate_pkg_domain_registry.VertexLocator": { "type": "object", "properties": { @@ -11778,12 +12247,18 @@ "identity_subject_kind": { "type": "string" }, + "input_tokens": { + "type": "integer" + }, "method": { "type": "string" }, "outcome": { "type": "string" }, + "output_tokens": { + "type": "integer" + }, "protocol_version": { "type": "string" }, diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 5fb13abde..4183d0c0f 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1570,6 +1570,8 @@ definitions: type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ATargetRequest: properties: + agentcore_harness: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator' allowed_methods: items: type: string @@ -1590,6 +1592,8 @@ definitions: type: string cloud_auth: $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ACloudAuthRequest' + databricks_agent: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator' headers: additionalProperties: type: string @@ -1605,6 +1609,8 @@ definitions: - bedrock_agentcore - azure_foundry - vertex_agent_engine + - agentcore_harness + - databricks_agent type: string url: type: string @@ -1783,6 +1789,34 @@ definitions: type: string url: type: string + user_headers: + description: |- + UserHeaders declares the upstream headers each caller fills with their + own value. Omitted on update, the stored declarations are kept; an empty + list removes them all. + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.MCPUserHeaderRequest: + properties: + description: + description: Description is the help shown to a person entering their value. + type: string + name: + description: Name is the HTTP header sent upstream, e.g. X-API-Key. + type: string + required: + description: Required refuses a call with a connect link until the caller + has a value. + type: boolean + scheme: + description: Scheme is written before the value, e.g. Bearer. Empty sends + it raw. + type: string + secret: + description: Secret keeps the value masked once entered. + type: boolean type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.OpenAPITargetRequest: properties: @@ -1791,6 +1825,8 @@ definitions: type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.PreviewAgentCardRequest: properties: + agentcore_harness: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator' allowed_methods: items: type: string @@ -1811,6 +1847,8 @@ definitions: type: string cloud_auth: $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.A2ACloudAuthRequest' + databricks_agent: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator' headers: additionalProperties: type: string @@ -1826,6 +1864,8 @@ definitions: - bedrock_agentcore - azure_foundry - vertex_agent_engine + - agentcore_harness + - databricks_agent type: string url: type: string @@ -1952,6 +1992,39 @@ definitions: additionalProperties: {} type: object type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest: + properties: + values: + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportValue: + properties: + header: + type: string + principal_sub: + type: string + value: + description: Value is the person's own value, stored encrypted and never returned. + type: string + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest: + properties: + consumer_path: + description: |- + ConsumerPath is the virtual MCP the person reaches the server through. + Empty uses the MCP Store. + type: string + principal_sub: + description: |- + PrincipalSub is the person: the subject their token carries, or + app:: for an end user an application names. + type: string + resume_url: + description: ResumeURL is where the page sends the person once they are done. + type: string + type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2AAWSAuthResponse: properties: access_key_id: @@ -1990,6 +2063,8 @@ definitions: type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2ATargetResponse: properties: + agentcore_harness: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator' allowed_methods: items: type: string @@ -2012,6 +2087,8 @@ definitions: type: string cloud_auth: $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.A2ACloudAuthResponse' + databricks_agent: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator' endpoint: type: string headers: @@ -2216,6 +2293,26 @@ definitions: type: string url: type: string + user_headers: + description: |- + UserHeaders are the upstream headers each caller fills with their own + value. Only the declarations: values live per person in the vault. + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.MCPUserHeaderResponse: + properties: + description: + type: string + name: + type: string + required: + type: boolean + scheme: + type: string + secret: + type: boolean type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.OpenAPITargetResponse: properties: @@ -2409,6 +2506,51 @@ definitions: type: string type: array type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse: + properties: + count: + type: integer + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse: + properties: + missing: + description: Missing lists the required headers this person has no usable + value for. + items: + type: string + type: array + principal_sub: + type: string + values: + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse: + properties: + holders: + items: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHolderResponse' + type: array + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse: + properties: + consumer_path: + type: string + ticket: + type: string + type: object + github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderValueResponse: + properties: + header: + type: string + rejected_at: + description: RejectedAt is set when the upstream refused the value with a + 401. + type: string + updated_at: + type: string + type: object github_com_NeuralTrust_TrustGate_pkg_api_handler_http_store_request.ConfigureLink: properties: code: @@ -3337,6 +3479,15 @@ definitions: runtime_arn: type: string type: object + github_com_NeuralTrust_TrustGate_pkg_domain_registry.DatabricksLocator: + properties: + app_url: + type: string + serving_endpoint: + type: string + workspace_url: + type: string + type: object github_com_NeuralTrust_TrustGate_pkg_domain_registry.FoundryLocator: properties: agent_name: @@ -3344,6 +3495,13 @@ definitions: project_endpoint: type: string type: object + github_com_NeuralTrust_TrustGate_pkg_domain_registry.HarnessLocator: + properties: + harness_arn: + type: string + qualifier: + type: string + type: object github_com_NeuralTrust_TrustGate_pkg_domain_registry.VertexLocator: properties: location: @@ -3413,10 +3571,14 @@ definitions: type: string identity_subject_kind: type: string + input_tokens: + type: integer method: type: string outcome: type: string + output_tokens: + type: integer protocol_version: type: string provider: @@ -7486,6 +7648,179 @@ paths: summary: List an MCP backend's tools tags: - registries + /v1/gateways/{gateway_id}/registries/{id}/user-headers: + get: + description: Lists every person holding a value for this MCP instance's per-user + headers, when each was written and whether the upstream refused it. Values + are never returned. + parameters: + - description: Gateway id + format: uuid + in: path + name: gateway_id + required: true + type: string + - description: Registry id + format: uuid + in: path + name: id + required: true + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderHoldersResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "409": + description: Conflict + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + security: + - BearerAuth: [] + summary: List who holds per-user header values + tags: + - registries + /v1/gateways/{gateway_id}/registries/{id}/user-headers/links: + post: + consumes: + - application/json + description: 'Mints the connect page one person walks to enter their own values + for this instance. Hand it to that person: it acts as them.' + parameters: + - description: Gateway id + format: uuid + in: path + name: gateway_id + required: true + type: string + - description: Registry id + format: uuid + in: path + name: id + required: true + type: string + - description: Whose link + in: body + name: body + required: true + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderLinkRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderLinkResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "409": + description: Conflict + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "422": + description: Unprocessable Entity + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + security: + - BearerAuth: [] + summary: Issue one person's link to enter their header values + tags: + - registries + /v1/gateways/{gateway_id}/registries/{id}/user-headers/values: + delete: + description: Removes the values one person holds for this instance (principal_sub), + or every person's when principal_sub is omitted. The next call of each affected + person answers with a connect link. + parameters: + - description: Gateway id + format: uuid + in: path + name: gateway_id + required: true + type: string + - description: Registry id + format: uuid + in: path + name: id + required: true + type: string + - description: One person; omitted resets everyone + in: query + name: principal_sub + type: string + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + security: + - BearerAuth: [] + summary: Reset per-user header values + tags: + - registries + put: + consumes: + - application/json + description: Stores values for many people at once (up to 1000 rows). Every + row is validated before any is written; values are encrypted and never returned. + parameters: + - description: Gateway id + format: uuid + in: path + name: gateway_id + required: true + type: string + - description: Registry id + format: uuid + in: path + name: id + required: true + type: string + - description: Values to load + in: body + name: body + required: true + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_request.UserHeaderImportRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_registry_response.UserHeaderCountResponse' + "404": + description: Not Found + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "409": + description: Conflict + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + "422": + description: Unprocessable Entity + schema: + $ref: '#/definitions/github_com_NeuralTrust_TrustGate_pkg_api_handler_http_httpio.ErrorBody' + security: + - BearerAuth: [] + summary: Load per-user header values in bulk + tags: + - registries /v1/gateways/{gateway_id}/registries/from-catalog: post: consumes: From ad5ad5de2e991a88dd7fa619b8a278176fdc7e02 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:34:07 +0100 Subject: [PATCH 07/14] test(functional): per-user upstream headers end to end A header-authenticated MCP upstream registered as a custom server, reached by one application on behalf of two end users. Covers: the application itself refused, a missing key answered with a connect link, a key entered on the connect page and one loaded by an admin, each call carrying only the caller's own key, a client-sent header never reaching the upstream, the admin roster never showing a key, a 401 marking the key for re-entry without retrying it, and an admin reset. Refs ENG-3243 --- tests/functional/mcp_user_headers_test.go | 235 ++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 tests/functional/mcp_user_headers_test.go diff --git a/tests/functional/mcp_user_headers_test.go b/tests/functional/mcp_user_headers_test.go new file mode 100644 index 000000000..1a032d1d7 --- /dev/null +++ b/tests/functional/mcp_user_headers_test.go @@ -0,0 +1,235 @@ +// Copyright 2026 NeuralTrust +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +//go:build functional + +package functional_test + +import ( + "fmt" + "io" + "net/http" + "net/http/httptest" + "net/url" + "strings" + "sync" + "testing" + + sdk "github.com/modelcontextprotocol/go-sdk/mcp" + "github.com/stretchr/testify/require" +) + +// keyedUpstream is an MCP server that authenticates each caller by their own +// X-API-Key, the way an upstream without OAuth does, and records the keys it +// was sent. +type keyedUpstream struct { + server *httptest.Server + mu sync.Mutex + keys []string + revoke map[string]bool +} + +func startKeyedUpstream(t *testing.T) *keyedUpstream { + t.Helper() + mcp := sdk.NewServer(&sdk.Implementation{Name: "keyed-upstream", Version: "1.0"}, nil) + addTool(mcp, "echo") + handler := sdk.NewStreamableHTTPHandler(func(*http.Request) *sdk.Server { return mcp }, nil) + up := &keyedUpstream{revoke: map[string]bool{}} + up.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + key := r.Header.Get("X-API-Key") + up.mu.Lock() + up.keys = append(up.keys, key) + refused := key == "" || up.revoke[key] + up.mu.Unlock() + if refused { + w.WriteHeader(http.StatusUnauthorized) + return + } + handler.ServeHTTP(w, r) + })) + t.Cleanup(up.server.Close) + return up +} + +func (u *keyedUpstream) seen() []string { + u.mu.Lock() + defer u.mu.Unlock() + return append([]string(nil), u.keys...) +} + +func (u *keyedUpstream) reset() { + u.mu.Lock() + defer u.mu.Unlock() + u.keys = nil +} + +func (u *keyedUpstream) refuse(key string) { + u.mu.Lock() + defer u.mu.Unlock() + u.revoke[key] = true +} + +func endUserHeaders(key, endUser string) map[string]string { + return map[string]string{"X-AG-API-Key": key, "X-NeuralTrust-End-User": endUser} +} + +func importUserHeaders(t *testing.T, gatewayID, registryID string, values []map[string]any) { + t.Helper() + target := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers/values", AdminURL, gatewayID, registryID) + status, body := sendRequest(t, http.MethodPut, target, nil, map[string]any{"values": values}) + require.Equal(t, http.StatusOK, status, "import failed: %v", body) + require.Equal(t, float64(len(values)), body["count"]) +} + +// requireConsentCause asserts the -32003 a person gets and returns the +// connect ticket it carries. +func requireConsentCause(t *testing.T, status int, body map[string]any, cause string) string { + t.Helper() + require.Equal(t, http.StatusOK, status) + rpcErr, ok := body["error"].(map[string]any) + require.True(t, ok, "expected a consent error, got %v", body) + require.Equal(t, float64(-32003), rpcErr["code"], "body=%v", body) + data, _ := rpcErr["data"].(map[string]any) + require.Equal(t, cause, data["cause"], "body=%v", body) + link, _ := data["connect_url"].(string) + require.NotEmpty(t, link, "a person is handed the link to enter their key: %v", body) + parsed, err := url.Parse(link) + require.NoError(t, err) + ticket := parsed.Query().Get("ticket") + require.NotEmpty(t, ticket, "the link carries a ticket: %s", link) + return ticket +} + +// enterKeyOnConnectPage does what a person's browser does: open the link, +// then post the form the page shows. +func enterKeyOnConnectPage(t *testing.T, ticket, registryID string, form url.Values) string { + t.Helper() + page := doWith(t, noRedirectClient(), http.MethodGet, MCPURL+"/+/connect?ticket="+url.QueryEscape(ticket), "connect page", nil) + html, err := io.ReadAll(page.Body) + _ = page.Body.Close() + require.NoError(t, err) + require.Equal(t, http.StatusOK, page.StatusCode) + action := "/oauth/user-headers/" + registryID + "?ticket=" + ticket + require.Contains(t, string(html), action, "the page offers the form for this server") + + req, err := http.NewRequest(http.MethodPost, MCPURL+action, strings.NewReader(form.Encode())) + require.NoError(t, err) + req.Header.Set("Content-Type", "application/x-www-form-urlencoded") + req.Header.Set("Origin", MCPURL) + resp, err := noRedirectClient().Do(req) + require.NoError(t, err) + saved, err := io.ReadAll(resp.Body) + _ = resp.Body.Close() + require.NoError(t, err) + require.Equal(t, http.StatusOK, resp.StatusCode, "save failed: %s", saved) + return string(saved) +} + +// Ana and Bruno reach the same header-authenticated upstream through one +// application; each call carries the caller's own key, never the other's, and +// the key never leaves the gateway. +func TestMCPUserHeaders_EachPersonSendsTheirOwnKey(t *testing.T) { + up := startKeyedUpstream(t) + gatewayID := CreateGateway(t, map[string]any{"slug": uniqueName("mcp-gw")}) + registryID := CreateRegistry(t, gatewayID, map[string]any{ + "name": uniqueName("keyed"), "type": "mcp", "weight": 1, + "mcp_target": map[string]any{ + "url": up.server.URL, + "auth": map[string]any{"mode": "none"}, + "user_headers": []map[string]any{ + {"name": "X-API-Key", "required": true, "secret": true, "description": "Your personal API key"}, + }, + }, + }) + consumerID, key := createMCPConsumer(t, gatewayID, []string{registryID}, nil, "") + echo := map[string]any{"name": exposedToolName(registryID, "echo"), "arguments": map[string]any{"message": "hola"}} + ana, bruno := "app:"+consumerID+":ana", "app:"+consumerID+":bruno" + + t.Run("the application itself has no key of its own", func(t *testing.T) { + status, body := mcpRPC(t, gatewayID, consumerID, apiKeyHeaders(key), "tools/call", echo) + requireNotConnected(t, status, body, false) + require.Empty(t, up.seen(), "a refused call must not reach the upstream") + }) + + t.Run("a person without a key enters it through the link they are handed", func(t *testing.T) { + status, body := mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + ticket := requireConsentCause(t, status, body, "user_header_missing") + require.Empty(t, up.seen()) + + page := enterKeyOnConnectPage(t, ticket, registryID, url.Values{"X-API-Key": {"ana-key"}}) + require.NotContains(t, page, "ana-key", "the saved key is never written back into the page") + require.Contains(t, page, "Saved") + }) + + // Bruno's key is loaded by an admin, the other way to enroll. + importUserHeaders(t, gatewayID, registryID, []map[string]any{ + {"principal_sub": bruno, "header": "x-api-key", "value": "bruno-key"}, + }) + + t.Run("each person's call carries their own key", func(t *testing.T) { + for person, want := range map[string]string{"ana": "ana-key", "bruno": "bruno-key"} { + up.reset() + status, body := mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, person), "tools/call", echo) + requireRPCSucceeded(t, status, body) + seen := up.seen() + require.NotEmpty(t, seen, "%s must reach the upstream", person) + for _, got := range seen { + require.Equal(t, want, got, "%s's call carried another key", person) + } + } + }) + + t.Run("a key the client sends never reaches the upstream", func(t *testing.T) { + up.reset() + headers := endUserHeaders(key, "ana") + headers["X-API-Key"] = "forged-key" + status, body := mcpRPC(t, gatewayID, consumerID, headers, "tools/call", echo) + requireRPCSucceeded(t, status, body) + for _, got := range up.seen() { + require.Equal(t, "ana-key", got) + } + }) + + t.Run("an admin sees who holds a key, never the key", func(t *testing.T) { + target := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers", AdminURL, gatewayID, registryID) + status, body := sendRequest(t, http.MethodGet, target, nil, nil) + require.Equal(t, http.StatusOK, status, "body=%v", body) + raw := fmt.Sprint(body) + require.Contains(t, raw, ana) + require.Contains(t, raw, bruno) + require.NotContains(t, raw, "ana-key") + require.NotContains(t, raw, "bruno-key") + }) + + t.Run("a key the upstream refuses must be entered again", func(t *testing.T) { + up.refuse("bruno-key") + status, body := mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "bruno"), "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_rejected") + up.reset() + status, body = mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "bruno"), "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_rejected") + require.Empty(t, up.seen(), "a refused key is not sent again") + + status, body = mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + requireRPCSucceeded(t, status, body) + }) + + t.Run("an admin reset asks everyone for their key again", func(t *testing.T) { + target := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers/values", AdminURL, gatewayID, registryID) + status, body := sendRequest(t, http.MethodDelete, target, nil, nil) + require.Equal(t, http.StatusOK, status, "body=%v", body) + status, body = mcpRPC(t, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_missing") + }) +} From 45ac3983db7a0c11af314920ff27a5f188451215 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:42:18 +0100 Subject: [PATCH 08/14] fix(mcp): mark a per-user key refused only when it caused the 401 A 401 does not say which credential failed. Per-user header values are now marked refused only on a registry whose auth mode sends nothing of its own, and only when the stored value is the one that was sent, so a key replaced during the call is kept and an admin's static key or a caller's token never sends everyone back to re-enter theirs. A caller with no individual identity now reads that the server takes each person's own key, instead of the shared-account remedy that does not apply. Refs ENG-3243 --- pkg/app/mcp/credentials.go | 2 +- pkg/app/mcp/errors.go | 12 ++++++++ pkg/app/mcp/user_headers.go | 35 ++++++++++++++------- pkg/app/mcp/user_headers_test.go | 53 ++++++++++++++++++++++++++++++++ 4 files changed, 90 insertions(+), 12 deletions(-) diff --git a/pkg/app/mcp/credentials.go b/pkg/app/mcp/credentials.go index 4aacc52e8..f36f1dac3 100644 --- a/pkg/app/mcp/credentials.go +++ b/pkg/app/mcp/credentials.go @@ -297,7 +297,7 @@ func (r *credentialResolver) Refresh( ) error { cfg := reg.MCPTarget.Auth if cfg == nil || cfg.Mode != registrydomain.MCPAuthModeForwarded { - return r.refuseRejectedUserHeaders(ctx, rc, reg) + return r.refuseRejectedUserHeaders(ctx, rc, reg, target) } principal := identity.PrincipalFromContext(ctx) if principal == nil { diff --git a/pkg/app/mcp/errors.go b/pkg/app/mcp/errors.go index c38c758b3..2fa0125d4 100644 --- a/pkg/app/mcp/errors.go +++ b/pkg/app/mcp/errors.go @@ -66,6 +66,10 @@ type ApplicationNotConnectedError struct { // calling can connect that one — telling them to link their own would send // them somewhere that changes nothing. Shared bool + // UserKeys marks a server whose upstream takes each person's own key in a + // header: only a person can hold one, so the only remedy is naming who the + // request acts for. A group key is refused the same way. + UserKeys bool } // UnknownToolError is a tools/call name that no bound registry owns. It wraps @@ -105,6 +109,14 @@ func (e *ApplicationNotConnectedError) Error() string { server, ) } + if e.UserKeys { + return fmt.Sprintf( + "mcp: %q takes each person's own key, and this request does not come from one person "+ + "(it carries only the application's key, or a key held for a group). Sign in as the person, "+ + "or send the %s header with the id of the end user it acts for", + server, consumerdomain.EndUserHeader, + ) + } // Every MCP client reads this, not only the SDK, so the remedy is the header // itself rather than a call in one language. return fmt.Sprintf( diff --git a/pkg/app/mcp/user_headers.go b/pkg/app/mcp/user_headers.go index 0a31c7278..370c87692 100644 --- a/pkg/app/mcp/user_headers.go +++ b/pkg/app/mcp/user_headers.go @@ -62,7 +62,7 @@ func (r *credentialResolver) applyUserHeaders( } label := registryLabelFor(reg) if principal.KeyGroup() != "" || principal.Subject == consumerdomain.AppSubject(rc.Consumer.ID) { - return &ApplicationNotConnectedError{Provider: label, Registry: label} + return &ApplicationNotConnectedError{Provider: label, Registry: label, UserKeys: true} } gatewayID := rc.Consumer.GatewayID if target.Headers == nil { @@ -135,14 +135,16 @@ func UserHeaderRejected(cred *vaultdomain.Credential) bool { return cred != nil && !cred.ExpiresAt.IsZero() && !cred.ExpiresAt.After(time.Now()) } -// rejectUserHeaders marks every per-user header value the caller sent to this -// registry as refused, after the upstream answered 401. It reports whether a -// value was marked, so the caller can tell the person to enter it again rather -// than retry with the same key. +// rejectUserHeaders marks the per-user header values the caller sent to this +// registry as refused, after the upstream answered 401. Only a value that is +// still the one sent is marked: a person who replaced their key while the call +// was in flight keeps the new one. It reports whether a value was marked, so +// the caller can tell the person to enter it again rather than retry. func (r *credentialResolver) rejectUserHeaders( ctx context.Context, rc *appconsumer.RoutableConsumer, reg *registrydomain.Registry, + target *Target, ) bool { if r.vault == nil || reg == nil || !reg.MCPTarget.HasUserHeaders() { return false @@ -163,6 +165,9 @@ func (r *credentialResolver) rejectUserHeaders( if err != nil || cred == nil || UserHeaderRejected(cred) { continue } + if target == nil || target.Headers[h.Name] != h.FormatValue(cred.AccessToken) { + continue + } if err := requirer.RequireReconnect(ctx, cred); err != nil && !errors.Is(err, vaultdomain.ErrCredentialChanged) { r.logger.Warn("mcp user headers: could not mark a rejected value", "gateway_id", gatewayID.String(), "registry_id", reg.ID.String(), @@ -179,17 +184,25 @@ func (r *credentialResolver) rejectUserHeaders( } // refuseRejectedUserHeaders answers an upstream 401 on a registry whose only -// per-caller credential is its per-user headers: the values are marked -// refused and the caller gets a connect link to enter them again. The call is -// not retried, since the same values would be refused again. A registry that -// also forwards an OAuth credential refreshes that one instead: a 401 does not -// say which credential failed, and the token is the one that expires. +// credential is its per-user headers: the values are marked refused and the +// caller gets a connect link to enter them again. The call is not retried, +// since the same values would be refused again. +// +// A 401 does not say which credential failed. When the auth mode sends one of +// its own — the admin's static key, a client-credentials token, the caller's +// forwarded or exchanged token — that one may be the cause, and marking every +// caller's key refused would make all of them enter it again for nothing, so +// the 401 is returned as it is. func (r *credentialResolver) refuseRejectedUserHeaders( ctx context.Context, rc *appconsumer.RoutableConsumer, reg *registrydomain.Registry, + target *Target, ) error { - if !r.rejectUserHeaders(ctx, rc, reg) { + if auth := reg.MCPTarget.Auth; auth != nil && auth.Mode != registrydomain.MCPAuthModeNone && auth.Mode != "" { + return errCredentialRefreshUnsupported + } + if !r.rejectUserHeaders(ctx, rc, reg, target) { return errCredentialRefreshUnsupported } principal := identity.PrincipalFromContext(ctx) diff --git a/pkg/app/mcp/user_headers_test.go b/pkg/app/mcp/user_headers_test.go index a320c5ecd..231cb9310 100644 --- a/pkg/app/mcp/user_headers_test.go +++ b/pkg/app/mcp/user_headers_test.go @@ -249,3 +249,56 @@ func TestRefresh_UpstreamRejectsUserHeader(t *testing.T) { } }) } + +func TestRefresh_UserHeaderRejectionIsNarrow(t *testing.T) { + t.Parallel() + gw := ids.New[ids.GatewayKind]() + rc := mcpConsumer(gw) + ctx := principalCtx(&identity.Principal{Subject: "ana"}) + + t.Run("a key replaced while the call was in flight is kept", func(t *testing.T) { + t.Parallel() + vault := userHeaderVault{&memVault{}} + reg := regWithUserHeaders(gw, registrydomain.MCPUserHeader{Name: "X-API-Key", Required: true}) + storeUserHeader(t, vault.memVault, gw, "ana", reg, "X-API-Key", "old") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()).(*credentialResolver) + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatal(err) + } + storeUserHeader(t, vault.memVault, gw, "ana", reg, "X-API-Key", "new") + if err := r.Refresh(ctx, rc, reg, &target); !errors.Is(err, errCredentialRefreshUnsupported) { + t.Fatalf("Refresh() = %v, want the 401 returned as is", err) + } + next := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &next); err != nil || next.Headers["X-API-Key"] != "new" { + t.Fatalf("the new key was marked refused: %v %q", err, next.Headers["X-API-Key"]) + } + }) + + t.Run("an auth mode with a credential of its own leaves the keys alone", func(t *testing.T) { + t.Parallel() + vault := userHeaderVault{&memVault{}} + reg, err := registrydomain.NewMCPRegistry(gw, "both", "", ®istrydomain.MCPTarget{ + URL: "https://both.example.com/mcp", + Auth: ®istrydomain.MCPAuth{Mode: registrydomain.MCPAuthModeStatic, Header: "Authorization", Value: "Bearer admin"}, + UserHeaders: []registrydomain.MCPUserHeader{{Name: "X-API-Key", Required: true}}, + }) + if err != nil { + t.Fatal(err) + } + storeUserHeader(t, vault.memVault, gw, "ana", reg, "X-API-Key", "ana-key") + r := NewCredentialResolver(nil, vault, &stubConnect{}, nil, discardLogger()).(*credentialResolver) + target := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &target); err != nil { + t.Fatal(err) + } + if err := r.Refresh(ctx, rc, reg, &target); !errors.Is(err, errCredentialRefreshUnsupported) { + t.Fatalf("Refresh() = %v, want the 401 returned as is", err) + } + next := targetFor(ctx, rc, reg) + if err := r.Apply(ctx, rc, reg, &next); err != nil { + t.Fatalf("ana's key was marked refused for the admin's credential: %v", err) + } + }) +} From 44ccd2b4f008042a4d9a63e6b0e57f300e5ab672 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:42:18 +0100 Subject: [PATCH 09/14] fix(oauth): a focused page for a key-only server does not wait for it The connect page held up to five seconds for a focused server with no account row, taking it for one not yet synced. A server whose only credential is its per-user keys is here; its key rows count as found. Refs ENG-3243 --- pkg/api/handler/http/oauth/connect_handler.go | 10 ++++++++-- .../oauth/connect_user_headers_handler_test.go | 17 +++++++++++++++++ 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/pkg/api/handler/http/oauth/connect_handler.go b/pkg/api/handler/http/oauth/connect_handler.go index 567962faa..84373d5d9 100644 --- a/pkg/api/handler/http/oauth/connect_handler.go +++ b/pkg/api/handler/http/oauth/connect_handler.go @@ -363,7 +363,7 @@ func (h *ConnectHandler) showPage(c *fiber.Ctx, ticket, flash string) error { // before. A page the ticket does not scope to one server, or whose server is // already here, is returned as it is. func (h *ConnectHandler) awaitServer(ctx context.Context, ticket string, page *appoauth.ConnectPage) *appoauth.ConnectPage { - if strings.TrimSpace(page.Code) == "" || len(providerRowsForPage(page)) > 0 || h.holdFor <= 0 { + if strings.TrimSpace(page.Code) == "" || serverOnPage(page) || h.holdFor <= 0 { return page } deadline := time.NewTimer(h.holdFor) @@ -382,13 +382,19 @@ func (h *ConnectHandler) awaitServer(ctx context.Context, ticket string, page *a return page } page = next - if len(providerRowsForPage(page)) > 0 { + if serverOnPage(page) { return page } } } } +// serverOnPage reports whether the server a focused page is for has reached +// this plane: as an account to connect, or as keys to enter. +func serverOnPage(page *appoauth.ConnectPage) bool { + return len(providerRowsForPage(page)) > 0 || len(page.UserHeaders) > 0 +} + func (h *ConnectHandler) pageError(c *fiber.Ctx, err error) error { if errors.Is(err, appoauth.ErrTicketNotFound) { return fiber.NewError(fiber.StatusUnauthorized, err.Error()) diff --git a/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go b/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go index 9ee6401ba..b19ba430b 100644 --- a/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go +++ b/pkg/api/handler/http/oauth/connect_user_headers_handler_test.go @@ -19,6 +19,7 @@ import ( "net/http/httptest" "strings" "testing" + "time" appoauth "github.com/NeuralTrust/TrustGate/pkg/app/oauth" "github.com/gofiber/fiber/v2" @@ -107,3 +108,19 @@ func TestSaveUserHeaders_OnlyFromTheGatewaysOwnPage(t *testing.T) { t.Fatalf("remove failed: %d", res.StatusCode) } } + +// A focused page for a server whose only credential is its keys is not +// waiting for the server: it is here, with nothing to connect. +func TestConnectPage_HeaderOnlyServerDoesNotWait(t *testing.T) { + t.Parallel() + h := newTestConnectHandler(&stubConnectService{page: userHeaderPage("com.keyed/mcp")}, nil, "") + h.holdFor = time.Minute + started := time.Now() + _, body := send(t, connectFlowApp(h), httptest.NewRequest(fiber.MethodGet, "/dev/mcp/connect?ticket=abc", nil)) + if time.Since(started) > 5*time.Second { + t.Fatalf("the page waited for a server that is already here") + } + if !strings.Contains(body, "/oauth/user-headers/inst-1") { + t.Fatalf("no key form: %s", body) + } +} From 733c5e77ded689036848de76bcb009065ca25f55 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:42:19 +0100 Subject: [PATCH 10/14] fix(registry): keep per-user values in the store every plane reads Values were written to Postgres and Redis, so a key a person removed or replaced on the MCP data plane (which reaches only Redis) left a stale copy the control plane kept reading. They are now written only to the shared Redis behind the control-plane vault, which both planes read, as the data plane's OAuth credentials already are. An admin link for a custom server now requires consumer_path: the Store serves only the servers it materialised, so a Store link showed nothing. Refs ENG-3243 --- .../registry/request/user_headers_request.go | 5 +++-- .../http/registry/user_headers_handler.go | 2 +- pkg/app/registry/user_headers.go | 17 ++++++++++------ pkg/app/registry/user_headers_test.go | 16 ++++++++------- pkg/domain/vault/provider_prefix.go | 13 ++++++------ pkg/infra/repository/vault/provider_prefix.go | 11 ++++------ .../repository/vault/provider_prefix_test.go | 20 +++++++++++-------- 7 files changed, 47 insertions(+), 37 deletions(-) diff --git a/pkg/api/handler/http/registry/request/user_headers_request.go b/pkg/api/handler/http/registry/request/user_headers_request.go index 95d1d9b64..551c3ed8c 100644 --- a/pkg/api/handler/http/registry/request/user_headers_request.go +++ b/pkg/api/handler/http/registry/request/user_headers_request.go @@ -20,8 +20,9 @@ type UserHeaderLinkRequest struct { // PrincipalSub is the person: the subject their token carries, or // app:: for an end user an application names. PrincipalSub string `json:"principal_sub"` - // ConsumerPath is the virtual MCP the person reaches the server through. - // Empty uses the MCP Store. + // ConsumerPath is the virtual MCP the person reaches the server through, + // e.g. /dev/mcp. Required for a custom server; empty uses the MCP Store, + // which serves only the servers it materialised. ConsumerPath string `json:"consumer_path,omitempty"` // ResumeURL is where the page sends the person once they are done. ResumeURL string `json:"resume_url,omitempty"` diff --git a/pkg/api/handler/http/registry/user_headers_handler.go b/pkg/api/handler/http/registry/user_headers_handler.go index e51bd2b7d..637519844 100644 --- a/pkg/api/handler/http/registry/user_headers_handler.go +++ b/pkg/api/handler/http/registry/user_headers_handler.go @@ -123,7 +123,7 @@ func (h *UserHeadersHandler) Import(c *fiber.Ctx) error { // Link godoc // @Summary Issue one person's link to enter their header values -// @Description Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. +// @Description Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. consumer_path names the virtual MCP that binds the server and is required for a custom server. // @Tags registries // @Accept json // @Produce json diff --git a/pkg/app/registry/user_headers.go b/pkg/app/registry/user_headers.go index 4b199920b..7a78571bf 100644 --- a/pkg/app/registry/user_headers.go +++ b/pkg/app/registry/user_headers.go @@ -296,6 +296,12 @@ func (s *userHeaderAdmin) Link( } consumerPath = strings.TrimSpace(consumerPath) if consumerPath == "" { + // Only a server the Store materialised is reached through the Store; a + // custom server is reached through the virtual MCP that binds it, and + // a link to the Store would show the person nothing to fill in. + if reg.MCPTarget.Origin != domain.MCPOriginStore { + return nil, fmt.Errorf("%w: consumer_path is required for a server the Store does not serve", ErrUserHeaderImportInvalid) + } consumerPath = appconsumer.MCPPath(consumerdomain.StoreSlug) } ticket, err := s.tickets.CreateResumableServerTicket( @@ -312,13 +318,12 @@ func (s *userHeaderAdmin) audit(ctx context.Context, event string, gatewayID ids AuditUserHeader(ctx, s.logger, event, gatewayID, registryID, principalSub, header, "admin") } -// WriteUserHeaderCredential stores a per-user header value where the MCP data -// plane reads it. A control-plane vault writes Postgres and reads the shared -// Redis behind it; the data plane reads only that Redis, so the write goes to -// both. Writing clears a refusal mark: the value is new. +// WriteUserHeaderCredential stores a per-user header value in the store every +// plane reads (see vaultdomain.SharedStoreUpserter). Writing clears a refusal +// mark: the value is new. func WriteUserHeaderCredential(ctx context.Context, vault vaultdomain.Repository, cred *vaultdomain.Credential) error { - if replicated, ok := vault.(vaultdomain.ReplicatedUpserter); ok { - return replicated.UpsertReplicated(ctx, cred) + if shared, ok := vault.(vaultdomain.SharedStoreUpserter); ok { + return shared.UpsertShared(ctx, cred) } return vault.Upsert(ctx, cred) } diff --git a/pkg/app/registry/user_headers_test.go b/pkg/app/registry/user_headers_test.go index 378649c77..4b4c6b8c3 100644 --- a/pkg/app/registry/user_headers_test.go +++ b/pkg/app/registry/user_headers_test.go @@ -34,9 +34,9 @@ import ( // prefixVault is an in-memory vault with the admin prefix operations and a // replicated write, recording which path a write took. type prefixVault struct { - mu sync.Mutex - creds map[string]*vaultdomain.Credential - replicated int + mu sync.Mutex + creds map[string]*vaultdomain.Credential + shared int } func newPrefixVault() *prefixVault { return &prefixVault{creds: map[string]*vaultdomain.Credential{}} } @@ -54,8 +54,8 @@ func (v *prefixVault) Upsert(_ context.Context, c *vaultdomain.Credential) error return nil } -func (v *prefixVault) UpsertReplicated(ctx context.Context, c *vaultdomain.Credential) error { - v.replicated++ +func (v *prefixVault) UpsertShared(ctx context.Context, c *vaultdomain.Credential) error { + v.shared++ return v.Upsert(ctx, c) } @@ -141,7 +141,7 @@ func TestUserHeaderAdmin_ImportListReset(t *testing.T) { }) require.NoError(t, err) require.Equal(t, 3, n) - require.Equal(t, 3, vault.replicated, "admin writes must reach the data plane's store") + require.Equal(t, 3, vault.shared, "admin writes must land in the store the data plane reads") holders, err := admin.Holders(ctx, gw, reg.ID) require.NoError(t, err) @@ -204,8 +204,10 @@ func TestUserHeaderAdmin_LinkActsAsThePerson(t *testing.T) { require.Equal(t, reg.ID.String(), tickets.last.instanceID) require.Equal(t, "/dev/mcp", tickets.last.consumerPath) - _, err = admin.Link(ctx, gw, reg.ID, "app:c1", "", "") + _, err = admin.Link(ctx, gw, reg.ID, "app:c1", "/dev/mcp", "") require.ErrorIs(t, err, commonerrors.ErrValidation) + _, err = admin.Link(ctx, gw, reg.ID, "ana", "", "") + require.ErrorIs(t, err, commonerrors.ErrValidation, "a custom server's link names the virtual MCP that binds it") } func TestUserHeaderAdmin_RegistryWithoutUserHeaders(t *testing.T) { diff --git a/pkg/domain/vault/provider_prefix.go b/pkg/domain/vault/provider_prefix.go index ddf9d653b..959b6648e 100644 --- a/pkg/domain/vault/provider_prefix.go +++ b/pkg/domain/vault/provider_prefix.go @@ -42,10 +42,11 @@ type ProviderPrefixStore interface { DeleteByProviderPrefix(ctx context.Context, gatewayID ids.GatewayID, prefix string) (int, error) } -// ReplicatedUpserter is a store that can write a credential everywhere it is -// read from. A control-plane write meant for the MCP data plane uses it: the -// control plane writes to Postgres, and the data plane reads the shared Redis -// vault only. -type ReplicatedUpserter interface { - UpsertReplicated(ctx context.Context, c *Credential) error +// SharedStoreUpserter is a store that can write a credential to the store +// every plane reads. The control-plane vault writes Postgres and reads the +// shared Redis behind it; the MCP data plane reads only that Redis. A value a +// person may write or remove from either plane is kept there alone, so no +// copy in Postgres outlives a change made on the data plane. +type SharedStoreUpserter interface { + UpsertShared(ctx context.Context, c *Credential) error } diff --git a/pkg/infra/repository/vault/provider_prefix.go b/pkg/infra/repository/vault/provider_prefix.go index ff71b6898..99269b672 100644 --- a/pkg/infra/repository/vault/provider_prefix.go +++ b/pkg/infra/repository/vault/provider_prefix.go @@ -33,7 +33,7 @@ var ( _ domain.ProviderPrefixStore = (*Repository)(nil) _ domain.ProviderPrefixStore = (*redisRepository)(nil) _ domain.ProviderPrefixStore = (*fallbackRepository)(nil) - _ domain.ReplicatedUpserter = (*fallbackRepository)(nil) + _ domain.SharedStoreUpserter = (*fallbackRepository)(nil) ) // errEmptyProviderPrefix refuses a prefix that would match every credential. @@ -210,12 +210,9 @@ func (r *fallbackRepository) DeleteByProviderPrefix(ctx context.Context, gateway return total, nil } -// UpsertReplicated writes to both stores, so a value an admin sets on the -// control plane is read by the data plane, which only reads the shared Redis. -func (r *fallbackRepository) UpsertReplicated(ctx context.Context, c *domain.Credential) error { - if err := r.primary.Upsert(ctx, c); err != nil { - return err - } +// UpsertShared writes to the shared store behind the primary, the one the +// data plane reads; the control plane finds it there through the fallback. +func (r *fallbackRepository) UpsertShared(ctx context.Context, c *domain.Credential) error { return r.fallback.Upsert(ctx, c) } diff --git a/pkg/infra/repository/vault/provider_prefix_test.go b/pkg/infra/repository/vault/provider_prefix_test.go index cffea1802..bfc51f340 100644 --- a/pkg/infra/repository/vault/provider_prefix_test.go +++ b/pkg/infra/repository/vault/provider_prefix_test.go @@ -65,23 +65,27 @@ func TestRedisRepository_ProviderPrefixListsAndDeletesEveryPrincipal(t *testing. } } -func TestFallbackRepository_ReplicatedWriteReachesBothStores(t *testing.T) { +func TestFallbackRepository_SharedWriteLandsWhereEveryPlaneReads(t *testing.T) { primary, _, _ := newRedisVaultRepo(t) secondary, _, _ := newRedisVaultRepo(t) repo := vaultrepo.NewFallbackRepository(primary, secondary) ctx := context.Background() gw := ids.New[ids.GatewayKind]() - writer, ok := repo.(domain.ReplicatedUpserter) + writer, ok := repo.(domain.SharedStoreUpserter) if !ok { - t.Fatal("fallback vault does not implement ReplicatedUpserter") + t.Fatal("fallback vault does not implement SharedStoreUpserter") } - if err := writer.UpsertReplicated(ctx, newTestCredential(t, gw, "ana", "uhdr:r:X-Api-Key", "v", "")); err != nil { + if err := writer.UpsertShared(ctx, newTestCredential(t, gw, "ana", "uhdr:r:X-Api-Key", "v", "")); err != nil { t.Fatal(err) } - for name, store := range map[string]domain.Repository{"primary": primary, "secondary": secondary} { - if _, err := store.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err != nil { - t.Fatalf("%s does not hold the value: %v", name, err) - } + if _, err := secondary.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err != nil { + t.Fatalf("the shared store does not hold the value: %v", err) + } + if _, err := primary.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err == nil { + t.Fatal("no copy may stay in the primary, where a data-plane change never reaches") + } + if _, err := repo.Find(ctx, gw, "ana", "uhdr:r:X-Api-Key"); err != nil { + t.Fatalf("the control plane must still read it: %v", err) } lister := repo.(domain.ProviderPrefixStore) list, err := lister.ListByProviderPrefix(ctx, gw, "uhdr:r:") From 5ef09de08d3b490aa943393e665dd232b0914764 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:42:19 +0100 Subject: [PATCH 11/14] docs(api): document consumer_path on per-user header links Refs ENG-3243 --- docs/docs.go | 4 ++-- docs/openapi.json | 4 ++-- docs/swagger.json | 4 ++-- docs/swagger.yaml | 8 +++++--- 4 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/docs.go b/docs/docs.go index ab31d7cf7..37f1d7ce5 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -4097,7 +4097,7 @@ const docTemplate = `{ }, "/v1/gateways/{gateway_id}/registries/{id}/user-headers/links": { "post": { - "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them.", + "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. consumer_path names the virtual MCP that binds the server and is required for a custom server.", "consumes": [ "application/json" ], @@ -10080,7 +10080,7 @@ const docTemplate = `{ "type": "object", "properties": { "consumer_path": { - "description": "ConsumerPath is the virtual MCP the person reaches the server through.\nEmpty uses the MCP Store.", + "description": "ConsumerPath is the virtual MCP the person reaches the server through,\ne.g. /dev/mcp. Required for a custom server; empty uses the MCP Store,\nwhich serves only the servers it materialised.", "type": "string" }, "principal_sub": { diff --git a/docs/openapi.json b/docs/openapi.json index aef4d3700..4cb8438d0 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -5184,7 +5184,7 @@ }, "/v1/gateways/{gateway_id}/registries/{id}/user-headers/links": { "post": { - "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them.", + "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. consumer_path names the virtual MCP that binds the server and is required for a custom server.", "tags": [ "registries" ], @@ -12030,7 +12030,7 @@ "type": "object", "properties": { "consumer_path": { - "description": "ConsumerPath is the virtual MCP the person reaches the server through.\nEmpty uses the MCP Store.", + "description": "ConsumerPath is the virtual MCP the person reaches the server through,\ne.g. /dev/mcp. Required for a custom server; empty uses the MCP Store,\nwhich serves only the servers it materialised.", "type": "string" }, "principal_sub": { diff --git a/docs/swagger.json b/docs/swagger.json index e6989e896..954d993cf 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -4090,7 +4090,7 @@ }, "/v1/gateways/{gateway_id}/registries/{id}/user-headers/links": { "post": { - "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them.", + "description": "Mints the connect page one person walks to enter their own values for this instance. Hand it to that person: it acts as them. consumer_path names the virtual MCP that binds the server and is required for a custom server.", "consumes": [ "application/json" ], @@ -10073,7 +10073,7 @@ "type": "object", "properties": { "consumer_path": { - "description": "ConsumerPath is the virtual MCP the person reaches the server through.\nEmpty uses the MCP Store.", + "description": "ConsumerPath is the virtual MCP the person reaches the server through,\ne.g. /dev/mcp. Required for a custom server; empty uses the MCP Store,\nwhich serves only the servers it materialised.", "type": "string" }, "principal_sub": { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 4183d0c0f..ef440c443 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -2013,8 +2013,9 @@ definitions: properties: consumer_path: description: |- - ConsumerPath is the virtual MCP the person reaches the server through. - Empty uses the MCP Store. + ConsumerPath is the virtual MCP the person reaches the server through, + e.g. /dev/mcp. Required for a custom server; empty uses the MCP Store, + which serves only the servers it materialised. type: string principal_sub: description: |- @@ -7691,7 +7692,8 @@ paths: consumes: - application/json description: 'Mints the connect page one person walks to enter their own values - for this instance. Hand it to that person: it acts as them.' + for this instance. Hand it to that person: it acts as them. consumer_path + names the virtual MCP that binds the server and is required for a custom server.' parameters: - description: Gateway id format: uuid From b7295a7e322a1c75d1b8a295f21219545a92abec Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:42:19 +0100 Subject: [PATCH 12/14] test(functional): per-user headers on the data plane and with OAuth inbound Adds a DB-less MCP plane receiving a key an admin loaded on the control plane, and a person signed in with the IdP who enrolls through an admin-issued link for a custom server. Refs ENG-3243 --- tests/functional/mcp_user_headers_test.go | 110 ++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/tests/functional/mcp_user_headers_test.go b/tests/functional/mcp_user_headers_test.go index 1a032d1d7..0e421ea05 100644 --- a/tests/functional/mcp_user_headers_test.go +++ b/tests/functional/mcp_user_headers_test.go @@ -17,6 +17,7 @@ package functional_test import ( + "encoding/json" "fmt" "io" "net/http" @@ -25,6 +26,7 @@ import ( "strings" "sync" "testing" + "time" sdk "github.com/modelcontextprotocol/go-sdk/mcp" "github.com/stretchr/testify/require" @@ -233,3 +235,111 @@ func TestMCPUserHeaders_EachPersonSendsTheirOwnKey(t *testing.T) { _ = requireConsentCause(t, status, body, "user_header_missing") }) } + +// mcpRPCAt is mcpRPC against a given MCP plane. +func mcpRPCAt(t *testing.T, base, gatewayID, consumerID string, headers map[string]string, method string, params any) (int, map[string]any) { + t.Helper() + raw, err := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": 1, "method": method, "params": params}) + require.NoError(t, err) + req, err := http.NewRequest(http.MethodPost, base+"/"+ConsumerSlug(t, consumerID)+"/mcp", strings.NewReader(string(raw))) + require.NoError(t, err) + req.Header.Set("Content-Type", "application/json") + req.Header.Set("Accept", "application/json") + for k, v := range headers { + req.Header.Set(k, v) + } + host, ok := gatewayHosts.Load(gatewayID) + require.True(t, ok, "gateway host missing for %s", gatewayID) + req.Host = host.(string) + return doJSONRequest(t, req) +} + +// On the MCP plane as production runs it — no database, reading the vault +// from the shared Redis only — a key an admin loads on the control plane is +// the key the plane sends, and an admin reset reaches it too. +func TestDBLessMCP_UserHeaderLoadedByAnAdminReachesTheDataPlane(t *testing.T) { + defer Track(t, "DBLessDataPlane")() + up := startKeyedUpstream(t) + gatewayID := CreateGateway(t, map[string]any{"slug": uniqueName("dbless-keyed")}) + registryID := CreateRegistry(t, gatewayID, map[string]any{ + "name": uniqueName("keyed"), "type": "mcp", "weight": 1, + "mcp_target": map[string]any{ + "url": up.server.URL, + "auth": map[string]any{"mode": "none"}, + "user_headers": []map[string]any{{"name": "X-API-Key", "required": true, "secret": true}}, + }, + }) + consumerID, key := createMCPConsumer(t, gatewayID, []string{registryID}, nil, "") + importUserHeaders(t, gatewayID, registryID, []map[string]any{ + {"principal_sub": "app:" + consumerID + ":ana", "header": "X-API-Key", "value": "ana-dbless-key"}, + }) + echo := map[string]any{"name": exposedToolName(registryID, "echo"), "arguments": map[string]any{"message": "hola"}} + + base, logs := startDBLessMCPPlane(t, GlobalConfig.Server.MCPPort+106, uniqueName("dbless-keyed")) + require.Eventually(t, func() bool { + up.reset() + status, body := mcpRPCAt(t, base, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + if status != http.StatusOK || body["error"] != nil { + return false + } + for _, got := range up.seen() { + if got != "ana-dbless-key" { + return false + } + } + return len(up.seen()) > 0 + }, 30*time.Second, 300*time.Millisecond, "the db-less plane never sent the imported key; logs:\n%s", logs.String()) + require.NotContains(t, logs.String(), "ana-dbless-key", "the key must never reach the plane's logs") + + target := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers/values", AdminURL, gatewayID, registryID) + status, body := sendRequest(t, http.MethodDelete, target, nil, nil) + require.Equal(t, http.StatusOK, status, "body=%v", body) + status, body = mcpRPCAt(t, base, gatewayID, consumerID, endUserHeaders(key, "ana"), "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_missing") +} + +// A person who signs in with the customer's IdP (OAuth inbound) holds their +// own key too: an admin hands them the link for a custom server through the +// virtual MCP that binds it, they enter the key on the page, and their calls +// carry it. +func TestMCPUserHeaders_OAuthCallerEnrollsThroughAnAdminLink(t *testing.T) { + up := startKeyedUpstream(t) + gatewayID := CreateGateway(t, map[string]any{"slug": uniqueName("mcp-gw")}) + registryID := CreateRegistry(t, gatewayID, map[string]any{ + "name": uniqueName("keyed"), "type": "mcp", "weight": 1, + "mcp_target": map[string]any{ + "url": up.server.URL, + "auth": map[string]any{"mode": "none"}, + "user_headers": []map[string]any{{"name": "X-API-Key", "required": true, "secret": true}}, + }, + }) + idp := newOAuthIDPStub(t) + consumerID, audience := createOAuthMCPConsumer(t, gatewayID, []string{registryID}, idp) + subject := uniqueName("carla") + carla := bearerHeaders(idp.mint(t, audience, map[string]any{"sub": subject})) + echo := map[string]any{"name": exposedToolName(registryID, "echo"), "arguments": map[string]any{"message": "hola"}} + + status, body := mcpRPC(t, gatewayID, consumerID, carla, "tools/call", echo) + _ = requireConsentCause(t, status, body, "user_header_missing") + + links := fmt.Sprintf("%s/v1/gateways/%s/registries/%s/user-headers/links", AdminURL, gatewayID, registryID) + status, body = sendRequest(t, http.MethodPost, links, nil, map[string]any{"principal_sub": subject}) + require.Equal(t, http.StatusUnprocessableEntity, status, "a custom server's link must name its virtual MCP: %v", body) + + consumerPath := "/" + ConsumerSlug(t, consumerID) + "/mcp" + status, body = sendRequest(t, http.MethodPost, links, nil, map[string]any{"principal_sub": subject, "consumer_path": consumerPath}) + require.Equal(t, http.StatusOK, status, "body=%v", body) + ticket, _ := body["ticket"].(string) + require.NotEmpty(t, ticket, "body=%v", body) + + enterKeyOnConnectPage(t, ticket, registryID, url.Values{"X-API-Key": {"carla-key"}}) + + up.reset() + status, body = mcpRPC(t, gatewayID, consumerID, carla, "tools/call", echo) + requireRPCSucceeded(t, status, body) + seen := up.seen() + require.NotEmpty(t, seen) + for _, got := range seen { + require.Equal(t, "carla-key", got) + } +} From 568d8d8f8b1bbc6fe9a20bdb0156c8994a15549e Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 15:53:45 +0100 Subject: [PATCH 13/14] test(registry): use a fixture gitleaks does not read as a key The per-user header value fixture looked like a live API key. Renamed, and the old commit's fingerprint is added to .gitleaksignore since the scan reads every commit. Refs ENG-3243 --- .gitleaksignore | 2 ++ pkg/domain/registry/mcp_user_headers_test.go | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.gitleaksignore b/.gitleaksignore index 6b3ce24df..44047b1e0 100644 --- a/.gitleaksignore +++ b/.gitleaksignore @@ -22,3 +22,5 @@ c2db9eae55225cbd50eeae07e73e11c2d1926e8b:postman/TrustGate-TrustGuard-E2E.postma 85c20374762fee0cf6fe1e184988a4ef214ecc62:pkg/app/oauth/connect_admin_row_test.go:generic-api-key:147 # credentials_test.go fake JWT {"alg":"RS256"}.{"sub":"x"}.sig, a bearer that must stay an API key (generic-api-key). d2210babd81542e4d28229fcbc37f7bd52fdc1dc:pkg/infra/providers/credentials_test.go:generic-api-key:194 +# mcp_user_headers_test.go fake per-user header value, since renamed (generic-api-key). +bb4c66398bdc2315629232d10de4ea81f6dd1e34:pkg/domain/registry/mcp_user_headers_test.go:generic-api-key:108 diff --git a/pkg/domain/registry/mcp_user_headers_test.go b/pkg/domain/registry/mcp_user_headers_test.go index ce841b278..f3998822b 100644 --- a/pkg/domain/registry/mcp_user_headers_test.go +++ b/pkg/domain/registry/mcp_user_headers_test.go @@ -105,7 +105,7 @@ func TestValidateUserHeaderValue(t *testing.T) { value string ok bool }{ - {"plain key", "sk-live_abc.123", true}, + {"plain value", "abc.123_xyz", true}, {"with space", "abc def", true}, {"empty", " ", false}, {"crlf injection", "abc\r\nX-Evil: 1", false}, From 7ce104d2f2e0eb7fd315f54575296caacb5e7110 Mon Sep 17 00:00:00 2001 From: Edu Date: Fri, 13 Nov 2026 16:23:43 +0100 Subject: [PATCH 14/14] test(functional): keep the A2A registration probe out of the agent's calls Registering an agent now probes its endpoint with a tasks/get (GetTask) for a task that cannot exist. The fake agent recorded that probe as a caller's call, so the tests asserting a refused or blocked call never reached the agent failed. It now answers the probe as an agent would, without recording it. Refs ENG-3243 --- tests/functional/a2a_common_test.go | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/tests/functional/a2a_common_test.go b/tests/functional/a2a_common_test.go index a9d793eef..d25e57c5e 100644 --- a/tests/functional/a2a_common_test.go +++ b/tests/functional/a2a_common_test.go @@ -123,6 +123,13 @@ func (a *fakeAgent) rpc(w http.ResponseWriter, r *http.Request) { http.Error(w, err.Error(), http.StatusBadRequest) return } + // The gateway probes the endpoint when the agent is registered, asking for + // a task that cannot exist. That is not a call a caller made, so it is + // answered as an agent would and not recorded. + if id, _ := req.Params["id"].(string); strings.HasPrefix(id, "trustgate-probe-") { + writeRPCError(w, req.ID, -32001, "Task not found") + return + } a.mu.Lock() a.calls = append(a.calls, agentCall{Method: req.Method, Header: r.Header.Clone(), Params: req.Params}) a.mu.Unlock() @@ -370,3 +377,10 @@ func a2aErrorData(body map[string]any) map[string]any { func a2aKey(key string) map[string]string { return map[string]string{"X-AG-API-Key": key} } + +func writeRPCError(w http.ResponseWriter, id json.RawMessage, code int, message string) { + w.Header().Set("Content-Type", "application/json") + _ = json.NewEncoder(w).Encode(map[string]any{ + "jsonrpc": "2.0", "id": id, "error": map[string]any{"code": code, "message": message}, + }) +}