# ADR-010: Static HTML Identity Pages for IndieAuth

## Status
Accepted

## Context

Users need a way to establish their identity on the web for IndieAuth authentication. This identity page serves as the authoritative source for:
- Discovering authentication endpoints
- Providing identity information (h-card)
- Establishing social proof through rel="me" links

The challenge is creating something that:
- Works immediately without any server-side code
- Has zero dependencies
- Can be hosted anywhere (static hosting, GitHub Pages, etc.)
- Is simple enough for non-technical users to customize

## Decision

We will provide a single, self-contained HTML file that serves as a complete IndieAuth identity page with:

1. **No external dependencies** - Everything needed is in one file
2. **No JavaScript** - Pure HTML with optional inline CSS
3. **Public IndieAuth endpoints** - Use indieauth.com's free service
4. **Comprehensive documentation** - Comments explaining every section
5. **Minimal but complete** - Only what's required, nothing more

## Rationale

### Why Static HTML?

1. **Maximum Portability**: Can be hosted anywhere that serves HTML
2. **Zero Maintenance**: No updates, no dependencies, no security patches
3. **Instant Setup**: Upload one file and it works
4. **Educational**: Users can read and understand the entire implementation

### Why Use indieauth.com?

1. **Free and Reliable**: Public service maintained by Aaron Parecki
2. **No Registration**: Works for any domain immediately
3. **Standards Compliant**: Reference implementation of IndieAuth
4. **Privacy Focused**: Doesn't store user data

### Why Inline Documentation?

1. **Self-Teaching**: The file explains itself
2. **No External Docs**: Everything needed is in the file
3. **Copy-Paste Friendly**: Users can take what they need
4. **Reduces Errors**: Instructions are right next to the code

## Consequences

### Positive

1. **Lowest Possible Barrier**: Anyone who can edit HTML can use this
2. **Future Proof**: HTML5 won't break backward compatibility
3. **Perfect for Examples**: Ideal reference implementation
4. **No Lock-in**: Users own their identity completely
5. **Immediate Testing**: Can validate instantly with online tools

### Negative

1. **Limited Functionality**: Can't do dynamic content without JavaScript
2. **Manual Updates**: Users must edit HTML directly
3. **No Analytics**: Can't track usage without JavaScript
4. **Basic Styling**: Limited to inline CSS for single-file approach

### Mitigation

For users who need more functionality:
- Can progressively enhance with JavaScript
- Can move to server-side rendering later
- Can use as a template for dynamic generation
- Can extend with additional microformats

## Alternatives Considered

### 1. JavaScript-Based Solution

**Rejected because**:
- Adds complexity and dependencies
- Requires ongoing maintenance
- Can break with browser updates
- Not necessary for core functionality

### 2. Server-Side Generation

**Rejected because**:
- Requires server infrastructure
- Increases hosting complexity
- Not portable across platforms
- Overkill for static identity data

### 3. External Stylesheet

**Rejected because**:
- Creates a dependency
- Can break if CSS file is moved
- Increases HTTP requests
- Inline CSS is small enough to not matter

### 4. Using Multiple Files

**Rejected because**:
- Complicates deployment
- Increases chance of errors
- Makes sharing/copying harder
- Benefits don't outweigh complexity

## Implementation Notes

The reference implementation (`/docs/examples/identity-page.html`) includes:

1. **Complete HTML5 structure** with semantic markup
2. **All required IndieAuth elements** properly configured
3. **h-card microformat** with required and optional properties
4. **Inline CSS** for basic but pleasant styling
5. **Extensive comments** explaining each section
6. **Testing instructions** embedded in HTML comments
7. **Common pitfalls** documented inline

## Testing Strategy

Users should test their identity page with:

1. **https://indielogin.com/** - Full authentication flow
2. **https://indiewebify.me/** - h-card validation
3. **W3C Validator** - HTML5 compliance
4. **Real authentication** - Sign in to an IndieWeb service

## Security Considerations

1. **HTTPS Only**: Page must be served over HTTPS
2. **No Secrets**: Everything in the file is public
3. **No JavaScript**: Eliminates XSS vulnerabilities
4. **No External Resources**: No CSRF or resource injection risks

## References

- [IndieAuth Specification](https://indieauth.spec.indieweb.org/)
- [Microformats2 h-card](http://microformats.org/wiki/h-card)
- [IndieWeb Authentication](https://indieweb.org/authentication)
- [indieauth.com](https://indieauth.com/)