StarPunk/docs/design/v1.1.1/auth-redirect-loop-executive-summary.md

Auth Redirect Loop - Executive Summary

Date: 2025-11-18 Status: ROOT CAUSE IDENTIFIED - FIX READY Priority: CRITICAL

The Problem (30 Second Version)

When you click dev login, you get redirected back to the login page instead of to the admin dashboard. This is a redirect loop.

Root Cause (One Sentence)

Flask's session object (used by flash() messages) and StarPunk's authentication both use a cookie named session, causing Flask to overwrite the auth token.

The Fix (One Sentence)

Rename StarPunk's authentication cookie from "session" to "starpunk_session".

What the Developer Needs to Do

1. Read /home/phil/Projects/starpunk/docs/design/auth-redirect-loop-fix-implementation.md
2. Change 6 lines in production code (3 files)
3. Change 5 lines in test code (2 files)
4. Run tests
5. Test manually (dev login → should work without loop)
6. Update changelog
7. Commit

Time Estimate: 30 minutes

Why This Happened

StarPunk uses a cookie named session to store the authentication token (e.g., "abc123xyz").

Flask uses a cookie named session to store server-side session data (for flash messages and session["next"]).

These are two different things trying to use the same cookie name.

The Sequence of Events

1. /dev/login sets cookie: session = "auth_token_abc123"
2. /dev/login calls flash() → Flask writes session = {flash: "message"}
3. Browser redirects to /admin/
4. @require_auth reads cookie: session = {flash: "message"} ← WRONG!
5. verify_session("flash: message") → FAIL (not a valid token)
6. Redirect to /admin/login
7. Loop!

The Fix Explained

By renaming StarPunk's cookie to starpunk_session, we avoid the collision:

1. /dev/login sets: starpunk_session = "auth_token_abc123"
2. /dev/login calls flash() → Flask sets: session = {flash: "message"}
3. Browser has TWO cookies now (no conflict)
4. @require_auth reads: starpunk_session = "auth_token_abc123" ← CORRECT!
5. verify_session("auth_token_abc123") → SUCCESS
6. Dashboard loads ✓

Files to Change

Production Code (3 files, 6 changes)

1. starpunk/routes/dev_auth.py - Line 75 (set_cookie)
2. starpunk/routes/auth.py - Lines 47, 121, 167, 178 (get/set/delete cookie)
3. starpunk/auth.py - Line 390 (get cookie)

Tests (2 files, 5 changes)

1. tests/test_routes_admin.py - Line 54
2. tests/test_templates.py - Lines 234, 247, 259, 272

Breaking Change

Yes - Existing logged-in users will be logged out and need to re-authenticate.

This is because we're changing the cookie name, so their existing session cookies won't be read as starpunk_session.

Detailed Documentation

• Diagnosis: /home/phil/Projects/starpunk/docs/design/auth-redirect-loop-diagnosis.md
• Implementation Guide: /home/phil/Projects/starpunk/docs/design/auth-redirect-loop-fix-implementation.md

Architecture Impact

This establishes a new architectural standard:

Cookie Naming Convention: All StarPunk cookies MUST use the starpunk_ prefix to avoid conflicts with framework-reserved names.

This prevents this class of bugs in the future.

Testing

Must Pass

1. Dev login flow (no redirect loop)
2. Session persistence across page loads
3. Logout clears cookie properly
4. Flash messages still work
5. All automated tests pass

Browser Check

After fix, cookies should be:

• starpunk_session = {long-auth-token}
• session = {flask-session-with-flash-messages}

Version Impact

This is a bugfix release: 0.5.0 → 0.5.1

Questions?

Read the full implementation guide: /home/phil/Projects/starpunk/docs/design/auth-redirect-loop-fix-implementation.md

It contains:

• Exact code changes (old vs new)
• Line-by-line change locations
• Complete testing plan
• Rollback instructions
• Git commit template