StarPunk/docs/architecture/simplified-auth-architecture.md

StarPunk Simplified Authentication Architecture

Overview

After removing the custom IndieAuth authorization server, StarPunk becomes a pure Micropub server that relies on external providers for all authentication and authorization.

Architecture Diagrams

Before: Complex Mixed-Mode Architecture

┌──────────────────────────────────────────────────────────────┐
│                     StarPunk Instance                         │
│                                                                │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                   Web Interface                         │   │
│  │  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
│  │  │ Admin Login │  │ Authorization │  │ Token Issuer │  │   │
│  │  └─────────────┘  └──────────────┘  └──────────────┘  │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                                │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                    Auth Module                          │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │   │
│  │  │ Sessions │ │   PKCE   │ │  Tokens  │ │   Codes  │ │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                                │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                     Database                            │   │
│  │  ┌────────┐ ┌──────────────────┐ ┌─────────────────┐  │   │
│  │  │ Users  │ │ authorization_codes│ │     tokens     │  │   │
│  │  └────────┘ └──────────────────┘ └─────────────────┘  │   │
│  └────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

Problems:
- 500+ lines of security-critical code
- Dual role: authorization server AND resource server
- Complex token lifecycle management
- Database bloat with token storage
- Maintenance burden for security updates

After: Clean Separation of Concerns

┌──────────────────────────────────────────────────────────────┐
│                     StarPunk Instance                         │
│                                                                │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                   Web Interface                         │   │
│  │  ┌─────────────┐                    ┌──────────────┐   │   │
│  │  │ Admin Login │                    │   Micropub   │   │   │
│  │  └─────────────┘                    └──────────────┘   │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                                │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                    Auth Module                          │   │
│  │  ┌──────────────┐            ┌──────────────────────┐  │   │
│  │  │   Sessions   │            │  Token Verification  │  │   │
│  │  │ (Admin Only) │            │  (External Provider) │  │   │
│  │  └──────────────┘            └──────────────────────┘  │   │
│  └────────────────────────────────────────────────────────┘   │
│                                                                │
│  ┌────────────────────────────────────────────────────────┐   │
│  │                     Database                            │   │
│  │  ┌────────┐ ┌──────────┐ ┌─────────┐                   │   │
│  │  │ Users  │ │auth_state│ │  posts  │  (No token tables)│   │
│  │  └────────┘ └──────────┘ └─────────┘                   │   │
│  └────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
                              │
                              │ API Calls
                              ▼
┌──────────────────────────────────────────────────────────────┐
│              External IndieAuth Providers                     │
│  ┌─────────────────────┐      ┌─────────────────────────┐    │
│  │  indieauth.com      │      │ tokens.indieauth.com    │    │
│  │  (Authorization)    │      │ (Token Verification)    │    │
│  └─────────────────────┘      └─────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘

Benefits:
- 500+ lines of code removed
- Clear single responsibility
- No security burden
- Minimal database footprint
- Zero maintenance for auth code

Authentication Flows

Flow 1: Admin Authentication (Unchanged)

Admin User                    StarPunk                    IndieLogin.com
    │                            │                              │
    ├──── GET /admin/login ───→  │                              │
    │                            │                              │
    │ ←── Login Form ───────────  │                              │
    │                            │                              │
    ├──── POST /auth/login ───→  │                              │
    │      (me=admin.com)        │                              │
    │                            ├──── Redirect ──────────────→ │
    │                            │    (client_id=starpunk.com)  │
    │ ←──────────── Authorization Request ─────────────────────  │
    │                            │                              │
    ├───────────── Authenticate with IndieLogin ──────────────→ │
    │                            │                              │
    │                            │ ←── Callback ────────────────│
    │                            │    (me=admin.com)           │
    │                            │                              │
    │ ←── Session Cookie ───────  │                              │
    │                            │                              │
    │      Admin Access           │                              │

Flow 2: Micropub Client Authentication (Simplified)

Micropub Client              StarPunk              External Token Endpoint
      │                         │                           │
      ├─── POST /micropub ───→  │                           │
      │   Bearer: token123      │                           │
      │                         ├──── GET /token ─────────→ │
      │                         │   Bearer: token123        │
      │                         │                           │
      │                         │ ←── Token Info ──────────│
      │                         │   {me, scope, client_id}  │
      │                         │                           │
      │                         │ [Validate me==ADMIN_ME]   │
      │                         │ [Check scope includes     │
      │                         │  "create"]                │
      │                         │                           │
      │ ←── 201 Created ────────│                           │
      │    Location: /post/123  │                           │

Component Responsibilities

StarPunk Components

