Challenge workflow file writes for OAuth scope

[SamMorrowDrums]

Summary

Conditionally require the workflow OAuth scope when file-write tools target .github/workflows/**, while preserving normal repo-only writes elsewhere.

Why

GitHub requires the additional workflow scope for workflow-file updates, but statically requiring it would over-scope every file write. The remote server needs a per-call 403 challenge before handlers execute.

Fixes # N/A

What changed

• Added a shared traversal-safe relative path validator used by create_or_update_file, delete_file, and every push_files entry.
• Added per-call scope resolution from parsed MCP arguments and a pre-handler insufficient-scope challenge for workflow paths.
• Projected top-level path through SEP-2243 headers while keeping paths nested in arrays body-parsed.
• Removed unused codespace OAuth scope metadata and added regression coverage for traversal, arrays, headers, and challenges.

MCP impact

• No tool or API changes
• Tool schema or behavior changed — workflow file writes can now receive a 403 OAuth challenge for the additional workflow scope; input schemas are unchanged.
• New tool added

Prompts tested (tool changes only)

• "Create .github/workflows/ci.yml in owner/repo" — exercises the conditional workflow-scope challenge.
• "Push README.md and .github/workflows/ci.yml in one commit" — exercises workflow detection inside the files array.
• "Delete .github/workflows/ci.yml" — exercises conditional scope resolution for deletion.

Security / limits

• No security or limits impact
• Auth / permissions considered — only workflow paths add workflow; existing token scopes are retained in the challenge.
• Data exposure, filtering, or token/size limits considered — authorization and handlers share path validation so traversal cannot bypass scope detection.

Tool renaming

• I am renaming tools as part of this PR (e.g. a part of a consolidation effort)
  • I have added the new tool aliases in deprecated_tool_aliases.go
• I am not renaming tools as part of this PR

Note: if you're renaming tools, you must add the tool aliases. For more information on how to do so, please refer to the official docs.

Lint & tests

• Linted locally with ./script/lint
• Tested locally with ./script/test

Docs

• Not needed — script/generate-docs produced no changes.
• Updated (README / docs / examples)

[Copilot]

Pull request overview

Adds per-call OAuth scope challenges for workflow-file writes while preserving repo-only authorization for other repository writes.

Changes:

• Adds traversal-safe path validation and conditional workflow scope resolution.
• Extends scope middleware and inventory metadata for argument-dependent scopes.
• Projects top-level paths into MCP headers and adds regression tests.

Show a summary per file

File	Description
pkg/scopes/scopes.go	Removes unused Codespace scope metadata.
pkg/scopes/scopes_test.go	Updates scope catalog expectations.
pkg/scopes/map.go	Resolves conditional scopes per invocation.
pkg/scopes/map_test.go	Tests conditional scope resolution.
pkg/inventory/server_tool.go	Adds scope resolvers and path header projection.
pkg/inventory/server_tool_test.go	Tests path header annotations.
pkg/http/oauth/oauth_test.go	Updates advertised scope expectations.
pkg/http/middleware/scope_challenge.go	Challenges only for missing resolved scopes.
pkg/http/middleware/scope_challenge_test.go	Tests body- and context-derived challenges.
pkg/github/repository_path.go	Adds safe path validation and workflow detection.
pkg/github/repository_path_test.go	Covers traversal and workflow scope behavior.
pkg/github/repositories.go	Integrates validation and resolvers into write tools.
pkg/github/header_params_test.go	Verifies top-level versus nested path projection.

Review details

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

• Files reviewed: 13/13 changed files
• Comments generated: 0
• Review effort level: Balanced

[IrynaKulakova]

This fallback silently converts "any of" into "all of".

When RequiredScopeGroups is empty, a multi-entry RequiredScopes means any of — generate_docs.go renders exactly that (Required OAuth Scopes (any of)), and HasAcceptedScope falls through to the AcceptedScopes union. Giving each entry its own group flips every alternative into an independently mandatory requirement.

No tool hits this today (all three resolvers sit on tools with a single repo scope), but it's a quiet landmine for whoever adds the next resolver. I probed it against a list_issue_fields-shaped tool:

base := &ToolScopeInfo{
    RequiredScopes: []string{"repo", "read:org"},
    AcceptedScopes: ExpandScopes(Repo, ReadOrg),
    ScopeResolver:  func(map[string]any) []string { return []string{"workflow"} },
}
base.HasAcceptedScope("repo")  // true — repo alone satisfies any-of

resolved := base.Resolve(map[string]any{})
// groups = [[repo] [admin:org read:org write:org] [workflow]]
resolved.HasAcceptedScope("repo", "workflow")  // false  ← now demands read:org too
resolved.MissingScopes("repo")                 // [read:org workflow]

A token holding repo + workflow would get challenged for read:org it never needed, and the challenge would ask for it by name.

Collapsing the base into a single group preserves the any-of semantics:

if len(resolved.RequiredScopeGroups) == 0 && len(resolved.AcceptedScopes) > 0 {
    resolved.RequiredScopeGroups = [][]string{resolved.AcceptedScopes}
}

Though note that also breaks the positional groups[i] -> RequiredScopes[i] assumption MissingScopes relies on, so that pairing probably wants to become explicit rather than positional. Happy with a comment documenting the single-scope precondition instead if you'd rather keep this narrow for now — mainly want the constraint written down somewhere.