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

feat: Complete IndieAuth server removal (Phases 2-4)

Browse Source 
Completed all remaining phases of ADR-030 IndieAuth provider removal.
StarPunk no longer acts as an authorization server - all IndieAuth
operations delegated to external providers.

Phase 2 - Remove Token Issuance:
- Deleted /auth/token endpoint
- Removed token_endpoint() function from routes/auth.py
- Deleted tests/test_routes_token.py

Phase 3 - Remove Token Storage:
- Deleted starpunk/tokens.py module entirely
- Created migration 004 to drop tokens and authorization_codes tables
- Deleted tests/test_tokens.py
- Removed all internal token CRUD operations

Phase 4 - External Token Verification:
- Created starpunk/auth_external.py module
- Implemented verify_external_token() for external IndieAuth providers
- Updated Micropub endpoint to use external verification
- Added TOKEN_ENDPOINT configuration
- Updated all Micropub tests to mock external verification
- HTTP timeout protection (5s) for external requests

Additional Changes:
- Created migration 003 to remove code_verifier from auth_state
- Fixed 5 migration tests that referenced obsolete code_verifier column
- Updated 11 Micropub tests for external verification
- Fixed test fixture and app context issues
- All 501 tests passing

Breaking Changes:
- Micropub clients must use external IndieAuth providers
- TOKEN_ENDPOINT configuration now required
- Existing internal tokens invalid (tables dropped)

Migration Impact:
- Simpler codebase: -500 lines of code
- Fewer database tables: -2 tables (tokens, authorization_codes)
- More secure: External providers handle token security
- More maintainable: Less authentication code to maintain

Standards Compliance:
- W3C IndieAuth specification
- OAuth 2.0 Bearer token authentication
- IndieWeb principle: delegate to external services

Related:
- ADR-030: IndieAuth Provider Removal Strategy
- ADR-050: Remove Custom IndieAuth Server
- Migration 003: Remove code_verifier from auth_state
- Migration 004: Drop tokens and authorization_codes tables

🤖 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-24 17:23:46 -07:00
parent 869402ab0d
commit a3bac86647
36 changed files with 5597 additions and 2670 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
docs/decisions/ADR-027-versioning-strategy-for-authorization-removal.md Normal file
View File

