feat(auth): add OAuth fallback validation for endpoints without OAuth support

[platinummonkey]

Summary

Implements automatic detection and fallback to API keys for Datadog API endpoints that don't support OAuth authentication. Based on comprehensive analysis of the datadog-api-spec repository, this ensures users get clear error messages and seamless fallback behavior when OAuth can't be used.

Problem

Analysis of the datadog-api-spec repository revealed that 30 out of 132 pup commands (23%) use API endpoints that don't support OAuth authentication:

• Logs API (11 endpoints) - missing logs_read_data scope
• RUM API (10 endpoints) - missing rum_apps_read/write scopes
• API/App Keys Management (7 endpoints) - missing api_keys_read/write scopes
• Error Tracking API (2 endpoints) - OAuth not working in practice

Previously, users authenticated with OAuth would receive generic 401 errors when attempting to use these endpoints, with no indication that API keys were required.

Solution

1. Authentication Validator (pkg/client/auth_validator.go)

• Maintains registry of 30 endpoints that don't support OAuth
• RequiresAPIKeyFallback() - checks if endpoint needs API keys
• ValidateEndpointAuth() - validates auth type matches endpoint requirements
• GetAuthType() - detects current authentication method
• Provides clear, actionable error messages

2. Enhanced Client (pkg/client/client.go)

• NewWithAPIKeys() - forces API key authentication
• NewWithOptions() - unified client creation with auth options
• ValidateEndpointAuth() - endpoint validation before requests
• RawRequest() now validates auth compatibility

3. Smart Command Layer (cmd/root.go)

• getClientForEndpoint() - automatically selects appropriate client
• Seamless fallback when OAuth isn't supported
• Clear error messages when API keys are required but missing

4. Updated Commands

• Logs: search, list, query (3 commands)
• RUM: apps list/get/create/update/delete (5 commands)
• API Keys: list/get/create/delete (4 commands)
• Error Tracking: issues search, issues get (2 commands)

Changes

New Files

• pkg/client/auth_validator.go - OAuth support detection and validation (244 lines)
• pkg/client/auth_validator_test.go - Comprehensive test coverage (237 lines)
• OAUTH_FALLBACK_IMPLEMENTATION.md - Full implementation documentation

Modified Files

• pkg/client/client.go - Enhanced auth handling with NewWithAPIKeys/NewWithOptions
• pkg/client/client_test.go - Fixed keychain blocking in tests
• cmd/root.go - Added getClientForEndpoint()
• cmd/logs_simple.go - Updated 3 log commands
• cmd/rum.go - Updated 5 RUM commands
• cmd/api_keys.go - Updated 4 API key commands
• cmd/error_tracking.go - Updated 2 error-tracking commands

User Experience

Before

$ pup auth login
$ pup logs search --query="status:error" --from="1h"
❌ Error: 401 Unauthorized

$ pup error-tracking issues search
❌ Error: 401 Unauthorized

After (with API keys)

$ pup auth login
$ export DD_API_KEY="..." DD_APP_KEY="..."
$ pup logs search --query="status:error" --from="1h"
✅ Works! Automatically uses API keys

$ pup error-tracking issues search
✅ Works! Automatically uses API keys

After (without API keys)

$ pup auth login
$ pup logs search --query="status:error" --from="1h"
❌ Error: endpoint POST /api/v2/logs/events/search does not support OAuth authentication.
   Please set DD_API_KEY and DD_APP_KEY environment variables.
   Reason: Logs API missing OAuth implementation in spec

$ pup error-tracking issues search
❌ Error: endpoint POST /api/v2/error_tracking/issues/search does not support OAuth authentication.
   Please set DD_API_KEY and DD_APP_KEY environment variables.
   Reason: Error Tracking API requires API keys

OAuth-Supported Endpoints (unchanged)

$ pup auth login
$ pup monitors list
✅ Works! Uses OAuth token

Testing

All tests passing ✅

=== Client Package Tests ===
✓ TestGetAuthType (3 subtests)
✓ TestRequiresAPIKeyFallback (7 subtests) - includes error-tracking
✓ TestValidateEndpointAuth (5 subtests)
✓ TestGetEndpointRequirement (3 subtests)
✓ TestGetAuthTypeDescription (3 subtests)
✓ All existing client tests updated and passing

Total: 37 tests passing in <1 second
Coverage: 100% for new auth validator code

Test Improvements

• Fixed keychain blocking in tests by using NewWithAPIKeys()
• All tests now complete in <1s (previously would timeout)
• Comprehensive coverage of auth detection and fallback logic
• Added specific tests for error-tracking endpoint detection

Endpoints Requiring API Keys

30 total endpoints in the fallback registry:

API Domain	Endpoints	Reason
Logs	11	Missing logs_read_data scope in spec
RUM	10	Missing rum_apps_read/write scopes in spec
API/App Keys	7	Missing api_keys_read/write scopes in spec
Error Tracking	2	OAuth not working in practice

Benefits

1. Better UX: Clear, actionable error messages instead of cryptic API errors
2. Automatic Fallback: Seamless API key usage when OAuth unsupported
3. No Breaking Changes: Existing workflows continue to work
4. Production Ready: Comprehensive testing with 100% coverage
5. Well Documented: Includes full implementation guide
6. Extensible: Easy to add more endpoints as needed

Related

• Full documentation: OAUTH_FALLBACK_IMPLEMENTATION.md
• Based on spec analysis from DataDog/datadog-api-spec repository

Commits

1. 2aee04e - feat(auth): add OAuth fallback validation for endpoints without OAuth support
2. 88132cd - fix(tests): update client tests to use NewWithAPIKeys to avoid keychain blocking
3. 791eaf7 - feat(error-tracking): add OAuth fallback for error-tracking commands

---

🤖 Generated with Claude Code

[github-actions]

📊 Test Coverage Report

Overall Coverage: 82.3%

Threshold: 80% ✅

Coverage by Package

## Coverage by Package

- github.com/DataDog/pup/pkg/auth/callback/server.go:40: 81.2%
- github.com/DataDog/pup/pkg/auth/dcr/client.go:28: 100.0%
- github.com/DataDog/pup/pkg/auth/dcr/types.go:24: 100.0%
- github.com/DataDog/pup/pkg/auth/oauth/client.go:22: 100.0%
- github.com/DataDog/pup/pkg/auth/oauth/pkce.go:24: 85.7%
- github.com/DataDog/pup/pkg/auth/storage/factory.go:53: 94.7%
- github.com/DataDog/pup/pkg/auth/storage/keychain.go:44: 42.9%
- github.com/DataDog/pup/pkg/auth/storage/storage.go:58: 71.4%
- github.com/DataDog/pup/pkg/auth/types/types.go:23: 100.0%
- github.com/DataDog/pup/pkg/client/auth_validator.go:79: 100.0%
- github.com/DataDog/pup/pkg/client/client.go:32: 100.0%
- github.com/DataDog/pup/pkg/config/alias.go:26: 100.0%
- github.com/DataDog/pup/pkg/config/config.go:22: 100.0%
- github.com/DataDog/pup/pkg/formatter/formatter.go:31: 100.0%
- github.com/DataDog/pup/pkg/useragent/useragent.go:32: 100.0%
- github.com/DataDog/pup/pkg/util/time.go:20: 95.8%

## Summary

total:								(statements)		82.3%

---

📈 Coverage Status: ✅ PASSED - Coverage meets minimum threshold

_{Updated for commit c596e0c}