ReadKeep/docs/OAuth2-Implementation-Plan.md

OAuth 2.0 Authentication - Implementation Plan

Date: December 19, 2025 Status: In Progress (Phase 1-4 Complete ✅) Goal: Add OAuth 2.0 authentication support as an alternative to API token authentication

---

📋 Overview

Current Situation (Updated)

• ✅ Phase 1-4 Complete: ServerInfo extended, OAuth core implemented, browser integration done, token management working
• ✅ Direct OAuth Flow: No login method selection - OAuth is tried automatically if server supports it
• ✅ Fallback to Classic: If OAuth fails or is not supported, classic username/password login is shown
• ✅ Endpoint Storage: Endpoint is now saved in both TokenProvider and Settings
• ❌ API Integration: API calls don't yet use OAuth tokens properly
• ❌ Testing: Manual and integration testing not complete

What's Implemented ✅

Phase 1: ServerInfo Extended

• ✅ ServerInfoDto with nested VersionInfo struct (canonical, release, build)
• ✅ ServerInfo model with features: [String]? and supportsOAuth computed property
• ✅ GetServerInfoUseCase with optional endpoint parameter
• ✅ InfoApiClient with endpoint parameter logic (custom endpoint vs TokenProvider)
• ✅ Unit tests for ServerInfo and feature detection
• ✅ Backward compatibility with old servers

Phase 2: OAuth Core

• ✅ PKCEGenerator with verifier/challenge generation
• ✅ OAuth DTOs: OAuthClientCreateDto, OAuthClientResponseDto, OAuthTokenRequestDto, OAuthTokenResponseDto
• ✅ Domain models: OAuthClient, OAuthToken, AuthenticationMethod
• ✅ API.swift extended with OAuth methods (registerOAuthClient, exchangeOAuthToken)
• ✅ OAuthRepository + POAuthRepository protocol
• ✅ OAuthManager orchestrates OAuth flow
• ✅ Unit tests for PKCEGenerator

Phase 3: Browser Integration

• ✅ OAuthSession wraps ASWebAuthenticationSession
• ✅ OAuthFlowCoordinator manages 5-phase OAuth flow
• ✅ readeck:// URL scheme registered in Info.plist
• ✅ State verification for CSRF protection
• ✅ Error handling for user cancellation

Phase 4: Token Management

• ✅ AuthenticationMethod enum (apiToken, oauth)
• ✅ TokenProvider extended with OAuth methods (getOAuthToken, setOAuthToken, getAuthMethod, setAuthMethod)
• ✅ setEndpoint(_ endpoint: String) added to TokenProvider
• ✅ KeychainHelper extended with OAuth token storage
• ✅ KeychainTokenProvider handles both token types
• ✅ AuthRepository extended with loginWithOAuth, getAuthenticationMethod, switchToClassicAuth
• ✅ Endpoint now saved in TokenProvider (was missing before)

Phase 5: UI & UX (Partially Complete)

• ✅ OnboardingServerView refactored with 2-phase flow:
  • Phase 1: Only endpoint field + Readeck logo
  • Phase 2a: OAuth attempted automatically if server supports it
  • Phase 2b: Username/Password fields shown if OAuth not supported or fails
• ✅ SettingsServerViewModel extended with checkServerOAuthSupport() and loginWithOAuth()
• ✅ LoginWithOAuthUseCase created
• ✅ Factories updated (DefaultUseCaseFactory, MockUseCaseFactory)
• ❌ LoginMethodSelectionView removed (no longer needed - OAuth is automatic)

Removed/Changed:

• ❌ All #if os(iOS) && !APP_EXTENSION checks removed
• ❌ LoginMethodSelectionView removed - OAuth is now attempted automatically
• ❌ showLoginMethodSelection flag removed
• ✅ Direct OAuth attempt with fallback to classic login on error

---

🎯 Updated Goals

