StarPunk/CHANGELOG.md

# Changelog

All notable changes to StarPunk will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.6.2] - 2025-11-19

### Fixed
- **CRITICAL**: Implemented OAuth Client ID Metadata Document to fix IndieAuth authentication
- Added `/.well-known/oauth-authorization-server` endpoint returning JSON metadata
- IndieLogin.com now correctly verifies StarPunk as a registered OAuth client
- Resolves "client_id is not registered" error preventing production authentication
- Fixes authentication flow with modern IndieAuth servers (2022+ specification)

### Added
- OAuth Client ID Metadata Document endpoint at `/.well-known/oauth-authorization-server`
- JSON metadata response with client_id, client_name, redirect_uris, and OAuth capabilities
- `<link rel="indieauth-metadata">` discovery hint in HTML head
- 24-hour caching for metadata endpoint (Cache-Control headers)
- Comprehensive test suite for OAuth metadata endpoint (12 new tests)
- Tests for indieauth-metadata link discovery (3 tests)

### Changed
- IndieAuth client discovery now uses modern JSON metadata (primary method)
- h-app microformats retained for backward compatibility (legacy fallback)
- Three-layer discovery: well-known URL, link rel hint, h-app markup

### Standards Compliance
- IndieAuth specification section 4.2 (Client Information Discovery)
- OAuth Client ID Metadata Document format
- IANA well-known URI registry standard
- OAuth 2.0 Dynamic Client Registration (RFC 7591)

### Technical Details
- Metadata endpoint uses configuration values (SITE_URL, SITE_NAME)
- client_id exactly matches document URL (spec requirement)
- redirect_uris properly formatted as array
- Supports PKCE (S256 code challenge method)
- Public client configuration (no client secret)

### Related Documentation
- ADR-017: OAuth Client ID Metadata Document Implementation
- IndieAuth Fix Summary report
- IndieAuth Client Discovery Root Cause Analysis

## [0.6.1] - 2025-11-19

### Fixed
- **CRITICAL**: Fixed IndieAuth client discovery to enable production authentication
- Added h-app microformats markup to base.html for IndieAuth client verification
- IndieLogin.com can now verify StarPunk as a legitimate OAuth client
- Resolves "client_id is not registered" error that blocked all production authentication

### Changed
- Added hidden h-app metadata div to footer with SITE_URL and SITE_NAME
- h-app markup uses aria-hidden="true" and hidden attribute for screen reader and visual hiding
- Implements IndieAuth legacy client discovery standard for backward compatibility

### Standards Compliance
- IndieAuth client discovery (legacy h-app microformats)
- Microformats2 h-app specification
- HTML5 hidden attribute standard
- ARIA accessibility standard

### Related Documentation
- ADR-016: IndieAuth Client Discovery Mechanism
- IndieAuth client discovery analysis report

## [0.6.0] - 2025-11-19

### Added
- **RSS Feed Generation**: Standards-compliant RSS 2.0 feed for published notes
- RSS feed module (`starpunk/feed.py`) with feed generation functions
- GET `/feed.xml` route for RSS feed access
- Server-side feed caching (5-minute default, configurable)
- ETag support for efficient feed updates
- Cache-Control headers for client-side caching
- RSS feed auto-discovery link in HTML templates
- RSS link in site navigation
- Comprehensive RSS feed test suite (44 tests)

### Production Container
- **Containerfile**: Multi-stage build for optimized image size (174MB)
- **Container Orchestration**: Podman and Docker Compose compatible
- **Health Check Endpoint**: GET `/health` for container monitoring
- **Gunicorn WSGI Server**: Production-ready with 4 workers
- **Security**: Non-root user execution (starpunk:1000)
- **Volume Mounts**: Data persistence for notes and database
- **Reverse Proxy Configs**: Caddy and Nginx examples with auto-HTTPS
- **Container Documentation**: Comprehensive deployment guide

