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).
TLS helpers are split across two packages:
internal/proxy (this file): certificate *generation* (GenerateSelfSignedTLS). This is the only place self-signed certs are created.
internal/httputil: protocol-level helpers and file-loading helpers that apply to all TLS listeners and clients (MinTLSVersion, NewServerTLSConfig, NewClientTLSConfig, ConfigureTLSTrustEnvironment, LoadGatewayTLS).
Architectural rule: add TLS *certificate generation* helpers here; add TLS *protocol and file-loading* helpers to internal/httputil/tls.go.
Index ¶
Constants ¶
const (
// DefaultGitHubAPIBase is the upstream GitHub API URL.
DefaultGitHubAPIBase = "https://api.github.com"
)
Variables ¶
This section is empty.
Functions ¶
func InjectGuardFields ¶ added in v0.2.0
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 ¶
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 ¶
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.
Uses a dispatch map keyed by the fixed sub-resource segment (e.g. "issues", "pulls", "actions") to narrow down the candidate routes before regexp matching. This reduces the average number of regexp evaluations from O(N) across all 49 routes to O(k) where k is the number of routes in the bucket (typically 1–14 instead of up to 49).
type Server ¶
type Server struct {
difc.DIFCComponents
// 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.
type TLSConfig ¶ added in v0.1.21
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 ¶ added in v0.1.21
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