1. Admin Authentication (/auth/*)

Responsibility: Manage admin sessions via IndieLogin.com Does:

• Initiate OAuth flow with IndieLogin.com
• Validate callback and create session
• Manage session lifecycle

Does NOT:

• Issue tokens
• Store passwords
• Manage user identities

2. Micropub Endpoint (/micropub)

Responsibility: Accept and process Micropub requests Does:

• Extract Bearer tokens from requests
• Verify tokens with external endpoint
• Create/update/delete posts
• Return proper Micropub responses

Does NOT:

• Issue tokens
• Manage authorization codes
• Store token data

3. Token Verification Module

Responsibility: Validate tokens with external providers Does:

• Call external token endpoint
• Cache valid tokens (5 min TTL)
• Validate scope and identity

Does NOT:

• Generate tokens
• Store tokens permanently
• Manage token lifecycle

External Provider Responsibilities

indieauth.com

• User authentication
• Authorization consent
• Authorization code generation
• Profile discovery

tokens.indieauth.com

• Token issuance
• Token verification
• Token revocation
• Scope management

Configuration

Required Settings

# Identity of the admin user
ADMIN_ME=https://your-domain.com

# External token endpoint for verification
TOKEN_ENDPOINT=https://tokens.indieauth.com/token

# Admin session secret (existing)
SECRET_KEY=your-secret-key

HTML Discovery

<!-- Added to all pages -->
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
<link rel="micropub" href="https://starpunk.example.com/micropub">

Security Model

Trust Boundaries

┌─────────────────────────────────────────────────────────────┐
│                    Trusted Zone                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │               StarPunk Application                    │   │
│  │  - Session management                                 │   │
│  │  - Post creation/management                          │   │
│  │  - Admin interface                                   │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
                  Token Verification API
                            │
┌─────────────────────────────────────────────────────────────┐
│                  Semi-Trusted Zone                           │
│  ┌──────────────────────────────────────────────────────┐   │
│  │           External IndieAuth Providers                │   │
│  │  - Token validation                                   │   │
│  │  - Identity verification                             │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
                     User Authentication
                            │
┌─────────────────────────────────────────────────────────────┐
│                    Untrusted Zone                            │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Micropub Clients                         │   │
│  │  - Must provide valid Bearer tokens                   │   │
│  │  - Tokens verified on every request                   │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Security Benefits of Simplified Architecture

1. Reduced Attack Surface

   • No token generation = no cryptographic mistakes
   • No token storage = no database leaks
   • No PKCE = no implementation errors

2. Specialized Security

   • Auth providers focus solely on security
   • Regular updates from specialized teams
   • Community-vetted implementations

3. Clear Boundaries

   • StarPunk only verifies, never issues
   • Single source of truth (external provider)
   • No confused deputy problems

Performance Characteristics

Token Verification Performance

Without Cache:
┌──────────┐     200-500ms      ┌─────────────┐
│ Micropub ├───────────────────→│Token Endpoint│
└──────────┘                     └─────────────┘

With Cache (95% hit rate):
┌──────────┐       <1ms          ┌─────────────┐
│ Micropub ├───────────────────→│ Memory Cache │
└──────────┘                     └─────────────┘

Cache Strategy

Cache Key: SHA256(token)
Cache Value: {
    'me': 'https://user.com',
    'client_id': 'https://client.com',
    'scope': 'create update delete',
    'expires_at': timestamp + 300  # 5 minutes
}

Expected Latencies

• First request: 200-500ms (external API)
• Cached request: <1ms
• Admin login: 1-2s (OAuth flow)
• Post creation: <50ms (after auth)

Migration Impact

Breaking Changes

1. All existing tokens invalid

   • Users must re-authenticate
   • No migration path for tokens

2. Endpoint removal

   • /auth/authorization → 404
   • /auth/token → 404

3. Configuration required

   • Must set ADMIN_ME
   • Must configure domain with IndieAuth links

Non-Breaking Preserved Functionality

1. Admin login unchanged

   • Same URL (/admin/login)
   • Same provider (IndieLogin.com)
   • Sessions preserved

2. Micropub API unchanged

   • Same endpoint (/micropub)
   • Same request format
   • Same response format

Comparison with Other Systems

WordPress + IndieAuth Plugin

• Similarity: External provider for auth
• Difference: WP has user management, we don't

Known IndieWeb Sites

• micro.blog: Custom auth server (complex)
• Indigenous: Client only, uses external auth
• StarPunk: Micropub server only (simple)

Architecture Philosophy

"Do one thing well"
       │
       ├── StarPunk: Publish notes
       ├── IndieAuth.com: Authenticate users
       └── Tokens.indieauth.com: Manage tokens

Future Considerations

Potential V2 Enhancements (NOT for V1)

1. Multi-user support

   • Would require user management
   • Still use external auth

2. Multiple token endpoints

   • Support different providers per user
   • Endpoint discovery from user domain

3. Token caching layer

   • Redis for distributed caching
   • Longer TTL with refresh

Explicitly NOT Implementing

1. Custom authorization server

   • Violates simplicity principle
   • Maintenance burden

2. Password authentication

   • Not IndieWeb compliant
   • Security burden

3. JWT validation

   • Not part of IndieAuth spec
   • Unnecessary complexity

Testing Strategy

Unit Tests

# Test external verification
@patch('httpx.get')
def test_token_verification(mock_get):
    # Mock successful response
    mock_get.return_value.status_code = 200
    mock_get.return_value.json.return_value = {
        'me': 'https://example.com',
        'scope': 'create'
    }

    result = verify_token('test-token')
    assert result is not None

Integration Tests

# Test with real endpoint (in CI)
def test_real_token_verification():
    # Use test token from tokens.indieauth.com
    token = get_test_token()
    result = verify_token(token)
    assert result['me'] == TEST_USER

Manual Testing

1. Configure domain with IndieAuth links
2. Use Quill or Indigenous
3. Create test post
4. Verify token caching

Metrics for Success

Quantitative Metrics

• Code removed: >500 lines
• Database tables removed: 2
• Complexity reduction: ~40%
• Test coverage maintained: >90%
• Performance: <500ms token verification

Qualitative Metrics

• Clarity: Clear separation of concerns
• Maintainability: No auth code to maintain
• Security: Specialized providers
• Flexibility: User choice of providers
• Simplicity: Focus on core functionality

---

Document Version: 1.0 Created: 2025-11-24 Author: StarPunk Architecture Team Purpose: Document simplified authentication architecture after IndieAuth server removal