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

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