apigateway

type Authenticator ¶

type Authenticator interface {
	Apply(req *http.Request) error
}

Authenticator applies a connection's authentication scheme to an outbound HTTP request before it is sent. Implementations must be safe for concurrent use — a single Authenticator is shared across all in-flight invocations of a connection.

Implementations MUST NOT log credential material. The toolkit's audit pipeline expects no Authorization or X-API-Key value to ever appear in slog output, error messages, or audit rows; carelessly formatted error strings are the most common leak path.

func NewAuthenticator(c Config) (Authenticator, error)

type Config ¶

type Config struct {
	// BaseURL is the upstream API root (e.g. "https://api.example.com").
	// Required. Trailing slash is stripped at parse time.
	BaseURL string
	// AuthMode is "none", "bearer", or "api_key" in v1. OAuth modes
	// land with #368.
	AuthMode string
	// Credential is the bearer token or API key. Ignored when AuthMode
	// is "none". Encrypted at rest via the platform's FieldEncryptor.
	Credential string
	// APIKeyPlacement is "header" (default) or "query" — only consulted
	// when AuthMode is "api_key".
	APIKeyPlacement string
	// APIKeyHeader is the header name to set when APIKeyPlacement is
	// "header". Defaults to "X-API-Key".
	APIKeyHeader string
	// APIKeyParam is the query parameter name when APIKeyPlacement is
	// "query". No default — required when placement is "query".
	APIKeyParam string
	// Username is the userid for HTTP Basic auth (RFC 7617). Required
	// when AuthMode is "basic". Ignored otherwise. Not a secret on its
	// own (per RFC 7617 §2 the userid is sent in clear after base64
	// decoding regardless), so it is not encrypted at rest.
	Username string
	// Password is the password for HTTP Basic auth. May be empty: some
	// legacy APIs accept a bearer token in the userid slot with an empty
	// password (the "token:" pattern). Encrypted at rest via the
	// platform's FieldEncryptor; the "password" cfg key is already in
	// the sensitive-keys list.
	Password string
	// ConnectionName is the audit-visible connection identifier and the
	// value passed in the tool's `connection` argument. Defaults to
	// the toolkit instance name when unset.
	ConnectionName string
	// ConnectTimeout caps the dial step on each invocation.
	ConnectTimeout time.Duration
	// CallTimeout caps the total per-invocation time.
	CallTimeout time.Duration
	// TrustLevel is "untrusted" (default) or "trusted".
	TrustLevel string
	// MaxResponseBytes caps how much of an upstream response body is
	// returned to the model. Defaults to DefaultMaxResponseBytes.
	MaxResponseBytes int64
	// CatalogID names the api_catalogs row whose component specs
	// describe this connection's upstream API. Empty = no spec
	// surface. The catalog is global and may back many connections;
	// editing it propagates to all of them via Toolkit.ReloadConnection.
	CatalogID string
	// OAuth2 carries the OAuth 2.1 parameters used when AuthMode
	// is oauth2_client_credentials. Empty for non-OAuth modes.
	OAuth2 OAuth2Config
	// StaticHeaders are operator-configured headers attached to every
	// outbound request, in addition to whatever AuthMode contributes.
	// Required for upstreams that demand a non-Authorization header on
	// top of the OAuth bearer (Google's x-goog-user-project,
	// vendor subscription keys, etc.). Operator-supplied; the model
	// never sets or overrides these. Values are encrypted at rest.
	StaticHeaders map[string]string
}

Config holds api-gateway toolkit configuration for a single upstream HTTP API connection.

func ParseConfig(cfg map[string]any) (Config, error)

func (c Config) Validate() error

type EndpointSchemaOutput ¶ added in v1.61.5

type EndpointSchemaOutput struct {
	Spec        string             `json:"spec,omitempty"`
	OperationID string             `json:"operation_id"`
	Method      string             `json:"method"`
	Path        string             `json:"path"`
	Summary     string             `json:"summary,omitempty"`
	Description string             `json:"description,omitempty"`
	Parameters  []ParameterDetail  `json:"parameters,omitempty"`
	RequestBody *RequestBodyDetail `json:"request_body,omitempty"`
	Responses   []ResponseDetail   `json:"responses,omitempty"`
	Examples    map[string]any     `json:"examples,omitempty"`
	Note        string             `json:"note,omitempty"`
}

EndpointSchemaOutput is the structured response. Fields are omitted from JSON when empty so the typical "GET /things" operation doesn't waste context on absent request_body or examples.

