handler

Documentation

Overview

Package handler implements HTTP handlers for the github-sts service.

Index

• Constants
• func HealthHandler() http.HandlerFunc
• func MetricsHandler(authToken string) http.Handler
• func ReadinessHandler(ready *atomic.Bool) http.HandlerFunc
• type ErrorResponse
• type ExchangeHandler
  • func NewExchangeHandler(jtiCache jti.Cache, policyLoader policy.Loader, ...) *ExchangeHandler
  • func (h *ExchangeHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ExchangeRequest
• type ExchangeResponse

Constants

const (
	// 400 — request shape rejected before any auth happened.
	CodeBadRequest = "bad_request"

	// 403 — token rejected. Coarse on purpose; the matching trace_id log line
	// carries the precise reason.
	CodeOIDCInvalid      = "oidc_invalid"      // missing/expired/bad-signature/unknown-issuer/missing-kid/malformed
	CodeAudienceMismatch = "audience_mismatch" // token aud did not match policy.audience
	CodeAppUnknown       = "app_unknown"       // requested ?app= is not configured on the server
	CodePolicyNotFound   = "policy_not_found"  // no .sts.yaml for this scope/app/identity
	CodePolicyDenied     = "policy_denied"     // policy exists but evaluation failed (subject/claim_pattern)

	// Other status codes.
	CodeMethodNotAllowed = "method_not_allowed" // 405
	CodeReplay           = "replay_detected"    // 409
	CodeInternal         = "internal_error"     // 500
	CodeUpstream         = "upstream_error"     // 502
)

Error codes returned in ErrorResponse.Code. These are a stable public API — do not rename without a major version bump.

const TraceIDKey contextKey = "trace_id"

TraceIDKey is the context key for the trace ID.

Functions

func HealthHandler

func HealthHandler() http.HandlerFunc

HealthHandler returns a handler for the liveness probe. Always returns 200 — if the process is alive, it's healthy.

func MetricsHandler

func MetricsHandler(authToken string) http.Handler

MetricsHandler returns the Prometheus metrics exposition handler. If authToken is non-empty, requests must include a matching Authorization: Bearer <token> header. The comparison is constant-time to prevent timing-oracle recovery of the token byte-by-byte.

func ReadinessHandler

func ReadinessHandler(ready *atomic.Bool) http.HandlerFunc

ReadinessHandler returns a handler for the readiness probe. Returns 200 when ready, 503 during startup/shutdown.

Types

type ErrorResponse

type ErrorResponse struct {
	Error   string `json:"error"`
	Code    string `json:"code,omitempty"`
	TraceID string `json:"trace_id,omitempty"`
}

ErrorResponse is returned on exchange errors.

Error stays deliberately generic ("forbidden", "upstream error") so attackers cannot probe the validator. Code is a stable, coarse category safe to surface to callers — operators use it to tell apart "fix the workflow" from "fix the policy" failures without log access. TraceID is the per-request identifier also emitted in audit/server logs; give it to ops to find the matching log line, which carries the full reason.

type ExchangeHandler

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

ExchangeHandler orchestrates the token exchange flow.

func NewExchangeHandler

func NewExchangeHandler(
	jtiCache jti.Cache,
	policyLoader policy.Loader,
	appProviders map[string]*github.AppTokenProvider,
	allowedIssuers []string,
	requiredAudience string,
	auditLogger audit.Logger,
	slogger *slog.Logger,
	trustForwardedHeaders bool,
) *ExchangeHandler

NewExchangeHandler creates a new ExchangeHandler with all dependencies injected. requiredAudience, when non-empty, is enforced on every token before policy lookup as a server-wide defense against permissive policy files.

func (*ExchangeHandler) ServeHTTP

func (h *ExchangeHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles the token exchange request.

type ExchangeRequest

type ExchangeRequest struct {
	Scope    string `json:"scope"`
	Identity string `json:"identity"`
	AppName  string `json:"app"`
}

ExchangeRequest represents parsed exchange parameters.

type ExchangeResponse

type ExchangeResponse struct {
	Token       string            `json:"token"`
	Scope       string            `json:"scope"`
	App         string            `json:"app"`
	Identity    string            `json:"identity"`
	Permissions map[string]string `json:"permissions"`
}

ExchangeResponse is returned on successful token exchange.