# 08. OAuth & Social Login Integration

meta:
  id: ios-production-08
  feature: ios-production
  priority: P1
  depends_on: []
  tags: [auth, security, production]

objective:
- Implement OAuth and social login (Apple Sign-In, Google) to replace the stubbed auth client

deliverables:
- Apple Sign-In integration
- Google Sign-In integration
- Backend OAuth token exchange
- AuthService wired to real API client

steps:
1. Implement Apple Sign-In:
   - Configure Sign in with Apple in Apple Developer portal
   - Add com.apple.developer.applesignin.customauth entitlement
   - Implement ASAuthorizationController in AuthService
   - Handle authorization code and identity token
   - Send Apple credentials to backend for verification
2. Implement Google Sign-In:
   - Configure Google Sign-In in Firebase/Google Cloud Console
   - Add URL scheme for Google callback
   - Integrate GoogleSignIn SDK
   - Handle ID token and send to backend
3. Update backend for OAuth:
   - Add OAuth endpoints to tRPC user router
   - Verify Apple ID token with Apple public keys
   - Verify Google ID token with Google certs
   - Create/link user accounts from OAuth providers
   - Return session token after OAuth login
4. Replace StubAPIClient:
   - Create real API client implementing AuthAPIClientProtocol
   - Wire into AuthService initialization in KordantApp.swift
   - Remove StubAPIClient from production builds
   - Keep StubAPIClient for unit tests
5. Add token refresh:
   - Implement refresh token rotation
   - Silent token refresh on expiry
   - Handle refresh failure (re-authenticate)
6. Add logout for OAuth:
   - Revoke OAuth tokens where possible
   - Clear all local auth state
   - Notify backend of logout

tests:
- Unit: Test OAuth token parsing and validation
- Integration: Test Apple Sign-In flow end-to-end
- Integration: Test Google Sign-In flow end-to-end
- Security: Verify token validation rejects invalid tokens

acceptance_criteria:
- Apple Sign-In working on iOS 13+
- Google Sign-In working with Firebase
- OAuth tokens verified server-side
- User accounts created or linked correctly
- AuthService uses real API client in production
- Token refresh working silently
- Logout clears all auth state and revokes tokens
- Unit tests use mock client, production uses real client
- Error handling for cancelled sign-in attempts

validation:
- Tap Apple Sign-In → native sheet → authenticate → logged in
- Tap Google Sign-In → Google flow → authenticate → logged in
- Check backend → user created with correct provider
- Wait for token expiry → automatic refresh
- Logout → all tokens cleared, login screen shown

notes:
- Apple Sign-In is required if app uses other third-party sign-in
- Apple Sign-In must be primary button if multiple options
- Store Apple user ID for account linking
- Backend must verify Apple JWT with Apple's public key