StarPunk/CHANGELOG.md

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

[0.7.0] - 2025-11-19

Added

• IndieAuth Detailed Logging: Comprehensive logging for authentication flows
• Logging helper functions with automatic token redaction (_redact_token, _log_http_request, _log_http_response)
• DEBUG-level HTTP request/response logging for IndieLogin.com interactions
• Configurable logging via LOG_LEVEL environment variable (DEBUG, INFO, WARNING, ERROR)
• Security-aware logging with automatic redaction of sensitive data (tokens, codes, secrets)
• Production warning when DEBUG logging is enabled in non-development environments
• Comprehensive test suite for logging functions (14 new tests)

Changed

• Enhanced authentication flow visibility with structured logging
• initiate_login(), handle_callback(), create_session(), and verify_session() now include detailed logging
• Flask logger configuration now based on LOG_LEVEL environment variable
• Log format varies by level: detailed for DEBUG, concise for INFO/WARNING/ERROR

Security

• All sensitive tokens automatically redacted in logs (show only first 6-8 and last 4 characters)
• Authorization codes, state tokens, and access tokens never logged in full
• Sensitive HTTP headers (Authorization, Cookie, Set-Cookie) excluded from logs
• Production warning prevents accidental DEBUG logging in production

Features

• Token redaction shows pattern like "abc123...********...xyz9" for debugging while protecting secrets
• HTTP request logging includes method, URL, and redacted parameters
• HTTP response logging includes status code, safe headers, and redacted body
• Session verification and creation logging for audit trails
• Admin authorization logging for security monitoring

Testing

• 51 authentication tests passing (100% pass rate)
• Tests verify token redaction at all levels
• Tests confirm no sensitive data appears in logs
• Tests verify logging behavior at different log levels (DEBUG vs INFO)

Standards Compliance

• OWASP Logging Cheat Sheet: Sensitive data redaction
• Python logging best practices
• IndieAuth specification compatibility (logging doesn't interfere with auth flow)

Related Documentation

• ADR-018: IndieAuth Detailed Logging Strategy
• Implementation includes complete specification from ADR-018

[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