StarPunk/docs/design/v1.0.0/indieauth-assessment.md

IndieAuth Architecture Assessment

Date: 2025-11-24 Author: StarPunk Architect Status: Critical Review

Executive Summary

You asked: "WHY? Why not use an established provider like indieauth for authorization and token?"

The honest answer: The current decision to implement our own authorization and token endpoints appears to be based on a fundamental misunderstanding of how IndieAuth works, combined with over-engineering for a single-user system.

Current Implementation Reality

StarPunk has already implemented its own authorization and token endpoints:

• /auth/authorization - Full authorization endpoint (327 lines of code)
• /auth/token - Full token endpoint implementation
• Complete authorization code flow with PKCE support
• Token generation, storage, and validation

This represents significant complexity that may not have been necessary.

The Core Misunderstanding

ADR-021 reveals the critical misunderstanding that drove this decision:

"The user reported that IndieLogin.com requires manual client_id registration, making it unsuitable for self-hosted software"

This is completely false. IndieAuth (including IndieLogin.com) requires no registration whatsoever. Each self-hosted instance uses its own domain as the client_id automatically.

What StarPunk Actually Needs

For a single-user personal CMS, StarPunk needs:

1. Admin Authentication: Log the owner into the admin panel

   • ✅ Currently uses IndieLogin.com correctly
   • Works perfectly, no changes needed

2. Micropub Token Verification: Verify tokens from Micropub clients

   • Only needs to verify tokens, not issue them
   • Could delegate entirely to the user's chosen authorization server

The Architectural Options

Option A: Use External Provider (Recommended for Simplicity)

How it would work:

1. User adds these links to their personal website:

   <link rel="authorization_endpoint" href="https://indielogin.com/auth">
   <link rel="token_endpoint" href="https://tokens.indieauth.com/token">
   <link rel="micropub" href="https://starpunk.example/micropub">
   

2. Micropub clients discover endpoints from user's site

3. Clients get tokens from indieauth.com/tokens.indieauth.com

4. StarPunk only verifies tokens (10-20 lines of code)

Benefits:

• ✅ Simplicity: 95% less code
• ✅ Security: Maintained by IndieAuth experts
• ✅ Reliability: Battle-tested infrastructure
• ✅ Standards: Full spec compliance guaranteed
• ✅ Zero maintenance: No security updates needed

Drawbacks:

• ❌ Requires user to configure their personal domain
• ❌ Dependency on external service
• ❌ User needs to understand IndieAuth flow

Option B: Implement Own Endpoints (Current Approach)

What we've built:

• Complete authorization endpoint
• Complete token endpoint
• Authorization codes table
• Token management system
• PKCE support
• Scope validation

Benefits:

• ✅ Self-contained system
• ✅ No external dependencies for Micropub
• ✅ User doesn't need separate domain configuration
• ✅ Complete control over auth flow

Drawbacks:

• ❌ Complexity: 500+ lines of auth code
• ❌ Security burden: We maintain all security
• ❌ Over-engineered: For a single-user system
• ❌ Spec compliance: Our responsibility
• ❌ Maintenance: Ongoing updates needed

My Honest Assessment

Was This the Right Decision?

No, probably not. For a single-user personal CMS that values simplicity:

1. We solved a problem that didn't exist (registration requirement)
2. We added unnecessary complexity (500+ lines vs 20 lines)
3. We took on security responsibilities unnecessarily
4. We violated our core principle: "Every line of code must justify its existence"

Why Did This Happen?

1. Misunderstanding: Believed IndieAuth required registration
2. Scope creep: Wanted StarPunk to be "complete"
3. Over-engineering: Built for theoretical multi-user future
4. Momentum: Once started, kept building

What Should We Do Now?

Option 1: Keep Current Implementation (Pragmatic)

Since it's already built and working:

• Document it properly
• Security audit the implementation
• Add comprehensive tests
• Accept the maintenance burden

Rationale: Sunk cost, but functional. Changing now adds work.

Option 2: Simplify to External Provider (Purist)

Remove our endpoints and use external providers:

• Delete /auth/authorization and /auth/token
• Keep only admin auth via IndieLogin
• Add token verification for Micropub
• Document user setup clearly

Rationale: Aligns with simplicity principle, reduces attack surface.

Option 3: Hybrid Approach (Recommended)

Keep implementation but make it optional:

1. Default: Use external providers (simple)
2. Advanced: Enable built-in endpoints (self-contained)
3. Configuration flag: INDIEAUTH_MODE = "external" | "builtin"

Rationale: Best of both worlds, user choice.

My Recommendation

For V1 Release

Keep the current implementation but:

1. Document the trade-offs clearly
2. Add configuration option to disable built-in endpoints
3. Provide clear setup guides for both modes:
   • Simple mode: Use external providers
   • Advanced mode: Use built-in endpoints
4. Security audit the implementation thoroughly

For V2 Consideration

1. Measure actual usage: Do users want built-in auth?
2. Consider removing if external providers work well
3. Or enhance if users value self-contained nature

The Real Question

You asked "WHY?" The honest answer:

We built our own auth endpoints because we misunderstood IndieAuth and over-engineered for a single-user system. It wasn't necessary, but now that it's built, it does provide a self-contained solution that some users might value.

Architecture Principles Violated

1. ✗ Minimal Code: Added 500+ lines unnecessarily
2. ✗ Simplicity First: Chose complex over simple
3. ✗ YAGNI: Built for imagined requirements
4. ✗ Single Responsibility: StarPunk is a CMS, not an auth server

Architecture Principles Upheld

1. ✓ Standards Compliance: Full IndieAuth spec implementation
2. ✓ No Lock-in: Users can switch providers
3. ✓ Self-hostable: Complete solution in one package

Conclusion

The decision to implement our own authorization and token endpoints was architecturally questionable for a minimal single-user CMS. It adds complexity without proportional benefit.

However, since it's already implemented:

1. We should keep it for V1 (pragmatism over purity)
2. Make it optional via configuration
3. Document both approaches clearly
4. Re-evaluate based on user feedback

The lesson: Always challenge requirements and complexity. Just because we can build something doesn't mean we should.

---

"Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." - Antoine de Saint-Exupéry

This applies directly to StarPunk's auth architecture.