phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Implement PKCE authentication for IndieLogin.com

Browse Source 
This fixes critical IndieAuth authentication by implementing PKCE (Proof Key
for Code Exchange) as required by IndieLogin.com API specification.

Added:
- PKCE code_verifier and code_challenge generation (RFC 7636)
- Database column: auth_state.code_verifier for PKCE support
- Issuer validation for authentication callbacks
- Comprehensive PKCE unit tests (6 tests, all passing)
- Database migration script for code_verifier column

Changed:
- Corrected IndieLogin.com API endpoints (/authorize and /token)
- State token validation now returns code_verifier for token exchange
- Authentication flow follows IndieLogin.com API specification exactly
- Enhanced logging with code_verifier redaction

Removed:
- OAuth metadata endpoint (/.well-known/oauth-authorization-server)
  Added in v0.7.0 but not required by IndieLogin.com
- h-app microformats markup from templates
  Modified in v0.7.1 but not used by IndieLogin.com
- indieauth-metadata link from HTML head

Security:
- PKCE prevents authorization code interception attacks
- Issuer validation prevents token substitution attacks
- Code verifier securely stored, redacted in logs, and single-use

Documentation:
- Version: 0.8.0
- CHANGELOG updated with v0.8.0 entry and v0.7.x notes
- ADR-016 and ADR-017 marked as superseded by ADR-019
- Implementation report created in docs/reports/
- Test update guide created in TODO_TEST_UPDATES.md

Breaking Changes:
- Users mid-authentication will need to restart login after upgrade
- Database migration required before deployment

Related: ADR-019

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Phil Skentelbery
2025-11-19 15:43:38 -07:00
parent caabf0087e
commit 5e50330bdf
18 changed files with 4208 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

399
docs/reports/ADR-019-versioning-guidance.md Normal file
View File

@@ -0,0 +1,399 @@
# 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**:
```markdown
## [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**:
```markdown
## [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**:
```markdown
## [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):
```python
__version__ = "0.7.1"
__version_info__ = (0, 7, 1)
```
**Change to**:
```python
__version__ = "0.8.0"
__version_info__ = (0, 8, 0)
```
### Git Tag Creation
**After implementation and testing complete**:
```bash
# 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