### Configuration
- `FEED_MAX_ITEMS`: Maximum items in RSS feed (default: 50)
- `FEED_CACHE_SECONDS`: Server-side cache duration in seconds (default: 300)
- `VERSION`: Application version for health checks (default: 0.6.0)
- `ENVIRONMENT`: Deployment environment (development/production)
- `WORKERS`: Number of Gunicorn workers (default: 4)
- `WORKER_TIMEOUT`: Gunicorn worker timeout in seconds (default: 30)
- `MAX_REQUESTS`: Max requests per worker before restart (default: 1000)

### Features
- RSS 2.0 compliant XML generation using feedgen library
- RFC-822 date formatting for RSS pubDate elements
- Intelligent note title extraction (first line or timestamp fallback)
- HTML content in CDATA sections for feed readers
- Atom self-link for feed discovery
- Only published notes included in feed
- Absolute URLs for all feed item links

### Testing
- 88% overall test coverage (up from 87%)
- 96% coverage for feed module
- 449/450 tests passing (99.78% pass rate)
- Test isolation with automatic cache clearing
- Unicode and special character handling verified

### Standards Compliance
- RSS 2.0 specification compliant
- RFC-822 date format for timestamps
- IndieWeb feed discovery support
- W3C Feed Validator compatible

### Container Features
- Multi-stage build optimizes image size (Python 3.11-slim base)
- uv package manager for fast dependency installation
- Health checks verify database connectivity and filesystem access
- Resource limits prevent container resource exhaustion
- Log rotation (10MB max, 3 files) prevents disk space issues
- Automatic restart policy for reliability
- SELinux compatibility with volume mount flags

### Deployment
- Podman-compatible with `--userns=keep-id` for proper permissions
- Docker-compatible with standard volume mounts
- Reverse proxy examples for Caddy (auto-HTTPS) and Nginx
- HTTPS required for IndieAuth in production
- Complete backup and restore procedures documented
- Performance tuning guide for worker configuration

### Related Documentation
- ADR-014: RSS Feed Implementation Strategy
- ADR-015: Phase 5 Implementation Approach
- Phase 5 design documentation
- Phase 5 quick reference guide
- Container deployment guide

## [0.5.2] - 2025-11-18

### Fixed
- **Admin Routes**: Fixed delete route to return HTTP 404 when attempting to delete nonexistent notes, per ADR-012 (HTTP Error Handling Policy)
- Added existence check to delete route before attempting deletion, consistent with edit route pattern
- Fixed test for delete nonexistent note to match ADR-012 compliance (expect 404 status, not 200 with follow_redirects)

### Changed
- Delete route now checks note existence before deletion and returns 404 with "Note not found" flash message for nonexistent notes
- Test suite: 405/406 tests passing (99.75%)

## [0.5.1] - 2025-11-18

### Fixed
- **CRITICAL**: Fixed authentication redirect loop caused by cookie name collision between Flask's session and StarPunk's auth token
- Renamed authentication cookie from `session` to `starpunk_session` to avoid conflict with Flask's server-side session mechanism used by flash messages
- All authentication flows (dev login, IndieAuth, logout) now work correctly without redirect loops
- Flash messages now display properly without interfering with authentication state

### Changed
- **BREAKING CHANGE**: Authentication cookie renamed from `session` to `starpunk_session`
  - Existing authenticated users will be logged out and need to re-authenticate after upgrade
  - This is an unavoidable breaking change required to fix the critical bug

### Documentation
- Established cookie naming convention standard (starpunk_* prefix for all application cookies)
- Created implementation report documenting the root cause and fix

## [0.5.0] - 2025-11-19

### Added
- Development authentication module (`starpunk/dev_auth.py`) for local testing
- `is_dev_mode()` function to check development mode status
- `create_dev_session()` function for authentication bypass in development
- Web interface templates with Microformats2 markup
- Admin dashboard, note editor, and login pages
- Public note display and RSS feed support

