frontend/specs/001-google-oauth-auth/research.md

Research: Google OAuth Authentication

Feature: 001-google-oauth-auth Date: 2026-01-29

1. NestJS Passport Google OAuth Setup

Decision: Use @nestjs/passport with passport-google-oauth20 strategy

Rationale:

• Official NestJS integration provides decorator-based guards and strategies
• passport-google-oauth20 is the actively maintained Google OAuth package
• Seamless integration with NestJS dependency injection and module system
• Built-in validate method simplifies user profile handling

Alternatives Considered:

• passport-google-oauth2: Older package, less TypeScript support
• Custom OAuth implementation: Too much boilerplate, harder to maintain

2. Authentication Strategy for SPAs

Decision: Hybrid approach - JWT access tokens (short-lived, in-memory) + HttpOnly cookie refresh tokens (7-day)

Rationale:

• Access tokens in memory provide stateless, scalable API authentication
• HttpOnly refresh tokens prevent XSS attacks while enabling token rotation
• Best balance between security, UX, and distributed system requirements
• Industry standard for modern SPAs

Alternatives Considered:

• Pure JWT (stateless): Can't invalidate tokens on logout/compromise
• Pure sessions: Doesn't scale well, requires sticky sessions
• localStorage for tokens: Vulnerable to XSS attacks

3. Token Storage in React

Decision: Access tokens in Zustand store (memory), refresh tokens in HttpOnly cookies

Rationale:

• HttpOnly cookies are inaccessible to JavaScript, preventing XSS token theft
• In-memory storage for short-lived access tokens (15-30 min)
• CSRF protection via sameSite: 'strict' and CORS configuration
• Silent refresh mechanism restores access token on page reload

Alternatives Considered:

• localStorage: Vulnerable to XSS attacks
• sessionStorage: Data lost on tab close, still XSS vulnerable

4. React Router Protected Routes

Decision: Layout-based protection using AuthGuard wrapper component with Navigate

Rationale:

• React Router v7 provides clean, declarative route protection
• Easy to preserve intended destination via location.state.from
• Simple loading state handling during auth check

Alternatives Considered:

• Higher-Order Component (HOC): More verbose in modern React
• Route-level guards: Duplicates auth logic across routes

5. OAuth Redirect Flow Implementation

Decision: Backend-initiated flow with frontend callback handler

Flow:

1. Frontend links to /api/auth/google (backend initiates OAuth)
2. NestJS redirects to Google consent screen
3. Google redirects to /api/auth/google/callback
4. Backend validates tokens, creates/updates user, issues JWT
5. Backend redirects to frontend /auth/callback?token=...
6. Frontend stores token, clears URL, redirects to intended destination

Rationale:

• NestJS handles OAuth state management and token exchange securely
• Supports TypeORM user creation/lookup with transaction safety
• Token cleared from URL immediately for security

Alternatives Considered:

• Frontend-initiated PKCE flow: More complex state management
• Popup-based flow: Poor UX on mobile, blocked by some browsers

6. Session Validity & Token Expiration

Decision:

• Access tokens: 15 minutes (short-lived for security)
• Refresh tokens: 7 days (per spec assumptions)
• Automatic token refresh via 401 interceptor in Axios

Rationale:

• Short access tokens limit exposure window if compromised
• 7-day refresh aligns with spec requirements
• Auto-refresh provides seamless UX

Implementation Notes

CORS Configuration Required:

origin: FRONTEND_URL
credentials: true (allow cookies)

Environment Variables Needed:

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_CALLBACK_URL
• JWT_SECRET
• JWT_ACCESS_EXPIRATION (15m)
• JWT_REFRESH_EXPIRATION (7d)
• FRONTEND_URL

TypeORM Indexes:

• Index googleId for OAuth lookups
• Index email for user queries