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

[1.2.0] - 2025-12-09

Added

• Feed Media Enhancement - Media RSS and JSON Feed image support for improved feed reader compatibility

  • RSS feeds now include Media RSS namespace (xmlns:media) for structured media metadata
  • RSS enclosure element added for first image (per RSS 2.0 spec)
  • Media RSS media:content elements for all images with type, medium, and fileSize attributes
  • Media RSS media:thumbnail element for first image preview
  • JSON Feed items include "image" field with first image URL (per JSON Feed 1.1 spec)
  • Image field absent (not null) when no media attached
  • Both feed formats maintain existing HTML embedding for universal reader support
  • Provides enhanced display in modern feed readers (Feedly, Inoreader, NetNewsWire)

• Custom Slug Input Field - Web UI now supports custom slugs (v1.2.0 Phase 1)

  • Added optional custom slug field to note creation form
  • Slugs are read-only after creation to preserve permalinks
  • Auto-validates and sanitizes slug format (lowercase, numbers, hyphens only)
  • Shows helpful placeholder text and validation guidance
  • Matches Micropub mp-slug behavior for consistency
  • Falls back to auto-generation when field is left blank

• Author Profile Discovery - Automatic h-card discovery from IndieAuth identity (v1.2.0 Phase 2)

  • Discovers author information from user's IndieAuth profile URL on login
  • Caches author h-card data (name, photo, bio, rel-me links) for 24 hours
  • Uses mf2py library for reliable Microformats2 parsing
  • Graceful fallback to domain name if discovery fails
  • Never blocks login functionality (per ADR-061)
  • Eliminates need for manual author configuration

