Documentation
¶
Index ¶
- Constants
- Variables
- func ChallengeAll(activeScopes []string, required ...Scope) []string
- func DefaultOAuthScopes() []string
- func DynamicChallenge(maxScopes []Scope, visible inventory.ScopeVisibility, ...) inventory.ScopeAccess
- func FetchTokenScopes(ctx context.Context, token string) ([]string, error)
- func FetchTokenScopesWithHost(ctx context.Context, token string, apiHost utils.APIHostResolver) ([]string, error)
- func HasAll(activeScopes []string, required ...Scope) bool
- func HasAllScopeNames(activeScopes, requiredScopes []string) bool
- func NoScopes() inventory.ScopeAccess
- func ParseScopeHeader(header string) []string
- func PublicRead(required ...Scope) inventory.ScopeAccess
- func RequireAll(required ...Scope) inventory.ScopeAccess
- func SetGlobalToolScopeMap(m ToolScopeMap)
- func SetToolScopeMapFromInventory(inv *inventory.Inventory)
- func SupportedOAuthScopes() []string
- type Fetcher
- type FetcherInterface
- type FetcherOptions
- type Scope
- type ToolScopeAccess
- type ToolScopeMap
Constants ¶
const DefaultFetchTimeout = 10 * time.Second
DefaultFetchTimeout is the default timeout for scope fetching requests.
const OAuthScopesHeader = "X-OAuth-Scopes"
OAuthScopesHeader is the HTTP response header containing the token's OAuth scopes.
Variables ¶
var ScopeHierarchy = map[Scope][]Scope{ Repo: {PublicRepo, SecurityEvents}, AdminOrg: {WriteOrg, ReadOrg}, WriteOrg: {ReadOrg}, Project: {ReadProject}, WritePackages: {ReadPackages}, User: {ReadUser, UserEmail}, }
ScopeHierarchy defines parent-child relationships between scopes. A parent scope implicitly grants access to all child scopes. For example, "repo" grants access to "public_repo" and "security_events".
Functions ¶
func ChallengeAll ¶ added in v1.11.0
ChallengeAll returns the complete scope set for an operation, or nil when the active token already grants every scope.
func DefaultOAuthScopes ¶ added in v1.10.0
func DefaultOAuthScopes() []string
DefaultOAuthScopes returns the lower-risk scopes requested by default.
func DynamicChallenge ¶ added in v1.11.0
func DynamicChallenge(maxScopes []Scope, visible inventory.ScopeVisibility, challenge inventory.ScopeChallenge) inventory.ScopeAccess
DynamicChallenge creates an argument-dependent scope policy. maxScopes must exhaustively list every scope challenge can return, allowing middleware to skip argument decoding and challenge evaluation when they are already granted.
func FetchTokenScopes ¶
FetchTokenScopes is a convenience function that creates a default fetcher and fetches the token scopes.
func FetchTokenScopesWithHost ¶
func FetchTokenScopesWithHost(ctx context.Context, token string, apiHost utils.APIHostResolver) ([]string, error)
FetchTokenScopesWithHost is a convenience function that creates a fetcher for a specific API host and fetches the token scopes.
func HasAllScopeNames ¶ added in v1.11.0
HasAllScopeNames reports whether a token grants every requested scope name. It avoids materializing an expanded scope set on the request hot path.
func NoScopes ¶ added in v1.11.0
func NoScopes() inventory.ScopeAccess
NoScopes creates scope checks for a tool that does not need OAuth scopes.
func ParseScopeHeader ¶
ParseScopeHeader parses the X-OAuth-Scopes header value into a list of scopes. The header contains comma-separated scope names. Returns an empty slice for empty or missing header.
func PublicRead ¶ added in v1.11.0
func PublicRead(required ...Scope) inventory.ScopeAccess
PublicRead creates checks for a read-only operation that may target public data.
func RequireAll ¶ added in v1.11.0
func RequireAll(required ...Scope) inventory.ScopeAccess
RequireAll creates scope checks for a tool that always needs the given scopes.
func SetGlobalToolScopeMap ¶ added in v0.31.0
func SetGlobalToolScopeMap(m ToolScopeMap)
SetGlobalToolScopeMap sets the scope map directly.
func SetToolScopeMapFromInventory ¶ added in v0.31.0
SetToolScopeMapFromInventory builds and stores the scope checks from an inventory.
func SupportedOAuthScopes ¶ added in v1.10.0
func SupportedOAuthScopes() []string
SupportedOAuthScopes returns every OAuth scope the server may request.
Types ¶
type Fetcher ¶
type Fetcher struct {
// contains filtered or unexported fields
}
Fetcher retrieves token scopes from GitHub's API. It uses an HTTP HEAD request to minimize bandwidth since we only need headers.
func NewFetcher ¶
func NewFetcher(apiHost utils.APIHostResolver, opts FetcherOptions) *Fetcher
NewFetcher creates a new scope fetcher with the given options.
func (*Fetcher) FetchTokenScopes ¶
FetchTokenScopes retrieves the OAuth scopes for a token by making an HTTP HEAD request to the GitHub API and parsing the X-OAuth-Scopes header.
Returns:
- []string: List of scopes (empty if no scopes or fine-grained PAT)
- error: Any HTTP or parsing error
Note: Fine-grained PATs don't return the X-OAuth-Scopes header, so an empty slice is returned for those tokens.
type FetcherInterface ¶ added in v0.31.0
type FetcherOptions ¶
type FetcherOptions struct {
// HTTPClient is the HTTP client to use for requests.
// If nil, a default client with DefaultFetchTimeout is used.
HTTPClient *http.Client
// APIHost is the GitHub API host (e.g., "https://api.github.com").
// Defaults to "https://api.github.com" if empty.
APIHost utils.APIHostResolver
}
FetcherOptions configures the scope fetcher.
type Scope ¶
type Scope string
Scope represents a GitHub OAuth scope. These constants define all OAuth scopes used by the GitHub MCP server tools. See https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps
const ( // NoScope indicates no scope is required (public access). NoScope Scope = "" // Repo grants full control of private repositories Repo Scope = "repo" // PublicRepo grants access to public repositories PublicRepo Scope = "public_repo" // DeleteRepo grants permission to delete repositories DeleteRepo Scope = "delete_repo" // ReadOrg grants read-only access to organization membership, teams, and projects ReadOrg Scope = "read:org" // WriteOrg grants write access to organization membership and teams WriteOrg Scope = "write:org" // AdminOrg grants full control of organizations and teams AdminOrg Scope = "admin:org" // Gist grants write access to gists Gist Scope = "gist" // Notifications grants access to notifications Notifications Scope = "notifications" // ReadProject grants read-only access to projects ReadProject Scope = "read:project" // Project grants full control of projects Project Scope = "project" // SecurityEvents grants read and write access to security events SecurityEvents Scope = "security_events" // User grants read/write access to profile info User Scope = "user" // ReadUser grants read-only access to profile info ReadUser Scope = "read:user" // UserEmail grants read access to user email addresses UserEmail Scope = "user:email" // ReadPackages grants read access to packages ReadPackages Scope = "read:packages" // WritePackages grants write access to packages WritePackages Scope = "write:packages" // Workflow grants permission to update GitHub Actions workflow files Workflow Scope = "workflow" // Codespace grants full control of codespaces Codespace Scope = "codespace" )
type ToolScopeAccess ¶ added in v1.11.0
type ToolScopeAccess struct {
// contains filtered or unexported fields
}
ToolScopeAccess is the immutable request-time subset of a tool scope policy. Its maximum scopes stay private so callers cannot mutate the global lookup.
func GetToolScopeAccess ¶ added in v1.11.0
func GetToolScopeAccess(toolName string) (ToolScopeAccess, bool)
GetToolScopeAccess returns the immutable request-time scope policy for a tool.
func (ToolScopeAccess) MaximumScopes ¶ added in v1.11.0
func (access ToolScopeAccess) MaximumScopes() []string
MaximumScopes returns a copy of the exhaustive upper bound.
func (ToolScopeAccess) MaximumScopesSatisfied ¶ added in v1.11.0
func (access ToolScopeAccess) MaximumScopesSatisfied(activeScopes []string) bool
MaximumScopesSatisfied reports whether activeScopes grants the exhaustive upper bound for this policy.
func (ToolScopeAccess) ResolveChallenge ¶ added in v1.11.0
func (access ToolScopeAccess) ResolveChallenge(arguments map[string]any, activeScopes []string) []string
ResolveChallenge evaluates the call-specific policy.
type ToolScopeMap ¶ added in v0.31.0
type ToolScopeMap map[string]inventory.ScopeAccess
ToolScopeMap maps tool names to their complete scope access policies.
func GetToolScopeMapFromInventory ¶ added in v0.31.0
func GetToolScopeMapFromInventory(inv *inventory.Inventory) ToolScopeMap
GetToolScopeMapFromInventory builds a scope map from an inventory.