StarPunk/docs/reports/ADR-019-versioning-guidance.md

ADR-019 Implementation: Versioning Guidance

Date: 2025-11-19 Author: StarPunk Architect Status: Final Recommendation

Current Situation

Current Version: 0.7.1 Released Tags: v0.4.0, v0.5.2, v0.6.0, v0.6.1, v0.7.0, v0.7.1

Problem: ADR-019 initially suggested v0.6.3, but we have already released v0.7.0 and v0.7.1. We cannot go backward in semantic versioning (0.7.1 → 0.6.3 is invalid).

What v0.7.0 and v0.7.1 Contained

v0.7.0 (2025-11-19)

Added:

• IndieAuth detailed logging with token redaction
• OAuth Client ID Metadata Document endpoint (/.well-known/oauth-authorization-server)
  • NOTE: This endpoint is unnecessary and will be removed in ADR-019 implementation

Changed:

• Enhanced authentication flow visibility with structured logging
• LOG_LEVEL environment variable for configurable logging

Security:

• Automatic token redaction in logs

v0.7.1 (2025-11-19)

Fixed:

• IndieAuth h-app visibility (removed hidden and aria-hidden attributes)
  • Made h-app microformat visible to parsers for backward compatibility
  • NOTE: h-app microformats are unnecessary and will be removed in ADR-019 implementation

Analysis of Changes in ADR-019 Implementation

What ADR-019 Will Do

Fixes:

1. Fix broken IndieAuth authentication (critical bug)
2. Add PKCE implementation (security enhancement, required by IndieLogin.com)
3. Correct API endpoints (/authorize and /token instead of /auth)
4. Add issuer validation

Removes:

1. OAuth metadata endpoint added in v0.7.0 (unnecessary)
2. h-app microformats modified in v0.7.1 (unnecessary)

Changes:

1. Database schema: adds code_verifier column to auth_state table
2. Authentication flow: implements PKCE properly

Semantic Versioning Analysis

According to /home/phil/Projects/starpunk/docs/standards/versioning-strategy.md:

MAJOR (x.0.0):

• Breaking API changes
• Database schema changes requiring migration ✓ (we have this)
• Configuration file format changes
• Removal of deprecated features

MINOR (0.x.0):

• New features (backward compatible)
• New API endpoints
• Non-breaking enhancements
• Optional configuration parameters

PATCH (0.0.x):

• Bug fixes
• Security patches
• Documentation corrections
• Dependency updates

Special Rules for 0.x.y versions (from versioning-strategy.md):

"Public API should not be considered stable. Breaking changes allowed without major version increment."

During the 0.x phase, we have flexibility.

Change Classification

This implementation includes:

1. Critical bug fix - Authentication completely broken
2. Security enhancement - PKCE implementation (best practice)
3. Database schema change - Adding column (backward compatible with DEFAULT)
4. Feature removal - OAuth metadata endpoint (added in v0.7.0, never worked)
5. Code cleanup - Removing unnecessary h-app microformats

NOT included:

• New user-facing features
• Breaking API changes for working features
• Configuration changes requiring user intervention

Version Number Decision

Recommended: v0.8.0 (MINOR Increment)

Rationale:

1. Following 0.x Convention: During the 0.x phase (pre-1.0), MINOR increments are used for both features and breaking changes. This is documented in our versioning strategy.

2. This is a Significant Change:

   • Fixes critical broken functionality
   • Adds PKCE (security enhancement)
   • Changes authentication flow
   • Modifies database schema
   • Removes features added in v0.7.0

3. Database Schema Change: While backward compatible (DEFAULT clause), schema changes traditionally warrant MINOR increment.

4. Not a PATCH: Too substantial for PATCH (0.7.2):

   • Not a simple bug fix
   • Adds new security mechanism (PKCE)
   • Removes endpoints
   • Changes multiple files and flow

5. Not MAJOR (1.0.0): We're not ready for 1.0:

   • Still in development phase
   • V1 feature set not complete
   • This fixes existing planned functionality, doesn't complete the roadmap

Version Progression Comparison

Option A: v0.8.0 (RECOMMENDED)

v0.7.0  → Logging + OAuth metadata (broken)
v0.7.1  → h-app visibility fix (unnecessary)
v0.8.0  → Fix IndieAuth with PKCE, remove unnecessary features
v1.0.0  → (Future) First stable release when all V1 features complete

Option B: v0.7.2 (NOT RECOMMENDED)

v0.7.0  → Logging + OAuth metadata (broken)
v0.7.1  → h-app visibility fix (unnecessary)
v0.7.2  → Fix IndieAuth with PKCE, remove unnecessary features
v1.0.0  → (Future) First stable release

