StarPunk/docs/decisions/ADR-023-indieauth-client-identification.md

ADR-023: 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:

<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
• Microformats h-app
• IndieWeb Client Information

Related ADRs

• ADR-003: Authentication Strategy (establishes IndieAuth as auth method)
• ADR-004: Frontend Architecture (defines template structure)