Add OAuth2 authentication support

[kioku]

Problem

When attempting to add the Jira API specification to Aperture, the validation fails with:

Validation Error
OAuth2 security scheme 'OAuth2' is not supported in v1.0.

This prevents users from integrating with many modern APIs that use OAuth2 authentication, including Atlassian products (Jira, Confluence), Google APIs, Microsoft Graph, and many others.

Current Limitation

Aperture currently rejects OAuth2 security schemes during validation (src/spec/validator.rs:190-193). The tool only supports:

• API Key authentication
• HTTP Basic authentication
• HTTP Bearer authentication

Architecture Impact

OAuth2 support represents a significant architectural change because Aperture's current model is stateless:

• Authentication credentials come from environment variables
• No state is maintained between command invocations
• No token persistence or refresh mechanism exists

OAuth2 requires:

• Token state management (access tokens, refresh tokens, expiry times)
• Token persistence between CLI invocations
• Automatic token refresh when expired
• Interactive flows for authorization (in some cases)

Proposed Implementation

Phase 1: Non-Interactive OAuth2 (Client Credentials Flow)

1. Remove OAuth2 Validation Rejection

   • File: src/spec/validator.rs
   • Remove lines 190-193 that reject OAuth2 schemes
   • Update associated tests

2. Add Token State Management

   • New module: src/auth/oauth2.rs
   • Token storage in ~/.config/aperture/.auth/
   • Store access tokens, refresh tokens, and expiry times
   • Implement secure file permissions (0600)

3. Extend Security Models

   • File: src/cache/models.rs
   • Add OAuth2-specific fields to CachedSecurityScheme:
     • authorization_url
     • token_url
     • refresh_url
     • scopes
     • flow_type

4. Update Executor

   • File: src/engine/executor.rs
   • Modify add_authentication_header to:
     • Check for valid cached tokens
     • Automatically refresh expired tokens
     • Acquire new tokens via client credentials flow
     • Handle OAuth2-specific errors

Phase 2: Interactive OAuth2 (Authorization Code Flow)

1. Add OAuth2 CLI Commands

   • aperture auth login - Interactive OAuth2 login
   • aperture auth logout - Clear stored tokens
   • aperture auth status - Show current auth state

2. Implement Browser-Based Flow

   • Local redirect server for OAuth callbacks
   • Browser launch for authorization
   • PKCE support for security

3. Enhanced Token Management

   • Multiple concurrent token support
   • Token refresh coordination
   • Error recovery strategies

Phase 3: Advanced Features

1. Additional OAuth2 Flows

   • Resource Owner Password Credentials (if needed)
   • Device Code Flow for CLI-only environments

2. Security Enhancements

   • OS keychain integration for token storage
   • Encrypted token storage as fallback
   • Token rotation policies

3. Performance Optimizations

   • Token caching strategies
   • Parallel request handling with token refresh
   • Minimize token acquisition overhead

Design Principles

1. Maintain Backward Compatibility

   • Existing authentication methods unchanged
   • OAuth2 is opt-in per API specification
   • No breaking changes to CLI interface

2. Security First

   • Client credentials still from environment variables
   • Tokens stored separately from configuration
   • Never log or expose tokens
   • Proper file permissions on token storage

3. Agent-Friendly

   • Non-interactive flows for automation
   • Structured error messages
   • Clear token state in --describe-json output

Technical Considerations

1. Token Storage Format

   {
     "api_name": {
       "access_token": "...",
       "refresh_token": "...",
       "expires_at": "2024-01-01T00:00:00Z",
       "token_type": "Bearer",
       "scopes": ["read", "write"]
     }
   }

2. Environment Variables for OAuth2

   • CLIENT_ID from x-aperture-secret
   • CLIENT_SECRET from x-aperture-secret
   • Optional: OAUTH_REDIRECT_URI

3. Error Handling

   • Token expired: Automatic refresh
   • Refresh failed: Re-authenticate
   • Network errors: Graceful degradation

Implementation Complexity

This is a major feature requiring:

• Significant new code (~1000+ lines)
• New dependencies (possibly oauth2-rs crate)
• Comprehensive testing strategy
• Security review
• Documentation updates

Alternatives Considered

1. External Token Management

   • Require users to manage tokens externally
   • Pass tokens via environment variables
   • Simpler but poor user experience

2. Minimal OAuth2 Support

   • Only support bearer tokens from OAuth2
   • No automatic refresh
   • Limited utility

Future Considerations

• Integration with system keychains
• Multi-tenant token management
• Token sharing across tools
• OAuth2 proxy mode for agents

References

• OAuth2 RFC: https://datatracker.ietf.org/doc/html/rfc6749
• OpenAPI OAuth2 Security Scheme: https://swagger.io/docs/specification/authentication/oauth2/
• Example APIs requiring OAuth2: Jira, GitHub (apps), Google APIs, Slack