mcpaggregate

type BearerVerifier ¶

type BearerVerifier interface {
	Verify(r *http.Request, token, cluster, mcpServerName string) (Caller, error)
}

BearerVerifier decides whether the bearer presented on an aggregate MCP request may act in the tenant cluster and MCPServer named by the request path. It runs before any federation, so a rejected bearer never reaches a provider.

Implementations return the verified Caller and a nil error to allow, ErrUnauthenticated when the bearer is not a credential the hub recognises, ErrForbidden when it is a valid credential for a different tenant or identity, and any other error when verification itself could not be performed (the handler answers 503).

type BearerVerifierFunc ¶

type BearerVerifierFunc func(r *http.Request, token, cluster, mcpServerName string) (Caller, error)

BearerVerifierFunc adapts a function to BearerVerifier.

func (f BearerVerifierFunc) Verify(r *http.Request, token, cluster, mcpServerName string) (Caller, error)

type Caller ¶

type Caller struct {
	// OrgUUID and WorkspaceUUID are the tenant the request's cluster belongs
	// to. WorkspaceUUID is empty for an org-scope cluster; both are empty for
	// a ServiceAccount bearer in a cluster outside the tenants tree, which
	// federates the platform catalog only.
	OrgUUID       string
	WorkspaceUUID string
	// User is the hub User name for a human bearer whose membership in the
	// tenant was verified. Empty for a ServiceAccount bearer.
	User string
	// ServiceAccount is the TokenReview username for a ServiceAccount bearer.
	// Empty for a human.
	ServiceAccount string
}

Caller is the verified tenant context of one aggregate request. Only a BearerVerifier produces it — from the cluster named in the request path, the cluster's own kcp.io/path, and an online check of the bearer — never from anything the client asserts in headers. It is what the ProviderEnumerator scopes federation to.

func (c Caller) IsServiceAccount() bool

type FederatedProvider ¶

type FederatedProvider struct {
	Name        string          `json:"name"`
	DisplayName string          `json:"displayName,omitempty"`
	MCPURL      string          `json:"mcpURL"`
	Reachable   bool            `json:"reachable"`
	Error       string          `json:"error,omitempty"`
	Tools       []FederatedTool `json:"tools"`
	// contains filtered or unexported fields
}

FederatedProvider is the introspection view of one federation target: a Ready provider, whether its MCP endpoint answered, and the tools it advertised. It is what the portal renders so a user can see what the aggregate is federating live, without connecting an MCP client.

func DiscoverFederation(ctx context.Context, targets []ProviderTarget, bearerToken, cluster string) []FederatedProvider

type FederatedTool ¶

