Documentation
¶
Overview ¶
Package sts implements the Security Token Service exchange workflow.
The Service orchestrates the full token exchange: OIDC validation, two-layer authorization, GitHub App selection, token generation, rate limit tracking, and audit logging.
Index ¶
Constants ¶
const ( ErrInvalidToken = "INVALID_TOKEN" ErrInvalidRequest = "INVALID_REQUEST" ErrRateLimited = "RATE_LIMITED" ErrAppSelectionFailed = "APP_SELECTION_FAILED" ErrClientNotFound = "GITHUB_CLIENT_NOT_FOUND" ErrInternalError = "INTERNAL_ERROR" ErrPolicyLoadFailed = "POLICY_LOAD_FAILED" ErrTrustPolicyNotFound = "TRUST_POLICY_NOT_FOUND" ErrRepositoryNotFound = "REPOSITORY_NOT_FOUND" ErrPolicyNotFound = "POLICY_NOT_FOUND" ErrIssuerNotAllowed = "ISSUER_NOT_ALLOWED" ErrGitHubAPIError = "GITHUB_API_ERROR" )
Error code constants used in ExchangeError. Returned to API clients in the error_code field.
Variables ¶
var ( // ErrNilConfig is returned when NewService is called with nil config. ErrNilConfig = errors.New("config is required") // ErrNilSelector is returned when NewService dependencies have a nil Selector. ErrNilSelector = errors.New("selector is required") // ErrNilAudit is returned when NewService dependencies have a nil Audit backend. ErrNilAudit = errors.New("audit backend is required") // ErrNoApps is returned when config has no GitHub apps configured. ErrNoApps = errors.New("at least one GitHub app is required") )
Functions ¶
This section is empty.
Types ¶
type Dependencies ¶
type Dependencies struct {
Selector *selector.Selector
Audit audit.AuditEntryBackend
Logger *slog.Logger
}
Dependencies holds external dependencies that cannot be derived from config alone.
type ExchangeError ¶
type ExchangeError struct {
Code string `json:"error_code"` // Machine-readable code (e.g. INVALID_TOKEN).
Message string `json:"error"` // Human-readable message.
Details string `json:"details,omitempty"` // Optional additional context.
RequestID string `json:"request_id"` // Request ID for correlation.
RetryAfterSeconds int `json:"retry_after_seconds,omitempty"` // Set when code is RATE_LIMITED.
Issuer string `json:"-"` // Caller issuer (set after OIDC validation).
Subject string `json:"-"` // Caller subject (set after OIDC validation).
}
ExchangeError represents a token exchange failure with structured error details for API responses.
func (*ExchangeError) Error ¶
func (e *ExchangeError) Error() string
Error returns the formatted error message including the error code and details.
func (*ExchangeError) WithCaller ¶ added in v1.0.4
func (e *ExchangeError) WithCaller(issuer, subject string) *ExchangeError
WithCaller sets the caller identity fields and returns the error for chaining.
type ExchangeRequest ¶
type ExchangeRequest struct {
OIDCToken string `json:"oidc_token"`
TargetRepository string `json:"target_repository"`
PolicyName string `json:"policy_name,omitempty"`
RequestedPermissions map[string]string `json:"requested_permissions,omitempty"`
RequestedTTL int `json:"requested_ttl,omitempty"`
}
ExchangeRequest represents an incoming token exchange request.
type ExchangeResponse ¶
type ExchangeResponse struct {
Token string `json:"token"`
ExpiresAt time.Time `json:"expires_at"`
MatchedPolicy string `json:"matched_policy"`
Permissions map[string]string `json:"permissions"`
RequestID string `json:"request_id"`
Issuer string `json:"-"`
Subject string `json:"-"`
ClientID string `json:"-"`
TokenHash string `json:"-"`
TTL int `json:"-"`
}
ExchangeResponse represents a successful token exchange result. Fields tagged `json:"-"` are populated for internal observers (logging, metrics) and never serialized to the API client.
type Exchanger ¶
type Exchanger interface {
// Exchange validates the OIDC token, authorizes the request,
// selects an app, and returns a GitHub installation token
// or an *ExchangeError.
Exchange(ctx context.Context, requestID string, req *ExchangeRequest) (*ExchangeResponse, error)
}
Exchanger defines the interface for the token exchange operation.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service orchestrates the complete STS token exchange workflow.
func NewService ¶
func NewService(cfg *config.Config, dependencies Dependencies) (*Service, error)
NewService creates a fully wired Service from config and external dependencies. It builds the OIDC validator, GitHub clients, and authorizer internally.
func (*Service) Exchange ¶
func (s *Service) Exchange(ctx context.Context, requestID string, req *ExchangeRequest) (*ExchangeResponse, error)
Exchange exchanges an OIDC token for a GitHub installation token, emitting one structured log line per call.
type TokenTracker ¶
type TokenTracker struct {
// contains filtered or unexported fields
}
TokenTracker tracks issued tokens in memory keyed by token hash.
func NewTokenTracker ¶
func NewTokenTracker() *TokenTracker
NewTokenTracker creates an empty tracker.
func (*TokenTracker) GetExpired ¶
func (c *TokenTracker) GetExpired() map[string]string
GetExpired returns all entries whose expiry has passed without removing them.
func (*TokenTracker) Record ¶
func (c *TokenTracker) Record(hash, token string, expires time.Time)
Record stores a token keyed by its hash with the given expiry.
func (*TokenTracker) Remove ¶
func (c *TokenTracker) Remove(hash string)
Remove deletes a single hash from the tracker.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package audit defines the audit logging interface and entry types.
|
Package audit defines the audit logging interface and entry types. |
|
backends
Package backends provides audit logging backend implementations.
|
Package backends provides audit logging backend implementations. |
|
Package authorizer implements two-layer authorization for token exchange requests.
|
Package authorizer implements two-layer authorization for token exchange requests. |
|
Package oidc validates OIDC tokens for the STS exchange flow.
|
Package oidc validates OIDC tokens for the STS exchange flow. |
|
Package selector implements GitHub App selection based on rate limit headroom.
|
Package selector implements GitHub App selection based on rate limit headroom. |
|
backends
Package backends provides selector store implementations.
|
Package backends provides selector store implementations. |