feat(auth): model alternative scope policies

Represent authorization as alternative execution paths with conjunctive
requirements and per-requirement accepted scopes. Resolve conditional tool
policies from call arguments while preserving legacy scope metadata.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

docs/scope-filtering.md

@@ -22,6 +22,19 @@ When the server starts with a classic PAT, it makes a lightweight HTTP HEAD requ
 
 With OAuth, the remote server can dynamically request additional scopes as needed. With PATs, scopes are fixed at token creation, so the server proactively hides tools you can't use.
 
+## Scope Policies
+
+Tool scopes are modeled as authorization paths rather than a flat list:
+
+- A tool may support multiple paths, and satisfying any path is sufficient.
+- Every independent requirement within the selected path must be satisfied.
+- A requirement may accept multiple alternative scopes, including broader scopes from the hierarchy.
+- Argument-dependent tools resolve the exact path at call time before an OAuth challenge is issued.
+
+For example, repository deletion requires `repo` **and** `delete_repo`, while listing issue fields requires `repo` for a repository request or `read:org` for an organization request. Updating an ordinary file requires `repo`; updating a workflow file requires both `repo` and `workflow`.
+
+PAT filtering runs before call arguments are known, so it keeps a tool when any supported path is usable. OAuth challenges resolve the actual arguments and request only the preferred missing scopes for that call.
+
 ## OAuth Scope Challenges (Remote Server)
 
 When using the [remote MCP server](./remote-server.md) with OAuth authentication, the server uses a different approach called **scope challenges**. Instead of hiding tools upfront, all tools are available, and the server requests additional scopes on-demand when you try to use a tool that requires them.

pkg/github/dependencies.go

@@ -230,9 +230,10 @@ func (d BaseDeps) IsFeatureEnabled(ctx context.Context, flagName string) bool {
 // The handler function receives deps extracted from context via MustDepsFromContext.
 // Ensure ContextWithDeps is called to inject deps before any tool handlers are invoked.
 //
-// requiredScopes specifies the minimum OAuth scopes needed for this tool.
-// AcceptedScopes are automatically derived using the scope hierarchy (e.g., if
-// public_repo is required, repo is also accepted since repo grants public_repo).
+// requiredScopes specifies alternative minimum OAuth scopes for this tool.
+// NewTool preserves the established any-of behavior; tools with conjunctive or
+// argument-dependent requirements should set ScopePolicy and ScopeResolver.
+// AcceptedScopes are automatically derived using the scope hierarchy.
 func NewTool[In, Out any](
 	toolset inventory.ToolsetMetadata,
 	tool mcp.Tool,
@@ -245,6 +246,9 @@ func NewTool[In, Out any](
 	})
 	st.RequiredScopes = scopes.ToStringSlice(requiredScopes...)
 	st.AcceptedScopes = scopes.ExpandScopes(requiredScopes...)
+	if len(requiredScopes) > 0 {
+		st.ScopePolicy = scopes.AnyOfScopePolicy(requiredScopes...)
+	}
 	return st
 }
 
@@ -254,8 +258,9 @@ func NewTool[In, Out any](
 // The handler function receives deps extracted from context via MustDepsFromContext.
 // Ensure ContextWithDeps is called to inject deps before any tool handlers are invoked.
 //
-// requiredScopes specifies the minimum OAuth scopes needed for this tool.
-// AcceptedScopes are automatically derived using the scope hierarchy.
+// requiredScopes specifies alternative minimum OAuth scopes for this tool.
+// NewToolFromHandler preserves the established any-of behavior; tools with
+// richer requirements should set ScopePolicy and ScopeResolver.
 func NewToolFromHandler(
 	toolset inventory.ToolsetMetadata,
 	tool mcp.Tool,
@@ -268,6 +273,9 @@ func NewToolFromHandler(
 	})
 	st.RequiredScopes = scopes.ToStringSlice(requiredScopes...)
 	st.AcceptedScopes = scopes.ExpandScopes(requiredScopes...)
+	if len(requiredScopes) > 0 {
+		st.ScopePolicy = scopes.AnyOfScopePolicy(requiredScopes...)
+	}
 	return st
 }
 

pkg/github/issue_fields.go

@@ -167,6 +167,7 @@ func ListIssueFields(t translations.TranslationHelperFunc) inventory.ServerTool
 			}
 			return result, nil, nil
 		})
+	st.ScopeResolver = repositoryOrOrganizationScopePolicy
 	return st
 }
 

pkg/github/issues.go

