Documentation
¶
Index ¶
- Constants
- Variables
- func ExpandScopes(required ...Scope) []string
- func FetchTokenScopes(ctx context.Context, token string) ([]string, error)
- func FetchTokenScopesWithHost(ctx context.Context, token, apiHost string) ([]string, error)
- func HasRequiredScopes(tokenScopes []string, acceptedScopes []string) bool
- func ParseScopeHeader(header string) []string
- func ToStringSlice(scopes ...Scope) []string
- type Fetcher
- type FetcherOptions
- type Scope
- type ScopeSet
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 ExpandScopes ¶
ExpandScopes takes a list of required scopes and returns all accepted scopes including parent scopes from the hierarchy. For example, if "public_repo" is required, "repo" is also accepted since having the "repo" scope grants access to "public_repo". The returned slice is sorted for deterministic output.
func FetchTokenScopes ¶
FetchTokenScopes is a convenience function that creates a default fetcher and fetches the token scopes.
func FetchTokenScopesWithHost ¶
FetchTokenScopesWithHost is a convenience function that creates a fetcher for a specific API host and fetches the token scopes.
func HasRequiredScopes ¶
HasRequiredScopes checks if tokenScopes satisfy the acceptedScopes requirement. A tool's acceptedScopes includes both the required scopes AND parent scopes that implicitly grant the required permissions (via ExpandScopes).
For PAT filtering: if ANY of the acceptedScopes are granted by the token (directly or via scope hierarchy), the tool should be visible.
Returns true if the tool should be visible to the token holder.
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 ToStringSlice ¶
ToStringSlice converts a slice of Scopes to a slice of strings.
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(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 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 string
}
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" // 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" )
type ScopeSet ¶
ScopeSet represents a set of OAuth scopes.
func NewScopeSet ¶
NewScopeSet creates a new ScopeSet from the given scopes.
func (ScopeSet) ToStringSlice ¶
ToStringSlice converts a ScopeSet to a slice of string values. The returned slice is sorted for deterministic output.
Source Files