StarPunk/docs/decisions/ADR-061-author-discovery.md

# ADR-061: Author Profile Discovery from IndieAuth

## Status
Accepted

## Context
StarPunk v1.2.0 requires Microformats2 compliance, including proper h-card author information in h-entries. The original design assumed author information would be configured via environment variables (AUTHOR_NAME, AUTHOR_PHOTO, etc.).

However, since StarPunk uses IndieAuth for authentication, and users authenticate with their domain/profile URL, we have an opportunity to discover author information directly from their IndieWeb profile rather than requiring manual configuration.

The user explicitly stated: "These should be retrieved from the logged in profile domain (rel me etc.)" when asked about author configuration.

## Decision
Implement automatic author profile discovery from the IndieAuth 'me' URL:

1. When a user logs in via IndieAuth, fetch their profile page
2. Parse h-card microformats and rel-me links from the profile
3. Cache this information in a new `author_profile` database table
4. Use discovered information in templates for Microformats2 markup
5. Provide fallback behavior when discovery fails

## Rationale
1. **IndieWeb Native**: Discovery from profile URLs is a core IndieWeb pattern
2. **DRY Principle**: Author already maintains their profile; no need to duplicate
3. **Dynamic Updates**: Profile changes are reflected on next login
4. **Standards-Based**: Uses existing h-card and rel-me specifications
5. **User Experience**: Zero configuration for author information
6. **Consistency**: Author info always matches their IndieWeb identity

## Consequences

### Positive
- No manual configuration of author information required
- Automatically stays in sync with user's profile
- Supports full IndieWeb identity model
- Works with any IndieAuth provider
- Discoverable rel-me links for identity verification

### Negative
- Requires network request during login (mitigated by caching)
- Depends on proper markup on user's profile page
- Additional database table required
- More complex than static configuration
- Parsing complexity for microformats

### Implementation Details

#### Database Schema
```sql
CREATE TABLE author_profile (
    id INTEGER PRIMARY KEY,
    me_url TEXT NOT NULL UNIQUE,
    name TEXT,
    photo TEXT,
    bio TEXT,
    rel_me_links TEXT,  -- JSON array
    discovered_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```

#### Discovery Flow
1. User authenticates with IndieAuth
2. On successful login, trigger discovery
3. Fetch user's profile page (with timeout)
4. Parse h-card for: name, photo, bio
5. Parse rel-me links
6. Store in database with timestamp
7. Use cache for 7 days, refresh on login

#### Fallback Strategy
- If discovery fails during login, use cached data if available
- If no cache exists, use minimal defaults (domain as name)
- Never block login due to discovery failure
- Log failures for monitoring

## Alternatives Considered

### 1. Environment Variables (Original Design)
Static configuration via .env file
- ✅ Simple, no network requests
- ❌ Requires manual configuration
- ❌ Duplicates information already on profile
- ❌ Can become out of sync

### 2. Hybrid Approach
Environment variables with optional discovery
- ✅ Flexibility for both approaches
- ❌ More complex configuration
- ❌ Unclear which takes precedence

### 3. Discovery Only, No Cache
Fetch profile on every request
- ✅ Always up to date
- ❌ Performance impact
- ❌ Reliability issues

### 4. Static Import Tool
CLI command to import profile once
- ✅ No runtime discovery needed
- ❌ Manual process
- ❌ Can become stale

## Implementation Priority
High - Required for v1.2.0 Microformats2 compliance

## References
- https://microformats.org/wiki/h-card
- https://indieweb.org/rel-me
- https://indieweb.org/discovery
- W3C IndieAuth specification