@@ -1256,7 +1256,7 @@ func GetIssueLabels(ctx context.Context, client *githubv4.Client, owner string,
 // ListIssueTypes creates a tool to list defined issue types for an organization or repository.
 // This can be used to understand supported issue type values for creating or updating issues.
 func ListIssueTypes(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewTool(
+	st := NewTool(
 		ToolsetMetadataIssues,
 		mcp.Tool{
 			Name:        "list_issue_types",
@@ -1354,6 +1354,8 @@ func ListIssueTypes(t translations.TranslationHelperFunc) inventory.ServerTool {
 			result = attachStaticIFCLabel(ctx, deps, result, ifc.LabelRepoMetadata(true))
 			return result, nil, nil
 		})
+	st.ScopeResolver = repositoryOrOrganizationScopePolicy
+	return st
 }
 
 // AddIssueComment creates a tool to add a comment or reaction to an issue.

pkg/github/repositories.go

@@ -625,7 +625,7 @@ SHA MUST be provided for existing file updates.
 			return MarshalledTextResult(minimalResponse), nil, nil
 		},
 	)
-	tool.ScopeResolver = workflowScopeForPath
+	tool.ScopeResolver = workflowScopePolicyForPath
 	return tool
 }
 
@@ -911,6 +911,7 @@ func DeleteRepository(t translations.TranslationHelperFunc) inventory.ServerTool
 	tool.MinimumProtocolVersion = inventory.ProtocolVersionMultiRoundTrip
 	tool.RequiredElicitationMode = inventory.ElicitationModeForm
 	tool.RequiredScopeGroups = scopes.ExpandScopeGroups(scopes.DeleteRepo, scopes.Repo)
+	tool.ScopePolicy = scopes.AllOfScopePolicy(scopes.DeleteRepo, scopes.Repo)
 	return tool
 }
 
@@ -1481,7 +1482,7 @@ func DeleteFile(t translations.TranslationHelperFunc) inventory.ServerTool {
 			return utils.NewToolResultText(string(r)), nil, nil
 		},
 	)
-	tool.ScopeResolver = workflowScopeForPath
+	tool.ScopeResolver = workflowScopePolicyForPath
 	return tool
 }
 
@@ -1832,7 +1833,7 @@ func PushFiles(t translations.TranslationHelperFunc) inventory.ServerTool {
 			return utils.NewToolResultText(string(r)), nil, nil
 		},
 	)
-	tool.ScopeResolver = workflowScopeForFiles
+	tool.ScopeResolver = workflowScopePolicyForFiles
 	return tool
 }
 

pkg/github/repository_path.go

