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.9.5] - 2025-11-23

Fixed

• SECRET_KEY empty string handling: Fixed config.py to properly handle empty FLASK_SECRET_KEY environment variable
  • os.getenv() returns empty string (not None) when env var is set to ""
  • Empty string now correctly falls back to SESSION_SECRET
  • Prevents Flask session/flash failures when FLASK_SECRET_KEY="" in .env file

[0.9.4] - 2025-11-22

Fixed

• IndieAuth authentication endpoint correction: Changed code redemption from token endpoint to authorization endpoint
  • Per IndieAuth spec: authentication-only flows use /authorize, not /token
  • StarPunk only needs identity verification, not access tokens
  • Removed unnecessary grant_type parameter (only needed for token endpoint)
  • Updated debug logging to reflect "code verification" terminology
  • Fixes authentication with IndieLogin.com and spec-compliant providers

Changed

• Code redemption now POSTs to /authorize endpoint instead of /token
• Log messages updated from "token exchange" to "code verification"

[0.9.3] - 2025-11-22

Fixed

• IndieAuth token exchange missing grant_type: Added required grant_type=authorization_code parameter to token exchange request
  • OAuth 2.0 spec requires this parameter for authorization code flow
  • Some IndieAuth providers reject token exchange without this parameter
  • Fixes authentication failures with spec-compliant IndieAuth providers

[0.9.2] - 2025-11-22

Fixed

