StarPunk/docs/decisions/ADR-010-static-identity-page.md

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
• Microformats2 h-card
• IndieWeb Authentication
• indieauth.com