feat(auth): add reusable OAuth2 base helper library

[LOVECAO1011]

Introduce a canonical OAuth2/OIDC helper module for token validation, claims extraction, metadata discovery, token exchange/refresh, and scope operations so auth plugins can share consistent protocol logic. Add focused unit coverage for the new helper APIs and RFC-oriented behaviors.

🔗 Related Issue

Closes #

---

📝 Summary

• mcpgateway/oauth2/base.py
• validate_token() with JWKS JWT verification and introspection fallback
• extract_claims() canonical claim mapping
• discover_authorization_server_metadata() (RFC 8414)
• discover_oidc_metadata() (OIDC discovery)
• discover_protected_resource_metadata() (RFC 9728)
• exchange_token() (RFC 8693)
• refresh_token() (RFC 6749)
• scope normalization/modification utilities
• authorization URL builder with resource indicators (RFC 8707)
• mcpgateway/oauth2/models.py typed request/response config models
• mcpgateway/oauth2/exceptions.py unified OAuth2 error types
• mcpgateway/oauth2/__init__.py public exports
• tests/unit/mcpgateway/oauth2/test_base.py focused unit tests for helper APIs and error paths

---

🏷️ Type of Change

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

---

🧪 Verification

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

---

✅ Checklist

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

---

📓 Notes (optional)

This PR delivers the OAuth2 base helper layer requested by #1434 and is designed to be consumed by plugin/auth flows in the #1422 epic.

• It is additive and does not remove existing OAuth manager/DCR behavior.

[crivetimihai]

Thanks @LOVECAO1011. A reusable OAuth2/OIDC helper module could reduce duplication across our OAuth integrations.

Key concerns:

1. Overlap: How does this relate to the existing implementation in mcpgateway/auth.py and mcpgateway/services/oauth_manager.py? Does it replace, extend, or run alongside them?
2. Dependencies: Does this introduce new external dependencies?
3. Testing: Are there unit tests? Token validation and claims extraction are security-critical.
4. Integration: Which existing code paths will use this, and are migration PRs planned?

[LOVECAO1011]

Thanks for the detailed review and questions.

1. Overlap
   This PR is additive and introduces a reusable OAuth2/OIDC helper layer. It does not replace mcpgateway/auth.py or mcpgateway/services/oauth_manager.py yet. Existing paths remain unchanged for safety; migration is planned incrementally.

2. Dependencies
   No new third-party dependencies were introduced. The helper reuses existing project dependencies (pyjwt, httpx) and existing internal HTTP client patterns.

3. Testing
   Yes — focused unit tests were added at:
   tests/unit/mcpgateway/oauth2/test_base.py
   Coverage includes token validation (JWKS + introspection), claims extraction, metadata discovery, token exchange/refresh, scope handling, and error paths.
   I also ran related regression suites:

• tests/unit/mcpgateway/services/test_oauth_manager.py
• tests/unit/mcpgateway/services/test_dcr_service.py
• tests/unit/mcpgateway/utils/test_verify_credentials.py

4. Integration / Migration plan
   Planned follow-up integration PRs:

• Wire oauth_manager flows to use the new helper APIs.
• Incrementally route token validation/claims paths to the helper.
• Remove duplicated protocol logic once migration is complete.