scopes

package
v1.11.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 25, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source
const DefaultFetchTimeout = 10 * time.Second

DefaultFetchTimeout is the default timeout for scope fetching requests.

View Source
const OAuthScopesHeader = "X-OAuth-Scopes"

OAuthScopesHeader is the HTTP response header containing the token's OAuth scopes.

Variables

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

func ChallengeAll(activeScopes []string, required ...Scope) []string

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

func FetchTokenScopes(ctx context.Context, token string) ([]string, error)

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 HasAll added in v1.11.0

func HasAll(activeScopes []string, required ...Scope) bool

HasAll reports whether a token grants every requested scope.

func HasAllScopeNames added in v1.11.0

func HasAllScopeNames(activeScopes, requiredScopes []string) bool

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

func ParseScopeHeader(header string) []string

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

func SetToolScopeMapFromInventory(inv *inventory.Inventory)

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

func (f *Fetcher) FetchTokenScopes(ctx context.Context, token string) ([]string, error)

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 FetcherInterface interface {
	FetchTokenScopes(ctx context.Context, token string) ([]string, error)
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL