Phil Skentelbery
0cca8169ce
## Phase 4: Web Interface Implementation Implemented complete web interface with public and admin routes, templates, CSS, and development authentication. ### Core Features **Public Routes**: - Homepage with recent published notes - Note permalinks with microformats2 - Server-side rendering (Jinja2) **Admin Routes**: - Login via IndieLogin - Dashboard with note management - Create, edit, delete notes - Protected with @require_auth decorator **Development Authentication**: - Dev login bypass for local testing (DEV_MODE only) - Security safeguards per ADR-011 - Returns 404 when disabled **Templates & Frontend**: - Base layouts (public + admin) - 8 HTML templates with microformats2 - Custom responsive CSS (114 lines) - Error pages (404, 500) ### Bugfixes (v0.5.1 → v0.5.2) 1. **Cookie collision fix (v0.5.1)**: - Renamed auth cookie from "session" to "starpunk_session" - Fixed redirect loop between dev login and admin dashboard - Flask's session cookie no longer conflicts with auth 2. **HTTP 404 error handling (v0.5.1)**: - Update route now returns 404 for nonexistent notes - Delete route now returns 404 for nonexistent notes - Follows ADR-012 HTTP Error Handling Policy - Pattern consistency across all admin routes 3. **Note model enhancement (v0.5.2)**: - Exposed deleted_at field from database schema - Enables soft deletion verification in tests - Follows ADR-013 transparency principle ### Architecture **New ADRs**: - ADR-011: Development Authentication Mechanism - ADR-012: HTTP Error Handling Policy - ADR-013: Expose deleted_at Field in Note Model **Standards Compliance**: - Uses uv for Python environment - Black formatted, Flake8 clean - Follows git branching strategy - Version incremented per versioning strategy ### Test Results - 405/406 tests passing (99.75%) - 87% code coverage - All security tests passing - Manual testing confirmed working ### Documentation - Complete implementation reports in docs/reports/ - Architecture reviews in docs/reviews/ - Design documents in docs/design/ - CHANGELOG updated for v0.5.2 ### Files Changed **New Modules**: - starpunk/dev_auth.py - starpunk/routes/ (public, admin, auth, dev_auth) **Templates**: 10 files (base, pages, admin, errors) **Static**: CSS and optional JavaScript **Tests**: 4 test files for routes and templates **Docs**: 20+ architectural and implementation documents 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
3.7 KiB
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
- Read
/home/phil/Projects/starpunk/docs/design/auth-redirect-loop-fix-implementation.md - Change 6 lines in production code (3 files)
- Change 5 lines in test code (2 files)
- Run tests
- Test manually (dev login → should work without loop)
- Update changelog
- 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)
starpunk/routes/dev_auth.py- Line 75 (set_cookie)starpunk/routes/auth.py- Lines 47, 121, 167, 178 (get/set/delete cookie)starpunk/auth.py- Line 390 (get cookie)
Tests (2 files, 5 changes)
tests/test_routes_admin.py- Line 54tests/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
- Dev login flow (no redirect loop)
- Session persistence across page loads
- Logout clears cookie properly
- Flash messages still work
- 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