• IndieAuth callback 404 error: Fixed auth blueprint URL prefix mismatch
  • Auth blueprint was using /admin prefix but redirect_uri used /auth/callback
  • Changed blueprint prefix from /admin to /auth as documented in ADR-022
  • Auth routes now correctly at /auth/login, /auth/callback, /auth/logout
  • Admin dashboard routes remain at /admin/* (unchanged)

Changed

• Updated test expectations to use new /auth/* URL patterns

[0.9.1] - 2025-11-19

Fixed

• IndieAuth client_id trailing slash: Added automatic trailing slash normalization to SITE_URL
  • IndieLogin.com spec requires client_id URLs to have trailing slash for root domains
  • Fixes "client_id is not registered" authentication errors
  • Normalizes https://example.com to https://example.com/
• Enhanced debug logging: Added detailed httpx request/response logging for token exchange
  • Shows exact HTTP method, URL, headers, and body being sent to IndieLogin.com
  • Helps troubleshoot authentication issues with full visibility
  • All sensitive data (tokens, verifiers) automatically redacted

Changed

• SITE_URL configuration now automatically adds trailing slash if missing

[0.9.0] - 2025-11-19

Added

• Automatic Database Migration System: Zero-touch database schema updates on application startup
• Migration runner module (starpunk/migrations.py) with automatic execution
• Fresh database detection to prevent unnecessary migration execution
• Legacy database detection to apply pending migrations automatically
• Migration tracking table (schema_migrations) to record applied migrations
• Helper functions for database introspection (table_exists, column_exists, index_exists)
• Comprehensive migration test suite (26 tests covering all scenarios)

Changed

• init_db() now automatically runs migrations after creating schema
• Database initialization is fully automatic in containerized deployments
• Migration files in migrations/ directory are executed in alphanumeric order

Features

• Fresh Database Behavior: New installations detect current schema and mark migrations as applied without execution
• Legacy Database Behavior: Existing databases automatically apply pending migrations on startup
• Migration Tracking: All applied migrations recorded with timestamps in schema_migrations table
• Idempotent: Safe to run multiple times, only applies pending migrations
• Fail-Safe: Application fails to start if migrations fail, preventing inconsistent state

Infrastructure

• Container deployments now self-initialize with correct schema automatically
• No manual SQL execution required for schema updates
• Clear migration history in database for audit purposes
• Migration failures logged with detailed error messages

Standards Compliance

• Sequential migration numbering (001, 002, 003...)
• One migration per schema change for clear audit trail
• Migration files include date and ADR reference headers
• Follows standard migration patterns from Django/Rails

Testing

• 100% test coverage for migration system (26/26 tests passing)
• Tests cover fresh DB, legacy DB, partial migrations, failures
• Integration tests with actual migration file (001_add_code_verifier_to_auth_state.sql)
• Verified both automatic detection scenarios in production

Related Documentation

• ADR-020: Automatic Database Migration System
• Implementation guidance document with step-by-step instructions
• Quick reference card for migration system usage

[0.8.0] - 2025-11-19

Fixed

• CRITICAL: Fixed IndieAuth authentication to work with IndieLogin.com API
• Implemented required PKCE (Proof Key for Code Exchange) for security
• Corrected IndieLogin.com API endpoints (/authorize and /token instead of /auth)
• Added issuer validation for authentication callbacks

Added

• PKCE code_verifier generation and storage
• PKCE code_challenge generation (SHA256, base64-url encoded)
• Database column: auth_state.code_verifier for PKCE support
• Database migration script: migrations/001_add_code_verifier_to_auth_state.sql
• Comprehensive PKCE unit tests (6 tests, all passing)

Removed

• OAuth Client ID Metadata Document endpoint (/.well-known/oauth-authorization-server)
  • Added in v0.7.0 but unnecessary for IndieLogin.com
  • IndieLogin.com does not use OAuth client discovery
• h-app microformats markup from templates
  • Modified in v0.7.1 but unnecessary for IndieLogin.com
  • IndieLogin.com does not parse h-app for client identification
• indieauth-metadata link from HTML head

Changed

• Authentication flow now follows IndieLogin.com API specification exactly
• Database schema: auth_state table includes code_verifier column
• State token validation now returns code_verifier for token exchange
• Token exchange uses /token endpoint (not /auth)
• Authorization requests use /authorize endpoint (not /auth)

Security

• PKCE prevents authorization code interception attacks
• Issuer validation prevents token substitution attacks
• Code verifier securely stored and single-use
• Code verifier redacted in logs for security

Breaking Changes

• Users mid-authentication when upgrading will need to restart login (state tokens expire in 5 minutes)
• Existing state tokens without code_verifier will be invalid (intentional security improvement)

Notes

• v0.7.0: OAuth metadata endpoint added based on misunderstanding of requirements. This endpoint was never functional for our use case and is removed in v0.8.0.
• v0.7.1: h-app visibility changes attempted to fix authentication but addressed wrong issue. h-app discovery not used by IndieLogin.com. Removed in v0.8.0.
• v0.8.0: Correct implementation based on official IndieLogin.com API documentation.

Related Documentation

• ADR-025: IndieAuth Correct Implementation Based on IndieLogin.com API
• Design Document: docs/designs/indieauth-pkce-authentication.md
• ADR-016: Superseded (h-app client discovery not required)
• ADR-017: Superseded (OAuth metadata not required)

Migration Notes

• Database migration required: Add code_verifier column to auth_state table
• See migrations/001_add_code_verifier_to_auth_state.sql for SQL
• See docs/designs/indieauth-pkce-authentication.md for full implementation guide

[0.7.1] - 2025-11-19

Known Issues

• IndieAuth authentication still broken: This release attempted to fix authentication by making h-app visible, but IndieLogin.com does not parse h-app. Missing PKCE implementation is the actual issue. Fixed in v0.8.0.

Fixed

• IndieAuth h-app Visibility: Removed hidden and aria-hidden="true" attributes from h-app microformat markup
  • h-app was invisible to IndieAuth parsers, preventing proper client discovery
  • Now visible in DOM for microformat parsers while remaining non-intrusive in footer
  • Provides backward compatibility for IndieAuth services that rely on h-app parsing

[0.7.0] - 2025-11-19

Known Issues

• IndieAuth authentication still broken: This release attempted to fix authentication by adding OAuth metadata endpoint, but this is not required by IndieLogin.com. Missing PKCE implementation is the actual issue. Fixed in v0.8.0.

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