# 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
```ini
# 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
```html
<!-- 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
```python
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
```python
# 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
```python
# 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