phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(auth): Implement IndieAuth endpoint discovery per W3C spec

Browse Source 
BREAKING: Removes INDIELOGIN_URL config - endpoints are now properly
discovered from user's profile URL as required by W3C IndieAuth spec.

- auth.py: Uses discover_endpoints() to find authorization_endpoint
- config.py: Deprecation warning for obsolete INDIELOGIN_URL setting
- auth_external.py: Relaxed validation (allows auth-only flows)
- tests: Updated to mock endpoint discovery

This fixes a regression where admin login was hardcoded to use
indielogin.com instead of respecting the user's declared endpoints.

Version: 1.5.0-hotfix.1

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Phil Skentelbery
2025-12-17 13:52:36 -07:00
parent 84e693fe57
commit 2bd971f3d6
12 changed files with 1366 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
docs/design/hotfix/2025-12-17-indieauth-pkce-endpoint-discovery-hotfix-implementation-report.md Normal file
View File

@@ -0,0 +1,173 @@
# IndieAuth Endpoint Discovery Hotfix - Implementation Report
**Date:** 2025-12-17
**Type:** Production Hotfix
**Priority:** Critical
**Status:** Implementation Complete
## Summary
Successfully implemented the IndieAuth endpoint discovery hotfix as specified in the design document. The authentication flow now correctly discovers endpoints from the user's profile URL per the W3C IndieAuth specification, instead of hardcoding the indielogin.com service.
## Implementation Steps
All implementation steps were completed successfully:
### Step 1: Update starpunk/config.py - Remove INDIELOGIN_URL
- Removed `INDIELOGIN_URL` config line (previously line 37)
- Added deprecation warning for users still setting `INDIELOGIN_URL` in environment
- Warning directs users to remove the deprecated config
### Step 2: Update starpunk/auth.py - Add imports and use endpoint discovery
- Added imports: `discover_endpoints`, `DiscoveryError`, `normalize_url` from `starpunk.auth_external`
- Rewrote `initiate_login()`:
- Now discovers authorization_endpoint from the user's profile URL
- Uses discovered endpoint instead of hardcoded INDIELOGIN_URL
- Raises DiscoveryError if endpoint discovery fails or no authorization_endpoint found
- Rewrote `handle_callback()`:
- Discovers authorization_endpoint from ADMIN_ME profile
- Uses authorization_endpoint for authentication-only flow (per IndieAuth spec)
- Does NOT include `grant_type` parameter (not needed for auth-only flows)
- Uses `normalize_url()` for URL comparison to handle trailing slashes and case differences
### Step 3: Update starpunk/auth_external.py - Relax endpoint validation
- Changed endpoint validation in `_fetch_and_parse()`:
- Now requires at least one endpoint (authorization_endpoint OR token_endpoint)
- Previously required token_endpoint to be present
- This allows profiles with only authorization_endpoint to work for login
- Micropub will still require token_endpoint and fail gracefully with 401
### Step 4: Update starpunk/routes/auth.py - Import and handle DiscoveryError
- Added import for `DiscoveryError` from `starpunk.auth_external`
- Added exception handler in `login_initiate()`:
- Catches DiscoveryError
- Logs technical details at ERROR level
- Shows user-friendly message: "Unable to verify your profile URL. Please check that it's correct and try again."
- Redirects back to login form
### Step 5: Update tests/test_auth.py - Mock discover_endpoints()
- Removed `INDIELOGIN_URL` from test app fixture
- Updated all tests that call `initiate_login()` or `handle_callback()`:
- Added `@patch("starpunk.auth.discover_endpoints")` decorator
- Mock returns both authorization_endpoint and token_endpoint
- Updated assertions to check for discovered endpoint instead of indielogin.com
- Tests updated:
- `TestInitiateLogin.test_initiate_login_success`
- `TestInitiateLogin.test_initiate_login_stores_state`
- `TestHandleCallback.test_handle_callback_success`
- `TestHandleCallback.test_handle_callback_unauthorized_user`
- `TestHandleCallback.test_handle_callback_indielogin_error`
- `TestHandleCallback.test_handle_callback_no_identity`
- `TestLoggingIntegration.test_initiate_login_logs_at_debug`
- `TestLoggingIntegration.test_initiate_login_info_level`
- `TestLoggingIntegration.test_handle_callback_logs_http_details`
### Step 6: Update tests/test_auth_external.py - Fix error message
- Updated `test_discover_endpoints_no_token_endpoint`:
- Changed assertion from "No token endpoint found" to "No IndieAuth endpoints found"
- Matches new relaxed validation error message
### Step 7: Run tests to verify implementation
- All 51 tests in `tests/test_auth.py` pass
- All 35 tests in `tests/test_auth_external.py` pass
- All 32 tests in `tests/test_routes_admin.py` pass
- No regressions detected
## Files Modified
| File | Lines Changed | Description |
|------|--------------|-------------|
| `starpunk/config.py` | 9 added, 1 removed | Removed INDIELOGIN_URL, added deprecation warning |
| `starpunk/auth.py` | 1 added, 84 replaced | Added imports, rewrote initiate_login() and handle_callback() |
| `starpunk/auth_external.py` | 6 replaced | Relaxed endpoint validation |
| `starpunk/routes/auth.py` | 5 added | Added DiscoveryError import and exception handling |
| `tests/test_auth.py` | 1 removed, 43 modified | Removed INDIELOGIN_URL from fixture, added mocks |
| `tests/test_auth_external.py` | 2 modified | Updated error message assertion |
## Key Implementation Details
### Authorization Endpoint Usage
Per IndieAuth spec and architect clarifications:
- Authentication-only flows POST to the **authorization_endpoint** (not token_endpoint)
- The `grant_type` parameter is NOT included (only for access token flows)
- This differs from the previous implementation which incorrectly used indielogin.com's endpoints
### URL Normalization
The implementation now uses `normalize_url()` when comparing the returned 'me' URL with ADMIN_ME:
- Handles trailing slash differences (https://example.com vs https://example.com/)
- Handles case differences (https://Example.com vs https://example.com)
- This is spec-compliant behavior that was previously missing
### Error Handling
- Discovery failures are caught and logged at ERROR level
- User-facing error message is simplified and friendly
- Technical details remain in logs for debugging
### Backward Compatibility
- Deprecation warning added for INDIELOGIN_URL environment variable
- Existing .env files with INDIELOGIN_URL will log a warning but continue to work
- Users are instructed to remove the deprecated config
## Testing Results
### Unit Tests
- `tests/test_auth.py`: 51/51 passed
- `tests/test_auth_external.py`: 35/35 passed
- `tests/test_routes_admin.py`: 32/32 passed
### Integration
All modified tests now correctly mock endpoint discovery and validate the new behavior.
## Issues Encountered
No significant issues encountered during implementation. The design document was thorough and all architect clarifications were addressed:
1. Import placement - Moved to top-level as specified
2. URL normalization - Included as intentional bugfix
3. Endpoint selection - Used authorization_endpoint for auth-only flows
4. Validation relaxation - Allowed profiles with only authorization_endpoint
5. Test strategy - Mocked discover_endpoints() and removed INDIELOGIN_URL
6. grant_type parameter - Correctly omitted for auth-only flows
7. Error messages - Simplified user-facing messages
## Next Steps
1. Manual testing recommended:
- Test login flow with actual IndieAuth profile
- Verify endpoint discovery logs appear
- Test with profiles that have custom endpoints
- Verify error message appears for profiles without endpoints
2. Deployment:
- Update production .env to remove INDIELOGIN_URL (optional - will show warning)
- Deploy changes
- Monitor logs for "Discovered authorization_endpoint" messages
- Verify login works for admin user
3. Documentation:
- Update CHANGELOG.md with hotfix entry
- Consider adding migration guide if needed
## Verification Checklist
- [x] All specified files modified
- [x] All code changes follow architect's design exactly
- [x] Tests updated and passing
- [x] Error messages user-friendly
- [x] Logging appropriate for debugging
- [x] URL normalization implemented
- [x] Endpoint validation relaxed correctly
- [x] No regressions in existing tests
- [x] Implementation report created
## Conclusion
The hotfix has been successfully implemented according to the architect's design. The authentication flow now correctly implements the W3C IndieAuth specification for endpoint discovery. All tests pass and no regressions were detected.
The critical production bug preventing user login should be resolved once this code is deployed.
---
**Developer:** Claude (Fullstack Developer Subagent)
**Date Completed:** 2025-12-17
**Ready for Review:** Yes

608
docs/design/hotfix/2025-12-17-indieauth-pkce-endpoint-discovery-hotfix.md Normal file
View File

@@ -0,0 +1,608 @@
# IndieAuth Endpoint Discovery Hotfix
**Date:** 2025-12-17
**Type:** Production Hotfix
**Priority:** Critical
**Status:** Ready for Implementation
## Problem Summary
Users cannot log in to StarPunk. The root cause is that the authentication code ignores endpoint discovery and hardcodes `INDIELOGIN_URL` instead of discovering the authorization and token endpoints from the user's profile URL.
**Root Cause:** The `starpunk/auth.py` module uses `INDIELOGIN_URL` config instead of discovering endpoints from the user's profile URL as required by the IndieAuth specification. This is a regression - the system used to respect discovered endpoints.
**Note:** The PKCE error message in the callback is a symptom, not the cause. Once we use the correct discovered endpoints, PKCE will not be required (since the user's actual IndieAuth server doesn't require it).
## Specification Requirements
### W3C IndieAuth Spec (https://www.w3.org/TR/indieauth/)
- Clients MUST discover `authorization_endpoint` from user's profile URL
- Clients MUST discover `token_endpoint` from user's profile URL
- Discovery via HTTP Link headers (highest priority) or HTML `<link>` elements
## Implementation Plan
### Overview
The fix reuses the existing `discover_endpoints()` function from `auth_external.py` in the login flow. Changes are minimal and focused:
1. Use `discover_endpoints()` in `initiate_login()` to get the `authorization_endpoint`
2. Use `discover_endpoints()` in `handle_callback()` to get the `token_endpoint`
3. Remove `INDIELOGIN_URL` config (with deprecation warning)
---
### Step 1: Update config.py - Remove INDIELOGIN_URL
In `/home/phil/Projects/starpunk/starpunk/config.py`:
**Change 1:** Remove the INDIELOGIN_URL config line (line 37):
```python
# DELETE THIS LINE:
app.config["INDIELOGIN_URL"] = os.getenv("INDIELOGIN_URL", "https://indielogin.com")
```
**Change 2:** Add deprecation warning for INDIELOGIN_URL (add after the TOKEN_ENDPOINT warning, around line 47):
```python
# DEPRECATED: INDIELOGIN_URL no longer used (hotfix 2025-12-17)
# Authorization endpoint is now discovered from ADMIN_ME profile per IndieAuth spec
if 'INDIELOGIN_URL' in os.environ:
app.logger.warning(
"INDIELOGIN_URL is deprecated and will be ignored. "
"Remove it from your configuration. "
"The authorization endpoint is now discovered automatically from your ADMIN_ME profile."
)
```
---
### Step 2: Update auth.py - Use Endpoint Discovery
In `/home/phil/Projects/starpunk/starpunk/auth.py`:
**Change 1:** Add import for endpoint discovery (after line 42):
```python
from starpunk.auth_external import discover_endpoints, DiscoveryError, normalize_url
```
> **Note:** The `normalize_url` import is at the top level (not inside `handle_callback()`) for consistency with the existing code style.
**Change 2:** Update `initiate_login()` to use discovered authorization_endpoint (replace lines 251-318):
```python
def initiate_login(me_url: str) -> str:
"""
Initiate IndieAuth authentication flow with endpoint discovery.
Per W3C IndieAuth spec, discovers authorization_endpoint from user's
profile URL rather than using a hardcoded service.
Args:
me_url: User's IndieWeb identity URL
Returns:
Redirect URL to discovered authorization endpoint
Raises:
ValueError: Invalid me_url format
DiscoveryError: Failed to discover endpoints from profile
"""
# Validate URL format
if not is_valid_url(me_url):
raise ValueError(f"Invalid URL format: {me_url}")
current_app.logger.debug(f"Auth: Validating me URL: {me_url}")
# Discover authorization endpoint from user's profile URL
# Per IndieAuth spec: clients MUST discover endpoints, not hardcode them
try:
endpoints = discover_endpoints(me_url)
except DiscoveryError as e:
current_app.logger.error(f"Auth: Endpoint discovery failed for {me_url}: {e}")
raise
auth_endpoint = endpoints.get('authorization_endpoint')
if not auth_endpoint:
raise DiscoveryError(
f"No authorization_endpoint found at {me_url}. "
"Ensure your profile has IndieAuth link elements or headers."
)
current_app.logger.info(f"Auth: Discovered authorization_endpoint: {auth_endpoint}")
# Generate CSRF state token
state = _generate_state_token()
current_app.logger.debug(f"Auth: Generated state token: {_redact_token(state, 8)}")
# Store state in database (5-minute expiry)
db = get_db(current_app)
expires_at = datetime.utcnow() + timedelta(minutes=5)
redirect_uri = f"{current_app.config['SITE_URL']}auth/callback"
db.execute(
"""
INSERT INTO auth_state (state, expires_at, redirect_uri)
VALUES (?, ?, ?)
""",
(state, expires_at, redirect_uri),
)
db.commit()
# Build authorization URL
params = {
"me": me_url,
"client_id": current_app.config["SITE_URL"],
"redirect_uri": redirect_uri,
"state": state,
"response_type": "code",
}
current_app.logger.debug(
f"Auth: Building authorization URL with params:\n"
f" me: {me_url}\n"
f" client_id: {current_app.config['SITE_URL']}\n"
f" redirect_uri: {redirect_uri}\n"
f" state: {_redact_token(state, 8)}\n"
f" response_type: code"
)
auth_url = f"{auth_endpoint}?{urlencode(params)}"
current_app.logger.debug(f"Auth: Complete authorization URL: {auth_url}")
current_app.logger.info(f"Auth: Authentication initiated for {me_url}")
return auth_url
```
**Change 3:** Update `handle_callback()` to use discovered authorization_endpoint (replace lines 321-474):
> **Important:** Per IndieAuth spec, authentication-only flows (identity verification without access tokens) POST to the **authorization_endpoint**, NOT the token_endpoint. The `grant_type` parameter is NOT included for authentication-only flows.
```python
def handle_callback(code: str, state: str, iss: Optional[str] = None) -> Optional[str]:
"""
Handle IndieAuth callback with endpoint discovery.
Discovers authorization_endpoint from ADMIN_ME profile and exchanges
authorization code for identity verification.
Per IndieAuth spec: Authentication-only flows POST to the authorization
endpoint (not token endpoint) and do not include grant_type.
Args:
code: Authorization code from authorization server
state: CSRF state token
iss: Issuer identifier (optional, for security validation)
Returns:
Session token if successful, None otherwise
Raises:
InvalidStateError: State token validation failed
UnauthorizedError: User not authorized as admin
IndieLoginError: Code exchange failed
"""
current_app.logger.debug(f"Auth: Verifying state token: {_redact_token(state, 8)}")
# Verify state token (CSRF protection)
if not _verify_state_token(state):
current_app.logger.warning(
"Auth: Invalid state token received (possible CSRF or expired token)"
)
raise InvalidStateError("Invalid or expired state token")
current_app.logger.debug("Auth: State token valid")
# Discover authorization endpoint from ADMIN_ME profile
admin_me = current_app.config.get("ADMIN_ME")
if not admin_me:
current_app.logger.error("Auth: ADMIN_ME not configured")
raise IndieLoginError("ADMIN_ME not configured")
try:
endpoints = discover_endpoints(admin_me)
except DiscoveryError as e:
current_app.logger.error(f"Auth: Endpoint discovery failed: {e}")
raise IndieLoginError(f"Failed to discover endpoints: {e}")
# Use authorization_endpoint for authentication-only flow (identity verification)
# Per IndieAuth spec: auth-only flows POST to authorization_endpoint, not token_endpoint
auth_endpoint = endpoints.get('authorization_endpoint')
if not auth_endpoint:
raise IndieLoginError(
f"No authorization_endpoint found at {admin_me}. "
"Ensure your profile has IndieAuth endpoints configured."
)
current_app.logger.debug(f"Auth: Using authorization_endpoint: {auth_endpoint}")
# Verify issuer if provided (security check - optional)
if iss:
current_app.logger.debug(f"Auth: Issuer provided: {iss}")
# Prepare code verification request
# Note: grant_type is NOT included for authentication-only flows per IndieAuth spec
token_exchange_data = {
"code": code,
"client_id": current_app.config["SITE_URL"],
"redirect_uri": f"{current_app.config['SITE_URL']}auth/callback",
}
# Log the request
_log_http_request(
method="POST",
url=auth_endpoint,
data=token_exchange_data,
)
current_app.logger.debug(
"Auth: Sending code verification request to authorization endpoint:\n"
" Method: POST\n"
" URL: %s\n"
" Data: code=%s, client_id=%s, redirect_uri=%s",
auth_endpoint,
_redact_token(code),
token_exchange_data["client_id"],
token_exchange_data["redirect_uri"],
)
# Exchange code for identity at authorization endpoint (authentication-only flow)
try:
response = httpx.post(
auth_endpoint,
data=token_exchange_data,
timeout=10.0,
)
current_app.logger.debug(
"Auth: Received code verification response:\n"
" Status: %d\n"
" Headers: %s\n"
" Body: %s",
response.status_code,
{k: v for k, v in dict(response.headers).items()
if k.lower() not in ["set-cookie", "authorization"]},
_redact_token(response.text) if response.text else "(empty)",
)
_log_http_response(
status_code=response.status_code,
headers=dict(response.headers),
body=response.text,
)
response.raise_for_status()
except httpx.RequestError as e:
current_app.logger.error(f"Auth: Authorization endpoint request failed: {e}")
raise IndieLoginError(f"Failed to verify code: {e}")
except httpx.HTTPStatusError as e:
current_app.logger.error(
f"Auth: Authorization endpoint returned error: {e.response.status_code} - {e.response.text}"
)
raise IndieLoginError(
f"Authorization endpoint returned error: {e.response.status_code}"
)
# Parse response
try:
data = response.json()
except Exception as e:
current_app.logger.error(f"Auth: Failed to parse authorization endpoint response: {e}")
raise IndieLoginError("Invalid JSON response from authorization endpoint")
me = data.get("me")
if not me:
current_app.logger.error("Auth: No identity returned from authorization endpoint")
raise IndieLoginError("No identity returned from authorization endpoint")
current_app.logger.debug(f"Auth: Received identity: {me}")
# Verify this is the admin user
current_app.logger.info(f"Auth: Verifying admin authorization for me={me}")
# Normalize URLs for comparison (handles trailing slashes and case differences)
# This is correct per IndieAuth spec - the returned 'me' is the canonical form
if normalize_url(me) != normalize_url(admin_me):
current_app.logger.warning(
f"Auth: Unauthorized login attempt: {me} (expected {admin_me})"
)
raise UnauthorizedError(f"User {me} is not authorized")
current_app.logger.debug("Auth: Admin verification passed")
# Create session
session_token = create_session(me)
# Trigger author profile discovery (v1.2.0 Phase 2)
# Per Q14: Never block login, always allow fallback
try:
from starpunk.author_discovery import get_author_profile
author_profile = get_author_profile(me, refresh=True)
current_app.logger.info(f"Author profile refreshed for {me}")
except Exception as e:
current_app.logger.warning(f"Author discovery failed: {e}")
# Continue login anyway - never block per Q14
return session_token
```
---
### Step 3: Update auth_external.py - Relax Endpoint Validation
The existing `_fetch_and_parse()` function requires `token_endpoint` to be present. We need to relax this since some profiles may only have `authorization_endpoint` (for authentication-only flows).
In `/home/phil/Projects/starpunk/starpunk/auth_external.py`, update the validation in `_fetch_and_parse()` (around lines 302-307):
**Change:** Make token_endpoint not strictly required (allow authentication-only profiles):
```python
# Validate we found at least one endpoint
# - authorization_endpoint: Required for authentication-only flows (admin login)
# - token_endpoint: Required for Micropub token verification
# Having at least one allows the appropriate flow to work
if 'token_endpoint' not in endpoints and 'authorization_endpoint' not in endpoints:
raise DiscoveryError(
f"No IndieAuth endpoints found at {profile_url}. "
"Ensure your profile has authorization_endpoint or token_endpoint configured."
)
```
---
### Step 4: Update routes/auth.py - Handle DiscoveryError
In `/home/phil/Projects/starpunk/starpunk/routes/auth.py`:
**Change 1:** Add import for DiscoveryError (update lines 20-29):
```python
from starpunk.auth import (
IndieLoginError,
InvalidStateError,
UnauthorizedError,
destroy_session,
handle_callback,
initiate_login,
require_auth,
verify_session,
)
from starpunk.auth_external import DiscoveryError
```
**Change 2:** Handle DiscoveryError in login_initiate() (update lines 79-85):
> **Note:** The user-facing error message is kept simple. Technical details are logged but not shown to users.
```python
try:
# Initiate IndieAuth flow
auth_url = initiate_login(me_url)
return redirect(auth_url)
except ValueError as e:
flash(str(e), "error")
return redirect(url_for("auth.login_form"))
except DiscoveryError as e:
current_app.logger.error(f"Endpoint discovery failed for {me_url}: {e}")
flash("Unable to verify your profile URL. Please check that it's correct and try again.", "error")
return redirect(url_for("auth.login_form"))
```
---
## File Summary
| File | Change Type | Description |
|------|-------------|-------------|
| `starpunk/config.py` | Edit | Remove INDIELOGIN_URL, add deprecation warning |
| `starpunk/auth.py` | Edit | Use endpoint discovery instead of hardcoded URL |
| `starpunk/auth_external.py` | Edit | Relax endpoint validation (allow auth-only flow) |
| `starpunk/routes/auth.py` | Edit | Handle DiscoveryError exception |
---
## Testing Requirements
### Manual Testing
1. **Login Flow Test**
- Navigate to `/auth/login`
- Enter ADMIN_ME URL
- Verify redirect goes to discovered authorization_endpoint (not hardcoded indielogin.com)
- Complete login and verify session is created
2. **Endpoint Discovery Test**
- Test with profile that declares custom endpoints
- Verify discovered endpoints are used, not defaults
### Existing Test Updates
**Update test fixture in `tests/test_auth.py`:**
Remove `INDIELOGIN_URL` from the app fixture (line 51):
```python
@pytest.fixture
def app(tmp_path):
"""Create Flask app for testing"""
from starpunk import create_app
test_data_dir = tmp_path / "data"
test_data_dir.mkdir(parents=True, exist_ok=True)
app = create_app(
{
"TESTING": True,
"SITE_URL": "http://localhost:5000/",
"ADMIN_ME": "https://example.com",
"SESSION_SECRET": secrets.token_hex(32),
"SESSION_LIFETIME": 30,
# REMOVED: "INDIELOGIN_URL": "https://indielogin.com",
"DATA_PATH": test_data_dir,
"NOTES_PATH": test_data_dir / "notes",
"DATABASE_PATH": test_data_dir / "starpunk.db",
}
)
return app
```
**Update existing tests that use `httpx.post` mock:**
Tests in `TestInitiateLogin` and `TestHandleCallback` need to mock `discover_endpoints()` in addition to `httpx.post`. Example pattern:
```python
@patch("starpunk.auth.discover_endpoints")
@patch("starpunk.auth.httpx.post")
def test_handle_callback_success(self, mock_post, mock_discover, app, db, client):
"""Test successful callback handling"""
# Mock endpoint discovery
mock_discover.return_value = {
'authorization_endpoint': 'https://auth.example.com/authorize',
'token_endpoint': 'https://auth.example.com/token'
}
# Rest of test remains the same...
```
**Update `TestInitiateLogin.test_initiate_login_success`:**
The assertion checking for `indielogin.com` needs to change to check for the mocked endpoint:
```python
@patch("starpunk.auth.discover_endpoints")
def test_initiate_login_success(self, mock_discover, app, db):
"""Test successful login initiation"""
mock_discover.return_value = {
'authorization_endpoint': 'https://auth.example.com/authorize',
'token_endpoint': 'https://auth.example.com/token'
}
with app.app_context():
me_url = "https://example.com"
auth_url = initiate_login(me_url)
# Changed: Check for discovered endpoint instead of indielogin.com
assert "auth.example.com/authorize" in auth_url
assert "me=https%3A%2F%2Fexample.com" in auth_url
# ... rest of assertions
```
### New Automated Tests to Add
```python
# tests/test_auth_endpoint_discovery.py
def test_initiate_login_uses_endpoint_discovery(client, mocker):
"""Verify login uses discovered endpoint, not hardcoded"""
mock_discover = mocker.patch('starpunk.auth.discover_endpoints')
mock_discover.return_value = {
'authorization_endpoint': 'https://custom-auth.example.com/authorize',
'token_endpoint': 'https://custom-auth.example.com/token'
}
response = client.post('/auth/login', data={'me': 'https://example.com'})
assert response.status_code == 302
assert 'custom-auth.example.com' in response.headers['Location']
def test_callback_uses_discovered_authorization_endpoint(client, mocker):
"""Verify callback uses discovered authorization endpoint (not token endpoint)"""
mock_discover = mocker.patch('starpunk.auth.discover_endpoints')
mock_discover.return_value = {
'authorization_endpoint': 'https://custom-auth.example.com/authorize',
'token_endpoint': 'https://custom-auth.example.com/token'
}
mock_post = mocker.patch('starpunk.auth.httpx.post')
# Setup state token and mock httpx response
# Verify code exchange POSTs to authorization_endpoint, not token_endpoint
pass
def test_discovery_error_shows_user_friendly_message(client, mocker):
"""Verify discovery failures show helpful error"""
mock_discover = mocker.patch('starpunk.auth.discover_endpoints')
mock_discover.side_effect = DiscoveryError("No endpoints found")
response = client.post('/auth/login', data={'me': 'https://example.com'})
assert response.status_code == 302
# Should redirect back to login form with flash message
def test_url_normalization_handles_trailing_slash(app, mocker):
"""Verify URL normalization allows trailing slash differences"""
# ADMIN_ME without trailing slash, auth server returns with trailing slash
# Should still authenticate successfully
pass
def test_url_normalization_handles_case_differences(app, mocker):
"""Verify URL normalization is case-insensitive"""
# ADMIN_ME: https://Example.com, auth server returns: https://example.com
# Should still authenticate successfully
pass
```
---
## Rollback Plan
If issues occur after deployment:
1. **Code:** Revert to previous commit
2. **Config:** Re-add INDIELOGIN_URL to .env if needed
---
## Post-Deployment Verification
1. Verify login works with the user's actual profile URL
2. Check logs for "Discovered authorization_endpoint" message
3. Test logout and re-login cycle
---
## Architect Q&A (2025-12-17)
Developer questions answered by the architect prior to implementation:
### Q1: Import Placement
**Q:** Should `normalize_url` import be inside the function or at top level?
**A:** Move to top level with other imports for consistency. The design has been updated.
### Q2: URL Normalization Behavior Change
**Q:** Is the URL normalization change intentional?
**A:** Yes, this is an intentional bugfix. The current exact-match behavior is incorrect per IndieAuth spec. URLs differing only in trailing slashes or case should be considered equivalent for identity purposes. The `normalize_url()` function already exists in `auth_external.py` and is used by `verify_external_token()`.
### Q3: Which Endpoint for Authentication Flow?
**Q:** Should we use token_endpoint or authorization_endpoint?
**A:** Use **authorization_endpoint** for authentication-only flows. Per IndieAuth spec: "the client makes a POST request to the authorization endpoint to verify the authorization code and retrieve the final user profile URL." The design has been corrected.
### Q4: Endpoint Validation Relaxation
**Q:** Is relaxed endpoint validation acceptable?
**A:** Yes. Login requires `authorization_endpoint`, Micropub requires `token_endpoint`. Requiring at least one is correct. If only auth endpoint exists, login works but Micropub fails gracefully (401).
### Q5: Test Update Strategy
**Q:** Remove INDIELOGIN_URL and/or mock discover_endpoints()?
**A:** Both. Remove `INDIELOGIN_URL` from fixtures, add `discover_endpoints()` mocking to existing tests. Detailed guidance added to Testing Requirements section.
### Q6: grant_type Parameter
**Q:** Should we include grant_type in the code exchange?
**A:** No. Authentication-only flows do not include `grant_type`. This parameter is only required when POSTing to the token_endpoint for access tokens. The design has been corrected.
### Q7: Error Message Verbosity
**Q:** Should we simplify the user-facing error message?
**A:** Yes. User-facing message should be simple: "Unable to verify your profile URL. Please check that it's correct and try again." Technical details are logged at ERROR level. The design has been updated.
---
## References
- W3C IndieAuth Specification: https://www.w3.org/TR/indieauth/
- IndieAuth Endpoint Discovery: https://www.w3.org/TR/indieauth/#discovery-by-clients

387
docs/design/v1.5.0/2025-12-17-indieauth-discovery-fix.md Normal file
View File

@@ -0,0 +1,387 @@
# IndieAuth Endpoint Discovery Regression Analysis
**Date**: 2025-12-17
**Author**: Agent-Architect
**Status**: Analysis Complete - Design Proposed
**Version**: v1.5.0 (or v1.6.0 depending on scope decision)
## Executive Summary
StarPunk has a **critical authentication bug** where admin login always redirects to `indielogin.com` instead of the user's declared IndieAuth endpoints. This violates the W3C IndieAuth specification and prevents users with self-hosted IndieAuth servers from logging in.
**Root Cause**: The `initiate_login()` function in `starpunk/auth.py` hardcodes `INDIELOGIN_URL` for authorization, bypassing endpoint discovery entirely. While `auth_external.py` correctly implements endpoint discovery for Micropub token verification, the admin login flow was never updated to use it.
**Impact**: Users whose site declares their own authorization endpoint (e.g., `https://gondulf.thesatelliteoflove.com/authorize`) cannot log in because StarPunk sends them to `https://indielogin.com/authorize` instead. The error message `code_challenge is required (PKCE)` occurs because indielogin.com requires PKCE but the user's server may not.
---
## 1. Git History Investigation
### Timeline of Changes
| Commit | Date | Description | Relevant? |
|--------|------|-------------|-----------|
| `d4f1bfb` | Early Nov 2025 | Initial auth module with IndieLogin support | **Origin of bug** |
| `a3bac86` | 2025-11-24 | Complete IndieAuth server removal (Phases 2-4) | Added `auth_external.py` |
| `80bd51e` | 2025-11-24 | Implement IndieAuth endpoint discovery (v1.0.0-rc.5) | Fixed discovery for **tokens only** |
### Key Finding
The endpoint discovery implemented in commit `80bd51e` (ADR-044) only applies to **Micropub token verification** via `auth_external.py`. The **admin login flow** in `auth.py` was never updated to discover endpoints.
### Code Locations
**Problem Location** - `starpunk/auth.py` lines 306-307:
```python
# CORRECT ENDPOINT: /authorize (not /auth)
auth_url = f"{current_app.config['INDIELOGIN_URL']}/authorize?{urlencode(params)}"
```
**Working Implementation** - `starpunk/auth_external.py` lines 195-247:
The `discover_endpoints()` function correctly implements W3C IndieAuth discovery but is only used for token verification, not login.
### Why This Was Missed
1. **Two separate auth flows**: StarPunk has two distinct authentication contexts:
- **Admin Login**: Delegates to external authorization server (currently hardcoded to indielogin.com)
- **Micropub Token Verification**: Validates bearer tokens against user's token endpoint (correctly discovers endpoints)
2. **ADR-044 scope**: The endpoint discovery ADR focused on token verification for Micropub, not the admin login flow.
3. **Working configuration**: indielogin.com works for users who delegate to it, masking the bug for those use cases.
---
## 2. W3C IndieAuth Specification Requirements
Per the [W3C IndieAuth Specification](https://www.w3.org/TR/indieauth/) and the [IndieAuth Living Spec](https://indieauth.spec.indieweb.org/):
### 2.1 Discovery Process (Section 4.2)
Clients MUST:
1. **Fetch the user's profile URL** (the "me" URL they enter at login)
2. **Look for `indieauth-metadata` link relation first** (modern approach)
3. **Fall back to `authorization_endpoint` and `token_endpoint` link relations** (legacy)
4. **Use the DISCOVERED endpoints**, not hardcoded values
### 2.2 Discovery Priority
1. HTTP Link header with `rel="indieauth-metadata"` (preferred)
2. HTML `<link rel="indieauth-metadata">` element
3. Fall back: HTTP Link header with `rel="authorization_endpoint"`
4. Fall back: HTML `<link rel="authorization_endpoint">` element
### 2.3 Metadata Document
When `indieauth-metadata` is found, fetch the JSON document which contains:
```json
{
"issuer": "https://auth.example.com/",
"authorization_endpoint": "https://auth.example.com/authorize",
"token_endpoint": "https://auth.example.com/token",
"code_challenge_methods_supported": ["S256"]
}
```
### 2.4 Key Quote from Spec
> "Clients MUST start by making a GET or HEAD request to fetch the user's profile URL to discover the necessary values."
---
## 3. Design for v1.5.0/v1.6.0
### 3.1 Architecture Decision
**Recommendation**: Reuse the existing `discover_endpoints()` function from `auth_external.py` for the login flow.
This function already:
- Implements W3C-compliant discovery
- Handles HTTP Link headers and HTML link elements
- Resolves relative URLs
- Validates HTTPS in production
- Caches results (1-hour TTL)
- Has comprehensive test coverage (35 tests)
### 3.2 Proposed Changes
#### 3.2.1 Extend `auth_external.py`
Add support for `indieauth-metadata` discovery (currently missing):
```python
def discover_endpoints(profile_url: str) -> Dict[str, str]:
"""
Discover IndieAuth endpoints from a profile URL
Implements IndieAuth endpoint discovery per W3C spec:
https://www.w3.org/TR/indieauth/#discovery-by-clients
Discovery priority:
1. indieauth-metadata link (modern approach)
2. HTTP Link headers for individual endpoints (legacy)
3. HTML link elements (legacy)
"""
# Check cache first
cached_endpoints = _cache.get_endpoints()
if cached_endpoints:
return cached_endpoints
# Validate and fetch profile
_validate_profile_url(profile_url)
try:
endpoints = _fetch_and_parse(profile_url)
_cache.set_endpoints(endpoints)
return endpoints
except Exception as e:
# Graceful fallback to expired cache
cached = _cache.get_endpoints(ignore_expiry=True)
if cached:
return cached
raise DiscoveryError(f"Endpoint discovery failed: {e}")
```
**New function needed**:
```python
def _fetch_metadata(metadata_url: str) -> Dict[str, str]:
"""
Fetch IndieAuth metadata document and extract endpoints.
Args:
metadata_url: URL of the indieauth-metadata document
Returns:
Dict with authorization_endpoint and token_endpoint
"""
response = httpx.get(metadata_url, timeout=DISCOVERY_TIMEOUT)
response.raise_for_status()
metadata = response.json()
return {
'authorization_endpoint': metadata.get('authorization_endpoint'),
'token_endpoint': metadata.get('token_endpoint'),
'issuer': metadata.get('issuer'),
}
```
#### 3.2.2 Update `auth.py::initiate_login()`
Replace hardcoded INDIELOGIN_URL with discovered endpoint:
**Before**:
```python
def initiate_login(me_url: str) -> str:
# ... validation ...
params = {
"me": me_url,
"client_id": current_app.config["SITE_URL"],
"redirect_uri": redirect_uri,
"state": state,
"response_type": "code",
}
# HARDCODED - THE BUG
auth_url = f"{current_app.config['INDIELOGIN_URL']}/authorize?{urlencode(params)}"
return auth_url
```
**After**:
```python
from starpunk.auth_external import discover_endpoints, DiscoveryError
def initiate_login(me_url: str) -> str:
# ... validation ...
# Discover endpoints from user's profile URL
try:
endpoints = discover_endpoints(me_url)
except DiscoveryError as e:
current_app.logger.error(f"Endpoint discovery failed for {me_url}: {e}")
raise ValueError(f"Could not discover IndieAuth endpoints for {me_url}")
authorization_endpoint = endpoints.get('authorization_endpoint')
if not authorization_endpoint:
raise ValueError(f"No authorization endpoint found at {me_url}")
params = {
"me": me_url,
"client_id": current_app.config["SITE_URL"],
"redirect_uri": redirect_uri,
"state": state,
"response_type": "code",
}
# Use discovered endpoint
auth_url = f"{authorization_endpoint}?{urlencode(params)}"
return auth_url
```
#### 3.2.3 Update `auth.py::handle_callback()`
The callback handler also references INDIELOGIN_URL for:
1. Issuer validation (line 350)
2. Token exchange (line 371)
These need to use the discovered endpoints instead. Store discovered endpoints in the auth_state table:
**Schema change** - Add column to auth_state:
```sql
ALTER TABLE auth_state ADD COLUMN discovered_endpoints TEXT;
```
Or use session storage (simpler, no migration needed):
```python
session['discovered_endpoints'] = endpoints
```
#### 3.2.4 Configuration Changes
- **Deprecate**: `INDIELOGIN_URL` configuration variable
- **Keep as fallback**: If discovery fails and user has configured INDIELOGIN_URL, use it as a last resort
- **Add deprecation warning**: Log warning if INDIELOGIN_URL is set
### 3.3 Edge Cases
| Scenario | Behavior |
|----------|----------|
| No endpoints found | Raise clear error, log details |
| Only authorization_endpoint found | Use it (token_endpoint not needed for login-only flow) |
| Discovery timeout | Use cached endpoints if available, else fail |
| Invalid endpoints (HTTP in production) | Reject with security error |
| Relative URLs | Resolve against profile URL |
| Redirected profile URL | Follow redirects, use final URL for resolution |
### 3.4 Backward Compatibility
Users who currently rely on indielogin.com via `INDIELOGIN_URL`:
- Their profiles likely don't declare endpoints (they delegate to indielogin.com)
- Discovery will fail, then fall back to INDIELOGIN_URL if configured
- Log deprecation warning recommending they add endpoint declarations to their profile
### 3.5 PKCE Considerations
The error message mentions PKCE (`code_challenge is required`). Current flow:
- StarPunk does NOT send PKCE parameters in `initiate_login()`
- indielogin.com requires PKCE
- User's server (gondulf) may or may not require PKCE
**Design Decision**: Add optional PKCE support based on metadata discovery:
1. If `indieauth-metadata` is found, check `code_challenge_methods_supported`
2. If S256 is supported, include PKCE parameters
3. If not discoverable, default to sending PKCE (most servers support it)
---
## 4. File Changes Summary
| File | Change Type | Description |
|------|-------------|-------------|
| `starpunk/auth_external.py` | Modify | Add `indieauth-metadata` discovery support |
| `starpunk/auth.py` | Modify | Use discovered endpoints instead of INDIELOGIN_URL |
| `starpunk/config.py` | Modify | Deprecate INDIELOGIN_URL with warning |
| `tests/test_auth.py` | Modify | Update tests for endpoint discovery |
| `tests/test_auth_external.py` | Modify | Add metadata discovery tests |
| `.env.example` | Modify | Update INDIELOGIN_URL documentation |
---
## 5. Testing Strategy
### 5.1 Unit Tests
```python
class TestEndpointDiscoveryForLogin:
"""Test endpoint discovery in login flow"""
def test_discover_from_link_header(self):
"""Authorization endpoint discovered from Link header"""
def test_discover_from_html_link(self):
"""Authorization endpoint discovered from HTML link element"""
def test_discover_from_metadata(self):
"""Endpoints discovered from indieauth-metadata document"""
def test_metadata_priority_over_link(self):
"""Metadata takes priority over individual link relations"""
def test_discovery_failure_clear_error(self):
"""Clear error message when no endpoints found"""
def test_fallback_to_indielogin_url(self):
"""Falls back to INDIELOGIN_URL if configured and discovery fails"""
def test_deprecation_warning_for_indielogin_url(self):
"""Logs deprecation warning when INDIELOGIN_URL used"""
```
### 5.2 Integration Tests
```python
class TestLoginWithDiscovery:
"""End-to-end login flow with endpoint discovery"""
def test_login_to_self_hosted_indieauth(self):
"""Login works with user's declared authorization endpoint"""
def test_login_callback_uses_discovered_token_endpoint(self):
"""Callback exchanges code at discovered endpoint"""
```
---
## 6. Open Questions for User
1. **Version Scope**: Should this fix be part of v1.5.0 (quality-focused release) or v1.6.0 (new feature)?
- **Argument for v1.5.0**: This is a critical bug preventing login
- **Argument for v1.6.0**: Significant changes to authentication flow
2. **PKCE Implementation**: Should we add full PKCE support as part of this fix?
- Current: No PKCE in login flow
- indielogin.com requires PKCE
- Many IndieAuth servers support PKCE
- W3C spec recommends PKCE
3. **Migration Path**: How should existing deployments handle this change?
- Remove INDIELOGIN_URL from config?
- Add endpoint declarations to their profile?
- Both (with fallback period)?
---
## 7. Recommended Implementation Order
1. **Phase A**: Extend `discover_endpoints()` to support `indieauth-metadata`
2. **Phase B**: Update `initiate_login()` to use discovered authorization_endpoint
3. **Phase C**: Update `handle_callback()` to use discovered token_endpoint
4. **Phase D**: Add PKCE support (if approved)
5. **Phase E**: Deprecate INDIELOGIN_URL configuration
6. **Phase F**: Update documentation and migration guide
---
## 8. References
- [W3C IndieAuth Specification](https://www.w3.org/TR/indieauth/)
- [IndieAuth Living Spec](https://indieauth.spec.indieweb.org/)
- ADR-044: Endpoint Discovery Implementation Details
- ADR-030: External Token Verification Architecture
- Commit `80bd51e`: Implement IndieAuth endpoint discovery (v1.0.0-rc.5)
---
## 9. Conclusion
The bug is a straightforward oversight: endpoint discovery was implemented for Micropub token verification but not for admin login. The fix involves:
1. Reusing the existing `discover_endpoints()` function
2. Adding `indieauth-metadata` support
3. Replacing hardcoded INDIELOGIN_URL references
4. Optionally adding PKCE support
**Estimated effort**: 8-12 hours including tests and documentation.
**Risk level**: Medium - changes to authentication flow require careful testing.