1. User Choice Automatic OAuth: OAuth is attempted automatically if server supports it
2. Auto-Detection: ✅ Automatically detect if server supports OAuth via /info endpoint
3. Security: ✅ OAuth 2.0 Authorization Code Flow with PKCE (S256)
4. UX: ✅ Seamless browser-based authentication using ASWebAuthenticationSession
5. Fallback: ✅ Graceful fallback to username/password if OAuth fails or is not supported
6. Migration Path: ❌ Not yet implemented for existing users

---

🔍 API Analysis

Server Info Response (Actual Format)

{
  "version": {
    "canonical": "0.21.4",
    "release": "0.21.4",
    "build": ""
  },
  "features": ["oauth"]
}

Changes from Original Plan:

• version is now an object, not a string
• buildDate and userAgent removed (not in actual response)
• features is optional (only in newer servers)

OAuth Endpoints

1. Feature Detection: GET /api/info (no auth)
2. Client Registration: POST /api/oauth/client (no auth)
3. Authorization: GET /authorize (browser, web page)
4. Token Exchange: POST /api/oauth/token (application/x-www-form-urlencoded)

---

🏗️ Architecture (Updated)

Data Flow

User Input → OnboardingServerView
  ↓
SettingsServerViewModel.checkServerOAuthSupport()
  ↓
GetServerInfoUseCase.execute(endpoint: normalizedEndpoint)
  ↓
ServerInfoRepository.getServerInfo(endpoint: normalizedEndpoint)
  ↓
InfoApiClient.getServerInfo(endpoint: normalizedEndpoint)
  ↓
GET {endpoint}/api/info (no auth token)
  ↓
Response: { version: {...}, features: ["oauth"] }
  ↓
serverSupportsOAuth = true
  ↓
SettingsServerViewModel.loginWithOAuth()
  ↓
LoginWithOAuthUseCase.execute(endpoint)
  ↓
OAuthFlowCoordinator.executeOAuthFlow(endpoint)
  ↓
[OAuth flow: client registration → browser → token exchange]
  ↓
AuthRepository.loginWithOAuth(endpoint, token)
  ↓
TokenProvider saves: OAuthToken, AuthMethod, Endpoint
  ↓
User logged in ✅

Key Components

Domain Layer:

• ServerInfo (version, features, supportsOAuth)
• OAuthClient (clientId, clientSecret, redirectUris, etc.)
• OAuthToken (accessToken, tokenType, scope, expiresIn, refreshToken, createdAt)
• AuthenticationMethod enum (apiToken, oauth)

Data Layer:

• InfoApiClient - handles /api/info with optional endpoint parameter
• API - extended with OAuth client registration and token exchange
• OAuthRepository - orchestrates OAuth API calls
• OAuthManager - business logic for OAuth flow
• OAuthSession - wraps ASWebAuthenticationSession
• OAuthFlowCoordinator - coordinates complete 5-phase flow

Use Cases:

• GetServerInfoUseCase(endpoint: String?) - get server info with optional custom endpoint
• LoginWithOAuthUseCase - execute OAuth login flow
• CheckServerReachabilityUseCase - check if server is reachable (existing)

UI Layer:

• OnboardingServerView - 2-phase onboarding (endpoint → OAuth or classic)
• SettingsServerViewModel - extended with OAuth support

---

🎨 User Experience Flow (Updated)

New User Onboarding

1. User opens app
   ↓
2. Screen shows:
   - Readeck logo (green circle)
   - "Enter your Readeck server"
   - Endpoint text field
   - Chips: http://, https://, 192.168., :8000
   - "Continue" button
   ↓
