Architecture, README, standards, CLAUDE.md, settings reference, indexes, backlog, release plans and CHANGELOG checked against the code at v2.14.0: backfeed, notifications, counts line and web actions documented; test policy (changed area locally, full suite in CI); stale versions, statuses and links fixed; legacy and superseded docs moved. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.2 KiB
Cookie Naming Convention
Status: Active Date: 2025-11-18 Last Updated: 2026-11-10 (v2.14.0; cookie list checked against the code) Version: 1.1
Purpose
This document establishes the naming convention for HTTP cookies in StarPunk to prevent conflicts with web framework reserved names and ensure clear ownership of cookie data.
Standard
All StarPunk application cookies MUST use the starpunk_ prefix to avoid conflicts with framework-reserved names.
Rationale
Problem: Cookie name collision between application cookies and framework cookies can cause unexpected behavior. In Phase 4, we discovered that using a cookie named session conflicted with Flask's server-side session mechanism, causing an authentication redirect loop.
Solution: Namespace all application cookies with an application-specific prefix.
Reserved Names (DO NOT USE)
The following cookie names are reserved by frameworks and libraries. StarPunk MUST NOT use these names:
Flask Framework
session- Reserved for Flask's server-side session (used by flash messages, session storage)
Common Auth Frameworks
csrf_token- Common CSRF protection cookie nameremember_token- Common "remember me" authenticationauth_token- Generic authentication token
Generic Reserved Names
Avoid any single-word generic names that might conflict with frameworks or browsers:
tokenuseriddatastate
StarPunk Cookie Names
All StarPunk cookies use the starpunk_ prefix for clear ownership.
Current Cookies
| Cookie Name | Set by | Purpose | Security Attributes | Max Age |
|---|---|---|---|---|
starpunk_session |
/auth/callback (starpunk/routes/auth.py, constant SESSION_COOKIE) |
Admin session token (the token's hash is stored in the sessions table) |
HttpOnly, SameSite=Lax, Secure when SITE_URL starts with https:// |
SESSION_LIFETIME days (default 30) |
starpunk_session |
/dev/login (starpunk/routes/dev_auth.py, only with DEV_MODE=true) |
Same cookie, created without authentication | HttpOnly, SameSite=Lax, never Secure | 30 days (fixed) |
starpunk_session is read in starpunk/auth.py (require_auth),
starpunk/routes/auth.py, starpunk/routes/indieauth.py (consent screen)
and starpunk/__init__.py (before_request, so every page knows whether
the owner is logged in), and deleted on logout.
Not cookies: the OIDC login state, nonce and PKCE verifier are kept
server-side in the oidc_login_state table, and Micropub clients
authenticate with bearer tokens (indieauth_tokens table), never cookies.
Future Cookies
All future cookies must:
- Use
starpunk_prefix - Be documented in this table
- Have explicit security attributes defined
- Be reviewed for conflicts with framework conventions
Example future cookies:
starpunk_preferences- User preferences (if added)starpunk_analytics- Analytics consent (if added)starpunk_theme- Theme selection (if added)
Security Attributes
All StarPunk cookies MUST specify these security attributes:
Required Attributes
HttpOnly:
- Use for authentication and sensitive cookies
- Prevents JavaScript access
- Mitigates XSS attacks
Secure:
- Use in production (HTTPS)
- Can be
Falsein development (HTTP) - Prevents transmission over unencrypted connections
SameSite:
- Use
LaxorStrict - Prevents CSRF attacks
Laxallows top-level navigation with cookieStrictnever sends cookie cross-site
Max-Age:
- Always set explicit expiry
- Don't rely on session cookies (cleared on browser close)
- Choose appropriate lifetime for use case
Example
response.set_cookie(
"starpunk_session", # Name with prefix
session_token, # Value
httponly=True, # Prevent JS access
secure=is_production, # HTTPS only in prod
samesite="Lax", # CSRF protection
max_age=30 * 24 * 60 * 60, # 30 days
)
Implementation Checklist
When adding a new cookie:
- Name uses
starpunk_prefix - Name doesn't conflict with framework/library cookies
- Purpose is documented in this file
- Security attributes are explicitly set
- HttpOnly is used for sensitive data
- Secure is conditional on production vs development
- SameSite is set (Lax or Strict)
- Max-Age is appropriate for use case
- Cookie is reviewed by architect
- Tests verify cookie behavior
- Cookie is documented in API contracts
Reading Cookies
When reading cookies, always use the full prefixed name:
# Correct
session_token = request.cookies.get("starpunk_session")
# Incorrect - missing prefix
session_token = request.cookies.get("session")
Deletion
When deleting cookies, use the same name that was used to set them:
# Correct
response.delete_cookie("starpunk_session")
# Incorrect - missing prefix
response.delete_cookie("session")
Framework Cookie Coexistence
StarPunk and Flask cookies can coexist without conflict:
StarPunk cookies:
starpunk_session- Application authentication
Flask cookies (framework-managed):
session- Flask's signed session cookie (signed withSECRET_KEY, which defaults toSESSION_SECRET). StarPunk stores flash messages andsession["next"], the page to return to after login (set byrequire_authand the IndieAuth consent screen). Keep it to small, non-secret values: it is signed, not encrypted.
Both are necessary and serve different purposes. Do not interfere with Flask's session cookie.
Migration Notes
Version 0.5.1 Migration
Breaking Change: Authentication cookie renamed from session to starpunk_session.
Impact: All existing authenticated users were logged out and needed to re-authenticate.
Reason: Fix critical authentication redirect loop caused by cookie name collision.
Future Migrations: If cookie names need to change, consider:
- Dual-cookie period (read from both old and new)
- Client-side cookie migration via JavaScript
- Clear documentation of breaking change
- User communication about re-authentication
Validation
During Development
- Review cookie names in code review
- Check for
starpunk_prefix - Verify security attributes are set
- Test with browser DevTools → Application → Cookies
During Testing
- Automated tests should verify cookie names
- Integration tests should check cookie attributes
- Browser tests should verify cookie behavior
Example Test
def test_auth_cookie_name(client):
"""Test authentication uses correct cookie name (app built with DEV_MODE=True)"""
response = client.post("/dev/login")
# Verify correct cookie name
assert "starpunk_session" in response.headers.getlist("Set-Cookie")
# Verify does not use reserved name
cookies_str = str(response.headers.getlist("Set-Cookie"))
assert "session=" not in cookies_str or "starpunk_session=" in cookies_str
References
Internal Documentation
- Auth Redirect Loop Fix:
docs/design/v1.0.0/2025-11-18-auth-redirect-loop-fix.md - ADR-011: Development Authentication Mechanism
- ADR-064: OIDC admin login and built-in IndieAuth server (replaced ADR-005, IndieLogin, in v2.0.0)
External Standards
- RFC 6265 - HTTP State Management Mechanism (Cookies)
- Flask Session Documentation
- OWASP Session Management Cheat Sheet
History
Version 1.1 (2026-11-03)
- Cookie table checked against v2.10.1:
starpunk_sessionlifetime followsSESSION_LIFETIME, Secure follows theSITE_URLscheme; dev login cookie listed; Flasksessioncontents and server-side OIDC state documented - References updated (reports folder no longer exists; ADR-064 replaced ADR-005)
Version 1.0 (2025-11-18)
- Initial version
- Established
starpunk_prefix convention - Documented reserved names
- Added security attribute requirements
- Created as part of auth redirect loop fix (v0.5.1)
Document Owner: StarPunk Architecture Team Last Updated: 2026-11-03 Status: Active Standard