fix(auth): handle OAuth scope claim as both string and list types

[bogdanmariusc10]

🔗 Related Issue

Closes #4593
Jira Issue: https://jsw.ibm.com/browse/ICACF-40

---

📝 Summary

Fixed OAuth token scope validation failure that caused "Failed to fetch tools after OAuth: 'list' object has no attribute 'split'" error when connecting to MCP servers (e.g., Gamma) that return OAuth scopes as a list instead of a space-separated string.

Root Cause: The code assumed OAuth scope/scp claims would always be strings, but some OAuth providers return them as lists, which is valid per OAuth 2.0 specifications.

Solution: Updated scope handling in two critical locations to accept both string and list formats:

1. JWT token claim validation (_normalize_scope())
2. OAuth token response processing (exchange_code_for_tokens())

---

🏷️ Type of Change

• Bug fix
• Feature / Enhancement
• Documentation
• Refactor
• Chore (deps, CI, tooling)
• Other (describe below)

---

🧪 Verification

Check	Command	Status
Lint suite	make lint	✅ Pass
Unit tests	make test	✅ Pass
Coverage ≥ 80%	make coverage	✅ Pass

Test Results:

• test_token_validation_service.py: 46 tests pass (including 5 new tests for list input)
• test_oauth_manager.py: 112 tests pass
• test_gateway_service_oauth_comprehensive.py: 29 tests pass

---

✅ Checklist

• Code formatted (make black isort pre-commit)
• Tests added/updated for changes
• Documentation updated (if applicable)
• No secrets or credentials committed

---

📓 Notes

Files Changed

1. mcpgateway/services/token_validation_service.py

• Updated _normalize_scope() to handle both str and list inputs
• Added type flexibility: scope_input: Any instead of scope_str: str
• Gracefully handles invalid types by returning empty set

2. mcpgateway/services/oauth_manager.py

• Updated exchange_code_for_tokens() to handle scope as string or list
• Added explicit type checking before calling .split()
• Ensures store_tokens() always receives List[str]

3. tests/unit/mcpgateway/services/test_token_validation_service.py

• Added 5 new test cases for list input scenarios:
  • test_list_input_simple_scopes
  • test_list_input_uri_prefixed_scopes
  • test_empty_list
  • test_mixed_list_with_uri_and_simple
  • test_invalid_input_type

Impact

• Before: OAuth authorization succeeded but tool fetching failed with AttributeError
• After: Both string and list scope formats are handled correctly
• Compatibility: Maintains backward compatibility with existing OAuth providers that return strings