proxy

Documentation

Overview

Package proxy implements a filtering HTTP proxy for the GitHub API. It intercepts gh CLI requests (via GH_HOST redirect) and applies the same DIFC enforcement pipeline as the MCP gateway, reusing the guard WASM module, evaluator, and agent registry.

Package proxy — TLS support for the GitHub API filtering proxy.

When running in self-signed TLS mode, the proxy auto-generates a CA and localhost server certificate at startup. This allows the gh CLI (which forces HTTPS for custom GH_HOST values) to connect via:

GH_HOST=localhost:8443 gh issue list -R org/repo

The CA certificate is written to a file so callers can inject it into their trust store (e.g., via NODE_EXTRA_CA_CERTS or update-ca-certificates).

Index

• Constants
• func IsGraphQLPath(path string) bool
• func StripGHHostPrefix(path string) string
• type Config
• type GraphQLRequest
• type GraphQLRouteMatch
  • func MatchGraphQL(body []byte) *GraphQLRouteMatch
• type RouteMatch
  • func MatchRoute(path string) *RouteMatch
• type Server
  • func New(ctx context.Context, cfg Config) (*Server, error)
  • func (s *Server) Handler() http.Handler
• type TLSConfig
  • func GenerateSelfSignedTLS(dir string) (*TLSConfig, error)

Constants

const (
	// DefaultGitHubAPIBase is the upstream GitHub API URL.
	DefaultGitHubAPIBase = "https://api.github.com"
)

Functions

func IsGraphQLPath

func IsGraphQLPath(path string) bool

IsGraphQLPath returns true if the request path is the GraphQL endpoint. Accepts /graphql (after prefix strip), /api/v3/graphql (before strip), and /api/graphql (GHES-style path used by gh CLI with GH_HOST).

func StripGHHostPrefix

func StripGHHostPrefix(path string) string

StripGHHostPrefix removes the /api/v3 prefix that gh adds when using GH_HOST.

Types

type Config

type Config struct {
	// WasmPath is the file path to the guard WASM module.
	WasmPath string

	// Policy is the guard policy JSON (e.g. {"allow-only":{...}}).
	Policy string

	// GitHubToken is a fallback token for upstream GitHub API requests.
	// When empty, the proxy forwards the client's Authorization header instead.
	GitHubToken string

	// GitHubAPIURL overrides the upstream API base URL (default: https://api.github.com).
	GitHubAPIURL string

	// DIFCMode is the enforcement mode (strict, filter, propagate).
	DIFCMode string
}

Config holds the configuration for creating a proxy Server.

type GraphQLRequest

type GraphQLRequest struct {
	Query     string                 `json:"query"`
	Variables map[string]interface{} `json:"variables,omitempty"`
}

GraphQLRequest represents a parsed GraphQL request body.

type GraphQLRouteMatch

type GraphQLRouteMatch struct {
	ToolName string
	Owner    string
	Repo     string
	Args     map[string]interface{}
}

GraphQLRouteMatch contains the result of matching a GraphQL query to a guard tool name.

func MatchGraphQL

func MatchGraphQL(body []byte) *GraphQLRouteMatch

MatchGraphQL matches a GraphQL request body to a guard tool name.

type RouteMatch

type RouteMatch struct {
	ToolName string
	Owner    string
	Repo     string
	Args     map[string]interface{} // Arguments to pass to LabelResource
}

RouteMatch contains the result of matching a REST API path to a guard tool name.

func MatchRoute

func MatchRoute(path string) *RouteMatch

MatchRoute matches a REST API path to a guard tool name. The path should NOT include the /api/v3 prefix.

type Server

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

Server is a filtering HTTP forward proxy for the GitHub REST/GraphQL API. It loads the same WASM guard used by the MCP gateway and runs the 6-phase DIFC pipeline on every proxied response.

func New

func New(ctx context.Context, cfg Config) (*Server, error)

New creates a new proxy Server from the given Config.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns an http.Handler for the proxy server.

type TLSConfig

type TLSConfig struct {
	// CACertPath is the path to the PEM-encoded CA certificate.
	// Callers should add this to their trust store or set NODE_EXTRA_CA_CERTS.
	CACertPath string

	// CertPath is the path to the PEM-encoded server certificate.
	CertPath string

	// KeyPath is the path to the PEM-encoded server private key.
	KeyPath string

	// TLSConfig is the assembled tls.Config ready for use with http.Server.
	Config *tls.Config
}

TLSConfig holds the paths to the generated certificate files.

func GenerateSelfSignedTLS

func GenerateSelfSignedTLS(dir string) (*TLSConfig, error)

GenerateSelfSignedTLS creates a self-signed CA and server certificate for localhost. All files are written to dir. The CA cert is suitable for injection into client trust stores.

Generated files:

• ca.crt — CA certificate (share with clients)
• server.crt — Server certificate (localhost + 127.0.0.1)
• server.key — Server private key