type ExportAsset ¶

type ExportAsset struct {
	ID             string
	OwnerID        string
	OwnerEmail     string
	Name           string
	Description    string
	ContentType    string
	S3Bucket       string
	S3Key          string
	SizeBytes      int64
	Tags           []string
	Provenance     ExportProvenance
	SessionID      string
	IdempotencyKey string
}

ExportAsset is the row inserted into portal_assets when an api_export call succeeds. Field shape mirrors trinokit.ExportAsset so the platform-side adapter can reuse its conversion logic.

type ExportAssetRef ¶

type ExportAssetRef struct {
	ID        string
	SizeBytes int64
}

ExportAssetRef is returned by idempotency-key lookup. We only need the id + size for the response — the model doesn't see the existing asset's full row.

type ExportAssetStore ¶

type ExportAssetStore interface {
	InsertExportAsset(ctx context.Context, asset ExportAsset) error
	GetByIdempotencyKey(ctx context.Context, ownerID, key string) (*ExportAssetRef, error)
}

ExportAssetStore is the subset of portal.AssetStore needed by api_export. Defined locally to avoid an import cycle (portal → registry → apigateway). Mirrors trinokit.ExportAssetStore.

type ExportConfig ¶

type ExportConfig struct {
	MaxBytes       int64
	DefaultTimeout time.Duration
	MaxTimeout     time.Duration
}

ExportConfig holds platform-level limits for api_export. MaxBytes caps any single export's size (above which the call returns an error rather than a truncated asset — partial-data assets would be misleading). DefaultTimeout / MaxTimeout bound how long a single call may run.

type ExportDeps ¶

type ExportDeps struct {
	AssetStore     ExportAssetStore
	VersionStore   ExportVersionStore
	S3Client       ExportS3Client
	ShareCreator   ExportShareCreator
	S3Bucket       string
	S3Prefix       string
	BaseURL        string
	Config         ExportConfig
	GetUserContext func(ctx context.Context) *ExportUserContext
}

ExportDeps holds platform-side dependencies injected into the api gateway toolkit. All types are defined locally to avoid import cycles. Mirrors trinokit.ExportDeps so the platform-side wiring can stay symmetric.

type ExportProvenance ¶

type ExportProvenance struct {
	ToolCalls []ExportProvenanceCall
	SessionID string
	UserID    string
}

ExportProvenance captures the chain of tool calls that produced an asset so portal viewers can render "exported via api_export from <connection> <method> <path>".

type ExportProvenanceCall ¶

type ExportProvenanceCall struct {
	ToolName   string
	Timestamp  string
	Parameters map[string]any
}

ExportProvenanceCall is one step in the provenance chain.

type ExportS3Client ¶

type ExportS3Client interface {
	PutObject(ctx context.Context, bucket, key string, data []byte, contentType string) error
}

ExportS3Client is the subset of portal.S3Client needed by api_export. Note: this is the same shape as trinokit's; the platform adapter implementing it can serve both toolkits.

type ExportShareCreator ¶

type ExportShareCreator interface {
	CreatePublicShare(ctx context.Context, assetID, createdBy string) (shareURL string, err error)
}

ExportShareCreator creates public share links for exported assets. nil disables public-link creation.

type ExportUserContext ¶

type ExportUserContext struct {
	UserID    string
	UserEmail string
	SessionID string
}

ExportUserContext holds user identity extracted from the request context. Populated by the GetUserContext callback provided in ExportDeps so the toolkit doesn't import middleware directly.

type ExportVersion ¶

type ExportVersion struct {
	ID            string
	AssetID       string
	S3Key         string
	S3Bucket      string
	ContentType   string
	SizeBytes     int64
	CreatedBy     string
	ChangeSummary string
}

ExportVersion is the row inserted into portal_asset_versions.

type ExportVersionStore ¶

type ExportVersionStore interface {
	CreateExportVersion(ctx context.Context, version ExportVersion) (int, error)
}

ExportVersionStore is the subset of portal.VersionStore needed by api_export.

type GetEndpointSchemaInput ¶ added in v1.61.5

type GetEndpointSchemaInput struct {
	Connection  string `json:"connection"`
	OperationID string `json:"operation_id"`
	Spec        string `json:"spec,omitempty"`
}

GetEndpointSchemaInput is the parsed argument shape for the api_get_endpoint_schema tool.

type InvokeInput ¶