• Complete Microformats2 Support - Full IndieWeb h-entry, h-card, h-feed markup (v1.2.0 Phase 2)

  • All notes display as proper h-entry with required properties (u-url, dt-published, e-content, p-author)
  • Author h-card nested within each h-entry (not standalone)
  • p-name property only added when note has explicit title (starts with # heading)
  • u-uid and u-url match for notes (permalink stability)
  • Homepage displays as h-feed with proper structure
  • rel-me links from discovered profile added to HTML head
  • dt-updated property shown when note is modified
  • Passes Microformats2 validation (indiewebify.me compatible)

• Media Upload Support - Image upload and display for notes (v1.2.0 Phase 3)

  • Upload up to 4 images per note via web UI (JPEG, PNG, GIF, WebP)
  • Automatic image optimization with Pillow library
  • Rejects files over 10MB or dimensions over 4096x4096 pixels
  • Auto-resizes images over 2048px (longest edge) to improve performance
  • EXIF orientation correction ensures proper display
  • Social media style layout: media displays at top, text content below
  • Optional captions for accessibility (used as alt text)
  • Media stored in date-organized folders (data/media/YYYY/MM/)
  • UUID-based filenames prevent collisions
  • Media included in all syndication feeds (RSS, ATOM, JSON Feed)
  • RSS: HTML embedding in description
  • ATOM: Both enclosures and HTML content
  • JSON Feed: Native attachments array
  • Multiple u-photo properties in Microformats2 markup
  • Media files cached immutably (1 year) for performance

Fixed

• Media Display on Homepage - Images now display correctly on homepage, not just individual note pages
• Responsive Image Sizing - Images constrained to container width with proper CSS
• Caption Display - Captions now used as alt text only, not displayed as visible text
• Logging Correlation ID - Fixed crash in non-request contexts (app init, memory monitor)

[1.1.2] - 2025-11-28

Fixed

• CRITICAL: Static files now load correctly - fixed HTTP middleware streaming response handling

  • HTTP metrics middleware was accessing .data on streaming responses (Flask's send_from_directory)
  • This caused RuntimeError: "Attempted implicit sequence conversion but the response object is in direct passthrough mode"
  • Now checks direct_passthrough attribute before accessing response data
  • Gracefully falls back to content_length for streaming responses
  • Fixes complete site failure (no CSS/JS loading)

• HIGH: Database metrics now display correctly - fixed configuration key mismatch

  • Config sets METRICS_SAMPLING_RATE (singular), metrics read METRICS_SAMPLING_RATES (plural)
  • Mismatch caused fallback to hardcoded 10% sampling regardless of config
  • Fixed key to use METRICS_SAMPLING_RATE (singular) consistently
  • MetricsBuffer now accepts both float (global rate) and dict (per-type rates)
  • Increased default sampling rate from 10% to 100% for low-traffic sites

Changed

• Default metrics sampling rate increased from 10% to 100%
  • Better visibility for low-traffic single-user deployments
  • Configurable via METRICS_SAMPLING_RATE environment variable (0.0-1.0)
  • Minimal overhead at typical usage levels
  • Power users can reduce if needed

[1.1.2-dev] - 2025-11-27

Added - Phase 3: Feed Statistics Dashboard & OPML Export (Complete)

Feed statistics dashboard and OPML 2.0 subscription list

• Feed Statistics Dashboard - Real-time feed performance monitoring

  • Added "Feed Statistics" section to /admin/metrics-dashboard
  • Tracks requests by format (RSS, ATOM, JSON Feed)
  • Cache hit/miss rates and efficiency metrics
  • Feed generation performance by format
  • Format popularity breakdown (pie chart)
  • Cache efficiency visualization (doughnut chart)
  • Auto-refresh every 10 seconds via htmx
  • Progressive enhancement (works without JavaScript)

• Feed Statistics API - Business metrics aggregation

  • New get_feed_statistics() function in starpunk.monitoring.business
  • Aggregates metrics from MetricsBuffer and FeedCache
  • Provides format-specific statistics (generated vs cached)
  • Calculates cache hit rates and format percentages
  • Integrated with /admin/metrics endpoint
  • Comprehensive test coverage (6 unit tests + 5 integration tests)

• OPML 2.0 Export - Feed subscription list for feed readers

  • New /opml.xml endpoint for OPML 2.0 subscription list
  • Lists all three feed formats (RSS, ATOM, JSON Feed)
  • RFC-compliant OPML 2.0 structure
  • Public access (no authentication required)
  • Feed discovery link in HTML <head>
  • Supports easy multi-feed subscription
  • Cache headers (same TTL as feeds)
  • Comprehensive test coverage (7 unit tests + 8 integration tests)

• Phase 3 Test Coverage - 26 new tests

  • 7 tests for OPML generation
  • 8 tests for OPML route and discovery
  • 6 tests for feed statistics functions
  • 5 tests for feed statistics dashboard integration

[1.1.2-dev] - 2025-11-26

Added - Phase 2: Feed Formats (Complete - RSS Fix, ATOM, JSON Feed, Content Negotiation)

Multi-format feed support with ATOM, JSON Feed, and content negotiation

• Content Negotiation - Smart feed format selection via HTTP Accept header

  • New /feed endpoint with HTTP content negotiation
  • Supports Accept header quality factors (e.g., q=0.9)
  • MIME type mapping:
    • application/rss+xml → RSS 2.0
    • application/atom+xml → ATOM 1.0
    • application/feed+json or application/json → JSON Feed 1.1
    • */* → RSS 2.0 (default)
  • Returns 406 Not Acceptable with helpful error message for unsupported formats
  • Simple implementation (StarPunk philosophy) - not full RFC 7231 compliance
  • Comprehensive test coverage (63 tests for negotiation + integration)

• Explicit Format Endpoints - Direct access to specific feed formats

  • /feed.rss - Explicit RSS 2.0 feed
  • /feed.atom - Explicit ATOM 1.0 feed
  • /feed.json - Explicit JSON Feed 1.1
  • /feed.xml - Backward compatibility (redirects to /feed.rss)
  • All endpoints support streaming and caching

• ATOM 1.0 Feed Support - RFC 4287 compliant ATOM feeds

  • Full ATOM 1.0 specification compliance with proper XML namespacing
  • RFC 3339 date format for published and updated timestamps
  • Streaming and non-streaming generation methods
  • XML escaping using standard library (xml.etree.ElementTree approach)
  • Business metrics integration for feed generation tracking
  • Comprehensive test coverage (11 tests)

• JSON Feed 1.1 Support - Modern JSON-based syndication format

  • JSON Feed 1.1 specification compliance
  • RFC 3339 date format for date_published
  • Streaming and non-streaming generation methods
  • UTF-8 JSON output with pretty-printing
  • Custom _starpunk extension with permalink_path and word_count
  • Business metrics integration
  • Comprehensive test coverage (13 tests)

• Feed Module Restructuring - Organized feed code for multiple formats

  • New starpunk/feeds/ module with format-specific files
  • feeds/rss.py - RSS 2.0 generation (moved from feed.py)
  • feeds/atom.py - ATOM 1.0 generation (new)
  • feeds/json_feed.py - JSON Feed 1.1 generation (new)
  • feeds/negotiation.py - Content negotiation logic (new)
  • Backward compatible feed.py shim for existing imports
  • All formats support both streaming and non-streaming generation
  • Business metrics integrated into all feed generators

Fixed - Phase 2: RSS Ordering

CRITICAL: Fixed RSS feed ordering bug

• RSS Feed Ordering - Corrected feed entry ordering
  • Fixed streaming RSS generation (removed incorrect reversed() at line 198)
  • Feedgen-based RSS correctly uses reversed() to compensate for library behavior
  • RSS feeds now properly show newest entries first (DESC order)
  • Created shared test helper tests/helpers/feed_ordering.py for all formats
  • All feed formats verified to maintain newest-first ordering

Added - Phase 1: Metrics Instrumentation

Complete metrics instrumentation foundation for production monitoring

• Database Operation Monitoring - Comprehensive database performance tracking

  • MonitoredConnection wrapper times all database operations
  • Extracts query type (SELECT, INSERT, UPDATE, DELETE, etc.)
  • Identifies table names using regex (simple queries) or "unknown" for complex queries
  • Detects slow queries (configurable threshold, default 1.0s)
  • Slow queries and errors always recorded regardless of sampling
  • Integrated at connection pool level for transparent operation
  • See developer Q&A CQ1, IQ1, IQ3 for design rationale

• HTTP Request/Response Metrics - Full request lifecycle tracking

  • Automatic request timing for all HTTP requests
  • UUID request ID generation for correlation (X-Request-ID header)
  • Request IDs included in ALL responses, not just debug mode
  • Tracks status codes, methods, endpoints, request/response sizes
  • Errors always recorded for debugging
  • Flask middleware integration for zero-overhead when disabled
  • See developer Q&A IQ2 for request ID strategy

• Memory Monitoring - Continuous background memory tracking

  • Daemon thread monitors RSS and VMS memory usage
  • 5-second baseline period after app initialization
  • Detects memory growth (warns at >10MB growth from baseline)
  • Tracks garbage collection statistics
  • Graceful shutdown handling
  • Automatically skipped in test mode to avoid thread pollution
  • Uses psutil for cross-platform memory monitoring
  • See developer Q&A CQ5, IQ8 for thread lifecycle design

• Business Metrics - Application-specific event tracking

  • Note operations: create, update, delete
  • Feed generation: timing, format, item count, cache hits/misses
  • All business metrics forced (always recorded)
  • Ready for integration into notes.py and feed.py
  • See implementation guide for integration examples

• Metrics Configuration - Flexible runtime configuration

  • METRICS_ENABLED - Master toggle (default: true)
  • METRICS_SLOW_QUERY_THRESHOLD - Slow query detection (default: 1.0s)
  • METRICS_SAMPLING_RATE - Sampling rate 0.0-1.0 (default: 1.0 = 100%)
  • METRICS_BUFFER_SIZE - Circular buffer size (default: 1000)
  • METRICS_MEMORY_INTERVAL - Memory check interval in seconds (default: 30)
  • All configuration via environment variables or .env file

Changed

• Database Connection Pool - Enhanced with metrics integration

  • Connections now wrapped with MonitoredConnection when metrics enabled
  • Passes slow query threshold from configuration
  • Logs metrics status on initialization
  • Zero overhead when metrics disabled

• Flask Application Factory - Metrics middleware integration

  • HTTP metrics middleware registered when metrics enabled
  • Memory monitor thread started (skipped in test mode)
  • Graceful cleanup handlers for memory monitor
  • Maintains backward compatibility

• Package Version - Bumped to 1.1.2-dev

  • Follows semantic versioning
  • Development version indicates work in progress
  • See docs/standards/versioning-strategy.md

Dependencies

• Added: psutil==5.9.* - Cross-platform system monitoring for memory tracking

Testing

• Added: Comprehensive monitoring test suite (tests/test_monitoring.py)
  • 28 tests covering all monitoring components
  • 100% test pass rate
  • Tests for database monitoring, HTTP metrics, memory monitoring, business metrics
  • Configuration validation tests
  • Thread lifecycle tests with proper cleanup

Documentation

• Added: Phase 1 implementation report (docs/reports/v1.1.2-phase1-metrics-implementation.md)
  • Complete implementation details
  • Q&A compliance verification
  • Test results and metrics demonstration
  • Integration guide for Phase 2

Notes

• This is Phase 1 of 3 for v1.1.2 "Syndicate" release
• All architect Q&A guidance followed exactly (zero deviations)
• Ready for Phase 2: Feed Formats (ATOM, JSON Feed)
• Business metrics functions available but not yet integrated into notes/feed modules

[1.1.1-rc.2] - 2025-11-25

Fixed

• CRITICAL: Resolved template/data mismatch causing 500 error on metrics dashboard
  • Fixed Jinja2 UndefinedError: 'dict object' has no attribute 'database'
  • Added transform_metrics_for_template() function to map data structure
  • Transforms metrics.by_type.database → metrics.database for template compatibility
  • Maps field names: avg_duration_ms → avg, min_duration_ms → min, etc.
  • Provides safe defaults for missing/empty metrics data
  • Renamed metrics dashboard route from /admin/dashboard to /admin/metrics-dashboard
  • Added defensive imports to handle missing monitoring module gracefully
  • All existing url_for("admin.dashboard") calls continue to work correctly
  • Notes dashboard at /admin/ remains unchanged and functional
  • See ADR-022 and ADR-060 for design rationale

[1.1.1] - 2025-11-25

Added

• Structured Logging - Enhanced logging system for production readiness

  • RotatingFileHandler with 10MB files, keeping 10 backups
  • Correlation IDs for request tracing across the entire request lifecycle
  • Separate log files in data/logs/starpunk.log
  • All print statements replaced with proper logging
  • See ADR-054 for architecture details

• Database Connection Pooling - Improved database performance

  • Connection pool with configurable size (default: 5 connections)
  • Request-scoped connections via Flask's g object
  • Pool statistics available for monitoring via /admin/metrics
  • Transparent to calling code (maintains same interface)
  • See ADR-053 for implementation details

• Enhanced Configuration Validation - Fail-fast startup validation

  • Validates both presence and type of all required configuration values
  • Clear, detailed error messages with specific fixes
  • Validates LOG_LEVEL against allowed values
  • Type checking for strings, integers, and Path objects
  • Non-zero exit status on configuration errors
  • See ADR-052 for configuration strategy

Changed

• Centralized Error Handling - Consistent error responses

  • Moved error handlers from inline decorators to starpunk/errors.py
  • Micropub endpoints return spec-compliant JSON errors
  • HTML error pages for browser requests
  • All errors logged with correlation IDs
  • MicropubError exception class for spec compliance
  • See ADR-055 for error handling strategy

• Database Module Reorganization - Better structure

  • Moved from single database.py to database/ package
  • Separated concerns: init.py, pool.py, schema.py
  • Maintains backward compatibility with existing imports
  • Cleaner separation of initialization and connection management

• Performance Monitoring Infrastructure - Track system performance

  • MetricsBuffer class with circular buffer (deque-based)
  • Per-process metrics with process ID tracking
  • Configurable sampling rates per operation type
  • Database pool statistics endpoint (/admin/metrics)
  • See Phase 2 implementation report for details

• Three-Tier Health Checks - Comprehensive health monitoring

  • Basic /health endpoint (public, load balancer-friendly)
  • Detailed /health?detailed=true (authenticated, comprehensive)
  • Full /admin/health diagnostics (authenticated, with metrics)
  • Progressive detail levels for different use cases
  • See developer Q&A Q10 for architecture

• Admin Metrics Dashboard - Visual performance monitoring (Phase 3)

  • Server-side rendering with Jinja2 templates
  • Auto-refresh with htmx (10-second interval)
  • Charts powered by Chart.js from CDN
  • Progressive enhancement (works without JavaScript)
  • Database pool statistics, performance metrics, system health
  • Access at /admin/dashboard
  • See developer Q&A Q19 for design decisions

Changed

• RSS Feed Streaming Optimization - Memory-efficient feed generation (Phase 3)

  • Generator-based streaming with yield (Q9)
  • Memory usage reduced from O(n) to O(1) for feed size
  • Yields XML in semantic chunks (channel metadata, items, closing tags)
  • Lower time-to-first-byte (TTFB) for large feeds
  • Note list caching still prevents repeated DB queries
  • No ETags (incompatible with streaming), but Cache-Control headers maintained
  • Recommended for feeds with 100+ items
  • Backward compatible - transparent to RSS clients

• Search Enhancements - Improved search robustness

  • FTS5 availability detection at startup with caching
  • Graceful fallback to LIKE queries when FTS5 unavailable
  • Search result highlighting with XSS prevention (markupsafe.escape())
  • Whitelist-only <mark> tags for highlighting
  • See Phase 2 implementation for details

• Unicode Slug Generation - International character support

  • Unicode normalization (NFKD) before slug generation
  • Timestamp-based fallback (YYYYMMDD-HHMMSS) for untranslatable text
  • Warning logs with original text for debugging
  • Never fails Micropub requests due to slug issues
  • See Phase 2 implementation for details

Fixed

• Migration Race Condition Tests - Fixed flaky tests (Phase 3, Q15)
  • Corrected off-by-one error in retry count expectations
  • Fixed mock time.time() call count in timeout tests
  • 10 retries = 9 sleep calls (not 10)
  • Tests now stable and reliable

Technical Details

• Phase 1, 2, and 3 of v1.1.1 "Polish" release completed
• Core infrastructure improvements for production readiness
• 600 tests passing (all tests stable, no flaky tests)
• No breaking changes to public API
• Complete operational documentation added

[1.1.0] - 2025-11-25

Added

• Full-Text Search - SQLite FTS5 implementation for searching note content

  • FTS5 virtual table with Porter stemming and Unicode normalization
  • Automatic index updates on note create/update/delete
  • Graceful degradation if FTS5 unavailable
  • Helper function to rebuild index from existing notes
  • See ADR-034 for architecture details
  • Note: Search UI (/api/search endpoint and templates) to be completed in follow-up

• Custom Slugs - User-specified URLs via Micropub

  • Support for mp-slug property in Micropub requests
  • Automatic slug sanitization (lowercase, hyphens only)
  • Reserved slug protection (api, admin, auth, feed, etc.)
  • Sequential conflict resolution with suffixes (-2, -3, etc.)
  • Hierarchical slugs (/) rejected (deferred to v1.2.0)
  • Maintains backward compatibility with auto-generation
  • See ADR-035 for implementation details

Fixed

• RSS Feed Ordering - Feed now correctly displays newest posts first

  • Added reversed() wrapper to compensate for feedgen internal ordering
  • Regression test ensures feed matches database DESC order

• Custom Slug Extraction - Fixed bug where mp-slug was ignored in Micropub requests

  • Root cause: mp-slug was extracted after normalize_properties() filtered it out
  • Solution: Extract mp-slug from raw request data before normalization
  • Affects both form-encoded and JSON Micropub requests
  • See docs/reports/custom-slug-bug-diagnosis.md for detailed analysis

Changed

• Database Migration System - Renamed for clarity
  • SCHEMA_SQL renamed to INITIAL_SCHEMA_SQL
  • Documentation clarifies this represents frozen v1.0.0 baseline
  • All schema changes after v1.0.0 must go in migration files
  • See ADR-033 for redesign rationale

Technical Details

• Migration 005: FTS5 virtual table with DELETE trigger
• New modules: starpunk/search.py, starpunk/slug_utils.py
• Modified: starpunk/notes.py (custom_slug param, FTS integration)
• Modified: starpunk/micropub.py (mp-slug extraction)
• Modified: starpunk/feed.py (reversed() fix)
• 100% backward compatible, no breaking changes
• All tests pass (557 tests)

[1.0.1] - 2025-11-25

Fixed

• Micropub Location header no longer contains double slash in URL
• Microformats2 query response URLs no longer contain double slash

Technical Details

Fixed URL construction in micropub.py to account for SITE_URL having a trailing slash (required for IndieAuth spec compliance). Changed from f"{site_url}/notes/{slug}" to f"{site_url}notes/{slug}" at two locations (lines 312 and 383). Added comments explaining the trailing slash convention.

[1.0.0] - 2025-11-24

Released

First production-ready release of StarPunk! A minimal, self-hosted IndieWeb CMS with full IndieAuth and Micropub compliance.

This milestone represents the completion of all V1 features:

• Full W3C IndieAuth specification compliance with endpoint discovery
• Complete W3C Micropub specification implementation for posting
• Robust database migrations with race condition protection
• Production-ready containerized deployment
• Comprehensive test coverage (536 tests passing)

StarPunk is now ready for production use as a personal IndieWeb publishing platform.

Summary of V1 Features

All features from release candidates (rc.1 through rc.5) are now stable:

IndieAuth Implementation

• External IndieAuth provider support (delegates to IndieLogin.com or similar)
• Dynamic endpoint discovery from user profile (ADMIN_ME)
• W3C IndieAuth specification compliance
• HTTP Link header and HTML link element discovery
• Endpoint caching (1 hour TTL) with graceful fallback
• Token verification caching (5 minutes TTL)

Micropub Implementation

• Full Micropub endpoint for creating posts
• Support for JSON and form-encoded requests
• Bearer token authentication with scope validation
• Content validation and sanitization
• Proper HTTP status codes and error responses
• Location header with post URL

Database & Migrations

• Automatic database migration system
• Migration race condition protection with database locking
• Exponential backoff retry logic for multi-worker deployments
• Safe container startup with gunicorn workers

Production Deployment

• Production-ready containerized deployment (Podman/Docker)
• Health check endpoint for monitoring
• Gunicorn WSGI server with multi-worker support
• Secure non-root user execution
• Reverse proxy configurations (Caddy/Nginx)

Configuration Changes from RC Releases

• TOKEN_ENDPOINT environment variable deprecated (endpoints discovered automatically)
• ADMIN_ME must be a valid profile URL with IndieAuth link elements

Standards Compliance

• W3C IndieAuth Specification (Section 4.2: Discovery by Clients)
• W3C Micropub Specification
• OAuth 2.0 Bearer Token Authentication
• Microformats2 Semantic HTML
• RSS 2.0 Feed Syndication

Testing

• 536 tests passing (99%+ pass rate)
• 87% overall code coverage
• Comprehensive endpoint discovery tests
• Complete Micropub integration tests
• Migration system tests

Documentation

Complete documentation available in /docs/:

• Architecture overview and design documents
• 31 Architecture Decision Records (ADRs)
• API contracts and specifications
• Deployment and migration guides
• Development standards and setup

Related Documentation

• ADR-031: IndieAuth Endpoint Discovery
• ADR-030: IndieAuth Provider Removal Strategy
• ADR-023: Micropub V1 Implementation Strategy
• ADR-022: Migration Race Condition Fix
• See /docs/reports/ for detailed implementation reports

[1.0.0-rc.5] - 2025-11-24

Fixed

Migration Race Condition (CRITICAL)

• CRITICAL: Migration race condition causing container startup failures with multiple gunicorn workers
  • Implemented database-level locking using SQLite's BEGIN IMMEDIATE transaction mode
  • Added exponential backoff retry logic (10 attempts, up to 120s total) for lock acquisition
  • Workers now coordinate properly: one applies migrations while others wait and verify
  • Graduated logging (DEBUG → INFO → WARNING) based on retry attempts
  • New connection created for each retry attempt to prevent state issues
  • See ADR-022 and migration-race-condition-fix-implementation.md for technical details

IndieAuth Endpoint Discovery (CRITICAL)

• CRITICAL: Fixed hardcoded IndieAuth endpoint configuration (violated IndieAuth specification)
  • Endpoints now discovered dynamically from user's profile URL (ADMIN_ME)
  • Implements W3C IndieAuth specification Section 4.2 (Discovery by Clients)
  • Supports both HTTP Link headers and HTML link elements for discovery
  • Endpoint discovery cached (1 hour TTL) for performance
  • Token verifications cached (5 minutes TTL)
  • Graceful fallback to expired cache on network failures
  • See ADR-031 and docs/architecture/indieauth-endpoint-discovery.md for details

Changed

IndieAuth Endpoint Discovery

• BREAKING: Removed TOKEN_ENDPOINT configuration variable

  • Endpoints are now discovered automatically from ADMIN_ME profile
  • Deprecation warning shown if TOKEN_ENDPOINT still in environment
  • See docs/migration/fix-hardcoded-endpoints.md for migration guide

• Token Verification (starpunk/auth_external.py)

  • Complete rewrite with endpoint discovery implementation
  • Always discovers endpoints from ADMIN_ME (single-user V1 assumption)
  • Validates discovered endpoints (HTTPS required in production, localhost allowed in debug)
  • Implements retry logic with exponential backoff for network errors
  • Token hashing (SHA-256) for secure caching
  • URL normalization for comparison (lowercase, no trailing slash)

• Caching Strategy

  • Simple single-user cache (V1 implementation)
  • Endpoint cache: 1 hour TTL with grace period on failures
  • Token verification cache: 5 minutes TTL
  • Cache cleared automatically on application restart

Added

IndieAuth Endpoint Discovery

• New dependency: beautifulsoup4>=4.12.0 for HTML parsing
• HTTP Link header parsing (RFC 8288 basic support)
• HTML link element extraction with BeautifulSoup4
• Relative URL resolution against profile base URL
• HTTPS enforcement in production (HTTP allowed in debug mode)
• Comprehensive error handling with clear messages
• 35 new tests covering all discovery scenarios

Technical Details

Migration Race Condition Fix

• Modified starpunk/migrations.py to wrap migration execution in BEGIN IMMEDIATE transaction
• Each worker attempts to acquire RESERVED lock; only one succeeds
• Other workers retry with exponential backoff (100ms base, doubling each attempt, plus jitter)
• Workers that arrive late detect completed migrations and exit gracefully
• Timeout protection: 30s per connection attempt, 120s absolute maximum
• Comprehensive error messages guide operators to resolution steps

Endpoint Discovery Implementation

• Discovery priority: HTTP Link headers (highest), then HTML link elements
• Profile URL fetch timeout: 5 seconds (cached results)
• Token verification timeout: 3 seconds (per request)
• Maximum 3 retries for server errors (500-504) and network failures
• No retries for client errors (400, 401, 403, 404)
• Single-user cache structure (no profile URL mapping needed in V1)
• Grace period: Uses expired endpoint cache if fresh discovery fails
• V2-ready: Cache structure can be upgraded to dict-based for multi-user

Breaking Changes

• TOKEN_ENDPOINT environment variable no longer used (will show deprecation warning)
• Micropub now requires discoverable IndieAuth endpoints in ADMIN_ME profile
• ADMIN_ME profile must include <link rel="token_endpoint"> or HTTP Link header

Migration Guide

See docs/migration/fix-hardcoded-endpoints.md for detailed migration steps:

1. Ensure your ADMIN_ME profile has IndieAuth link elements
2. Remove TOKEN_ENDPOINT from your .env file
3. Restart StarPunk - endpoints will be discovered automatically

Configuration

Updated requirements:

• ADMIN_ME: Required, must be a valid profile URL with IndieAuth endpoints
• TOKEN_ENDPOINT: Deprecated, will be ignored (remove from configuration)

Tests

• 536 tests passing (excluding timing-sensitive migration race tests)
• 35 new endpoint discovery tests:
  • Link header parsing (absolute and relative URLs)
  • HTML parsing (including malformed HTML)
  • Discovery priority (Link headers over HTML)
  • HTTPS validation (production vs debug mode)
  • Caching behavior (TTL, expiry, grace period)
  • Token verification (success, errors, retries)
  • URL normalization and scope checking

[1.0.0-rc.4] - 2025-11-24

Complete IndieAuth Server Removal (Phases 1-4)

StarPunk no longer acts as an IndieAuth authorization server. All IndieAuth operations are now delegated to external providers (e.g., IndieLogin.com). This simplifies the codebase and aligns with IndieWeb best practices.

Removed

• Phase 1: Authorization Endpoint

  • Deleted /auth/authorization endpoint and authorization_endpoint() function
  • Removed authorization consent UI template (templates/auth/authorize.html)
  • Removed authorization-related imports: create_authorization_code and validate_scope
  • Deleted tests: tests/test_routes_authorization.py, tests/test_auth_pkce.py

• Phase 2: Token Issuance

  • Deleted /auth/token endpoint and token_endpoint() function
  • Removed all token issuance functionality
  • Deleted tests: tests/test_routes_token.py

• Phase 3: Token Storage

  • Deleted starpunk/tokens.py module entirely
  • Dropped tokens and authorization_codes database tables (migration 004)
  • Removed token CRUD and verification functions
  • Deleted tests: tests/test_tokens.py

Added

• Phase 4: External Token Verification
  • New module starpunk/auth_external.py for external IndieAuth token verification
  • verify_external_token() function to verify tokens with external providers
  • check_scope() function moved from tokens module
  • Configuration: TOKEN_ENDPOINT for external token endpoint URL
  • HTTP client (httpx) for token verification requests
  • Proper error handling for unreachable auth servers
  • Timeout protection (5s) for external verification requests

Changed

• Micropub endpoint now verifies tokens with external IndieAuth providers

  • Updated routes/micropub.py to use verify_external_token()
  • Updated micropub.py to import check_scope from auth_external
  • All Micropub tests updated to mock external verification

• Migrations:

  • Migration 003: Remove code_verifier column from auth_state table
  • Migration 004: Drop tokens and authorization_codes tables
  • Both migrations applied automatically on startup

• Tests: All 501 tests passing

  • Fixed migration tests to work with current schema (no code_verifier)
  • Updated Micropub tests to mock external token verification
  • Fixed test fixtures and app context usage
  • Removed 38 obsolete token-related tests

Configuration

New required configuration for production:

• TOKEN_ENDPOINT: External IndieAuth token endpoint (e.g., https://tokens.indieauth.com/token)
• ADMIN_ME: Site owner's identity URL (already required)

Technical Details

• External token verification follows IndieAuth specification
• Tokens verified via GET request with Authorization header
• Token response validated for required fields (me, client_id, scope)
• Only tokens matching ADMIN_ME are accepted
• Graceful degradation if external server unavailable

Breaking Changes

• Micropub clients must obtain tokens from external IndieAuth providers
• Existing internal tokens are invalid (tables dropped in migration 004)
• TOKEN_ENDPOINT configuration required for Micropub to function

Migration Guide

1. Choose external IndieAuth provider (recommended: IndieLogin.com)
2. Set TOKEN_ENDPOINT environment variable
3. Existing sessions unaffected - admin login still works
4. Micropub clients need new tokens from external provider

Standards Compliance

• Fully compliant with W3C IndieAuth specification
• Follows IndieWeb principle: delegate to external services
• OAuth 2.0 Bearer token authentication maintained

Related Documentation

• ADR-030: IndieAuth Provider Removal Strategy
• ADR-050: Remove Custom IndieAuth Server
• Implementation report: docs/reports/2025-11-24-indieauth-removal-complete.md

Notes

• This completes the transition from self-hosted IndieAuth to external delegation
• Simpler codebase: -500 lines of code, -5 database tables
• More secure: External providers handle token security
• More maintainable: Less code to secure and update

[1.0.0-rc.3] - 2025-11-24

Fixed

• CRITICAL: Migration detection failure for partially migrated databases: Fixed migration 002 detection logic
  • Production database had migration 001 applied but not migration 002
  • Migration 002's tables (tokens, authorization_codes) already existed from SCHEMA_SQL in v1.0.0-rc.1
  • Previous logic only used smart detection for fresh databases (migration_count == 0)
  • For partially migrated databases (migration_count > 0), it tried to run migration 002 normally
  • This caused "table already exists" error because CREATE TABLE statements would fail
  • Fixed by checking migration 002's state regardless of migration_count
  • Migration 002 now checks if its tables exist before running, skips table creation if they do
  • Missing indexes are created even when tables exist, ensuring complete database state
  • Fixes deployment failure on production database with existing tables but missing migration record

Technical Details

• Affected databases: Any database with migration 001 applied but not migration 002, where tables were created by SCHEMA_SQL
• Root cause: Smart detection (is_migration_needed) was only called when migration_count == 0
• Solution: Always check migration 002's state, regardless of migration_count
• Backwards compatibility: Works for fresh databases, partially migrated databases, and fully migrated databases
• Migration 002 will create only missing indexes if tables already exist

[1.0.0-rc.2] - 2025-11-24

Fixed

• CRITICAL: Database migration failure on existing databases: Removed duplicate index definitions from SCHEMA_SQL
  • Migration 002 creates indexes idx_tokens_hash, idx_tokens_me, and idx_tokens_expires
  • These same indexes were also in SCHEMA_SQL (database.py lines 58-60)
  • When applying migration 002 to existing databases, indexes already existed from SCHEMA_SQL, causing failure
  • Removed the three index creation statements from SCHEMA_SQL to prevent conflicts
  • Migration 002 is now the sole source of truth for token table indexes
  • Fixes "index already exists" error when running migrations on databases created before v1.0.0-rc.1

Technical Details

• Affected databases: Any database created with v1.0.0-rc.1 or earlier that had run init_db()
• Root cause: SCHEMA_SQL ran on every init_db() call, creating indexes before migration could run
• Solution: Remove index creation from SCHEMA_SQL, delegate to migration 002 exclusively
• Backwards compatibility: Fresh databases will get indexes from migration 002 automatically

[1.0.0-rc.1] - 2025-11-24

Release Candidate for V1.0.0

First release candidate with complete IndieWeb support. This milestone implements the full V1 specification with IndieAuth authentication and Micropub posting capabilities.

Added

• Phase 1: Secure Token Management

  • Bearer token storage with Argon2id hashing
  • Automatic token expiration (90 days default)
  • Token revocation endpoint (POST /micropub?action=revoke)
  • Admin interface for token management with creation, viewing, and revocation
  • Comprehensive test coverage for token operations (14 tests)

• Phase 2: IndieAuth Token Endpoint

  • Token endpoint (POST /indieauth/token) for access token issuance
  • Authorization endpoint (POST /indieauth/authorize) for consent flow
  • PKCE verification for authorization code exchange
  • Token verification endpoint (GET /indieauth/token) for clients
  • Proper OAuth 2.0/IndieAuth spec compliance
  • Client credential validation and scope enforcement
  • Test suite for token and authorization endpoints (13 tests)

• Phase 3: Micropub Endpoint

  • Micropub endpoint (POST /micropub) for creating posts
  • Support for both JSON and form-encoded requests
  • Bearer token authentication with scope validation
  • Content validation and sanitization
  • Post creation with automatic timestamps
  • Location header with post URL in responses
  • Comprehensive error handling with proper HTTP status codes
  • Integration tests for complete authentication flow (11 tests)

Changed

• Admin interface now includes token management section
• Database schema extended with tokens table for secure token storage
• Authentication system now supports both admin sessions and bearer tokens
• Authorization flow integrated with existing IndieAuth authentication

Security

• Bearer tokens hashed with Argon2id (same as passwords)
• Tokens support automatic expiration
• Scope validation enforces create permission for posting
• PKCE prevents authorization code interception
• Token verification validates both hash and expiration

Standards Compliance

• IndieAuth specification (W3C) for authentication and authorization
• Micropub specification (W3C) for posting interface
• OAuth 2.0 bearer token authentication
• Proper HTTP status codes and error responses
• Location header for created resources

Testing

• 77 total tests (all passing)
• Complete coverage of token management, IndieAuth endpoints, and Micropub
• Integration tests verify end-to-end flows
• Error case coverage for validation and authentication failures

Documentation

• Implementation reports for all three phases
• Architecture reviews documenting design decisions
• API contracts specified in docs/design/api-contracts.md
• Test coverage documented in implementation reports

Related Standards

• ADR-023: Micropub V1 Implementation Strategy
• W3C IndieAuth Specification
• W3C Micropub Specification

Notes

This is a release candidate for testing. Stable 1.0.0 will be released after testing period and any necessary fixes.

[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