mcpfacade

Documentation

Overview

Package mcpfacade composes AppTheory's Go runtime MCP OAuth facade.

The package registers the route families defined by runtime/mcproutes.ContractVersion. It serves RFC 9728 protected-resource metadata and RFC 8414 authorization-server discovery while leaving authorization and token behavior in application-owned handlers.

Index

• type Capabilities
  • func DefaultCapabilities() Capabilities
• type FacadeConfig
• type HandlerFactory
• type RootDiscoveryConfig
• type Route
• type RouteInventory
  • func RegisterMCPFacade(app *apptheory.App, config FacadeConfig) (*RouteInventory, error)
• type URLMode

Types

type Capabilities

type Capabilities struct {
	ResponseTypes            []string
	GrantTypes               []string
	TokenEndpointAuthMethods []string
	CodeChallengeMethods     []string
}

Capabilities controls the RFC 8414 capability lists advertised by the facade. Nil fields use DefaultCapabilities; non-nil fields replace a default.

func DefaultCapabilities

func DefaultCapabilities() Capabilities

DefaultCapabilities returns the golden-path OAuth capabilities: code responses, authorization-code and refresh-token grants, public clients, and S256 PKCE.

type FacadeConfig

type FacadeConfig struct {
	// IssuerURL is the absolute HTTPS authorization-server issuer advertised by
	// both metadata document families.
	IssuerURL string
	// JWKSURI is the absolute HTTPS key-set URL advertised by both metadata
	// document families.
	JWKSURI string
	// RegistrationEndpointURL optionally overrides the RFC 8414 registration
	// endpoint. When empty, issuer + /register is advertised.
	RegistrationEndpointURL string

	URLMode       URLMode
	PublicBaseURL string
	// AllowedHostnames is required in request-host mode. Configuration entries
	// normalize case, trailing dots, and default ports scheme-agnostically;
	// request authorities normalize case and trailing dots too, but strip only
	// the request scheme's own default port.
	// The normalized request authority must exact-match an entry or metadata
	// fails with HTTP 400.
	AllowedHostnames []string

	// Scopes must contain a non-empty scope set for every contract endpoint
	// kind. Scope policy remains application-owned.
	Scopes map[mcproutes.EndpointKind][]string
	// Capabilities selectively overrides DefaultCapabilities.
	Capabilities Capabilities

	// MCPHandler serves every POST, GET, and DELETE MCP endpoint pattern.
	MCPHandler apptheory.Handler
	// AuthorizeHandler and TokenHandler are an all-or-none pair. AppTheory only
	// mounts the derived paths; all authorization behavior remains app-owned.
	AuthorizeHandler HandlerFactory
	TokenHandler     HandlerFactory

	// RootAuthorizationServer optionally installs one static GET at the
	// algebra-derived root authorization-server discovery path.
	RootAuthorizationServer *RootDiscoveryConfig
}

FacadeConfig configures the complete route-algebra MCP OAuth facade.

type HandlerFactory

type HandlerFactory func(mcproutes.EndpointKind) apptheory.Handler

HandlerFactory returns an application-owned handler for one endpoint kind. Factories run during facade registration, never during request handling.

type RootDiscoveryConfig

type RootDiscoveryConfig struct {
	IssuerURL                string
	AuthorizationEndpointURL string
	TokenEndpointURL         string
	RegistrationEndpointURL  string
	JWKSURI                  string
	Scopes                   []string
}

RootDiscoveryConfig configures the optional, unscoped authorization-server discovery document. Unlike routed discovery, every endpoint is fixed at registration time and belongs to the upstream authorization server.

type Route

type Route struct {
	Kind                        mcproutes.EndpointKind
	MCPPattern                  string
	MCPMethods                  []string
	ProtectedResourcePattern    string
	DiscoveryCanonicalPattern   string
	DiscoverySuffixPattern      string
	AuthorizePattern            string
	TokenPattern                string
	AuthorizationRoutesAttached bool
}

Route describes one endpoint-kind route family installed by the helper.

type RouteInventory

type RouteInventory struct {
	ContractVersion                 string
	Routes                          []Route
	RootAuthorizationServerPattern  string
	RootAuthorizationServerAttached bool
}

RouteInventory is a defensive snapshot of the installed facade surface.

func RegisterMCPFacade

func RegisterMCPFacade(app *apptheory.App, config FacadeConfig) (*RouteInventory, error)

RegisterMCPFacade installs the complete MCP OAuth facade described by mcproutes.ContractVersion and returns its route inventory. The helper owns composition only: authorize and token routes are absent unless the application supplies both handler factories.

type URLMode

type URLMode string

URLMode selects the source of absolute URLs in facade metadata documents.

const (
	// URLModePublicBaseURL uses FacadeConfig.PublicBaseURL fixed at registration
	// time. Use it when a front door or CDN owns the public origin.
	URLModePublicBaseURL URLMode = "public_base_url"
	// URLModeRequestHost derives the origin from each normalized request. Use it
	// for direct API Gateway custom-domain and test deployments.
	URLModeRequestHost URLMode = "request_host"
)