type InvokeInput struct {
	Connection     string            `json:"connection"`
	Method         string            `json:"method"`
	Path           string            `json:"path"`
	Query          map[string]any    `json:"query_params,omitempty"`
	Headers        map[string]string `json:"headers,omitempty"`
	Body           any               `json:"body,omitempty"`
	TimeoutSeconds int               `json:"timeout_seconds,omitempty"`
}

InvokeInput is the parsed argument shape for api_invoke_endpoint. Field names match the JSON schema.

type InvokeOutput ¶

type InvokeOutput struct {
	Status        int                 `json:"status"`
	Headers       map[string][]string `json:"headers,omitempty"`
	Body          any                 `json:"body,omitempty"`
	BodyTruncated bool                `json:"body_truncated,omitempty"`
	// Pagination is populated when the upstream response carries a
	// recognizable cursor (RFC 5988 Link rel="next", @odata.nextLink,
	// next_cursor, etc). The model uses this to decide whether to
	// issue a follow-up call. The gateway does NOT auto-follow so
	// each loop iteration stays observable in audit + conversation.
	Pagination *PaginationInfo `json:"pagination,omitempty"`
	// Hint surfaces operator-actionable advice to the model when the
	// response itself can't carry it — most importantly the "use
	// api_export instead" suggestion when the body exceeded
	// max_response_bytes. Distinct from Error: Hint is informational,
	// the call still succeeded.
	Hint       string `json:"hint,omitempty"`
	DurationMs int64  `json:"duration_ms"`
	Error      string `json:"error,omitempty"`
}