Too minor for the scope of changes. PATCH should be simple fixes.

Option C: v1.0.0 (NOT RECOMMENDED - TOO EARLY)

v0.7.0  → Logging + OAuth metadata (broken)
v0.7.1  → h-app visibility fix (unnecessary)
v1.0.0  → Fix IndieAuth with PKCE, remove unnecessary features

Premature. Not all V1 features complete. 1.0.0 should signal "production ready."

Git Tag Handling

Recommendation: Keep All Existing Tags

Do NOT delete v0.7.0 or v0.7.1

Rationale:

1. Git History Integrity: Tags mark historical points. Deleting creates confusion.
2. Semantic Versioning Rules: You can't "un-release" a version.
3. Traceability: Keep record of what was attempted even if it didn't work.
4. Documentation: CHANGELOG will explain the situation clearly.

What To Do Instead

Mark v0.7.0 and v0.7.1 as broken in documentation:

• CHANGELOG notes explain what didn't work
• GitHub release notes (if using) can be updated with warnings
• README or docs can reference the issue

CHANGELOG Updates

How to Document This

Add v0.8.0 entry:

## [0.8.0] - 2025-11-19

### Fixed
- **CRITICAL**: Fixed IndieAuth authentication to work with IndieLogin.com
- Implemented required PKCE (Proof Key for Code Exchange) for security
- Corrected IndieLogin.com API endpoints (/authorize and /token)
- Added issuer validation for authentication callbacks

### Added
- PKCE code_verifier generation and storage
- PKCE code_challenge generation and validation
- Database column: auth_state.code_verifier for PKCE support

### Removed
- OAuth Client ID Metadata Document endpoint (/.well-known/oauth-authorization-server)
  - Added in v0.7.0 but unnecessary for IndieLogin.com
  - IndieLogin.com does not use OAuth client discovery
- h-app microformats markup from templates
  - Modified in v0.7.1 but unnecessary for IndieLogin.com
  - IndieLogin.com does not parse h-app for client identification
- indieauth-metadata link from HTML head

### Changed
- Authentication flow now follows IndieLogin.com API specification exactly
- Database schema: auth_state table includes code_verifier column
- State token validation now returns code_verifier for token exchange

### Security
- PKCE prevents authorization code interception attacks
- Issuer validation prevents token substitution attacks
- Code verifier securely stored and single-use

### Breaking Changes
- Users mid-authentication when upgrading will need to restart login (state tokens expire in 5 minutes)
- Existing state tokens without code_verifier will be invalid (intentional security improvement)

### Notes on Previous Versions
- **v0.7.0**: OAuth metadata endpoint added based on misunderstanding of requirements. This endpoint was never functional for our use case and is removed in v0.8.0.
- **v0.7.1**: h-app visibility changes attempted to fix authentication but addressed wrong issue. h-app discovery not used by IndieLogin.com. Removed in v0.8.0.
- **v0.8.0**: Correct implementation based on official IndieLogin.com API documentation.

### Related Documentation
- ADR-019: IndieAuth Correct Implementation Based on IndieLogin.com API
- Design Document: docs/designs/indieauth-pkce-authentication.md
- ADR-016: Superseded (h-app client discovery not required)
- ADR-017: Superseded (OAuth metadata not required)

### Migration Notes
- Database migration required: Add code_verifier column to auth_state table
- See docs/designs/indieauth-pkce-authentication.md for full implementation guide

Update v0.7.0 entry with note:

## [0.7.0] - 2025-11-19

### Added
- **IndieAuth Detailed Logging**: Comprehensive logging for authentication flows
- Logging helper functions with automatic token redaction
- **OAuth Client ID Metadata Document endpoint** (/.well-known/oauth-authorization-server)
  - **NOTE (2025-11-19)**: This endpoint was added based on misunderstanding of IndieLogin.com requirements. IndieLogin.com does not use OAuth client discovery. This endpoint is removed in v0.8.0. See ADR-019 for correct implementation.

[... rest of v0.7.0 entry ...]

### Known Issues
- **IndieAuth authentication still broken**: This release attempted to fix authentication by adding OAuth metadata endpoint, but this is not required by IndieLogin.com. Missing PKCE implementation is the actual issue. Fixed in v0.8.0.

Update v0.7.1 entry with note:

## [0.7.1] - 2025-11-19

### Fixed
- **IndieAuth h-app Visibility**: Removed `hidden` and `aria-hidden="true"` attributes from h-app microformat markup
  - h-app was invisible to IndieAuth parsers
  - **NOTE (2025-11-19)**: This fix attempted to enable client discovery, but IndieLogin.com does not use h-app microformats. h-app markup removed entirely in v0.8.0. See ADR-019 for correct implementation.

