StarPunk/docs/standards/cookie-naming-convention.md

# Cookie Naming Convention

**Status**: ACTIVE
**Date**: 2025-11-18
**Version**: 1.0

## 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 name
- `remember_token` - Common "remember me" authentication
- `auth_token` - Generic authentication token

### Generic Reserved Names
Avoid any single-word generic names that might conflict with frameworks or browsers:
- `token`
- `user`
- `id`
- `data`
- `state`

## StarPunk Cookie Names

All StarPunk cookies use the `starpunk_` prefix for clear ownership.

### Current Cookies

| Cookie Name | Purpose | Security Attributes | Max Age |
|-------------|---------|---------------------|---------|
| `starpunk_session` | Authentication session token | HttpOnly, Secure (prod), SameSite=Lax | 30 days |

### Future Cookies

All future cookies must:
1. Use `starpunk_` prefix
2. Be documented in this table
3. Have explicit security attributes defined
4. 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 `False` in development (HTTP)
- Prevents transmission over unencrypted connections

**SameSite**:
- Use `Lax` or `Strict`
- Prevents CSRF attacks
- `Lax` allows top-level navigation with cookie
- `Strict` never 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

```python
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:

```python
# 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:

```python
# 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 server-side session (for flash messages)

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:
1. Dual-cookie period (read from both old and new)
2. Client-side cookie migration via JavaScript
3. Clear documentation of breaking change
4. 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

```python
def test_auth_cookie_name(client):
    """Test authentication uses correct cookie name"""
    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/reports/2025-11-18-auth-redirect-loop-fix.md`
- **ADR-011**: Development Authentication Mechanism
- **ADR-005**: IndieLogin Authentication

### External Standards
- [RFC 6265 - HTTP State Management Mechanism (Cookies)](https://tools.ietf.org/html/rfc6265)
- [Flask Session Documentation](https://flask.palletsprojects.com/en/latest/api/#flask.session)
- [OWASP Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)

## History

### 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**: 2025-11-18
**Status**: Active Standard