InvokeOutput is the structured result returned to the model and to the REST gateway shim. Outcomes are distinguished at the MCP-result layer (see buildInvokeResult and issue #432):

• Upstream responded with anything (2xx-5xx): the gateway succeeded at proxying. Status carries the upstream HTTP code, Error is normally empty, and the wrapping CallToolResult has IsError=false. Wire-level HTTP status from the REST shim stays 200; HTTP clients read the upstream code from Status and branch on it.
• Upstream responded with a status but the body could not be read in full (mid-stream drop, body exceeded the buffer allocator): Status carries the upstream code, Error carries the read-failure text, IsError stays false. The partial body is still returned in Body so callers can inspect what arrived.
• Gateway could not reach upstream OR the upstream call timed out: gateway-level failure. Status is 0, Error carries the scrubbed transport-error text, the wrapping CallToolResult has IsError=true, and the REST shim maps this to wire 502 (transport) or 504 (timeout).

type ListEndpointsInput ¶

type ListEndpointsInput struct {
	Connection string `json:"connection"`
	Query      string `json:"query,omitempty"`
	Limit      int    `json:"limit,omitempty"`
	Ranking    string `json:"ranking,omitempty"`
	Spec       string `json:"spec,omitempty"`
}

ListEndpointsInput is the parsed argument shape for api_list_endpoints. Field names match the JSON schema.

Spec restricts results to one component spec inside the connection's catalog. For a multi-spec catalog (e.g. a vendor shipping nine component specs under one connection) this is the per-section filter operators reach for once the catalog passes the size at which substring search across all 300+ operations stops being useful. Spec values come from the spec field on each operation in a prior api_list_endpoints response, so the model can pass them back verbatim.

type ListEndpointsOutput ¶

type ListEndpointsOutput struct {
	Operations []OperationSummary `json:"operations"`
	Note       string             `json:"note,omitempty"`
}

ListEndpointsOutput is the structured result. Empty + Note when the connection has no OpenAPI spec configured (so the model can distinguish "no spec" from "no matches").

type MultiConfig ¶

type MultiConfig struct {
	DefaultName string
	Instances   map[string]Config
}

MultiConfig holds parsed per-connection configs plus the aggregate toolkit's default connection name.

func ParseMultiConfig(defaultName string, raw map[string]map[string]any) (MultiConfig, error)

type OAuth2Config ¶

type OAuth2Config struct {
	// TokenURL is the upstream's token endpoint. Required.
	TokenURL string
	// ClientID is the platform's registered client id. Required.
	ClientID string
	// ClientSecret is the platform's registered client secret.
	// Required. Encrypted at rest via the platform's
	// FieldEncryptor (sensitive-key list already includes
	// "client_secret"; the nested map's value is encrypted before
	// storage in connection_instances.config).
	ClientSecret string
	// Scopes is an optional list of OAuth scopes to request.
	Scopes []string
	// EndpointAuthStyle controls how the client credentials are
	// transmitted at token-fetch time. "header" (default) sends
	// them as HTTP Basic auth on the token request; "params"
	// sends them as POST body parameters. Some IdPs require one
	// or the other; "header" is the OAuth 2.1 default.
	EndpointAuthStyle string
	// AuthorizationURL is the upstream's authorization endpoint.
	// Required only for the authorization_code grant — that's
	// where the platform redirects the admin's browser to start
	// the flow.
	AuthorizationURL string
	// Prompt is an optional OIDC prompt parameter (RFC OIDC
	// §3.1.2.1). Common values: "login" (force credential prompt),
	// "consent" (force consent screen), "select_account",
	// "none" (silent auth). Empty by default — the IdP decides.
	// Operators of strict OIDC realms (Keycloak, Auth0, Okta)
	// typically set this to "login" so admin Reconnect actions
	// always re-prompt the user. Pure-OAuth (non-OIDC) providers
	// often reject unknown parameters with invalid_request, so
	// leave empty for those.
	Prompt string
}

OAuth2Config describes the OAuth 2.1 client_credentials grant parameters. The platform exchanges ClientID + ClientSecret at TokenURL for an access token (cached + refreshed by the golang.org/x/oauth2 library) and applies it as "Authorization: Bearer <token>" on outbound calls.

Authorization-code (browser-driven, refresh-token-persisting) grants are deferred to a follow-up — they require DB state (PKCE verifier table, refresh-token cache) and an admin reauth callback handler that this PR intentionally does not bring in.

type OAuthKindHandler ¶ added in v1.60.1

type OAuthKindHandler struct{}

OAuthKindHandler adapts the HTTP API gateway toolkit to the unified connoauth flow. The admin layer's unified OAuth handler dispatches on the connection_kind path parameter ("api" for HTTP API gateway connections) and invokes this implementation for config extraction and post-auth side effects.

AfterConnect is a no-op for this kind: the toolkit's Authenticator reads the persisted token from the store lazily on every outbound request, so once the token is persisted the connection is immediately usable without further toolkit-side work.

func NewOAuthKindHandler(_ *Toolkit) *OAuthKindHandler

func (*OAuthKindHandler) AfterConnect(_ context.Context, _ string, _ map[string]any) error

func (*OAuthKindHandler) ParseOAuthConfig(connConfig map[string]any) (connoauth.Config, error)

type OperationSummary ¶

type OperationSummary struct {
	OperationID string   `json:"operation_id"`
	Method      string   `json:"method"`
	Path        string   `json:"path"`
	Summary     string   `json:"summary,omitempty"`
	Tags        []string `json:"tags,omitempty"`
	Spec        string   `json:"spec,omitempty"`
}

OperationSummary is the slim per-operation view returned by api_list_endpoints. Designed to be cheap on context: the model gets enough to decide whether an operation is relevant (operation_id, method, path, summary, tags) without paying for the full request / response schema. Per-endpoint detail is fetched on demand via api_get_endpoint_schema.

Spec names the component spec inside the connection's catalog (e.g. "users", "orders"). Omitted from JSON when empty so connections with no catalog or a single anonymous spec stay slim on context.

type PaginationInfo ¶

type PaginationInfo struct {
	HasMore    bool   `json:"has_more,omitempty"`
	NextCursor string `json:"next_cursor,omitempty"`
	NextURL    string `json:"next_url,omitempty"`
	Source     string `json:"source,omitempty"`
}

PaginationInfo is the structured pagination state api_invoke_endpoint surfaces to the model on every response. The model uses HasMore + NextCursor (or NextURL) to decide whether to issue a follow-up call; the gateway does NOT auto-follow so each loop iteration stays observable in the conversation and audit log.

Fields are populated only when the upstream response carries a recognizable pagination signal. When none are populated the field is omitted from the JSON response — the model sees no pagination envelope and treats the response as terminal.

type ParameterDetail ¶ added in v1.61.5

type ParameterDetail struct {
	Name        string `json:"name"`
	In          string `json:"in"`
	Required    bool   `json:"required,omitempty"`
	Description string `json:"description,omitempty"`
	Schema      any    `json:"schema,omitempty"`
}

ParameterDetail mirrors OpenAPI's parameter shape, stripped to the fields the model needs to construct a call.

type RankingMode ¶

type RankingMode string

RankingMode selects the algorithm api_list_endpoints uses to score candidate operations against the model's query.

Lexical (default) is the substring-match filter that v1 shipped: fast, deterministic, no embedding-provider dependency. Misses on natural-language queries when the model's phrasing doesn't share vocabulary with the spec author's (e.g. query "create order" vs summary "Place a new order").

Semantic uses cosine similarity between the query embedding and each operation's pre-computed embedding. Best for free-form intent queries; needs an embedding provider wired via SetEmbeddingProvider.

Hybrid blends a lexical signal (substring match) with the semantic cosine score. The blend recovers the precision of substring match for queries that DO share vocabulary while still returning semantically-related results when they don't. The blend weight (alpha) is fixed at hybridSemanticWeight; tuning is deferred to a config knob if a real-world deployment needs it.

const (
	// RankingLexical is the v1 substring-match filter (default).
	RankingLexical RankingMode = "lexical"
	// RankingSemantic ranks by embedding cosine similarity only.
	RankingSemantic RankingMode = "semantic"
	// RankingHybrid blends a lexical signal with the cosine score.
	RankingHybrid RankingMode = "hybrid"
)

type RequestBodyDetail ¶ added in v1.61.5

type RequestBodyDetail struct {
	Required     bool           `json:"required,omitempty"`
	Description  string         `json:"description,omitempty"`
	ContentTypes []string       `json:"content_types,omitempty"`
	Schema       any            `json:"schema,omitempty"`
	Examples     map[string]any `json:"examples,omitempty"`
}

RequestBodyDetail describes the request body shape.

type ResponseDetail ¶ added in v1.61.5

type ResponseDetail struct {
	Status       string         `json:"status"`
	Description  string         `json:"description,omitempty"`
	ContentTypes []string       `json:"content_types,omitempty"`
	Schema       any            `json:"schema,omitempty"`
	Examples     map[string]any `json:"examples,omitempty"`
}

ResponseDetail describes one response status's shape.

type RoutePolicy ¶

type RoutePolicy interface {
	Allow(ctx context.Context, connection, method, path string) (allowed bool, reason string)
}

RoutePolicy gates an api_invoke_endpoint call by (connection, method, path) on top of the platform's existing tool/connection authorization. Layered design: the MCP middleware's Authorizer.IsAuthorized check covers "may this user call api_invoke_endpoint at all?" and "on this connection at all?". RoutePolicy answers the more specific question "may this user call THIS method on THIS path of this connection?".

Reason is included for audit/log clarity when Allowed is false. Implementations must read the caller's roles from ctx (typically via the middleware's pre-authenticated user or an Authenticator) and resolve them to a persona's APIRoutes rules.

