phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add reference IndieAuth identity page implementation

Browse Source 
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:
Phil Skentelbery
2025-11-19 13:03:49 -07:00
parent 155cae8055
commit 68669b9a6a
5 changed files with 1153 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

334
docs/examples/identity-page-customization-guide.md Normal file
View File

@@ -0,0 +1,334 @@
# IndieAuth Identity Page Customization Guide
## Quick Start
The identity page template (`identity-page.html`) is a complete, working IndieAuth identity page. To use it:
1. Download `identity-page.html`
2. Edit the marked sections with your information
3. Upload to your domain root as `index.html`
4. Test at https://indielogin.com/
## What to Customize
### Required Changes
These MUST be changed for the page to work correctly:
#### 1. Your Name
```html
<!-- Change this -->
<title>Phil Skents</title>
<h1 class="p-name">Phil Skents</h1>
<!-- To this -->
<title>Your Name</title>
<h1 class="p-name">Your Name</h1>
```
#### 2. Your Domain
```html
<!-- Change this -->
<a class="u-url" href="https://thesatelliteoflove.com" rel="me">
https://thesatelliteoflove.com
</a>
<!-- To this (must match where you host this file) -->
<a class="u-url" href="https://yourdomain.com" rel="me">
https://yourdomain.com
</a>
```
### Optional Customizations
#### Add Your Photo
```html
<!-- Uncomment and modify this line -->
<img class="u-photo" src="/avatar.jpg" alt="Your Name">
```
Photo tips:
- Use a square image (1:1 ratio)
- 240x240 pixels minimum recommended
- JPEG or PNG format
- Under 100KB for fast loading
#### Add Your Bio
```html
<p class="p-note">
Your bio here. Keep it brief - 1-2 sentences.
</p>
```
#### Add Social Media Links
Uncomment and modify the social links section:
```html
<li>
<a href="https://github.com/yourusername" rel="me">
GitHub: @yourusername
</a>
</li>
```
**Important**: Only add profiles you control. Some services that support rel="me":
- GitHub (automatic)
- Mastodon (automatic)
- Personal websites
- Some IndieWeb services
#### Add Micropub Endpoint
If you have a Micropub server (like StarPunk):
```html
<link rel="micropub" href="https://yourmicropub.example.com/micropub">
```
## Advanced Customizations
### Custom Styling
The template includes minimal inline CSS. To customize:
1. **Colors**: Change the color values in the `<style>` section
```css
color: #333; /* Text color */
background: #fff; /* Background color */
color: #0066cc; /* Link color */
```
2. **Fonts**: Modify the font-family stack
```css
font-family: Georgia, serif; /* For a more classic look */
```
3. **Layout**: Adjust spacing and widths
```css
max-width: 800px; /* Wider content */
padding: 4rem; /* More padding */
```
### Multiple Profiles
For multiple online identities, add more h-cards:
```html
<div class="h-card">
<h2 class="p-name">Professional Name</h2>
<a class="u-url" href="https://professional.com" rel="me">
https://professional.com
</a>
</div>
<div class="h-card">
<h2 class="p-name">Personal Name</h2>
<a class="u-url" href="https://personal.com" rel="me">
https://personal.com
</a>
</div>
```
### Language Support
For non-English pages:
```html
<html lang="es"> <!-- Spanish -->
<meta charset="utf-8"> <!-- Supports all Unicode characters -->
```
### Accessibility Improvements
```html
<!-- Add language attributes -->
<html lang="en">
<!-- Add descriptive alt text -->
<img class="u-photo" src="/avatar.jpg" alt="Headshot of Your Name">
<!-- Add skip navigation -->
<a href="#main" class="skip-link">Skip to content</a>
```
## Testing Your Customizations
### 1. Local Testing
Open the file in your browser:
```
file:///path/to/identity-page.html
```
Check:
- [ ] Your name appears correctly
- [ ] Links work (won't authenticate locally)
- [ ] Page looks good on mobile (resize browser)
### 2. HTML Validation
Visit https://validator.w3.org/:
1. Choose "Validate by File Upload"
2. Upload your modified file
3. Fix any errors shown
### 3. Microformats Testing
Visit https://indiewebify.me/:
1. After uploading to your domain
2. Use "Validate h-card"
3. Enter your domain
4. Verify your information is detected
### 4. IndieAuth Testing
Visit https://indielogin.com/:
1. Enter your domain
2. Should see "IndieAuth.com" as option
3. Click to authenticate
4. Should complete successfully
## Common Mistakes to Avoid
### 1. URL Mismatches
❌ **Wrong**:
```html
<!-- Hosted at https://example.com but u-url says: -->
<a class="u-url" href="https://different.com">
```
✅ **Correct**:
```html
<!-- URLs must match exactly -->
<a class="u-url" href="https://example.com">
```
### 2. Missing HTTPS
❌ **Wrong**:
```html
<a class="u-url" href="http://example.com">
```
✅ **Correct**:
```html
<a class="u-url" href="https://example.com">
```
### 3. Broken Social Links
❌ **Wrong**:
```html
<!-- Empty href -->
<a href="" rel="me">GitHub</a>
<!-- Placeholder text -->
<a href="https://github.com/yourusername" rel="me">
```
✅ **Correct**:
```html
<!-- Real, working link -->
<a href="https://github.com/actualusername" rel="me">GitHub</a>
```
### 4. Multiple u-url Values
❌ **Wrong**:
```html
<a class="u-url" href="https://example.com">Example</a>
<a class="u-url" href="https://other.com">Other</a>
```
✅ **Correct**:
```html
<!-- Only one u-url that matches your domain -->
<a class="u-url" href="https://example.com">Example</a>
<a href="https://other.com">Other</a> <!-- No u-url class -->
```
## Deployment Options
### Static Hosting Services
The identity page works on any static host:
1. **GitHub Pages**
- Free with GitHub account
- Upload as `index.html` in repository
- Enable Pages in repository settings
2. **Netlify**
- Drag and drop deployment
- Free tier available
- Automatic HTTPS
3. **Vercel**
- Simple deployment
- Free tier available
- Good performance
4. **Traditional Web Hosting**
- Upload via FTP/SFTP
- Place in document root
- Ensure HTTPS is enabled
### File Naming
- `index.html` - For domain root (https://example.com/)
- `identity.html` - For subfolder (https://example.com/identity.html)
- Any name works, but update your StarPunk configuration accordingly
## Integration with StarPunk
Once your identity page is working:
1. **Configure StarPunk** to use your identity URL:
```
IDENTITY_URL=https://yourdomain.com
```
2. **Test Authentication**:
- Visit your StarPunk instance
- Click "Sign In"
- Enter your identity URL
- Should authenticate successfully
3. **Add Micropub Endpoint** (after StarPunk is running):
```html
<link rel="micropub" href="https://starpunk.yourdomain.com/micropub">
```
## Troubleshooting
### Page Not Found
- Ensure file is named correctly (usually `index.html`)
- Check file is in correct directory (document root)
- Verify domain is configured correctly
### Authentication Fails
- Verify HTTPS is working
- Check u-url matches actual URL exactly
- Ensure no typos in endpoint URLs
- Test with browser developer tools for errors
### h-card Not Detected
- Check class names are exact (`h-card`, `p-name`, `u-url`)
- Ensure HTML structure is valid
- Verify no typos in microformat classes
### Social Links Not Working
- Only include rel="me" on profiles you control
- Check URLs are correct and working
- Some services don't support rel="me" back-linking
## Getting Help
- **IndieWeb Chat**: https://indieweb.org/discuss
- **StarPunk Issues**: [GitHub repository]
- **IndieAuth Spec**: https://indieauth.spec.indieweb.org/
- **Microformats Wiki**: http://microformats.org/
Remember: The simplest solution is often the best. Don't add complexity unless you need it.

271
docs/examples/identity-page.html Normal file
View File

@@ -0,0 +1,271 @@
<!DOCTYPE html>
<html lang="en">
<head>
<!--
============================================================
IndieAuth Identity Page - Minimal Reference Implementation
============================================================
This is a complete, working IndieAuth identity page that requires:
- Zero JavaScript
- Zero external dependencies
- Only this single HTML file
To use this template:
1. Replace "Phil Skents" with your name
2. Replace "https://thesatelliteoflove.com" with your domain
3. Optionally add your social media profiles with rel="me"
4. Upload to your domain root (e.g., index.html)
5. Test at https://indielogin.com/
============================================================
-->
<!-- Required: Character encoding -->
<meta charset="utf-8">
<!-- Required: Responsive viewport -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- Page title: Your name -->
<title>Phil Skents</title>
<!--
============================================================
CRITICAL: IndieAuth Endpoint Discovery
These links tell IndieAuth clients where to authenticate.
Using indieauth.com as a public service that works for everyone.
============================================================
-->
<!-- Required: Authorization endpoint for IndieAuth -->
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<!-- Required: Token endpoint for obtaining access tokens -->
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
<!--
Optional: If you have a Micropub server (like StarPunk), add:
<link rel="micropub" href="https://starpunk.thesatelliteoflove.com/micropub">
-->
<!-- Optional: Minimal styling for readability -->
<style>
/* Reset and base styles */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
"Helvetica Neue", Arial, sans-serif;
line-height: 1.6;
color: #333;
background: #fff;
padding: 2rem;
max-width: 600px;
margin: 0 auto;
}
/* Typography */
h1 {
font-size: 2rem;
margin-bottom: 0.5rem;
color: #000;
}
p {
margin: 1rem 0;
}
a {
color: #0066cc;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
/* Layout */
.h-card {
margin: 2rem 0;
}
.identity-url {
font-size: 1.1rem;
color: #666;
margin-bottom: 1.5rem;
}
.social-links {
margin-top: 2rem;
padding-top: 2rem;
border-top: 1px solid #eee;
}
.social-links h2 {
font-size: 1.2rem;
margin-bottom: 1rem;
color: #666;
}
.social-links ul {
list-style: none;
}
.social-links li {
margin: 0.5rem 0;
}
/* Optional: Avatar styling */
.u-photo {
width: 120px;
height: 120px;
border-radius: 60px;
margin-bottom: 1rem;
}
/* Info box */
.info-box {
background: #f5f5f5;
border-left: 4px solid #0066cc;
padding: 1rem;
margin: 2rem 0;
}
.info-box h3 {
margin-bottom: 0.5rem;
}
.info-box p {
margin: 0.5rem 0;
font-size: 0.9rem;
}
</style>
</head>
<body>
<!--
============================================================
h-card Microformat: Your Identity Information
This is machine-readable markup that IndieAuth uses to
identify you. The h-card is the IndieWeb's business card.
============================================================
-->
<div class="h-card">
<!-- Optional: Your photo/avatar
<img class="u-photo" src="/avatar.jpg" alt="Phil Skents">
-->
<!-- Required: Your name (p-name) -->
<h1 class="p-name">Phil Skents</h1>
<!-- Required: Your identity URL (u-url)
MUST match the URL where this page is hosted -->
<div class="identity-url">
<a class="u-url" href="https://thesatelliteoflove.com" rel="me">
https://thesatelliteoflove.com
</a>
</div>
<!-- Optional: Brief bio or description -->
<p class="p-note">
IndieWeb enthusiast building minimal, standards-compliant web tools.
Creator of StarPunk CMS.
</p>
<!--
============================================================
Optional: Social Media Links with rel="me"
These create a web of trust by linking your identities.
Only include profiles you control.
The receiving site should link back with rel="me" for
bidirectional verification (GitHub and some others do this).
============================================================
-->
<div class="social-links">
<h2>Also me on the web</h2>
<ul>
<!-- Example social links - replace with your actual profiles -->
<!--
<li>
<a href="https://github.com/yourusername" rel="me">
GitHub: @yourusername
</a>
</li>
<li>
<a href="https://mastodon.social/@yourusername" rel="me">
Mastodon: @yourusername@mastodon.social
</a>
</li>
<li>
<a href="https://twitter.com/yourusername" rel="me">
Twitter: @yourusername
</a>
</li>
-->
<!-- For now, just a note about StarPunk -->
<li>
Publishing with
<a href="https://starpunk.thesatelliteoflove.com">
StarPunk
</a>
</li>
</ul>
</div>
</div>
<!--
============================================================
Information Box: How This Works
This section is optional but helpful for visitors.
============================================================
-->
<div class="info-box">
<h3>About This Page</h3>
<p>
This is my IndieAuth identity page. It allows me to sign in to
IndieWeb services using my domain name instead of passwords.
</p>
<p>
<strong>Technical:</strong> This page uses
<a href="https://indieauth.spec.indieweb.org/">IndieAuth</a> for
authentication and
<a href="http://microformats.org/wiki/h-card">h-card microformats</a>
for identity markup.
</p>
<p>
<strong>Privacy:</strong> Authentication is handled by
<a href="https://indieauth.com">IndieAuth.com</a>.
No passwords or personal data are stored on this site.
</p>
</div>
<!--
============================================================
Testing Your Identity Page
After uploading this file to your domain:
1. Visit https://indielogin.com/
2. Enter your domain (e.g., https://thesatelliteoflove.com)
3. You should see IndieAuth.com as an option
4. Complete the authentication flow
To validate your h-card:
1. Visit https://indiewebify.me/
2. Use the h-card validator
3. Enter your domain
4. Verify all information is detected
Common Issues:
- URL mismatch: The u-url must exactly match your domain
- Missing HTTPS: Both your domain and endpoints need HTTPS
- Wrong endpoints: The endpoint URLs must be exactly as shown
============================================================
-->
</body>
</html>