From f2571105fd60cd8df2bbd464afab5c1ff370ae8d Mon Sep 17 00:00:00 2001 From: Andrew Beveridge Date: Tue, 30 Dec 2025 00:36:25 -0500 Subject: [PATCH] docs: Add auth session persistence fix documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add archive doc explaining the two bugs and their fixes - Update LESSONS-LEARNED with Firestore timezone and Next.js caching insights - Update README with recent changes entry 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/LESSONS-LEARNED.md | 45 +++++++++ docs/README.md | 1 + ...2025-12-30-auth-session-persistence-fix.md | 92 +++++++++++++++++++ 3 files changed, 138 insertions(+) create mode 100644 docs/archive/2025-12-30-auth-session-persistence-fix.md diff --git a/docs/LESSONS-LEARNED.md b/docs/LESSONS-LEARNED.md index 26d4ab04..d95817f6 100644 --- a/docs/LESSONS-LEARNED.md +++ b/docs/LESSONS-LEARNED.md @@ -372,6 +372,51 @@ def verify_in_transaction(transaction): transaction.update(doc_ref, {'used': True}) ``` +### Firestore Returns Timezone-Aware Datetimes + +**Problem**: Firestore stores datetimes as timezone-aware (UTC). Code using `datetime.utcnow()` (naive) for comparisons fails with `TypeError: can't compare offset-naive and offset-aware datetimes`. + +**Symptoms**: +- Session validation fails silently (exception caught, returns error) +- Session exists and appears valid in database +- First request after login may work, subsequent requests fail (because `last_activity_at` is updated to TZ-aware on first access) + +**Solution**: Always use timezone-aware datetimes: +```python +from datetime import datetime, timezone + +# GOOD +now = datetime.now(timezone.utc) + +# Normalize Firestore datetimes that might be naive (legacy data) +if session.expires_at.tzinfo is None: + expires_at = session.expires_at.replace(tzinfo=timezone.utc) +``` + +**Note**: `datetime.utcnow()` is deprecated in Python 3.12+. Use `datetime.now(timezone.utc)` instead. + +See `docs/archive/2025-12-30-auth-session-persistence-fix.md` for full details. + +### Frontend Module-Level State in Next.js + +**Problem**: Caching values in module-level variables can cause stale state in Next.js due to module caching and hydration timing. + +```javascript +// BAD - may return stale value +let accessToken = localStorage.getItem('key'); +export function getToken() { return accessToken; } + +// GOOD - always fresh +export function getToken() { + if (typeof window !== 'undefined') { + return localStorage.getItem('key'); + } + return null; +} +``` + +**Lesson**: For values that can change (auth tokens, user preferences), read fresh from storage on each access rather than caching in module scope. + ## What We'd Do Differently 1. **Add Pydantic model fields test first** - Would have caught the silent field issue immediately diff --git a/docs/README.md b/docs/README.md index 7450bec1..790613d7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -34,6 +34,7 @@ ## Recent Changes +- **Auth Session Persistence Fix** (2025-12-30): Fixed two bugs causing 401 errors despite valid sessions: timezone-aware datetime comparisons in backend, and stale token caching in frontend. Firestore indexes now tracked in Pulumi. See [archive/2025-12-30-auth-session-persistence-fix.md](archive/2025-12-30-auth-session-persistence-fix.md) - **E2E Test Suite Consolidated** (2025-12-29): Tests reorganized into `production/` (real API) and `regression/` (mocked API, CI-safe). See [archive/2025-12-29-e2e-test-consolidation-plan.md](archive/2025-12-29-e2e-test-consolidation-plan.md) ## Quick Links diff --git a/docs/archive/2025-12-30-auth-session-persistence-fix.md b/docs/archive/2025-12-30-auth-session-persistence-fix.md new file mode 100644 index 00000000..71856477 --- /dev/null +++ b/docs/archive/2025-12-30-auth-session-persistence-fix.md @@ -0,0 +1,92 @@ +# Auth Session Persistence Fix + +**Date**: 2025-12-30 +**PR**: #130 + +## Problem + +Users were being logged out immediately after logging in via magic link: +1. User clicks magic link, successfully authenticates +2. User is shown as logged in +3. On page reload (or even without reload), API calls return 401 Unauthorized +4. Session exists and is valid in Firestore, but requests fail + +## Root Causes + +### 1. Frontend Token Caching Bug + +`frontend/lib/api.ts` cached the auth token in a module-level variable: + +```javascript +// OLD - Buggy +let accessToken: string | null = null; +if (typeof window !== 'undefined') { + accessToken = localStorage.getItem('karaoke_access_token'); +} + +export function getAccessToken(): string | null { + return accessToken; // Returns cached value, may be stale +} +``` + +**Issue**: In Next.js, if the module initializes before localStorage is properly hydrated, or if there's any module caching behavior, the cached value could be stale or null. + +**Fix**: Always read fresh from localStorage: + +```javascript +export function getAccessToken(): string | null { + if (typeof window !== 'undefined') { + return localStorage.getItem('karaoke_access_token'); + } + return null; +} +``` + +### 2. Backend Timezone Comparison Bug (Main Culprit) + +`backend/services/user_service.py` compared naive and timezone-aware datetimes: + +```python +# OLD - Buggy +now = datetime.utcnow() # Naive datetime (no timezone) +if session.last_activity_at < inactivity_limit: # last_activity_at from Firestore is TZ-aware! + # TypeError: can't compare offset-naive and offset-aware datetimes +``` + +**What happens**: Firestore stores datetimes as timezone-aware. The first time a session is validated, `last_activity_at` is updated in Firestore. On subsequent reads, Firestore returns it as timezone-aware. Comparing this against `datetime.utcnow()` (naive) raises TypeError, caught by the exception handler, returning "An error occurred during validation" → 401. + +**Fix**: Use timezone-aware datetimes throughout: + +```python +now = datetime.now(timezone.utc) + +# Normalize session datetimes to be timezone-aware +expires_at = session.expires_at +if expires_at.tzinfo is None: + expires_at = expires_at.replace(tzinfo=timezone.utc) +``` + +## Additional Changes + +### Firestore Indexes Added to Pulumi + +The `scripts/investigate_user.py` script requires composite indexes. These were created manually and are now tracked in Pulumi IaC: + +- `jobs`: user_email + created_at (user job lists) +- `jobs`: status + created_at (admin/system job lists) +- `sessions`: is_active + user_email + created_at (active session queries) +- `magic_links`: email + created_at (magic link history) + +### Script Deprecation Fix + +Fixed `datetime.utcnow()` deprecation warning in `scripts/investigate_user.py`. + +## Debugging Tools Used + +1. **Direct Firestore query** to verify session exists and is valid +2. **Browser DevTools Network tab** to see 401 responses with valid-looking Authorization header +3. **`scripts/investigate_user.py`** to check user's sessions, jobs, magic links + +## Key Insight + +The session was valid in the database the entire time. The bug was in the *validation code*, not in session creation or storage. Always check the validation logic when auth fails unexpectedly.