Phil Skentelbery
a7e0af9c2c
Complete architectural documentation for: - Migration race condition fix with database locking - IndieAuth endpoint discovery implementation - Security considerations and migration guides New documentation: - ADR-030-CORRECTED: IndieAuth endpoint discovery decision - ADR-031: Endpoint discovery implementation details - Architecture docs on endpoint discovery - Migration guide for removed TOKEN_ENDPOINT - Security analysis of endpoint discovery - Implementation and analysis reports
3.5 KiB
ADR-031: IndieAuth Endpoint Discovery Implementation Details
Status
Accepted
Context
The developer raised critical implementation questions about ADR-030-CORRECTED regarding IndieAuth endpoint discovery. The primary blocker was the "chicken-and-egg" problem: when receiving a token, how do we know which endpoint to verify it with?
Decision
For StarPunk V1 (single-user CMS), we will:
- ALWAYS use ADMIN_ME for endpoint discovery when verifying tokens
- Use simple caching structure optimized for single-user
- Add BeautifulSoup4 as a dependency for robust HTML parsing
- Fail closed on security errors with cache grace period
- Allow HTTP in debug mode for local development
Core Implementation
def verify_external_token(token: str) -> Optional[Dict[str, Any]]:
"""Verify token - single-user V1 implementation"""
admin_me = current_app.config.get("ADMIN_ME")
# Always discover from ADMIN_ME (single-user assumption)
endpoints = discover_endpoints(admin_me)
token_endpoint = endpoints['token_endpoint']
# Verify and validate token belongs to admin
token_info = verify_with_endpoint(token_endpoint, token)
if normalize_url(token_info['me']) != normalize_url(admin_me):
raise TokenVerificationError("Token not for admin user")
return token_info
Rationale
Why ADMIN_ME Discovery?
StarPunk V1 is explicitly single-user. Only the admin can post, so any valid token MUST belong to ADMIN_ME. This eliminates the chicken-and-egg problem entirely.
Why Simple Cache?
With only one user, we don't need complex profile->endpoints mapping. A simple cache suffices:
class EndpointCache:
def __init__(self):
self.endpoints = None # Single user's endpoints
self.endpoints_expire = 0
self.token_cache = {} # token_hash -> (info, expiry)
Why BeautifulSoup4?
- Industry standard for HTML parsing
- More robust than regex or built-in parsers
- Pure Python implementation available
- Worth the dependency for correctness
Why Fail Closed?
Security principle: when in doubt, deny access. We use cached endpoints as a grace period during network failures, but ultimately deny access if we cannot verify.
Consequences
Positive
- Eliminates complexity of multi-user endpoint discovery
- Simple, clear implementation path
- Secure by default
- Easy to test and verify
Negative
- Will need refactoring for V2 multi-user support
- Adds BeautifulSoup4 dependency
- First request after cache expiry has ~850ms latency
Migration Impact
- Breaking change: TOKEN_ENDPOINT config removed
- Users must update configuration
- Clear deprecation warnings provided
Alternatives Considered
Alternative 1: Require 'me' Parameter
Rejected: Would violate Micropub specification
Alternative 2: Try Multiple Endpoints
Rejected: Complex, slow, and unnecessary for single-user
Alternative 3: Pre-warm Cache
Rejected: Adds complexity for minimal benefit
Implementation Timeline
- v1.0.0-rc.5: Full implementation with migration guide
- Remove TOKEN_ENDPOINT configuration
- Add endpoint discovery from ADMIN_ME
- Document single-user assumption
Testing Strategy
- Unit tests with mocked HTTP responses
- Edge case coverage (malformed HTML, network errors)
- One integration test with real IndieAuth.com
- Skip real provider tests in CI (manual testing only)
References
- W3C IndieAuth Specification Section 4.2 (Discovery)
- ADR-030-CORRECTED (Original design)
- Developer analysis report (2025-11-24)