StarPunk/docs/decisions/ADR-027-versioning-strategy-for-authorization-removal.md

ADR-027: Versioning Strategy for Authorization Server Removal

Status

Accepted

Context

We have identified that the authorization server functionality added in v1.0.0-rc.1 was architectural over-engineering. The implementation includes:

• Token endpoint (POST /indieauth/token)
• Authorization endpoint (POST /indieauth/authorize)
• Token verification endpoint (GET /indieauth/token)
• Database tables: tokens, authorization_codes
• Complex OAuth 2.0/PKCE flows

This violates our core principle: "Every line of code must justify its existence." StarPunk V1 only needs authentication (identity verification), not authorization (access tokens). The Micropub endpoint can work with simpler admin session authentication.

We are currently at version 1.0.0-rc.3 (release candidate). The question is: what version number should we use when removing this functionality?

Decision

Continue with release candidates and fix before 1.0.0 final: 1.0.0-rc.4

We will:

1. Create version 1.0.0-rc.4 that removes the authorization server
2. Continue iterating through release candidates until the system is truly minimal
3. Only release 1.0.0 final when we have achieved the correct architecture
4. Consider this part of the release candidate testing process

Rationale

Why Not Jump to 2.0.0?

While removing features is technically a breaking change that would normally require a major version bump, we are still in release candidate phase. Release candidates explicitly exist to identify and fix issues before the final release. The "1.0.0" milestone has not been officially released yet.

Why Not Go Back to 0.x?

Moving backward from 1.0.0-rc.3 to 0.x would be confusing and violate semantic versioning principles. Version numbers should always move forward. Additionally, the core functionality (IndieAuth authentication, Micropub, RSS) is production-ready - it's just over-engineered.

Why Release Candidates Are Perfect For This

Release candidates serve exactly this purpose:

• Testing reveals issues (in this case, architectural over-engineering)
• Problems are fixed before the final release
• Multiple RC versions are normal and expected
• Users of RCs understand they are testing pre-release software

Semantic Versioning Compliance

Per SemVer 2.0.0 specification:

• Pre-release versions (like -rc.3) indicate unstable software
• Changes between pre-release versions don't require major version bumps
• The version precedence is: 1.0.0-rc.3 < 1.0.0-rc.4 < 1.0.0
• This is the standard pattern: fix issues in RCs, then release final

Honest Communication

The version progression tells a clear story:

• 1.0.0-rc.1: First attempt at V1 feature complete
• 1.0.0-rc.2: Bug fixes for migration issues
• 1.0.0-rc.3: More migration fixes
• 1.0.0-rc.4: Architectural correction - remove unnecessary complexity
• 1.0.0: Final, minimal, production-ready release

Consequences

Positive

• Maintains forward version progression
• Uses release candidates for their intended purpose
• Avoids confusing version number changes
• Clearly communicates that 1.0.0 final is the stable release
• Allows multiple iterations to achieve true minimalism
• Sets precedent that we'll fix architectural issues before declaring "1.0"

Negative

• Users of RC versions will experience breaking changes
• Might need multiple additional RCs (rc.5, rc.6) if more issues found
• Some might see many RCs as a sign of instability

Migration Path

Users on 1.0.0-rc.1, rc.2, or rc.3 will need to:

1. Backup their database
2. Update to 1.0.0-rc.4
3. Run migrations (which will clean up unused tables)
4. Update any Micropub clients to use session auth instead of bearer tokens

Alternatives Considered

Option 1: Jump to v2.0.0

• Rejected: We haven't released 1.0.0 final yet, so there's nothing to major-version bump from

Option 2: Release 1.0.0 then immediately 2.0.0

• Rejected: Releasing a known over-engineered 1.0.0 violates our principles

Option 3: Go back to 0.x series

• Rejected: Version numbers must move forward, this would confuse everyone

Option 4: Use 1.0.0-alpha or 1.0.0-beta

• Rejected: We're already in RC phase, moving backward in stability indicators is wrong

Option 5: Skip to 1.0.0 final with changes

• Rejected: Would surprise RC users with breaking changes in what should be a stable release

Implementation Plan

1. Version 1.0.0-rc.4:

   • Remove authorization server components
   • Update Micropub to use session authentication
   • Add migration to drop unnecessary tables
   • Update all documentation
   • Clear changelog entry explaining the architectural correction

2. Potential 1.0.0-rc.5+:

   • Fix any issues discovered in rc.4
   • Continue refining until truly minimal

3. Version 1.0.0 Final:

   • Release only when architecture is correct
   • No over-engineering
   • Every line justified

Changelog Entry Template

## [1.0.0-rc.4] - 2025-11-24

### Removed
- **Authorization Server**: Removed unnecessary OAuth 2.0 authorization server
  - Removed token endpoint (`POST /indieauth/token`)
  - Removed authorization endpoint (`POST /indieauth/authorize`)
  - Removed token verification endpoint (`GET /indieauth/token`)
  - Removed `tokens` and `authorization_codes` database tables
  - Removed PKCE verification for authorization code exchange
  - Removed bearer token authentication

### Changed
- **Micropub Simplified**: Now uses admin session authentication
  - Micropub endpoint only accessible to authenticated admin user
  - Removed scope validation (unnecessary for single-user system)
  - Simplified to basic POST endpoint with session check

### Fixed
- **Architectural Over-Engineering**: Returned to minimal implementation
  - V1 only needs authentication, not authorization
  - Single-user system doesn't need OAuth 2.0 token complexity
  - Follows core principle: "Every line must justify its existence"

### Migration Notes
- This is a breaking change for anyone using bearer tokens with Micropub
- Micropub clients must authenticate via IndieAuth login flow
- Database migration will drop `tokens` and `authorization_codes` tables
- Existing sessions remain valid

Conclusion

Version 1.0.0-rc.4 is the correct choice. It:

• Uses release candidates for their intended purpose
• Maintains semantic versioning compliance
• Communicates honestly about the development process
• Allows us to achieve true minimalism before declaring 1.0.0

The lesson learned: Release candidates are valuable for discovering not just bugs, but architectural issues. We'll continue iterating through RCs until StarPunk truly embodies minimal, elegant simplicity.

References

• Semantic Versioning 2.0.0
• ADR-008: Versioning Strategy
• ADR-021: IndieAuth Provider Strategy
• StarPunk Philosophy

---

Decision Date: 2024-11-24 Decision Makers: StarPunk Architecture Team Status: Accepted and will be implemented immediately