docs: add reference IndieAuth identity page implementation
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>
This commit is contained in:
155
docs/architecture/indieauth-identity-page.md
Normal file
155
docs/architecture/indieauth-identity-page.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# IndieAuth Identity Page Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
An IndieAuth identity page serves as the authoritative source for a user's online identity in the IndieWeb ecosystem. This document defines the minimal requirements and best practices for creating a static HTML page that functions as an IndieAuth identity URL.
|
||||
|
||||
## Purpose
|
||||
|
||||
The identity page serves three critical functions:
|
||||
|
||||
1. **Authentication Endpoint Discovery** - Provides rel links to IndieAuth endpoints
|
||||
2. **Identity Verification** - Contains h-card microformats with user information
|
||||
3. **Social Proof** - Optional rel="me" links for identity consolidation
|
||||
|
||||
## Technical Requirements
|
||||
|
||||
### 1. HTML Structure
|
||||
|
||||
```
|
||||
DOCTYPE html5
|
||||
├── head
|
||||
│ ├── meta charset="utf-8"
|
||||
│ ├── meta viewport (responsive)
|
||||
│ ├── title (user's name)
|
||||
│ ├── rel="authorization_endpoint"
|
||||
│ ├── rel="token_endpoint"
|
||||
│ └── optional: rel="micropub"
|
||||
└── body
|
||||
└── h-card
|
||||
├── p-name (full name)
|
||||
├── u-url (identity URL)
|
||||
├── u-photo (optional avatar)
|
||||
└── rel="me" links (optional)
|
||||
```
|
||||
|
||||
### 2. IndieAuth Discovery
|
||||
|
||||
The page MUST include these link elements in the `<head>`:
|
||||
|
||||
```html
|
||||
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
|
||||
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
|
||||
```
|
||||
|
||||
These endpoints:
|
||||
- **authorization_endpoint**: Handles the OAuth 2.0 authorization flow
|
||||
- **token_endpoint**: Issues access tokens for API access
|
||||
|
||||
### 3. Microformats2 h-card
|
||||
|
||||
The h-card provides machine-readable identity information:
|
||||
|
||||
```html
|
||||
<div class="h-card">
|
||||
<h1 class="p-name">User Name</h1>
|
||||
<a class="u-url" href="https://example.com" rel="me">https://example.com</a>
|
||||
</div>
|
||||
```
|
||||
|
||||
Required properties:
|
||||
- `p-name`: The person's full name
|
||||
- `u-url`: The canonical identity URL (must match the page URL)
|
||||
|
||||
Optional properties:
|
||||
- `u-photo`: Avatar image URL
|
||||
- `p-note`: Brief biography
|
||||
- `u-email`: Contact email (consider privacy implications)
|
||||
|
||||
### 4. rel="me" Links
|
||||
|
||||
For identity consolidation and social proof:
|
||||
|
||||
```html
|
||||
<a href="https://github.com/username" rel="me">GitHub</a>
|
||||
```
|
||||
|
||||
Best practices:
|
||||
- Only include links to profiles you control
|
||||
- Ensure reciprocal rel="me" links where possible
|
||||
- Use HTTPS URLs whenever available
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. HTTPS Requirement
|
||||
- Identity URLs MUST use HTTPS
|
||||
- All linked endpoints MUST use HTTPS
|
||||
- Mixed content will break authentication flows
|
||||
|
||||
### 2. Content Security
|
||||
- No inline JavaScript required or recommended
|
||||
- Minimal inline CSS only if necessary
|
||||
- No external dependencies for core functionality
|
||||
|
||||
### 3. Privacy
|
||||
- Consider what information to make public
|
||||
- Email addresses can attract spam
|
||||
- Phone numbers should generally be avoided
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### 1. IndieAuth Validation
|
||||
- Test with https://indielogin.com/
|
||||
- Verify endpoint discovery works
|
||||
- Complete a full authentication flow
|
||||
|
||||
### 2. Microformats Validation
|
||||
- Use https://indiewebify.me/
|
||||
- Verify h-card is properly parsed
|
||||
- Check all properties are detected
|
||||
|
||||
### 3. HTML Validation
|
||||
- Validate with W3C validator
|
||||
- Ensure semantic HTML5 compliance
|
||||
- Check accessibility basics
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### 1. Missing or Wrong URLs
|
||||
- Identity URL must be absolute and match the actual page URL
|
||||
- Endpoints must be absolute URLs
|
||||
- rel="me" links must be to HTTPS when available
|
||||
|
||||
### 2. Incorrect Microformats
|
||||
- Missing required h-card properties
|
||||
- Using old hCard format instead of h-card
|
||||
- Nesting errors in microformat classes
|
||||
|
||||
### 3. Authentication Failures
|
||||
- Using HTTP instead of HTTPS
|
||||
- Incorrect or missing endpoint declarations
|
||||
- Not including trailing slashes consistently
|
||||
|
||||
## Minimal Implementation Checklist
|
||||
|
||||
- [ ] HTML5 DOCTYPE declaration
|
||||
- [ ] UTF-8 character encoding
|
||||
- [ ] Viewport meta tag for mobile
|
||||
- [ ] Authorization endpoint link
|
||||
- [ ] Token endpoint link
|
||||
- [ ] h-card with p-name
|
||||
- [ ] h-card with u-url matching page URL
|
||||
- [ ] All URLs use HTTPS
|
||||
- [ ] No broken links or empty hrefs
|
||||
- [ ] Valid HTML5 structure
|
||||
|
||||
## Reference Implementations
|
||||
|
||||
See `/docs/examples/identity-page.html` for a complete, working example that can be customized for any IndieAuth user.
|
||||
|
||||
## Standards References
|
||||
|
||||
- [IndieAuth Specification](https://indieauth.spec.indieweb.org/)
|
||||
- [Microformats2 h-card](http://microformats.org/wiki/h-card)
|
||||
- [rel="me" specification](https://microformats.org/wiki/rel-me)
|
||||
- [IndieWeb Authentication](https://indieweb.org/authentication)
|
||||
Reference in New Issue
Block a user