diff --git a/docs/architecture/indieauth-identity-page.md b/docs/architecture/indieauth-identity-page.md new file mode 100644 index 0000000..6884988 --- /dev/null +++ b/docs/architecture/indieauth-identity-page.md @@ -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 ``: + +```html + + +``` + +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 +
+

User Name

+ https://example.com +
+``` + +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 +GitHub +``` + +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) \ No newline at end of file diff --git a/docs/decisions/ADR-010-static-identity-page.md b/docs/decisions/ADR-010-static-identity-page.md new file mode 100644 index 0000000..f07bcb5 --- /dev/null +++ b/docs/decisions/ADR-010-static-identity-page.md @@ -0,0 +1,144 @@ +# 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/) \ No newline at end of file diff --git a/docs/examples/identity-page-customization-guide.md b/docs/examples/identity-page-customization-guide.md new file mode 100644 index 0000000..85ec699 --- /dev/null +++ b/docs/examples/identity-page-customization-guide.md @@ -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 + +Phil Skents +

Phil Skents

+ + +Your Name +

Your Name

+``` + +#### 2. Your Domain +```html + + + https://thesatelliteoflove.com + + + + + https://yourdomain.com + +``` + +### Optional Customizations + +#### Add Your Photo +```html + +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 +

+ Your bio here. Keep it brief - 1-2 sentences. +

