# 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