oauthserver

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 22, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package oauthserver implements a minimal, standards-based OAuth 2.1 authorization server plus resource-server token verification so MCPlex can be exposed to OAuth-only MCP clients (e.g. Gemini custom apps) through a public HTTPS tunnel, following the MCP Authorization specification (2025-11-25):

  • RFC 9728 Protected Resource Metadata (`/.well-known/oauth-protected-resource[/<mcp-path>]`)
  • RFC 8414 Authorization Server Metadata (`/.well-known/oauth-authorization-server`)
  • RFC 7591 Dynamic Client Registration (`/oauth/register`) with a redirect-URI allowlist
  • Authorization code + mandatory PKCE S256 (`/oauth/authorize`), approved by the owner secret
  • RFC 8707 resource-bound, opaque, hashed-at-rest access/refresh tokens (`/oauth/token`)
  • RFC 7009 revocation (`/oauth/revoke`), RFC 9207 `iss` in authorization responses

Refresh tokens rotate for public clients (OAuth 2.1 §4.3.1) and stay stable with a sliding expiry for confidential clients (Gemini "persistent linking" requirement).

Index

Constants

View Source
const (
	// ScopeMCP is the single scope granted to OAuth clients: full access to the MCP endpoint.
	ScopeMCP = "mcp"
)

Variables

View Source
var GoogleRedirectPatterns = []string{
	"https://oauth-redirect.googleusercontent.com/r/*",
	"https://oauth-redirect-sandbox.googleusercontent.com/r/*",
	"https://oauth-redirect-test.googleusercontent.com/r/*",
	"https://oauth-redirect.googleusercontent.com/a/*",
	"https://oauth-redirect-sandbox.googleusercontent.com/a/*",
	"https://oauth-redirect-test.googleusercontent.com/a/*",
}

GoogleRedirectPatterns are the redirect URIs Gemini / Google Connected Apps use for OAuth account linking.

Functions

func RevokeClients

func RevokeClients(dataDir string, ids []string) (int, error)

RevokeClients deletes the given client IDs (or all clients when ids contains "all") together with their grants and tokens. A running server picks the change up on its next request. Returns the number of clients removed.

func StateDir

func StateDir(dataDir string) string

StateDir returns the directory holding persisted OAuth server state for a data dir.

Types

type ClientInfo

type ClientInfo struct {
	ID         string    `json:"id"`
	Name       string    `json:"name,omitempty"`
	AuthMethod string    `json:"authMethod"`
	Redirects  []string  `json:"redirectUris"`
	Grants     int       `json:"activeGrants"`
	CreatedAt  time.Time `json:"createdAt"`
	LastUsedAt time.Time `json:"lastUsedAt"`
}

ClientInfo is a read-only summary of a registered client for `mcplex oauth clients`.

func ListClients

func ListClients(dataDir string) ([]ClientInfo, error)

ListClients returns registered clients persisted under dataDir.

type Config

type Config struct {
	// PublicURL is the externally reachable HTTPS origin of this MCPlex instance (e.g. https://mcp.example.com).
	// It becomes the OAuth issuer; the protected resource is PublicURL + MCPPath.
	PublicURL string
	// MCPPath is the MCP Streamable HTTP endpoint path (default "/mcp").
	MCPPath string
	// OwnerSecret is the secret the owner types on the consent page to approve a client (MCPlex reuses --token).
	OwnerSecret string
	// DataDir stores persisted clients and grants under DataDir/oauth-server.
	DataDir string
	// RedirectAllow lists extra allowed redirect URI patterns. A trailing "*" is a prefix wildcard; the special
	// value "loopback" allows http://127.0.0.1|localhost|[::1] on any port (native clients such as Claude Code).
	// Google's redirect URIs are always allowed.
	RedirectAllow []string
	// Now overrides the clock (tests).
	Now func() time.Time
}

Config configures the OAuth server.

type Server

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

Server is the OAuth authorization server + resource-server verifier for one public MCPlex endpoint.

func New

func New(cfg Config) (*Server, error)

New builds an OAuth server from cfg, loading persisted clients and grants.

func (*Server) Issuer

func (s *Server) Issuer() string

Issuer returns the OAuth issuer (public origin).

func (*Server) PublicHost

func (s *Server) PublicHost() string

PublicHost returns the host[:port] of the public URL (for Host-header allowlisting).

func (*Server) Resource

func (s *Server) Resource() string

Resource returns the canonical protected resource URI (public origin + MCP path).

func (*Server) ResourceMetadataURL

func (s *Server) ResourceMetadataURL() string

ResourceMetadataURL is advertised in WWW-Authenticate on 401 responses from the MCP endpoint.

func (*Server) Routes

func (s *Server) Routes() map[string]http.HandlerFunc

Routes returns the OAuth/metadata endpoints keyed by exact path.

func (*Server) SetOwnerSecret added in v0.5.1

func (s *Server) SetOwnerSecret(secret string) error

SetOwnerSecret rotates the owner secret checked on the authorization consent page at runtime. Existing approved grants and access/refresh tokens remain valid until revoked.

func (*Server) VerifyAccessToken

func (s *Server) VerifyAccessToken(token string) bool

VerifyAccessToken validates an OAuth access token for the MCP endpoint: it must exist, be unexpired, belong to a live grant and be bound to this server's resource (RFC 8707 audience).

func (*Server) WWWAuthenticate

func (s *Server) WWWAuthenticate(invalidToken bool) string

WWWAuthenticate returns the RFC 6750 / RFC 9728 challenge for an unauthenticated or invalid-token request.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL