Documentation
¶
Overview ¶
Package connoauthapi serves the admin OAuth-to-upstream surface: starting an authorization-code flow for a connection, receiving the IdP redirect, reporting per-connection token health, and listing the durable auth-event history. It is a decomposition seam of pkg/admin (which sat at the package size budget); the parent registers it on the admin mux and injects the request-scoped helpers it shares with the other admin routes.
Three route families live here. The unified surface (/api/v1/admin/connections/{kind}/...) dispatches on the kind path value through a registry of OAuthKindHandler, and is the path every new connection kind takes. The two legacy per-kind surfaces (MCP gateway and HTTP API gateway) remain for deployments whose IdP client configuration still names their callback URLs; Register picks between them exactly as the parent did before the move.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Register ¶
Register mounts the OAuth routes on mux, and the IdP redirect targets on publicMux — the callback carries PKCE state rather than an admin session, which is what authenticates it, so it must not sit behind the admin auth middleware.
The unified surface activates once the platform has wired the shared token store and at least one kind handler; otherwise the legacy per-kind routes register so deployments mid-rollout keep working. This is the branch the parent used to make in registerRoutes.
Types ¶
type Config ¶
type Config struct {
// Connections reads the connection instance whose OAuth settings drive
// the flow. nil disables every route in this package.
Connections ConnectionReader
// Tokens persists OAuth tokens for every connection kind in one shared
// table. nil selects the legacy per-kind routes below.
Tokens connoauth.Store
// Kinds maps connection kind to its config extractor and post-auth
// hook. Empty selects the legacy per-kind routes below.
Kinds OAuthKindHandlers
// PKCEStore holds in-flight authorization_code+PKCE state between
// oauth-start and the callback. Required: oauth-start answers 503 when
// nil.
PKCEStore pkcestore.Store
// AuthEvents writes the durable per-connection OAuth-lifecycle audit
// trail. nil disables event writes; the endpoints still work.
AuthEvents *authevents.Writer
// AuthEventStore is the read surface behind the History endpoint. Kept
// distinct from AuthEvents because writes are best-effort while reads
// need a real implementation to return 200 rather than an empty list.
AuthEventStore authevents.Store
// GatewayToolkit returns the live MCP gateway toolkit, so a completed
// legacy flow can re-add the connection and register its tools. Returns
// nil when no gateway toolkit is registered.
GatewayToolkit func() *gatewaykit.Toolkit
// Mutable reports database config mode; false registers nothing, since
// every route here mutates stored credentials.
Mutable bool
// Author resolves the acting admin from the request context for audit
// attribution and auth-event actors.
Author func(ctx context.Context) string
// Decode is the parent's strict JSON body decoder (unknown fields
// rejected, size-capped).
Decode func(w http.ResponseWriter, r *http.Request, dst any) error
// DecodeOptional is Decode for endpoints whose body is optional (an
// OAuth start with an optional return_url), treating an empty body as
// success.
DecodeOptional func(w http.ResponseWriter, r *http.Request, dst any) error
}
Config carries the stores and parent-owned helpers these routes need.
type ConnectionReader ¶
type ConnectionReader interface {
List(ctx context.Context) ([]platform.ConnectionInstance, error)
Get(ctx context.Context, kind, name string) (*platform.ConnectionInstance, error)
}
ConnectionReader is the read side of the connection store. These routes never write a connection instance — they persist tokens through Tokens instead — so they take the narrower interface.
type OAuthKindHandler ¶
type OAuthKindHandler interface {
// ParseOAuthConfig validates the connection's stored config and
// extracts the OAuth 2.1 settings (auth URL, token URL,
// credentials, scopes, etc.) into a connoauth.Config. Returns an
// error when the connection is not configured for the
// authorization_code grant (the unified handler maps the error to
// HTTP 409 Conflict with the operator-facing message).
ParseOAuthConfig(connConfig map[string]any) (connoauth.Config, error)
// AfterConnect runs after a successful Connect or Reacquire so
// the kind can perform any per-kind side effect needed to make
// the connection usable. The MCP gateway re-adds the connection
// here so its tool surface is registered with the platform's MCP
// server; the HTTP API gateway is a no-op because its
// Authenticator reads the store lazily on every request.
AfterConnect(ctx context.Context, name string, connConfig map[string]any) error
}
OAuthKindHandler adapts a kind-specific connection config to the shared connoauth flow. The platform registers one per kind (MCP gateway, HTTP API gateway, future kinds) at startup. The unified connection OAuth handler dispatches on r.PathValue("kind") and invokes the registered OAuthKindHandler for ParseConfig and post-auth side effects.
New connection kinds add support by implementing this interface (typically in their toolkit package) and registering it in HandlerDeps.OAuthKinds — they do NOT add a parallel handler file or a parallel token store.
type OAuthKindHandlers ¶
type OAuthKindHandlers map[string]OAuthKindHandler
OAuthKindHandlers is the registry shape passed via HandlerDeps. The key is the kind string (e.g. connoauth.KindMCP). Keep keys aligned with the connection_kind values stored in connection_instances and connection_oauth_tokens.
Source Files