@@ -0,0 +1,167 @@
# 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
```markdown
## [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](https://semver.org/)
- [ADR-008: Versioning Strategy](../standards/versioning-strategy.md)
- [ADR-021: IndieAuth Provider Strategy](./ADR-021-indieauth-provider-strategy.md)
- [StarPunk Philosophy](../architecture/philosophy.md)
---
**Decision Date**: 2024-11-24
**Decision Makers**: StarPunk Architecture Team
**Status**: Accepted and will be implemented immediately

251
docs/decisions/ADR-030-external-token-verification-architecture.md Normal file
View File

@@ -0,0 +1,251 @@
# ADR-030: External Token Verification Architecture
## Status
Accepted
## Context
Following the decision in ADR-021 to use external IndieAuth providers, we need to define the architecture for token verification. Several critical questions arose during implementation planning:
1. How should we handle the existing database migration that creates token tables?
2. What caching strategy should we use for token verification?
3. How should we handle network errors when contacting external providers?
4. What are the security implications of caching tokens?
## Decision
### 1. Database Migration Strategy
**Keep migration 002 but document its future purpose.**
The migration creates `tokens` and `authorization_codes` tables that are not used in V1 but will be needed if V2 adds an internal provider option. Rather than removing and later re-adding these tables, we keep them empty in V1.
**Rationale**:
- Empty tables have zero performance impact
- Avoids complex migration rollback/recreation cycles
- Provides clear upgrade path to V2
- Follows principle of forward compatibility
### 2. Token Caching Architecture
**Implement a configurable memory cache with 5-minute default TTL.**
```python
class TokenCache:
"""Simple time-based token cache"""
def __init__(self, ttl=300, enabled=True):
self.ttl = ttl
self.enabled = enabled
self.cache = {} # token_hash -> (info, expiry)
```
**Configuration**:
```ini
MICROPUB_TOKEN_CACHE_ENABLED=true # Can disable for high security
MICROPUB_TOKEN_CACHE_TTL=300 # 5 minutes default
```
**Security Measures**:
- Store SHA256 hash of token, never plain text
- Memory-only storage (no persistence)
- Short TTL to limit revocation delay
- Option to disable entirely
### 3. Network Error Handling
**Implement clear error messages with appropriate HTTP status codes.**
| Scenario | HTTP Status | User Message |
|----------|------------|--------------|
| Auth server timeout | 503 | "Authorization server is unreachable" |
| Invalid token | 403 | "Access token is invalid or expired" |
| Network error | 503 | "Cannot connect to authorization server" |
| No token provided | 401 | "No access token provided" |
**Implementation**:
```python
try:
response = httpx.get(endpoint, timeout=5.0)
except httpx.TimeoutError:
raise TokenEndpointError("Authorization server is unreachable")
```
### 4. Endpoint Discovery
**Implement full IndieAuth spec discovery with fallbacks.**
Priority order:
1. HTTP Link header (highest priority)
2. HTML link elements
3. IndieAuth metadata endpoint
This ensures compatibility with all IndieAuth providers while following the specification exactly.
## Rationale
### Why Cache Tokens?
**Performance**:
- Reduces latency for Micropub posts (5ms vs 500ms)
- Reduces load on external authorization servers
- Improves user experience for rapid posting
**Trade-offs Accepted**:
- 5-minute revocation delay is acceptable for most use cases
- Can disable cache for high-security requirements
- Cache is memory-only, cleared on restart
### Why Keep Empty Tables?
**Simplicity**:
- Simpler than conditional migrations
- Cleaner upgrade path to V2
- No production impact (tables unused)
- Avoids migration complexity
**Forward Compatibility**:
- V2 might add internal provider
- Tables already have correct schema
- Migration already tested and working
### Why External-Only Verification?
**Alignment with Principles**:
- StarPunk is a Micropub server, not an auth server
- Users control their own identity infrastructure
- Reduces code complexity significantly
- Follows IndieWeb separation of concerns
## Consequences
### Positive
- **Simplicity**: No complex OAuth flows to implement
- **Security**: No tokens stored in database
- **Performance**: Cache provides fast token validation
- **Flexibility**: Users choose their auth providers
- **Compliance**: Full IndieAuth spec compliance
### Negative
- **Dependency**: Requires external auth server availability
- **Latency**: Network call for uncached tokens (mitigated by cache)
- **Revocation Delay**: Up to 5 minutes for cached tokens (configurable)
### Neutral
- **Database**: Unused tables in V1 (no impact, future-ready)
- **Configuration**: Requires ADMIN_ME setting (one-time setup)
- **Documentation**: Must explain external provider setup
## Implementation Details
### Token Verification Flow
```
1. Extract Bearer token from Authorization header
2. Check cache for valid cached result
3. If not cached:
a. Discover token endpoint from ADMIN_ME URL
b. Verify token with external endpoint
c. Cache result if valid
4. Validate response:
a. 'me' field matches ADMIN_ME
b. 'scope' includes 'create'
5. Return validation result
```
### Security Checklist
- [ ] Never log tokens in plain text
- [ ] Use HTTPS for all token verification
- [ ] Implement timeout on HTTP requests
- [ ] Hash tokens before caching
- [ ] Validate SSL certificates
- [ ] Clear cache on configuration changes
### Performance Targets
- Cached token verification: < 10ms
- Uncached token verification: < 500ms
- Endpoint discovery: < 1000ms (cached after first)
- Cache memory usage: < 10MB for 1000 tokens
## Alternatives Considered
### Alternative 1: No Token Cache
**Pros**: Immediate revocation, simpler code
**Cons**: High latency (500ms per request), load on auth servers
**Verdict**: Rejected - poor user experience
### Alternative 2: Database Token Cache
**Pros**: Persistent cache, survives restarts
**Cons**: Complex invalidation, security concerns
**Verdict**: Rejected - unnecessary complexity
### Alternative 3: Redis Token Cache
**Pros**: Distributed cache, proven solution
**Cons**: Additional dependency, deployment complexity
**Verdict**: Rejected - violates simplicity principle
### Alternative 4: Remove Migration 002
**Pros**: Cleaner V1 codebase
**Cons**: Complex V2 upgrade, breaks existing databases
**Verdict**: Rejected - creates future problems
## Migration Impact
### For Existing Installations
- No database changes needed
- Add ADMIN_ME configuration
- Token verification switches to external
### For New Installations
- Clean V1 implementation
- Empty future-use tables
- Simple configuration
## Security Considerations
### Token Revocation Delay
- Cached tokens remain valid for TTL duration
- Maximum exposure: 5 minutes default
- Can disable cache for immediate revocation
- Document delay in security guide
### Network Security
- Always use HTTPS for token verification
- Validate SSL certificates
- Implement request timeouts
- Handle network errors gracefully
### Cache Security
- SHA256 hash tokens before storage
- Memory-only cache (no disk persistence)
- Clear cache on shutdown
- Limit cache size to prevent DoS
## References
- [IndieAuth Spec Section 6.3](https://www.w3.org/TR/indieauth/#token-verification) - Token verification
- [OAuth 2.0 Bearer Token](https://tools.ietf.org/html/rfc6750) - Bearer token usage
- [ADR-021](./ADR-021-indieauth-provider-strategy.md) - Provider strategy decision
- [ADR-029](./ADR-029-micropub-indieauth-integration.md) - Integration strategy
## Related Decisions
- ADR-021: IndieAuth Provider Strategy
- ADR-029: Micropub IndieAuth Integration Strategy
- ADR-005: IndieLogin Authentication
- ADR-010: Authentication Module Design
---
**Document Version**: 1.0
**Created**: 2024-11-24
**Author**: StarPunk Architecture Team
**Status**: Accepted

374
docs/decisions/ADR-050-remove-custom-indieauth-server.md Normal file
View File

@@ -0,0 +1,374 @@
# ADR-050: Remove Custom IndieAuth Server
## Status
Proposed
## Context
StarPunk currently includes a custom IndieAuth authorization server implementation that:
- Provides authorization endpoint (`/auth/authorization`)
- Provides token issuance endpoint (`/auth/token`)
- Manages authorization codes and access tokens
- Implements PKCE for security
- Stores hashed tokens in the database
However, this violates our core philosophy of "every line of code must justify its existence." The custom authorization server adds significant complexity without clear benefit, as users can use external IndieAuth providers like indieauth.com and tokens.indieauth.com.
### Current Architecture Problems
1. **Unnecessary Complexity**: ~500+ lines of authorization/token management code
2. **Security Burden**: We're responsible for secure token generation, storage, and validation
3. **Maintenance Overhead**: Must keep up with IndieAuth spec changes and security updates
4. **Database Bloat**: Two additional tables for codes and tokens
5. **Confusion**: Mixing authorization server and resource server responsibilities
### Proposed Architecture
StarPunk should be a pure Micropub server that:
- Accepts Bearer tokens in the Authorization header
- Verifies tokens with the user's configured token endpoint
- Does NOT issue tokens or handle authorization
- Uses external providers for all IndieAuth functionality
## Decision
Remove all custom IndieAuth authorization server code and rely entirely on external providers.
### What Gets Removed
1. **Python Modules**:
- `/home/phil/Projects/starpunk/starpunk/tokens.py` - Entire file
- Authorization endpoint code from `/home/phil/Projects/starpunk/starpunk/routes/auth.py`
- Token endpoint code from `/home/phil/Projects/starpunk/starpunk/routes/auth.py`
2. **Templates**:
- `/home/phil/Projects/starpunk/templates/auth/authorize.html` - Authorization consent UI
3. **Database**:
- `authorization_codes` table
- `tokens` table
- Migration: `/home/phil/Projects/starpunk/migrations/002_secure_tokens_and_authorization_codes.sql`
4. **Tests**:
- `/home/phil/Projects/starpunk/tests/test_tokens.py`
- `/home/phil/Projects/starpunk/tests/test_routes_authorization.py`
- `/home/phil/Projects/starpunk/tests/test_routes_token.py`
- `/home/phil/Projects/starpunk/tests/test_auth_pkce.py`
### What Gets Modified
1. **Micropub Token Verification** (`/home/phil/Projects/starpunk/starpunk/micropub.py`):
- Replace local token lookup with external token endpoint verification
- Use token introspection endpoint to validate tokens
2. **Configuration** (`/home/phil/Projects/starpunk/starpunk/config.py`):
- Add `TOKEN_ENDPOINT` setting for external provider
- Remove any authorization server settings
3. **HTML Headers** (base template):
- Add link tags pointing to external providers
- Remove references to local authorization endpoints
4. **Admin Auth** (`/home/phil/Projects/starpunk/starpunk/routes/auth.py`):
- Keep IndieLogin.com integration for admin sessions
- Remove authorization/token endpoint routes
## Rationale
### Simplicity Score: 10/10
- Removes ~500+ lines of complex security code
- Eliminates two database tables
- Reduces attack surface
- Clearer separation of concerns
### Maintenance Score: 10/10
- No security updates for auth code
- No spec compliance to maintain
- External providers handle all complexity
- Focus on core CMS functionality
### Standards Compliance: Pass
- Still fully IndieAuth compliant
- Better separation of resource server vs authorization server
- Follows IndieWeb principle of using existing infrastructure
### User Impact: Minimal
- Users already need to configure their domain
- External providers are free and require no registration
- Better security (specialized providers)
- More flexibility in provider choice
## Implementation Plan
### Phase 1: Remove Authorization Server (Day 1)
**Goal**: Remove authorization endpoint and consent UI
**Tasks**:
1. Delete `/home/phil/Projects/starpunk/templates/auth/authorize.html`
2. Remove `authorization_endpoint()` from `/home/phil/Projects/starpunk/starpunk/routes/auth.py`
3. Delete `/home/phil/Projects/starpunk/tests/test_routes_authorization.py`
4. Delete `/home/phil/Projects/starpunk/tests/test_auth_pkce.py`
5. Remove PKCE-related functions from auth module
6. Update route tests to not expect /auth/authorization
**Verification**:
- Server starts without errors
- Admin login still works
- No references to authorization endpoint in codebase
### Phase 2: Remove Token Issuance (Day 1)
**Goal**: Remove token endpoint and generation logic
**Tasks**:
1. Remove `token_endpoint()` from `/home/phil/Projects/starpunk/starpunk/routes/auth.py`
2. Delete `/home/phil/Projects/starpunk/tests/test_routes_token.py`
3. Remove token generation functions from `/home/phil/Projects/starpunk/starpunk/tokens.py`
4. Remove authorization code exchange logic
**Verification**:
- Server starts without errors
- No references to token issuance in codebase
### Phase 3: Simplify Database Schema (Day 2)
**Goal**: Remove authorization and token tables
**Tasks**:
1. Create new migration to drop tables:
```sql
-- 003_remove_indieauth_server_tables.sql
DROP TABLE IF EXISTS authorization_codes;
DROP TABLE IF EXISTS tokens;
```
2. Remove `/home/phil/Projects/starpunk/migrations/002_secure_tokens_and_authorization_codes.sql`
3. Update schema documentation
4. Run migration on test database
**Verification**:
- Database migration succeeds
- No orphaned foreign keys
- Application starts without database errors
### Phase 4: Update Micropub Token Verification (Day 2)
**Goal**: Use external token endpoint for verification
**New Implementation**:
```python
def verify_token(bearer_token: str) -> Optional[Dict[str, Any]]:
"""
Verify token with external token endpoint
Args:
bearer_token: Token from Authorization header
Returns:
Token info if valid, None otherwise
"""
token_endpoint = current_app.config['TOKEN_ENDPOINT']
try:
response = httpx.get(
token_endpoint,
headers={'Authorization': f'Bearer {bearer_token}'}
)
if response.status_code != 200:
return None
data = response.json()
# Verify token is for our user
if data.get('me') != current_app.config['ADMIN_ME']:
return None
# Check scope
if 'create' not in data.get('scope', ''):
return None
return data
except Exception:
return None
```
**Tasks**:
1. Replace `verify_token()` in `/home/phil/Projects/starpunk/starpunk/micropub.py`
2. Add `TOKEN_ENDPOINT` to config with default `https://tokens.indieauth.com/token`
3. Remove local database token lookup
4. Update Micropub tests to mock external verification
**Verification**:
- Micropub endpoint accepts valid tokens
- Rejects invalid tokens
- Proper error responses
### Phase 5: Documentation and Configuration (Day 3)
**Goal**: Update all documentation and add discovery headers
**Tasks**:
1. Update base template with IndieAuth discovery:
```html
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
```
2. Update README with setup instructions
3. Create user guide for configuring external providers
4. Update architecture documentation
5. Update CHANGELOG.md
6. Increment version per versioning strategy
**Verification**:
- Discovery links present in HTML
- Documentation accurate and complete
- Version number updated
## Rollback Strategy
### Immediate Rollback
If critical issues found during implementation:
1. **Git Revert**: Revert the removal commits
2. **Database Restore**: Re-run migration 002 to recreate tables
3. **Config Restore**: Revert configuration changes
4. **Test Suite**: Run full test suite to verify restoration
### Gradual Rollback
If issues found in production:
1. **Feature Flag**: Add config flag to toggle between internal/external auth
2. **Dual Mode**: Support both modes temporarily
3. **Migration Path**: Give users time to switch
4. **Deprecation**: Mark internal auth as deprecated
## Testing Strategy
### Unit Tests to Update
- Remove all token generation/validation tests
- Update Micropub tests to mock external verification
- Keep admin authentication tests
### Integration Tests
- Test Micropub with mock external token endpoint
- Test admin login flow (unchanged)
- Test token rejection scenarios
### Manual Testing Checklist
- [ ] Admin can log in via IndieLogin.com
- [ ] Micropub accepts valid Bearer tokens
- [ ] Micropub rejects invalid tokens
- [ ] Micropub rejects tokens with wrong scope
- [ ] Discovery links present in HTML
- [ ] Documentation explains external provider setup
## Acceptance Criteria
### Must Work
1. Admin authentication via IndieLogin.com
2. Micropub token verification via external endpoint
3. Proper error responses for invalid tokens
4. HTML discovery links for IndieAuth endpoints
### Must Not Exist
1. No authorization endpoint (`/auth/authorization`)
2. No token endpoint (`/auth/token`)
3. No authorization consent UI
4. No token storage in database
5. No PKCE implementation
### Performance Criteria
1. Token verification < 500ms (external API call)
2. Consider caching valid tokens for 5 minutes
3. No database queries for token validation
## Version Impact
Per `/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md`:
This is a **breaking change** that removes functionality:
- Removes authorization server endpoints
- Changes token verification method
- Requires external provider configuration
**Version Change**: 0.4.0 → 0.5.0 (minor version bump for breaking change in 0.x)
## Consequences
### Positive
- **Massive Simplification**: ~500+ lines removed
- **Better Security**: Specialized providers handle auth
- **Less Maintenance**: No security updates needed
- **Clearer Architecture**: Pure Micropub server
- **Standards Compliant**: Better separation of concerns
### Negative
- **External Dependency**: Requires internet connection for token verification
- **Latency**: External API calls for each request (mitigate with caching)
- **Not Standalone**: Cannot work in isolated environment
### Neutral
- **User Configuration**: Users must set up external providers (already required)
- **Provider Choice**: Users can choose any IndieAuth provider
## Alternatives Considered
### Keep Internal Auth as Option
**Rejected**: Violates simplicity principle, maintains complexity
### Token Caching/Storage
**Consider**: Cache validated tokens for performance
- Store token hash + expiry in memory/Redis
- Reduce external API calls
- Implement in Phase 4 if needed
### Offline Mode
**Rejected**: Incompatible with external verification
- Could allow "trust mode" for development
- Not suitable for production
## Migration Path for Existing Users
### For Users with Existing Tokens
1. Tokens become invalid after upgrade
2. Must re-authenticate with external provider
3. Document in upgrade notes
### Configuration Changes
```ini
# OLD (remove these)
# AUTHORIZATION_ENDPOINT=/auth/authorization
# TOKEN_ENDPOINT=/auth/token
# NEW (add these)
ADMIN_ME=https://user-domain.com
TOKEN_ENDPOINT=https://tokens.indieauth.com/token
```
### User Communication
1. Announce breaking change in release notes
2. Provide migration guide
3. Explain benefits of simplification
## Success Metrics
### Code Metrics
- Lines of code removed: ~500+
- Test coverage maintained > 90%
- Cyclomatic complexity reduced
### Operational Metrics
- Zero security vulnerabilities in auth code (none to maintain)
- Token verification latency < 500ms
- 100% compatibility with IndieAuth clients
## References
- [IndieAuth Spec](https://www.w3.org/TR/indieauth/)
- [tokens.indieauth.com](https://tokens.indieauth.com/)
- [ADR-021: IndieAuth Provider Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-021-indieauth-provider-strategy.md)
- [Micropub Spec](https://www.w3.org/TR/micropub/)
---
**Document Version**: 1.0
**Created**: 2025-11-24
**Author**: StarPunk Architecture Team
**Status**: Proposed

227
docs/decisions/ADR-051-phase1-test-strategy.md Normal file
View File

@@ -0,0 +1,227 @@
# ADR-051: Phase 1 Test Strategy and Implementation Review
## Status
Accepted
## Context
The developer has completed Phase 1 of the IndieAuth authorization server removal, which involved:
- Removing the `/auth/authorization` endpoint
- Deleting the authorization UI template
- Removing authorization and PKCE-specific test files
- Cleaning up related imports
The implementation has resulted in 539 of 569 tests passing (94.7%), with 30 tests failing. These failures fall into six categories:
1. OAuth metadata endpoint tests (10 tests)
2. State token tests (6 tests)
3. Callback tests (4 tests)
4. Migration tests (2 tests)
5. IndieAuth client discovery tests (5 tests)
6. Development auth tests (1 test)
## Decision
### On Phase 1 Implementation Quality
Phase 1 has been executed correctly and according to plan. The developer properly:
- Removed only the authorization-specific code
- Preserved admin login functionality
- Documented all changes comprehensively
- Identified and categorized all test failures
### On Handling the 30 Failing Tests
**We choose Option A: Delete all 30 failing tests now.**
Rationale:
1. **All failures are expected** - Every failing test is testing functionality we intentionally removed
2. **Clean state principle** - Leaving failing tests creates confusion and technical debt
3. **No value in preservation** - These tests will never be relevant again in V1
4. **Simplified maintenance** - A green test suite is easier to maintain and gives confidence
### On the Overall Implementation Plan
**The 5-phase approach remains correct, but we should accelerate execution.**
Recommended adjustments:
1. **Combine Phases 2 and 3** - Remove token functionality AND database tables together
2. **Keep Phase 4 separate** - External verification is complex enough to warrant isolation
3. **Keep Phase 5 separate** - Documentation deserves dedicated attention
### On Immediate Next Steps
1. **Clean up the 30 failing tests immediately** (before committing Phase 1)
2. **Commit Phase 1 with clean test suite**
3. **Proceed directly to combined Phase 2+3**
## Rationale
### Why Delete Tests Now
- **False positives harm confidence**: Failing tests that "should" fail train developers to ignore test failures
- **Git preserves history**: If we ever need these tests, they're in git history
- **Clear intention**: Deleted tests make it explicit that functionality is gone
- **Faster CI/CD**: No time wasted running irrelevant tests
### Why Accelerate Phases
- **Momentum preservation**: The developer understands the codebase now
- **Reduced intermediate states**: Fewer partially-functional states reduces confusion
- **Coherent changes**: Token removal and database cleanup are logically connected
### Why Not Fix Tests
- **Wasted effort**: Fixing tests for removed functionality is pure waste
- **Misleading coverage**: Tests for non-existent features inflate coverage metrics
- **Future confusion**: Future developers would wonder why we test things that don't exist
## Consequences
### Positive
- **Clean test suite**: 100% passing tests after cleanup
- **Clear boundaries**: Each phase has unambiguous completion
- **Faster delivery**: Combined phases reduce total implementation time
- **Reduced complexity**: Fewer intermediate states to manage
### Negative
- **Larger commits**: Combined phases create bigger changesets
- **Rollback complexity**: Larger changes are harder to revert
- **Testing gaps**: Need to ensure no valid tests are accidentally removed
### Mitigations
- **Careful review**: Double-check each test deletion is intentional
- **Git granularity**: Use separate commits for test deletion vs. code removal
- **Backup branch**: Keep Phase 1 isolated in case rollback needed
## Implementation Instructions
### Immediate Actions (30 minutes)
1. **Delete OAuth metadata tests**:
```bash
# Remove the entire TestOAuthMetadataEndpoint class from test_routes_public.py
# Also remove TestIndieAuthMetadataLink class
```
2. **Delete state token tests**:
```bash
# Review each state token test - some may be testing admin login
# Only delete tests specific to authorization flow
```
3. **Delete callback tests**:
```bash
# Verify these are authorization callbacks, not admin login callbacks
# If admin login, fix them; if authorization, delete them
```
4. **Delete migration tests expecting PKCE**:
```bash
# Update tests to not expect code_verifier column
# These tests should verify current schema, not old schema
```
5. **Delete h-app microformat tests**:
```bash
# Remove all IndieAuth client discovery tests
# These are no longer relevant without authorization endpoint
```
6. **Verify clean suite**:
```bash
uv run pytest
# Should show 100% passing
```
### Commit Strategy
Create two commits:
**Commit 1**: Test cleanup
```bash
git add tests/
git commit -m "test: Remove tests for deleted IndieAuth authorization functionality
- Remove OAuth metadata endpoint tests (no longer serving authorization metadata)
- Remove authorization-specific state token tests
- Remove authorization callback tests
- Remove h-app client discovery tests
- Update migration tests to reflect current schema
All removed tests were for functionality intentionally deleted in Phase 1.
Tests preserved in git history if ever needed for reference."
```
**Commit 2**: Phase 1 implementation
```bash
git add .
git commit -m "feat!: Phase 1 - Remove IndieAuth authorization server
BREAKING CHANGE: Removed built-in IndieAuth authorization endpoint
- Remove /auth/authorization endpoint
- Delete authorization consent UI template
- Remove authorization-related imports
- Clean up PKCE test file
- Update version to 1.0.0-rc.4
This is Phase 1 of 5 in the IndieAuth removal plan.
Admin login functionality remains fully operational.
Token endpoint preserved for Phase 2 removal.
See: docs/architecture/indieauth-removal-phases.md"
```
### Phase 2+3 Combined Plan (Next)
After committing Phase 1:
1. **Remove token endpoint** (`/auth/token`)
2. **Remove token module** (`starpunk/tokens.py`)
3. **Create and run database migration** to drop tables
4. **Remove all token-related tests**
5. **Update version** to 1.0.0-rc.5
This combined approach will complete the removal faster while maintaining coherent system states.
## Alternatives Considered
### Alternative 1: Fix Failing Tests
**Rejected** because:
- Effort to fix tests for removed features is wasted
- Creates false sense that features still exist
- Contradicts the removal intention
### Alternative 2: Leave Tests Failing Until End
**Rejected** because:
- Creates confusion about system state
- Makes it hard to identify real failures
- Violates principle of maintaining green test suite
### Alternative 3: Comment Out Failing Tests
**Rejected** because:
- Dead code accumulates
- Comments tend to persist forever
- Git history is better for preservation
### Alternative 4: Keep Original 5 Phases
**Rejected** because:
- Unnecessary granularity
- More intermediate states to manage
- Slower overall delivery
## Review Checklist
Before proceeding:
- [ ] Verify each deleted test was actually testing removed functionality
- [ ] Confirm admin login tests are preserved and passing
- [ ] Ensure no accidental deletion of valid tests
- [ ] Document test removal in commit messages
- [ ] Verify 100% test pass rate after cleanup
- [ ] Create backup branch before Phase 2+3
## References
- `docs/architecture/indieauth-removal-phases.md` - Original phase plan
- `docs/reports/2025-11-24-phase1-indieauth-server-removal.md` - Phase 1 implementation report
- ADR-030 - External token verification architecture
- ADR-050 - Decision to remove custom IndieAuth server
---
**Decision Date**: 2025-11-24
**Decision Makers**: StarPunk Architecture Team
**Status**: Accepted and ready for immediate implementation