docs: add IndieAuth client identification analysis and decision
Architect analysis identified the root cause of 'client_id is not registered' error: h-app microformat is hidden from parsers. Includes: - Complete diagnosis of IndieAuth client registration issue - ADR-006: IndieAuth Client Identification decision record - Implementation guidelines for developer Developer task: Remove hidden attributes from h-app div. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
139
docs/architecture/indieauth-client-diagnosis.md
Normal file
139
docs/architecture/indieauth-client-diagnosis.md
Normal file
@@ -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
|
||||||
|
<!-- IndieAuth endpoints are correctly declared -->
|
||||||
|
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
|
||||||
|
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
|
||||||
|
|
||||||
|
<!-- h-card is properly structured -->
|
||||||
|
<div class="h-card">
|
||||||
|
<h1 class="p-name">Phil Skents</h1>
|
||||||
|
<p class="identity-url">
|
||||||
|
<a class="u-url u-uid" href="https://thesatelliteoflove.com">
|
||||||
|
https://thesatelliteoflove.com
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. StarPunk Client (https://starpunk.thesatelliteoflove.com) ❌
|
||||||
|
|
||||||
|
**Status:** MISCONFIGURED - Client identification is hidden
|
||||||
|
|
||||||
|
The h-app microformat exists but is **invisible** to parsers:
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- PROBLEM: hidden and aria-hidden attributes -->
|
||||||
|
<div class="h-app" hidden aria-hidden="true">
|
||||||
|
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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
|
||||||
|
<div class="h-app" hidden aria-hidden="true">
|
||||||
|
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fixed:
|
||||||
|
```html
|
||||||
|
<div class="h-app">
|
||||||
|
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
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
|
||||||
|
<footer>
|
||||||
|
<div class="h-app">
|
||||||
|
<p>
|
||||||
|
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
|
||||||
|
<span class="p-version">v0.6.1</span>
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
</footer>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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
|
||||||
|
<div class="h-app">
|
||||||
|
<img src="/static/logo.png" class="u-logo" alt="StarPunk logo">
|
||||||
|
<a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
|
||||||
|
<p class="p-summary">A minimal IndieWeb CMS</p>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
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)
|
||||||
101
docs/decisions/ADR-006-indieauth-client-identification.md
Normal file
101
docs/decisions/ADR-006-indieauth-client-identification.md
Normal file
@@ -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
|
||||||
|
<footer>
|
||||||
|
<div class="h-app">
|
||||||
|
<p>
|
||||||
|
Powered by <a href="https://starpunk.thesatelliteoflove.com" class="u-url p-name">StarPunk</a>
|
||||||
|
<span class="p-version">v0.6.1</span>
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
</footer>
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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)
|
||||||
Reference in New Issue
Block a user