# 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://www.w3.org/TR/indieauth/)
- [Microformats2 h-card](http://microformats.org/wiki/h-card)
- [rel="me" specification](https://microformats.org/wiki/rel-me)
- [IndieWeb Authentication](https://indieweb.org/authentication)