@@ -6,12 +6,14 @@ import (
 	"slices"
 	"strings"
 
+	"github.com/github/github-mcp-server/pkg/inventory"
 	"github.com/github/github-mcp-server/pkg/scopes"
 )
 
 const workflowPathPrefix = ".github/workflows/"
 
 func validateRelativePath(value string) (string, error) {
+	value = strings.TrimPrefix(value, "/")
 	if value == "" {
 		return "", fmt.Errorf("path must not be empty")
 	}
@@ -36,31 +38,42 @@ func isWorkflowPath(value string) bool {
 	return strings.HasPrefix(value, workflowPathPrefix) && len(value) > len(workflowPathPrefix)
 }
 
-func workflowScopeForPath(arguments map[string]any) []string {
+func workflowScopePolicyForPath(arguments map[string]any) inventory.ScopePolicy {
 	value, ok := arguments["path"].(string)
 	if !ok {
-		return nil
+		return scopes.UnscopedScopePolicy()
 	}
 	cleaned, err := validateRelativePath(value)
-	if err != nil || !isWorkflowPath(cleaned) {
-		return nil
+	if err != nil {
+		return scopes.UnscopedScopePolicy()
 	}
-	return []string{string(scopes.Workflow)}
+	if !isWorkflowPath(cleaned) {
+		return scopes.AllOfScopePolicy(scopes.Repo)
+	}
+	return scopes.AllOfScopePolicy(scopes.Repo, scopes.Workflow)
 }
 
-func workflowScopeForFiles(arguments map[string]any) []string {
+func workflowScopePolicyForFiles(arguments map[string]any) inventory.ScopePolicy {
 	files, ok := arguments["files"].([]any)
 	if !ok {
-		return nil
+		return scopes.UnscopedScopePolicy()
 	}
 	for _, file := range files {
 		fileMap, ok := file.(map[string]any)
 		if !ok {
-			continue
+			return scopes.UnscopedScopePolicy()
+		}
+		value, ok := fileMap["path"].(string)
+		if !ok {
+			return scopes.UnscopedScopePolicy()
+		}
+		cleaned, err := validateRelativePath(value)
+		if err != nil {
+			return scopes.UnscopedScopePolicy()
 		}
-		if len(workflowScopeForPath(fileMap)) > 0 {
-			return []string{string(scopes.Workflow)}
+		if isWorkflowPath(cleaned) {
+			return scopes.AllOfScopePolicy(scopes.Repo, scopes.Workflow)
 		}
 	}
-	return nil
+	return scopes.AllOfScopePolicy(scopes.Repo)
 }

pkg/github/repository_path_test.go

@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	"github.com/github/github-mcp-server/pkg/inventory"
+	"github.com/github/github-mcp-server/pkg/scopes"
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -18,11 +19,12 @@ func TestValidateRelativePath(t *testing.T) {
 		wantErr string
 	}{
 		{name: "file", value: "docs/readme.md", want: "docs/readme.md"},
+		{name: "normalizes leading slash", value: "/docs/readme.md", want: "docs/readme.md"},
 		{name: "normalizes dot segment", value: "./.github/workflows/ci.yml", want: ".github/workflows/ci.yml"},
 		{name: "normalizes duplicate separator", value: ".github//workflows/ci.yml", want: ".github/workflows/ci.yml"},
 		{name: "empty", value: "", wantErr: "must not be empty"},
 		{name: "current directory", value: ".", wantErr: "must identify a file"},
-		{name: "absolute", value: "/.github/workflows/ci.yml", wantErr: "must be relative"},
+		{name: "double leading slash", value: "//.github/workflows/ci.yml", wantErr: "must be relative"},
 		{name: "parent traversal", value: "docs/../.github/workflows/ci.yml", wantErr: "parent directory traversal"},
 		{name: "leading traversal", value: "../.github/workflows/ci.yml", wantErr: "parent directory traversal"},
 		{name: "backslash traversal", value: `docs\..\.github\workflows\ci.yml`, wantErr: "forward slashes"},
@@ -47,34 +49,37 @@ func TestFileWriteWorkflowScopeResolvers(t *testing.T) {
 		name string
 		tool inventory.ServerTool
 		args map[string]any
-		want []string
+		want inventory.ScopePolicy
 	}{
 		{
 			name: "create regular file",
 			tool: CreateOrUpdateFile(translations.NullTranslationHelper),
 			args: map[string]any{"path": "docs/readme.md"},
+			want: scopes.AllOfScopePolicy(scopes.Repo),
 		},
 		{
 			name: "create workflow",
 			tool: CreateOrUpdateFile(translations.NullTranslationHelper),
 			args: map[string]any{"path": ".github/workflows/ci.yml"},
-			want: []string{"workflow"},
+			want: scopes.AllOfScopePolicy(scopes.Repo, scopes.Workflow),
 		},
 		{
 			name: "delete normalized workflow",
 			tool: DeleteFile(translations.NullTranslationHelper),
 			args: map[string]any{"path": "./.github/workflows/ci.yml"},
-			want: []string{"workflow"},
+			want: scopes.AllOfScopePolicy(scopes.Repo, scopes.Workflow),
 		},
 		{
 			name: "reject traversal instead of resolving it",
 			tool: DeleteFile(translations.NullTranslationHelper),
 			args: map[string]any{"path": "docs/../.github/workflows/ci.yml"},
+			want: scopes.UnscopedScopePolicy(),
 		},
 		{
 			name: "push regular files",
 			tool: PushFiles(translations.NullTranslationHelper),
 			args: map[string]any{"files": []any{map[string]any{"path": "README.md"}}},
+			want: scopes.AllOfScopePolicy(scopes.Repo),
 		},
 		{
 			name: "push includes workflow",
@@ -83,7 +88,7 @@ func TestFileWriteWorkflowScopeResolvers(t *testing.T) {
 				map[string]any{"path": "README.md"},
 				map[string]any{"path": ".github/workflows/ci.yml"},
 			}},
-			want: []string{"workflow"},
+			want: scopes.AllOfScopePolicy(scopes.Repo, scopes.Workflow),
 		},
 	}
 
@@ -113,7 +118,7 @@ func TestFileWriteToolsRejectUnsafePathsBeforeAPICalls(t *testing.T) {
 			name: "delete",
 			tool: DeleteFile(translations.NullTranslationHelper),
 			args: map[string]any{
-				"owner": "owner", "repo": "repo", "path": "/.github/workflows/ci.yml",
+				"owner": "owner", "repo": "repo", "path": "//.github/workflows/ci.yml",
 				"message": "message", "branch": "main",
 			},
 		},

pkg/github/scope_filter.go

@@ -15,19 +15,35 @@ var repoScopesSet = map[string]bool{
 	string(scopes.PublicRepo): true,
 }
 
-// onlyRequiresRepoScopes returns true if all of the tool's accepted scopes
-// are repo-related scopes (repo, public_repo). Such tools work on public
-// repositories without needing any scope.
-func onlyRequiresRepoScopes(acceptedScopes []string) bool {
-	if len(acceptedScopes) == 0 {
-		return false
-	}
-	for _, scope := range acceptedScopes {
-		if !repoScopesSet[scope] {
-			return false
+// hasRepoOnlyScopeAlternative returns true if at least one authorization path
+// uses only repo-related scopes. Such a path may work on a public repository
+// without any token scope.
+func hasRepoOnlyScopeAlternative(policy inventory.ScopePolicy) bool {
+	for _, alternative := range policy.AnyOf {
+		if len(alternative.AllOf) == 0 {
+			continue
+		}
+		repoOnly := true
+		for _, requirement := range alternative.AllOf {
+			accepted := requirement.AcceptedScopes
+			if len(accepted) == 0 {
+				accepted = []string{requirement.RequiredScope}
+			}
+			for _, scope := range accepted {
+				if !repoScopesSet[scope] {
+					repoOnly = false
+					break
+				}
+			}
+			if !repoOnly {
+				break
+			}
+		}
+		if repoOnly {
+			return true
 		}
 	}
-	return true
+	return false
 }
 
 // CreateToolScopeFilter creates an inventory.ToolFilter that filters tools
@@ -41,9 +57,9 @@ func onlyRequiresRepoScopes(acceptedScopes []string) bool {
 // token is known at startup and won't change during the session.
 //
 // The filter returns true (include tool) if:
-//   - The tool has no scope requirements (AcceptedScopes is empty)
+//   - The tool has an unscoped authorization path
 //   - The tool is read-only and only requires repo/public_repo scopes (works on public repos)
-//   - The token has at least one of the tool's accepted scopes
+//   - The token satisfies every requirement in any authorization path
 //
 // Example usage:
 //
@@ -55,13 +71,11 @@ func onlyRequiresRepoScopes(acceptedScopes []string) bool {
 //	inventory := github.NewInventory(t).WithFilter(filter).Build()
 func CreateToolScopeFilter(tokenScopes []string) inventory.ToolFilter {
 	return func(_ context.Context, tool *inventory.ServerTool) (bool, error) {
+		policy := scopes.ScopePolicyForTool(tool)
 		// Read-only tools requiring only repo/public_repo work on public repos without any scope
-		if tool.Tool.Annotations != nil && tool.Tool.Annotations.ReadOnlyHint && onlyRequiresRepoScopes(tool.AcceptedScopes) {
+		if tool.Tool.Annotations != nil && tool.Tool.Annotations.ReadOnlyHint && hasRepoOnlyScopeAlternative(policy) {
 			return true, nil
 		}
-		if len(tool.RequiredScopeGroups) > 0 {
-			return scopes.HasRequiredScopeGroups(tokenScopes, tool.RequiredScopeGroups), nil
-		}
-		return scopes.HasRequiredScopes(tokenScopes, tool.AcceptedScopes), nil
+		return scopes.ScopePolicySatisfied(tokenScopes, policy), nil
 	}
 }

pkg/github/scope_filter_test.go

@@ -211,6 +211,7 @@ func TestCreateToolScopeFilter_Integration(t *testing.T) {
 
 func TestCreateToolScopeFilterPreservesExistingMultiScopeSemantics(t *testing.T) {
 	filter := CreateToolScopeFilter([]string{"repo"})
+	unscopedFilter := CreateToolScopeFilter(nil)
 	tools := []inventory.ServerTool{
 		ListIssueFields(translations.NullTranslationHelper),
 		ListIssueTypes(translations.NullTranslationHelper),
@@ -222,5 +223,9 @@ func TestCreateToolScopeFilterPreservesExistingMultiScopeSemantics(t *testing.T)
 		require.NoError(t, err)
 		assert.True(t, allowed, "%s should remain visible with a repo-only token", tools[i].Tool.Name)
 		assert.Empty(t, tools[i].RequiredScopeGroups, "%s should retain legacy any-of scope semantics", tools[i].Tool.Name)
+
+		allowed, err = unscopedFilter(context.Background(), &tools[i])
+		require.NoError(t, err)
+		assert.True(t, allowed, "%s should remain visible when a public-repository path is plausible", tools[i].Tool.Name)
 	}
 }