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 DeriveGitHubAPIURL() string
• func InjectGuardFields(body []byte, toolName string) []byte
• 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 DeriveGitHubAPIURL

func DeriveGitHubAPIURL() string

DeriveGitHubAPIURL resolves the upstream GitHub API URL from environment variables. Priority order:

1. GITHUB_API_URL — explicit API endpoint (e.g. https://copilot-api.mycompany.ghe.com)
2. GITHUB_SERVER_URL — auto-derive API endpoint from server URL: - https://mycompany.ghe.com → https://copilot-api.mycompany.ghe.com - https://github.mycompany.com → https://github.mycompany.com/api/v3 - https://github.com → https://api.github.com
3. Returns empty string if no env vars are set (caller uses DefaultGitHubAPIBase)

func InjectGuardFields

func InjectGuardFields(body []byte, toolName string) []byte

InjectGuardFields rewrites a GraphQL request body to include fields required by the DIFC guard (e.g. author{login} for trusted-bot detection). Returns the (possibly modified) body. If injection is not needed or fails, the original body is returned unchanged.

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

	// TrustedBots is an optional list of additional trusted bot usernames.
	// These are passed to the guard alongside the policy during LabelAgent
	// initialization, extending the guard's built-in trusted bot list
	// (e.g. dependabot[bot], github-actions[bot]).
	TrustedBots []string

	// TrustedUsers is an optional list of GitHub usernames to elevate to approved
	// (writer) integrity, regardless of their author_association. These are injected
	// into the allow-only policy's trusted-users field during LabelAgent initialization.
	TrustedUsers []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