diff --git a/docs/architecture/indieauth-client-diagnosis.md b/docs/architecture/indieauth-client-diagnosis.md new file mode 100644 index 0000000..995a507 --- /dev/null +++ b/docs/architecture/indieauth-client-diagnosis.md @@ -0,0 +1,139 @@ +# IndieAuth Client Registration Issue - Diagnosis Report + +**Date:** 2025-11-19 +**Issue:** IndieLogin.com reports "This client_id is not registered" +**Client ID:** https://starpunk.thesatelliteoflove.com + +## Executive Summary + +The issue is caused by the h-app microformat on StarPunk being **hidden** with both `hidden` and `aria-hidden="true"` attributes. This makes the client identification invisible to IndieAuth parsers. + +## Analysis Results + +### 1. Identity Domain (https://thesatelliteoflove.com) ✅ + +**Status:** PROPERLY CONFIGURED + +The identity page has all required IndieAuth elements: + +```html + + + + + +
+

Phil Skents

+

+ + https://thesatelliteoflove.com + +

+
+``` + +### 2. StarPunk Client (https://starpunk.thesatelliteoflove.com) ❌ + +**Status:** MISCONFIGURED - Client identification is hidden + +The h-app microformat exists but is **invisible** to parsers: + +```html + + +``` + +## Root Cause + +IndieAuth clients must be identifiable through visible h-app or h-x-app microformats. The `hidden` attribute makes the element completely invisible to: +1. Microformat parsers +2. Screen readers +3. Search engines +4. IndieAuth verification services + +When IndieLogin.com attempts to verify the client_id, it cannot find any client identification because the h-app is hidden from the DOM. + +## IndieAuth Client Verification Process + +1. User initiates auth with client_id=https://starpunk.thesatelliteoflove.com +2. IndieLogin fetches the client URL +3. IndieLogin parses for h-app/h-x-app microformats +4. **FAILS:** No visible h-app found due to `hidden` attribute +5. Returns error: "This client_id is not registered" + +## Solution + +Remove the `hidden` and `aria-hidden="true"` attributes from the h-app div: + +### Current (Broken): +```html + +``` + +### Fixed: +```html +
+ StarPunk +
+``` + +If visual hiding is desired, use CSS instead: + +```css +.h-app { + position: absolute; + left: -9999px; + width: 1px; + height: 1px; + overflow: hidden; +} +``` + +However, **best practice** is to keep it visible as client identification, possibly styled as: +```html + +``` + +## Verification Steps + +After fixing: + +1. Deploy the updated HTML without `hidden` attributes +2. Test at https://indiewebify.me/ - verify h-app is detected +3. Clear any caches (CloudFlare, browser, etc.) +4. Test authentication flow at https://indielogin.com/ + +## Additional Recommendations + +1. **Add more client metadata** for better identification: + ```html +
+ + StarPunk +

A minimal IndieWeb CMS

+
+ ``` + +2. **Consider adding redirect_uri registration** if using fixed callback URLs + +3. **Test with multiple IndieAuth parsers**: + - https://indiewebify.me/ + - https://sturdy-backbone.glitch.me/ + - https://microformats.io/ + +## References + +- [IndieAuth Spec - Client Information Discovery](https://indieauth.spec.indieweb.org/#client-information-discovery) +- [Microformats h-app](http://microformats.org/wiki/h-app) +- [IndieWeb Client ID](https://indieweb.org/client_id) \ No newline at end of file diff --git a/docs/decisions/ADR-006-indieauth-client-identification.md b/docs/decisions/ADR-006-indieauth-client-identification.md new file mode 100644 index 0000000..a606010 --- /dev/null +++ b/docs/decisions/ADR-006-indieauth-client-identification.md @@ -0,0 +1,101 @@ +# ADR-006: IndieAuth Client Identification Strategy + +## Status +Accepted + +## Context + +StarPunk needs to identify itself as an IndieAuth client when initiating authentication flows. The current implementation uses a hidden h-app microformat which causes IndieAuth services to reject the client_id with "This client_id is not registered" errors. + +IndieAuth specification requires clients to provide discoverable information about themselves using microformats. This allows authorization endpoints to: +- Display client information to users +- Verify the client is legitimate +- Show what application is requesting access + +## Decision + +StarPunk will use **visible h-app microformats** in the footer of all pages to identify itself as an IndieAuth client. + +The h-app will include: +- Application name (p-name) +- Application URL (u-url) +- Version number (p-version) +- Optional: logo (u-logo) +- Optional: description (p-summary) + +Implementation: +```html + +``` + +## Rationale + +1. **Specification Compliance**: IndieAuth spec requires client information to be discoverable via microformats parsing +2. **Transparency**: Users should see what software they're using +3. **Simplicity**: No JavaScript or complex rendering needed +4. **Debugging**: Visible markup is easier to verify and debug +5. **SEO Benefits**: Search engines can understand the application structure + +## Consequences + +### Positive +- IndieAuth flows will work correctly +- Client identification is transparent to users +- Easier to debug authentication issues +- Follows IndieWeb principles of visible metadata +- Can be styled to match site design + +### Negative +- Takes up visual space in the footer (minimal) +- Cannot be completely hidden from view +- Must be maintained on all pages that might be used as client_id + +## Alternatives Considered + +### 1. Hidden h-app with display:none +**Rejected**: Some microformat parsers ignore display:none elements + +### 2. Off-screen positioning +**Rejected**: Considered deceptive by some services, accessibility issues + +### 3. Separate client information endpoint +**Rejected**: Adds complexity, not standard practice + +### 4. HTTP headers +**Rejected**: Not part of IndieAuth specification, wouldn't work + +### 5. Meta tags +**Rejected**: IndieAuth uses microformats, not meta tags + +## Implementation Guidelines + +1. **Placement**: Always in the footer, consistent across all pages +2. **Styling**: Subtle but visible, matching site design +3. **Content**: Minimum of name and URL, optional logo and description +4. **Testing**: Verify with microformats parsers before deployment + +## Testing Checklist + +- [ ] h-app is visible in HTML source +- [ ] No hidden, display:none, or visibility:hidden attributes +- [ ] Validates at https://indiewebify.me/ +- [ ] Parses correctly at https://microformats.io/ +- [ ] IndieAuth flow works at https://indielogin.com/ + +## References + +- [IndieAuth Spec Section 4.2.2](https://indieauth.spec.indieweb.org/#client-information-discovery) +- [Microformats h-app](http://microformats.org/wiki/h-app) +- [IndieWeb Client Information](https://indieweb.org/client-id) + +## Related ADRs + +- ADR-003: Authentication Strategy (establishes IndieAuth as auth method) +- ADR-004: Frontend Architecture (defines template structure) \ No newline at end of file