type Toolkit ¶

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

Toolkit is the api-gateway toolkit. A single Toolkit manages multiple named connections, each addressing a different upstream HTTP API. Connections are added either at startup (from the platform's merged YAML+DB config) or at runtime via AddConnection (used by the admin REST handler when an operator saves a new connection through the portal).

func New(name string) *Toolkit

func NewMulti(cfg MultiConfig) *Toolkit

func (t *Toolkit) AddConnection(name string, config map[string]any) error

func (t *Toolkit) CatalogStore() catalog.Store

func (t *Toolkit) Close() error

func (t *Toolkit) ConnOAuthStore() connoauth.Store

func (t *Toolkit) Connection() string

func (t *Toolkit) EmbeddingProvider() embedding.Provider

func (t *Toolkit) HasConnection(name string) bool

func (*Toolkit) Kind() string

func (t *Toolkit) ListConnections() []toolkit.ConnectionDetail

func (t *Toolkit) Name() string

func (t *Toolkit) RegisterTools(s *mcp.Server)

func (t *Toolkit) ReloadConnection(name string) error

func (t *Toolkit) ReloadConnectionsByCatalog(catalogID string)

func (t *Toolkit) RemoveConnection(name string) error

func (t *Toolkit) RoutePolicy() RoutePolicy

func (t *Toolkit) SetAuthEvents(w *authevents.Writer)

func (t *Toolkit) SetCatalogStore(s catalog.Store)

func (t *Toolkit) SetConnOAuthStore(s connoauth.Store)

func (t *Toolkit) SetEmbeddingProvider(p embedding.Provider)

func (t *Toolkit) SetExportDeps(deps ExportDeps)

func (t *Toolkit) SetMetrics(m *observability.Metrics)

func (t *Toolkit) SetQueryProvider(provider query.Provider)

func (t *Toolkit) SetRoutePolicy(p RoutePolicy)

func (t *Toolkit) SetSemanticProvider(provider semantic.Provider)

func (t *Toolkit) Tools() []string