fix: Implement IndieAuth endpoint discovery (v1.0.0-rc.5)
CRITICAL: Fix hardcoded IndieAuth endpoint configuration that violated the W3C IndieAuth specification. Endpoints are now discovered dynamically from the user's profile URL as required by the spec. This combines two critical fixes for v1.0.0-rc.5: 1. Migration race condition fix (previously committed) 2. IndieAuth endpoint discovery (this commit) ## What Changed ### Endpoint Discovery Implementation - Completely rewrote starpunk/auth_external.py with full endpoint discovery - Implements W3C IndieAuth specification Section 4.2 (Discovery by Clients) - Supports HTTP Link headers and HTML link elements for discovery - Always discovers from ADMIN_ME (single-user V1 assumption) - Endpoint caching (1 hour TTL) for performance - Token verification caching (5 minutes TTL) - Graceful fallback to expired cache on network failures ### Breaking Changes - REMOVED: TOKEN_ENDPOINT configuration variable - Endpoints now discovered automatically from ADMIN_ME profile - ADMIN_ME profile must include IndieAuth link elements or headers - Deprecation warning shown if TOKEN_ENDPOINT still in environment ### Added - 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 URL - HTTPS enforcement in production (HTTP allowed in debug mode) - Comprehensive error handling with clear messages - 35 new tests covering all discovery scenarios ### Security - Token hashing (SHA-256) for secure caching - HTTPS required in production, localhost only in debug mode - URL validation prevents injection - Fail closed on security errors - Single-user validation (token must belong to ADMIN_ME) ### Performance - Cold cache: ~700ms (first request per hour) - Warm cache: ~2ms (subsequent requests) - Grace period maintains service during network issues ## Testing - 536 tests passing (excluding timing-sensitive migration tests) - 35 new endpoint discovery tests (all passing) - Zero regressions in existing functionality ## Documentation - Updated CHANGELOG.md with comprehensive v1.0.0-rc.5 entry - Implementation report: docs/reports/2025-11-24-v1.0.0-rc.5-implementation.md - Migration guide: docs/migration/fix-hardcoded-endpoints.md (architect) - ADR-031: Endpoint Discovery Implementation Details (architect) ## Migration Required 1. Ensure ADMIN_ME profile has IndieAuth link elements 2. Remove TOKEN_ENDPOINT from .env file 3. Restart StarPunk - endpoints discovered automatically Following: - ADR-031: Endpoint Discovery Implementation Details - docs/architecture/endpoint-discovery-answers.md (architect Q&A) - docs/architecture/indieauth-endpoint-discovery.md (architect guide) - W3C IndieAuth Specification Section 4.2 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
84
CHANGELOG.md
84
CHANGELOG.md
@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
## [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
|
||||
@@ -18,7 +20,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- 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)
|
||||
@@ -26,6 +73,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- 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)
|
||||
|
||||
Reference in New Issue
Block a user