diff --git a/CHANGELOG.md b/CHANGELOG.md index 5cae15f..06cc00c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [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 diff --git a/docs/decisions/ADR-016-indieauth-client-discovery.md b/docs/decisions/ADR-016-indieauth-client-discovery.md new file mode 100644 index 0000000..8094ada --- /dev/null +++ b/docs/decisions/ADR-016-indieauth-client-discovery.md @@ -0,0 +1,308 @@ +# ADR-016: IndieAuth Client Discovery Mechanism + +## Status + +Accepted + +## Context + +StarPunk uses IndieLogin.com as a delegated IndieAuth provider for admin authentication. During the first production deployment to https://starpunk.thesatelliteoflove.com, authentication failed with the error: + +``` +Request Error +There was a problem with the parameters of this request. + +This client_id is not registered (https://starpunk.thesatelliteoflove.com) +``` + +### Root Cause + +The IndieAuth specification requires authorization servers to verify client applications by fetching the `client_id` URL and discovering client metadata. StarPunk's implementation was missing this client discovery mechanism entirely. + +### Why This Was Missed + +1. Phase 3 authentication design focused on the authentication flow but didn't address client identification +2. Testing used DEV_MODE which bypasses IndieAuth entirely +3. The IndieAuth spec has evolved over time (2020 → 2022 → current) with different discovery mechanisms +4. Client discovery is a prerequisite that wasn't explicitly called out in our design + +### IndieAuth Client Discovery Standards + +The IndieAuth specification (as of 2025) supports three discovery mechanisms: + +#### 1. OAuth Client ID Metadata Document (Current - 2022+) + +A JSON document at `/.well-known/oauth-authorization-server` or linked via `rel="indieauth-metadata"`: + +```json +{ + "issuer": "https://example.com", + "client_id": "https://example.com", + "client_name": "App Name", + "client_uri": "https://example.com", + "redirect_uris": ["https://example.com/callback"] +} +``` + +**Pros**: Current standard, machine-readable, clean separation +**Cons**: Newer standard, may not be supported by older servers + +#### 2. h-app Microformats (Legacy - Pre-2022) + +HTML microformats markup in the page: + +```html +
+ App Name +
+``` + +**Pros**: Widely supported, backward compatible, simple +**Cons**: Uses "legacy" standard, mixes presentation and metadata + +#### 3. Basic HTTP 200 (Minimal) + +Some servers accept any valid HTTP 200 response as sufficient client verification. + +**Pros**: Simplest possible +**Cons**: Provides no metadata, not standards-compliant + +## Decision + +**Implement h-app microformats in base.html template** + +We will add microformats2 h-app markup to the site footer for IndieAuth client discovery. + +## Rationale + +### Why h-app Microformats? + +1. **Simplicity**: 3 lines of HTML vs new route with JSON endpoint + - Aligns with project philosophy: "Every line of code must justify its existence" + - Minimal implementation complexity + +2. **Compatibility**: Works with all IndieAuth servers + - Supports legacy servers (IndieLogin.com likely runs older code) + - Backward compatible with 2020-era IndieAuth spec + - Forward compatible (current spec still supports h-app) + +3. **Pragmatic**: Addresses immediate production need + - V1 requirement is "working IndieAuth authentication" + - h-app provides necessary client verification + - Low risk, high confidence in success + +4. **Low Maintenance**: No new routes or endpoints + - Template-based, no server-side logic + - No additional testing surface + - Can't break existing functionality + +5. **Standards-Compliant**: Still part of IndieAuth spec + - Officially supported for backward compatibility + - Used by many IndieAuth clients and servers + - Well-documented and understood + +### Why Not OAuth Client ID Metadata Document? + +While this is the "current" standard, we rejected it for V1 because: + +1. **Complexity**: Requires new route, JSON serialization, additional tests +2. **Uncertainty**: Unknown if IndieLogin.com supports it (software may be older) +3. **Risk**: Higher chance of bugs in new endpoint +4. **V1 Scope**: Violates minimal viable product philosophy + +This could be added in V2 for modern IndieAuth server support. + +### Why Not Basic HTTP 200? + +This provides no client metadata and isn't standards-compliant. While some servers may accept it, it doesn't fulfill the spirit of client verification and could fail with stricter authorization servers. + +## Implementation + +### Location + +`templates/base.html` in the `