### Fixed
- Phase 4 test suite now passing (400/406 tests, 98.5% pass rate)
- Template encoding issues (removed corrupted Unicode characters)
- Test database initialization using tmp_path fixtures
- Route URL patterns (trailing slash consistency)
- Template variable naming (g.user_me → g.me)
- Function name mismatches in tests (get_all_notes → list_notes)
- URL builder endpoint name (auth.login → auth.login_form)
- Session verification return type handling in tests
- Flake8 code quality issues (unused imports, f-strings)

### Security
- Development authentication includes prominent warning logging
- DEV_MODE validation ensures DEV_ADMIN_ME is set
- Production mode validation ensures ADMIN_ME is set

### Testing
- 87% overall test coverage
- All Phase 4 route and template tests functional
- Proper test isolation with temporary databases
- Fixed test context usage (test_request_context)

### Code Quality
- All code formatted with Black
- Passes Flake8 validation
- Removed unused imports and fixed f-string warnings

## [0.4.0] - 2025-11-18

### Added
- **Authentication module** (`starpunk/auth.py`) with IndieLogin support
- Core authentication functions: `initiate_login`, `handle_callback`, `create_session`, `verify_session`, `destroy_session`
- `require_auth` decorator for protecting admin routes
- Custom authentication exceptions (AuthError, InvalidStateError, UnauthorizedError, IndieLoginError)
- CSRF protection via state tokens
- Secure session management with SHA-256 token hashing
- Session metadata tracking (user agent, IP address)
- Automatic cleanup of expired sessions and state tokens
- URL validation utility function (`is_valid_url`)
- Comprehensive authentication test suite (37 tests, 96% coverage)

### Changed
- Updated sessions table schema to use `session_token_hash` instead of plaintext tokens
- Added `user_agent` and `ip_address` fields to sessions table
- Added `redirect_uri` field to auth_state table
- Added indexes for authentication performance (session_token_hash, me)

### Security
- Token hashing with SHA-256 for secure storage
- CSRF protection with single-use state tokens
- Cryptographically secure token generation (secrets module)
- SQL injection prevention with prepared statements
- Comprehensive security logging

## [0.3.0] - 2025-11-18

### Added
- Notes management module (`starpunk/notes.py`) with CRUD operations
- Custom exceptions for note operations (NoteError, NoteNotFoundError, InvalidNoteDataError, NoteSyncError)
- File and database synchronization with transaction safety
- Support for soft and hard note deletion
- Comprehensive test suite for notes module (85 tests, 86% coverage)
- Database schema support for soft deletes (deleted_at column)
- Slug uniqueness enforcement with random suffix generation
- Content hash calculation for integrity verification

### Changed
- Updated database schema to include `deleted_at` column in notes table
- Added index on `deleted_at` for query performance

## [0.1.0] - 2024-11-18

### Added
- Initial project structure
- Core architecture design
- Technology stack selection (Flask, SQLite, file-based storage)
- Architecture Decision Records (ADR-001 through ADR-007)
- Development documentation and standards
- Phase 1.1 design: Core utilities specification
- Python coding standards
- Documentation organization structure

### Documentation
- Complete architecture overview
- Technology stack documentation
- ADR-001: Python web framework (Flask)
- ADR-002: Flask extensions (minimal approach)
- ADR-003: Frontend technology (server-side rendering)
- ADR-004: File-based note storage
- ADR-005: IndieLogin authentication
- ADR-006: Python virtual environment (uv)
- ADR-007: Slug generation algorithm
- ADR-008: Versioning strategy

[Unreleased]: https://github.com/YOUR_USERNAME/starpunk/compare/v0.4.0...HEAD
[0.4.0]: https://github.com/YOUR_USERNAME/starpunk/compare/v0.3.0...v0.4.0
[0.3.0]: https://github.com/YOUR_USERNAME/starpunk/compare/v0.1.0...v0.3.0
[0.1.0]: https://github.com/YOUR_USERNAME/starpunk/releases/tag/v0.1.0