From 6a29b0199e58a925783de408ac43a26ad1499041 Mon Sep 17 00:00:00 2001 From: Phil Skentelbery Date: Wed, 19 Nov 2025 11:44:35 -0700 Subject: [PATCH] Fix IndieAuth client discovery for production authentication MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add h-app microformats markup to base.html to enable IndieLogin.com to verify StarPunk as a legitimate OAuth client. Without this markup, IndieLogin returns "client_id is not registered" error, blocking all production authentication. The h-app markup provides client identification per IndieAuth legacy standard, which is widely supported by authorization servers including IndieLogin.com. Changes: - Add h-app microformats div to base.html footer (hidden) - Update version to v0.6.1 (patch release per ADR-008) - Update CHANGELOG.md with v0.6.1 release notes - Add 6 comprehensive tests for h-app markup (all passing) - Create ADR-016 documenting client discovery decision - Create architecture analysis report - Create implementation report Tests: 456 total, 455 passing (99.78%) New tests: 6 for h-app microformats (100% passing) Fixes critical bug preventing production authentication. Related: Phase 3 Authentication implementation, ADR-016 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CHANGELOG.md | 23 + .../ADR-016-indieauth-client-discovery.md | 308 ++++++++ .../indieauth-client-discovery-analysis.md | 688 ++++++++++++++++++ ...uth-client-discovery-fix-implementation.md | 396 ++++++++++ starpunk/__init__.py | 4 +- templates/base.html | 5 + tests/test_templates.py | 43 ++ 7 files changed, 1465 insertions(+), 2 deletions(-) create mode 100644 docs/decisions/ADR-016-indieauth-client-discovery.md create mode 100644 docs/reports/indieauth-client-discovery-analysis.md create mode 100644 docs/reports/indieauth-client-discovery-fix-implementation.md 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 `