type FederatedTool struct {
	Name        string `json:"name"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
}

FederatedTool is one tool advertised by a federated provider. Names are the provider-local names; the aggregate prefixes them "<provider>__" when it proxies, but introspection shows the raw names the provider reports.

type Options ¶

type Options struct {
	// Providers enumerates the live Ready providers to federate for a
	// verified caller. Required.
	Providers ProviderEnumerator
	// ExternalURL is the hub's externally reachable base URL, used only to
	// self-describe the endpoint in the railgrid://about resource. Optional.
	ExternalURL string
	// Logger is used for federation diagnostics. Optional.
	Logger logr.Logger
	// Verifier checks the bearer against the tenant cluster and MCPServer
	// named by the request before anything is federated. Required: without
	// one every request is refused with 503 rather than forwarded unverified.
	Verifier BearerVerifier
	// VerifyCacheTTL bounds how long a successful verification is reused for
	// the same bearer, cluster and MCPServer. Defaults to DefaultVerifyCacheTTL.
	VerifyCacheTTL time.Duration
	// RateLimiter, when set, caps uncached verification attempts per client
	// address; cache hits are never counted so verified clients are not
	// throttled. Optional.
	RateLimiter RateLimiter
	// ClientIP derives the address the rate limiter keys on. Defaults to the
	// host part of RemoteAddr; the hub passes its proxy-header-aware helper.
	ClientIP func(*http.Request) string
	// DiscoveryCacheTTL is how long a provider's discovered tools and
	// instructions are served before a background refresh (see discovery.go).
	// Defaults to DefaultDiscoveryCacheTTL; negative disables the cache, so
	// every request discovers every provider afresh.
	DiscoveryCacheTTL time.Duration
}

Options configures the aggregate handler.

type OrgProviderRouter ¶

type OrgProviderRouter interface {
	OrgProviderRoute(ctx context.Context, prov providers.Provider, caller providers.DelegatedCaller) (providers.OrgProviderRoute, error)
}

OrgProviderRouter resolves how a hub-originated request reaches an org-owned provider's backend on behalf of a caller. The hub's backend proxy (*providers.ProviderProxy) implements it, so the aggregate reuses the exact edge hop and delegated-token substitution that /services/providers/{name} applies, rather than a second copy of that boundary.

type ProviderEnumerator ¶

type ProviderEnumerator func(ctx context.Context, caller Caller) []ProviderTarget

ProviderEnumerator returns the live set of Ready providers exposing an MCP endpoint that the verified caller may see. Called once per MCP request from buildServer with the Caller its BearerVerifier returned, never with anything taken from request headers.

func RegistryEnumerator(reg *providers.Registry, router OrgProviderRouter, log logr.Logger) ProviderEnumerator

type ProviderTarget ¶

type ProviderTarget struct {
	Name        string
	DisplayName string
	MCPURL      string

	// OrgUUID is the owning Org of an org-owned ("bring your own") provider;
	// empty for a platform provider. An org-owned target is only ever reached
	// through Transport: one without a Transport is not contacted at all.
	OrgUUID string
	// Transport, when set, carries every request to this target and owns its
	// authorization: the federation client never attaches the caller's bearer
	// to a request that goes through it. Org-owned targets get one from
	// providers.ProviderProxy.OrgProviderRoute (edge hop + delegated token).
	// Nil for a platform provider, which is dialled directly with the caller's
	// bearer as before.
	Transport http.RoundTripper
}

ProviderTarget is one federation target: a Ready provider and the URL of its own MCP endpoint.

type RateLimiter ¶

type RateLimiter interface {
	Allow(clientIP string) bool
}

RateLimiter admits or rejects a pre-authentication verification attempt for one client address. The hub's token-login limiter satisfies it.

type Verifier ¶

type Verifier struct {
	// contains filtered or unexported fields
}

Verifier is the production BearerVerifier. It accepts three kinds of bearer:

1. The MCPServer's own ServiceAccount token, which the mcpserver controller mints and the portal / REST API hand to the user for long-lived MCP client configuration. It is verified online with a TokenReview in the tenant cluster named by the request, and the reviewed username must be ServiceAccountUsername(name) for the MCPServer named by the request.
2. A hub user bearer (static token or OIDC id_token) as resolved by the hub's normal identity path; the CLI's `railgrid mcp` and the e2e suites use these. The user must hold a live Membership covering the tenant the cluster belongs to, per the UserMembershipIndex.
3. Other tenant ServiceAccounts with explicit RBAC permission to use the named MCPServer. TokenReview authenticates them before SubjectAccessReview authorizes access; platform providers still receive the original bearer.

Signatures and claims are never trusted offline; both paths are online checks against kcp. Either way the result carries the tenant (Org and Workspace) the cluster belongs to, which is what federation is scoped to.

func NewVerifier(clusterConfig func(cluster string) *rest.Config, opts ...VerifierOption) *Verifier

func (v *Verifier) SetUserIdentity(
	identify func(*http.Request) (string, error),
	membership func(ctx context.Context, user string) (*tenancyv1alpha1.UserMembershipIndex, error),
)

func (v *Verifier) Verify(r *http.Request, token, cluster, mcpServerName string) (Caller, error)

type VerifierOption ¶

type VerifierOption func(*Verifier)

VerifierOption customises a Verifier.

func WithClusterPathResolver(f func(ctx context.Context, cluster string) (string, error)) VerifierOption

func WithKubeClientFactory(f func(*rest.Config) (kubernetes.Interface, error)) VerifierOption