3. User enters endpoint (e.g., https://readeck.example.com)
   ↓
4. User taps "Continue"
   ↓
5. App normalizes endpoint and calls /api/info
   ↓
6a. If OAuth supported:
    ↓
    App automatically starts OAuth flow
    ↓
    Browser opens with /authorize page
    ↓
    User logs in with username/password on server
    ↓
    User approves permissions
    ↓
    Redirect to readeck://oauth-callback?code=...
    ↓
    App exchanges code for token
    ↓
    Token + endpoint saved
    ↓
    User logged in ✅

6b. If OAuth NOT supported OR OAuth fails:
    ↓
    Username and Password fields appear
    ↓
    Text changes to "Enter your credentials"
    ↓
    Button changes to "Login & Save"
    ↓
    User enters credentials
    ↓
    Classic API token login
    ↓
    User logged in ✅

Key UX Changes:

• No login method selection screen (removed)
• OAuth is attempted automatically
• Fallback to classic is seamless
• User sees endpoint field first, login fields only if needed

---

🚀 Implementation Status

✅ Phase 1: ServerInfo Extended (COMPLETE)

• ✅ ServerInfoDto with VersionInfo nested struct
• ✅ ServerInfo.features optional array
• ✅ supportsOAuth computed property
• ✅ GetServerInfoUseCase with endpoint parameter
• ✅ Backward compatibility tests
• ✅ Mock implementations updated

✅ Phase 2: OAuth Core (COMPLETE)

• ✅ PKCEGenerator (verifier + challenge)
• ✅ All OAuth DTOs created
• ✅ Domain models created
• ✅ API methods implemented
• ✅ OAuthRepository created
• ✅ OAuthManager created
• ✅ Unit tests for PKCE

✅ Phase 3: Browser Integration (COMPLETE)

• ✅ OAuthSession wraps ASWebAuthenticationSession
• ✅ OAuthFlowCoordinator manages complete flow
• ✅ URL scheme registered (readeck://)
• ✅ State verification
• ✅ Error handling

✅ Phase 4: Token Management (COMPLETE)

• ✅ AuthenticationMethod enum
• ✅ TokenProvider extended with OAuth methods
• ✅ setEndpoint() added to TokenProvider
• ✅ KeychainHelper extended
• ✅ Token type detection in getToken()
• ✅ AuthRepository extended
• ✅ Endpoint saved in both TokenProvider and Settings

🟡 Phase 5: Use Cases & ViewModels (MOSTLY COMPLETE)

• ✅ LoginWithOAuthUseCase created
• ✅ AuthRepository extended
• ✅ SettingsServerViewModel extended
• ✅ Factories updated
• ❌ LoginMethodSelectionView removed (design change)
• ❌ Integration tests not complete

🟡 Phase 6: UI Implementation (MOSTLY COMPLETE)

• ✅ OnboardingServerView refactored (2-phase flow)
• ✅ Readeck logo with green background
• ✅ Dynamic text based on phase
• ✅ Conditional login fields
• ✅ OAuth auto-attempt logic
• ❌ Settings migration UI not implemented
• ❌ OAuth token info display not implemented

❌ Phase 7: Testing & Polish (NOT STARTED)

• ❌ Manual testing checklist
• ❌ Integration tests
• ❌ Performance testing
• ❌ Code review

❌ Phase 8: Migration & Documentation (NOT STARTED)

• ❌ Migration flow for existing users
• ❌ Release notes
• ❌ Documentation

---

🐛 Known Issues & TODOs

Critical Issues

1. API Calls Don't Use OAuth Token Properly

   • Problem: When using OAuth, API calls may not be sending the Bearer token correctly
   • The TokenProvider.getToken() checks auth method and returns OAuth access token
   • But need to verify API calls actually use it in Authorization header
   • Check if API.swift properly uses await tokenProvider.getToken() for all authenticated requests

2. Endpoint Parameter Flow Needs Verification

   • GetServerInfoUseCase.execute(endpoint:) receives endpoint parameter
   • ServerInfoRepository.getServerInfo(endpoint:) passes it through
   • InfoApiClient.getServerInfo(endpoint:) uses it OR falls back to TokenProvider
   • Need to verify this chain works correctly

Minor Issues

3. No Migration UI for Existing Users

   • Users with API tokens can't migrate to OAuth yet
   • Settings screen needs "Switch to OAuth" button

4. No OAuth Token Display

   • Can't see which auth method is active
   • Can't see token expiry or scopes

5. All #if Checks Removed

   • Removed all #if os(iOS) && !APP_EXTENSION conditionals
   • May cause issues with URLShare extension (needs verification)

---

✅ Updated TODO List

🔴 IMMEDIATE (Critical for functionality)

• Verify API Integration with OAuth Token

  • Check that API.swift uses await tokenProvider.getToken() in all authenticated requests
  • Verify Bearer token is sent correctly in Authorization header
  • Test actual API call (e.g., fetch bookmarks) with OAuth token
  • Add logging to confirm which token type is being used

• Test Complete OAuth Flow End-to-End

  • Fresh install → OAuth server → OAuth login → fetch data
  • Fresh install → non-OAuth server → classic login → fetch data
  • OAuth login failure → fallback to classic login
  • Verify endpoint is saved correctly in TokenProvider

🟡 HIGH PRIORITY (Important for UX)

• Settings Screen Migration

  • Show current authentication method (OAuth vs API Token)
  • Add "Switch to OAuth" button (if server supports it and user has API token)
  • Add "Switch to Classic Login" option
  • Show OAuth token info (scopes, expiry if available)

• Error Handling & Messages

  • Better error messages for OAuth failures
  • Network error handling
  • Token expiry handling
  • Server not reachable scenarios

🟢 MEDIUM PRIORITY (Nice to have)

• Testing

  • Manual testing on real device
  • Integration tests for OAuth flow
  • Test on different iOS versions
  • Test with different server versions

• Documentation

  • Update README with OAuth instructions
  • Add inline code documentation
  • Create user guide for OAuth setup

⚪ LOW PRIORITY (Future enhancements)

• Token refresh support (if server implements it)
• Revoke token on logout
• Multiple account support
• Biometric re-authentication

---

📚 Implementation Notes

Design Decisions

1. No Login Method Selection Screen

   • Original plan had LoginMethodSelectionView
   • Removed in favor of automatic OAuth attempt
   • Rationale: Better UX, fewer clicks, OAuth is preferred
   • Fallback to classic login happens automatically on error

2. Endpoint in TokenProvider

   • Endpoint now saved in BOTH TokenProvider (Keychain) and Settings
   • Rationale: InfoApiClient needs endpoint from TokenProvider for /api/info calls
   • Ensures endpoint is available for all API calls

3. Removed All #if os(iOS) && !APP_EXTENSION

   • Original code had many conditional compilation checks
   • All removed for cleaner code
   • May need to revisit if URLShare extension has issues

4. ServerInfoDto Structure Changed

   • Original plan had flat version string
   • Actual API returns nested VersionInfo object
   • Adapted to match real API response

Code Patterns

Endpoint Resolution:

// InfoApiClient
func getServerInfo(endpoint: String? = nil) async throws -> ServerInfoDto {
    let baseEndpoint = try await resolveEndpoint(endpoint)
    // Uses provided endpoint OR falls back to tokenProvider.getEndpoint()
}

Token Type Detection:

// KeychainTokenProvider
func getToken() async -> String? {
    if let method = await getAuthMethod(), method == .oauth {
        return await getOAuthToken()?.accessToken
    }
    return keychainHelper.loadToken() // API token
}

OAuth Flow:

// 5-phase flow in OAuthFlowCoordinator
1. Register client + generate PKCE
2. Build authorization URL
3. Open browser (ASWebAuthenticationSession)
4. Parse callback URL
5. Exchange code for token

---

🎯 Next Steps

For Next Development Session

1. Verify API Integration (Most Critical)

   • Add logging to see which token is being used
   • Test actual API call with OAuth token
   • Confirm Bearer token in Authorization header

2. Manual Testing

   • Test OAuth flow end-to-end
   • Test fallback to classic login
   • Test on real device

3. Settings Screen

   • Show current auth method
   • Add migration button

4. Error Handling

   • Better error messages
   • Handle all failure scenarios

---

Last Updated: December 19, 2025 Status: Phase 1-4 Complete, Phase 5-6 Mostly Complete, Testing Needed