### Known Issues
- **IndieAuth authentication still broken**: This release attempted to fix authentication by making h-app visible, but IndieLogin.com does not parse h-app. Missing PKCE implementation is the actual issue. Fixed in v0.8.0.

Version File Updates

File: /home/phil/Projects/starpunk/starpunk/__init__.py

Current (line 156):

__version__ = "0.7.1"
__version_info__ = (0, 7, 1)

Change to:

__version__ = "0.8.0"
__version_info__ = (0, 8, 0)

Git Tag Creation

After implementation and testing complete:

# Commit all changes
git add .
git commit -m "feat: Implement PKCE authentication for IndieLogin.com

- Add PKCE code_verifier and code_challenge generation
- Correct IndieLogin.com API endpoints (/authorize, /token)
- Add issuer validation
- Remove unnecessary OAuth metadata endpoint (from v0.7.0)
- Remove unnecessary h-app microformats (from v0.7.1)
- Update database schema: add auth_state.code_verifier column

Fixes critical IndieAuth authentication bug.
Version: 0.8.0

Related: ADR-019

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

# Create annotated tag
git tag -a v0.8.0 -m "Release 0.8.0: Fix IndieAuth Authentication with PKCE

Critical Fixes:
- Implemented PKCE (Proof Key for Code Exchange) as required by IndieLogin.com
- Corrected IndieLogin.com API endpoints
- Added issuer validation
- Fixed broken authentication flow

Removals:
- OAuth metadata endpoint (v0.7.0, unnecessary)
- h-app microformats (v0.7.1, unnecessary)

Security Enhancements:
- PKCE prevents authorization code interception
- Issuer validation prevents token substitution

Breaking Changes:
- Users mid-authentication must restart login after upgrade
- Database migration required (add auth_state.code_verifier column)

This release corrects authentication issues in v0.7.0 and v0.7.1 by implementing
the IndieLogin.com API specification correctly. See ADR-019 and design document
for full details.

See CHANGELOG.md for complete change details."

# Push
git push origin main
git push origin v0.8.0

Summary: What the Developer Should Do

1. Version Number

Use: 0.8.0

• Update starpunk/__init__.py: __version__ = "0.8.0" and __version_info__ = (0, 8, 0)

2. Git Tags

Keep all existing tags: v0.4.0, v0.5.2, v0.6.0, v0.6.1, v0.7.0, v0.7.1 Create new tag: v0.8.0 after implementation complete

3. CHANGELOG Updates

• Add v0.8.0 entry with comprehensive details
• Update v0.7.0 entry with note about OAuth metadata being unnecessary
• Update v0.7.1 entry with note about h-app being unnecessary
• Explain the progression and corrections clearly

4. GitHub Release (if used)

• Create v0.8.0 release from tag
• Use tag message as release notes
• Optionally update v0.7.0 and v0.7.1 release descriptions with warnings

5. Documentation Updates

• ADR-016: Change status to "Superseded by ADR-019"
• ADR-017: Change status to "Superseded by ADR-019"
• ADR-005: Add implementation note referencing ADR-019

Rationale for v0.8.0

Why NOT v0.7.2 (PATCH):

• Too substantial (PKCE implementation, endpoint changes, removals)
• Database schema change
• Semantic versioning: PATCH should be simple fixes
• This is a significant rework, not a small fix

Why NOT v1.0.0 (MAJOR):

• Not all V1 features complete yet
• Still in development phase (0.x series)
• 1.0.0 should signal "production ready, all planned features"
• This fixes existing planned functionality, doesn't complete roadmap

Why v0.8.0 (MINOR):

• Appropriate for 0.x development phase
• Signals significant change from v0.7.x
• Follows project versioning strategy for 0.x phase
• Database schema change warrants MINOR
• Keeps clean numbering progression toward 1.0.0

Version Roadmap

Current Path:

v0.7.0  - Logging + OAuth metadata (misunderstood requirements)
v0.7.1  - h-app visibility (wrong fix)
v0.8.0  - PKCE + correct IndieLogin.com implementation (THIS RELEASE)
v0.9.0  - (Future) Additional features or fixes
v1.0.0  - (Future) First stable release with all V1 features

This progression clearly shows:

1. v0.7.x attempted fixes based on wrong understanding
2. v0.8.0 correct implementation based on actual API requirements
3. Clean path to v1.0.0 when V1 scope is complete

---

Decision: Use v0.8.0 Reasoning: MINOR increment appropriate for significant fix with schema change during 0.x phase Action: Update version to 0.8.0, create tag v0.8.0, update CHANGELOG with detailed notes Git Tags: Keep all existing tags (v0.7.0, v0.7.1), add v0.8.0