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