Document scope-filter limitations and fail-open posture

Correct the over-claim that the scope hierarchy covers all OR cases. The
hierarchy only models ancestor substitution, not sibling alternatives, so it
cannot represent every way a tool may legitimately be satisfied.

- Reword HasRequiredScopes doc: AND-of-ORs is ancestor-only; note the
  best-effort/fail-open posture and make the future CNF extension concrete using
  code scanning as the motivating example (security_events OR public_repo OR repo).
- Note in CreateToolScopeFilter that filtering is a best-effort UX filter, not an
  authorization boundary (gated to ghp_ PATs, skipped when scopes can't be fetched).
- Verify security tools ({security_events}) stay behavior-neutral under AND: a
  repo token still satisfies them; a public_repo-only token was already hidden
  before. Add explicit neutrality tests at the scope and filter layers.
- docs/scope-filtering.md: add a Limitations and Fail-Open Posture section
  (sibling scopes, org roles, repo visibility) and a best-effort intro note.

No tool declarations or scopes changed; no CNF structure built.

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

Author: SamMorrowDrums

docs/scope-filtering.md

@@ -4,6 +4,8 @@ The GitHub MCP Server automatically filters available tools based on your classi
 
 > **Note:** This feature applies to **classic PATs** (tokens starting with `ghp_`). Fine-grained PATs, GitHub App installation tokens, and server-to-server tokens don't support scope detection and show all tools.
 
+> **Important:** Scope filtering is a best-effort UX convenience, **not an authorization boundary**. The GitHub API is always the source of truth and enforces real permissions. The server therefore **fails open**: it only hides a tool when confident your token cannot use it, and shows the tool whenever access is plausible. See [Limitations and Fail-Open Posture](#limitations-and-fail-open-posture).
+
 ## How It Works
 
 When the server starts with a classic PAT, it makes a lightweight HTTP HEAD request to the GitHub API to discover your token's scopes from the `X-OAuth-Scopes` header. Tools that require scopes your token doesn't have are automatically hidden.
@@ -76,6 +78,18 @@ If the server cannot fetch your token's scopes (e.g., network issues, rate limit
 WARN: failed to fetch token scopes, continuing without scope filtering
 ```
 
+## Limitations and Fail-Open Posture
+
+Scope filtering is a **best-effort UX nicety**, not an authorization boundary. The GitHub API is the source of truth and enforces real permissions regardless of what the server shows. Because of this, the server is designed to **fail open**: it only hides a tool (or, for OAuth, issues a scope challenge) when it is confident the token cannot use it. When access is plausible, it prefers to show the tool and let the API decide. Filtering is also limited to classic PATs (`ghp_`) and is skipped entirely when scopes can't be fetched.
+
+A tool's declared scopes are **all required** (logical AND), and each one may be satisfied directly or by an ancestor scope from the [hierarchy](#scope-hierarchy). However, some ways a tool can legitimately be used cannot be determined from OAuth scopes alone, so the server intentionally does not try to model them:
+
+- **Sibling scopes outside the hierarchy.** The hierarchy only models *ancestor* substitution. For example, code scanning alerts on a **public** repository are readable with `public_repo`, which is a *sibling* of the declared `security_events` (both are children of `repo`), not an ancestor. Token expansion can't bridge siblings. Capturing this faithfully would require representing requirements as a list of OR-groups (groups AND-ed, members within a group OR-ed), e.g. code scanning = `security_events` OR `public_repo` OR `repo`. That model isn't implemented today; instead the server relies on the fail-open posture so these cases aren't wrongly hidden.
+- **Organization roles.** Roles such as *security manager* grant access orthogonally to OAuth scopes and are invisible to scope detection. A user may legitimately have access the server cannot see from scopes alone.
+- **Public vs. private repositories.** Whether a given scope suffices depends on the target repository's visibility, which isn't known at filter time.
+
+In each of these cases the server errs toward showing the tool; if the token truly lacks access, the API returns the appropriate error.
+
 ## Classic vs Fine-Grained Personal Access Tokens
 
 **Classic PATs** (`ghp_` prefix) support OAuth scopes and return them in the `X-OAuth-Scopes` header. Scope filtering works fully with these tokens.
@@ -92,7 +106,7 @@ WARN: failed to fetch token scopes, continuing without scope filtering
 |---------|-------|----------|
 | Missing expected tools | Token lacks required scope | [Edit your PAT's scopes](https://github.com/settings/tokens) in GitHub settings |
 | All tools visible despite limited PAT | Scope detection failed | Check logs for warnings about scope fetching |
-| "Insufficient permissions" errors | Tool visible but scope insufficient | This shouldn't happen with scope filtering; report as bug |
+| "Insufficient permissions" errors | Tool visible but scope insufficient | Expected in some cases (fail-open, public/private ambiguity, org roles, or scope detection skipped). The API enforces the real boundary—grant the needed scope or access |
 
 > **Tip:** You can adjust the scopes of an existing classic PAT at any time via [GitHub's token settings](https://github.com/settings/tokens). After updating scopes, restart the MCP server to pick up the changes.
 

pkg/github/scope_filter.go

@@ -37,6 +37,12 @@ func onlyRequiresRepoScopes(requiredScopes []string) bool {
 // like we can with OAuth apps. Instead, we hide tools that require scopes
 // the token doesn't have.
 //
+// This is a best-effort UX filter, not an authorization boundary: the GitHub
+// API still enforces real permissions. It is gated to classic ghp_ PATs and is
+// skipped entirely when scopes can't be fetched, so the posture is to fail open
+// (prefer showing a tool when access is plausible). See docs/scope-filtering.md
+// for the known limitations (sibling scopes, org roles, repo visibility).
+//
 // This is the recommended way to filter tools for stdio servers where the
 // token is known at startup and won't change during the session.
 //

pkg/github/scope_filter_test.go

@@ -63,6 +63,15 @@ func TestCreateToolScopeFilter(t *testing.T) {
 		RequiredScopes: []string{"repo", "read:org"},
 	}
 
+	// Models security tools (code scanning etc.): read-only, single {security_events}.
+	toolSecurityEvents := &inventory.ServerTool{
+		Tool: mcp.Tool{
+			Name:        "list_code_scanning_alerts",
+			Annotations: &mcp.ToolAnnotations{ReadOnlyHint: true},
+		},
+		RequiredScopes: []string{"security_events"},
+	}
+
 	tests := []struct {
 		name        string
 		tokenScopes []string
@@ -147,6 +156,24 @@ func TestCreateToolScopeFilter(t *testing.T) {
 			tool:        toolRepoAndReadOrg,
 			expected:    true,
 		},
+		{
+			name:        "security tool: repo token satisfies security_events (neutral)",
+			tokenScopes: []string{"repo"},
+			tool:        toolSecurityEvents,
+			expected:    true,
+		},
+		{
+			name:        "security tool: security_events token shows tool",
+			tokenScopes: []string{"security_events"},
+			tool:        toolSecurityEvents,
+			expected:    true,
+		},
+		{
+			name:        "security tool: public_repo (sibling) does not show tool",
+			tokenScopes: []string{"public_repo"},
+			tool:        toolSecurityEvents,
+			expected:    false,
+		},
 	}
 
 	for _, tt := range tests {

pkg/scopes/scopes.go

@@ -172,20 +172,29 @@ func expandScopeSet(scopes []string) map[string]bool {
 // requiredScopes. The requiredScopes are the literal scopes a tool declares and
 // they are all required: satisfaction is AND-of-ORs (conjunctive normal form).
 //
-// The AND is over the distinct required scopes. The OR is the hierarchy: each
-// required scope can be satisfied either directly or by a higher scope that
-// implicitly grants it. This is implemented by expanding the TOKEN downward
-// through the hierarchy (via expandScopeSet, e.g. repo -> public_repo and
-// admin:org -> read:org) and checking that every required scope is present in
-// that expanded set.
+// The AND is over the distinct required scopes. The OR, for each required
+// scope, is limited to the scope hierarchy: a required scope is satisfied
+// directly or by one of its ANCESTOR scopes that implicitly grants it. This is
+// implemented by expanding the TOKEN downward through the hierarchy (via
+// expandScopeSet, e.g. repo -> public_repo and admin:org -> read:org) and
+// checking that every required scope is present in that expanded set.
 //
 // An empty requiredScopes is always satisfied.
 //
-// Each required scope currently has exactly one satisfying alternative set (the
-// scope itself plus its hierarchy ancestors). If a tool ever needs true
-// arbitrary alternatives (e.g. "repo OR admin:org" for a single requirement),
-// the place to add it is a list-of-groups extension to RequiredScopes; that is
-// deliberately not built yet (YAGNI).
+// Scope filtering is a best-effort UX nicety for classic PATs, NOT an
+// authorization boundary: the GitHub API remains the source of truth, so the
+// intended posture is to fail open (only hide when confident the token cannot
+// work). See docs/scope-filtering.md.
+//
+// Limitation: the hierarchy only models ancestor substitution, not sibling
+// alternatives, so it does not capture every way a tool may be satisfied. For
+// example, reading code scanning alerts on a PUBLIC repo is possible with
+// public_repo, a sibling of the declared security_events (both children of
+// repo), which token expansion cannot bridge. Representing that faithfully
+// would require RequiredScopes to become a CNF list of OR-groups (groups
+// AND-ed, members within a group OR-ed), e.g. code scanning =
+// {security_events OR public_repo OR repo}. That structure is deliberately not
+// built yet (YAGNI).
 func HasRequiredScopes(tokenScopes []string, requiredScopes []string) bool {
 	// No scopes required = always allowed
 	if len(requiredScopes) == 0 {

pkg/scopes/scopes_test.go

@@ -309,6 +309,24 @@ func TestHasRequiredScopes(t *testing.T) {
 			requiredScopes: []string{"repo"},
 			expected:       false,
 		},
+		{
+			name:           "security tool: repo token satisfies security_events (neutral)",
+			tokenScopes:    []string{"repo"},
+			requiredScopes: []string{"security_events"},
+			expected:       true,
+		},
+		{
+			name:           "security tool: security_events token satisfies security_events",
+			tokenScopes:    []string{"security_events"},
+			requiredScopes: []string{"security_events"},
+			expected:       true,
+		},
+		{
+			name:           "security tool: public_repo (sibling) does NOT satisfy security_events",
+			tokenScopes:    []string{"public_repo"},
+			requiredScopes: []string{"security_events"},
+			expected:       false,
+		},
 		{
 			name:           "user scope grants read:user",
 			tokenScopes:    []string{"user"},