+``` + +#### Add Social Media Links + +Uncomment and modify the social links section: + +```html +
  • + + GitHub: @yourusername + +
    • +``` + +**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 + +``` + +## Advanced Customizations + +### Custom Styling + +The template includes minimal inline CSS. To customize: + +1. **Colors**: Change the color values in the ` + + + +
    + + + +

    Phil Skents

    + + +
    + + https://thesatelliteoflove.com + +
    + + +

    + IndieWeb enthusiast building minimal, standards-compliant web tools. + Creator of StarPunk CMS. +

    + + +
    +

    Also me on the web

    + +
    +
    + + +
    +

    About This Page

    +

    + This is my IndieAuth identity page. It allows me to sign in to + IndieWeb services using my domain name instead of passwords. +

    +

    + Technical: This page uses + IndieAuth for + authentication and + h-card microformats + for identity markup. +

    +

    + Privacy: Authentication is handled by + IndieAuth.com. + No passwords or personal data are stored on this site. +

    +
    + + + + \ No newline at end of file diff --git a/docs/reports/identity-domain-validation-2025-11-19.md b/docs/reports/identity-domain-validation-2025-11-19.md new file mode 100644 index 0000000..957c0b3 --- /dev/null +++ b/docs/reports/identity-domain-validation-2025-11-19.md @@ -0,0 +1,249 @@ +# Identity Domain Validation Report +**Domain**: https://thesatelliteoflove.com +**Date**: 2025-11-19 +**Validator**: StarPunk Architect Agent +**Purpose**: Validate IndieAuth configuration for StarPunk authentication + +## Executive Summary + +**STATUS**: PARTIALLY READY - Configuration present but has critical issues + +The identity domain `https://thesatelliteoflove.com` has the core IndieAuth metadata in place, but contains several configuration errors that will prevent successful authentication. The domain requires fixes before it can be used with StarPunk. + +## IndieAuth Configuration Analysis + +### 1. Authorization Endpoint ✓ PRESENT (with issues) +```html + +``` +- **Status**: Configured +- **Endpoint**: IndieAuth.com (established IndieAuth service) +- **Issue**: HEAD request returned HTTP 400, suggesting the endpoint may have issues or requires specific parameters +- **Impact**: May cause authentication to fail + +### 2. Token Endpoint ✓ PRESENT +```html + +``` +- **Status**: Configured +- **Endpoint**: tokens.indieauth.com (official token service) +- **Validation**: Returns HTTP 200, endpoint is accessible +- **Impact**: Token generation should work correctly + +### 3. Micropub Endpoint ⚠️ DUPLICATE CONFIGURATION +```html + + +``` +- **Issue**: Two micropub declarations, one empty +- **Impact**: May confuse clients; the empty one should be removed +- **Note**: The first one points to the domain but has double slash (//) + +## Identity Information (h-card) + +### Body-level h-card ✓ PRESENT (incomplete) +```html + +``` +- **Status**: Configured at body level +- **Issue**: The entire page is marked as an h-card, which is technically valid but not best practice + +### Identity Properties Found: + +1. **Name (p-name)**: ✓ PRESENT + ```html + Home + Phil Skents + ``` + - Conflicting names: "Home" vs "Phil Skents" + - Best practice: Should have a single, clear p-name property + +2. **URL (u-url)**: ✓ PRESENT + ```html + Home + ``` + - Links to homepage + - Should be full URL (https://thesatelliteoflove.com) for clarity + +3. **Photo (u-photo)**: ✗ MISSING + - No photo property found + - Recommended for complete identity representation + +4. **Email (u-email)**: Potentially present + ```html + + ``` + - Present as rel="me" link, not as u-email property + +## Social Proof (rel="me" links) + +### Links Found: +1. ✗ **Empty rel="me"**: `` +2. ✓ **Email**: `` + +**Issues**: +- One empty rel="me" link should be removed +- No links to social media profiles (GitHub, Mastodon, etc.) +- Missing bidirectional verification for rel="me" web sign-in + +## Security Assessment + +### HTTPS Configuration: ✓ PASS +- Domain properly serves over HTTPS +- No mixed content detected in initial inspection + +### Endpoint Accessibility: +- Token endpoint: ✓ Accessible (HTTP 200) +- Authorization endpoint: ⚠️ Returns HTTP 400 (may need investigation) + +### Domain Redirects: +- No redirects detected +- Clean HTTPS delivery + +## IndieWeb Microformats + +### Found: +- `h-card`: Present (body-level) +- `h-feed`: Present on homepage +- `h-entry`: Present for content items +- `p-name`, `u-url`, `dt-published`: Properly used in feed items +- `p-author`: Present in footer + +**Assessment**: Good microformats2 markup for content, but identity h-card needs refinement. + +## Critical Issues Requiring Fixes + +### Priority 1: Must Fix Before Production +1. **Remove empty links**: + - Empty `rel="me"` link + - Empty `rel="micropub"` link + - Empty `rel="webmention"` link + - Empty `rel="pingback"` link + +2. **Fix micropub double-slash**: + - Change `https://thesatelliteoflove.com//micropub` + - To: `https://starpunk.thesatelliteoflove.com/micropub` + - (This should point to StarPunk, not the identity domain) + +3. **Clarify h-card identity**: + - Create a dedicated h-card element (not body-level) + - Use consistent p-name ("Phil Skents", not "Home") + - Add u-url with full domain URL + - Consider adding u-photo + +### Priority 2: Should Fix for Best Practice +1. **Add social proof**: + - Add rel="me" links to social profiles + - Ensure bidirectional linking for web sign-in + +2. **Simplify h-card structure**: + - Move h-card from body to specific element (header or aside) + - Reduce confusion with multiple p-name properties + +3. **Investigation needed**: + - Determine why https://indieauth.com/auth returns HTTP 400 + - May need to test full authentication flow + +## Expected Authentication Flow + +### Current State: +1. User enters `https://thesatelliteoflove.com` as identity URL +2. StarPunk fetches the page and finds: + - Authorization endpoint: `https://indieauth.com/auth` + - Token endpoint: `https://tokens.indieauth.com/token` +3. StarPunk redirects to IndieAuth.com with: + - client_id: `https://starpunk.thesatelliteoflove.com/` + - redirect_uri: `https://starpunk.thesatelliteoflove.com/auth/callback` + - state: (random value) +4. IndieAuth.com verifies the identity domain +5. User approves the authorization +6. IndieAuth.com redirects back with auth code +7. StarPunk exchanges code for token at tokens.indieauth.com +8. User is authenticated + +### Potential Issues: +- Empty rel="me" links may confuse IndieAuth.com +- HTTP 400 from authorization endpoint needs investigation +- Micropub endpoint configuration may cause client confusion + +## Recommendations + +### Immediate Actions: +1. **Clean up the HTML head**: + ```html + + + + + + + + + ``` + +2. **Improve h-card**: + ```html +
    + + Phil Skents + + Email +
    + ``` + +3. **Add social verification**: + ```html + + + ``` + +### Testing Actions: +1. Test full IndieAuth flow with IndieLogin.com +2. Verify authorization endpoint functionality +3. Test with StarPunk once fixes are applied +4. Validate h-card parsing with microformats validator + +## Architectural Compliance + +### IndieWeb Standards: ⚠️ PARTIAL +- Has required IndieAuth endpoints +- Has microformats markup +- Missing complete identity information +- Has configuration errors + +### Security Standards: ✓ PASS +- HTTPS properly configured +- Using established IndieAuth services +- No obvious security issues + +### Best Practices: ⚠️ NEEDS IMPROVEMENT +- Multiple empty link elements (code smell) +- Duplicate micropub declarations +- Inconsistent identity markup +- Missing social proof + +## Conclusion + +**Can authentication work right now?** POSSIBLY, but with high risk of failure. + +**Should it be used in production?** NO, not until critical issues are fixed. + +**Estimated time to fix**: 15-30 minutes of HTML editing. + +The domain has the foundational IndieAuth configuration in place, which is excellent. However, the presence of empty link elements and duplicate declarations suggests the site may have been generated from a template with placeholder values that weren't fully configured. + +Once the empty links are removed, the micropub endpoint is corrected to point to StarPunk, and the h-card is refined, this domain will be fully ready for IndieAuth authentication. + +## Next Steps + +1. Fix the identity domain HTML (see Immediate Actions above) +2. Test authentication flow with IndieLogin.com directly +3. Verify StarPunk can discover and use the endpoints +4. Document successful authentication in test report +5. Consider creating a validation script for identity domain setup + +--- + +**Document Status**: Complete +**Last Updated**: 2025-11-19 +**Maintained By**: StarPunk Architect Agent