Phil Skentelbery
68669b9a6a
Add minimal, production-ready static HTML identity page as reference implementation for IndieAuth authentication. Includes: - Complete identity-page.html with h-card and IndieAuth endpoints - Architectural documentation and rationale - ADR-010: Static Identity Page decision record - Customization guide for users The example is zero-dependency, copy-paste ready, and guaranteed to work with IndieLogin.com and StarPunk. Pre-configured for thesatelliteoflove.com as working example. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
# 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/) |