# 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)