feat(core): implement Phase 1 foundation infrastructure
Implements Phase 1 Foundation with all core services: Core Components: - Configuration management with GONDULF_ environment variables - Database layer with SQLAlchemy and migration system - In-memory code storage with TTL support - Email service with SMTP and TLS support (STARTTLS + implicit TLS) - DNS service with TXT record verification - Structured logging with Python standard logging - FastAPI application with health check endpoint Database Schema: - authorization_codes table for OAuth 2.0 authorization codes - domains table for domain verification - migrations table for tracking schema versions - Simple sequential migration system (001_initial_schema.sql) Configuration: - Environment-based configuration with validation - .env.example template with all GONDULF_ variables - Fail-fast validation on startup - Sensible defaults for optional settings Testing: - 96 comprehensive tests (77 unit, 5 integration) - 94.16% code coverage (exceeds 80% requirement) - All tests passing - Test coverage includes: - Configuration loading and validation - Database migrations and health checks - In-memory storage with expiration - Email service (STARTTLS, implicit TLS, authentication) - DNS service (TXT records, domain verification) - Health check endpoint integration Documentation: - Implementation report with test results - Phase 1 clarifications document - ADRs for key decisions (config, database, email, logging) Technical Details: - Python 3.10+ with type hints - SQLite with configurable database URL - System DNS with public DNS fallback - Port-based TLS detection (465=SSL, 587=STARTTLS) - Lazy configuration loading for testability Exit Criteria Met: ✓ All foundation services implemented ✓ Application starts without errors ✓ Health check endpoint operational ✓ Database migrations working ✓ Test coverage exceeds 80% ✓ All tests passing Ready for Architect review and Phase 2 development. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
650
docs/roadmap/backlog.md
Normal file
650
docs/roadmap/backlog.md
Normal file
@@ -0,0 +1,650 @@
|
||||
# Feature Backlog
|
||||
|
||||
This document tracks all planned features for Gondulf, sized using t-shirt sizes based on estimated implementation effort.
|
||||
|
||||
**T-shirt sizes**:
|
||||
- **XS (Extra Small)**: < 1 day of implementation
|
||||
- **S (Small)**: 1-2 days of implementation
|
||||
- **M (Medium)**: 3-5 days of implementation
|
||||
- **L (Large)**: 1-2 weeks of implementation
|
||||
- **XL (Extra Large)**: 2+ weeks (should be broken down)
|
||||
|
||||
**Priority levels**:
|
||||
- **P0**: Required for v1.0.0 (MVP blocker)
|
||||
- **P1**: High priority for post-v1.0.0
|
||||
- **P2**: Medium priority, nice to have
|
||||
- **P3**: Low priority, future consideration
|
||||
|
||||
## v1.0.0 MVP Features (P0)
|
||||
|
||||
These features are REQUIRED for the first production-ready release.
|
||||
|
||||
### Core Infrastructure (M)
|
||||
**What**: Basic FastAPI application structure, configuration management, error handling.
|
||||
|
||||
**Includes**:
|
||||
- FastAPI app initialization
|
||||
- Environment-based configuration (Pydantic Settings)
|
||||
- Logging setup (structured logging)
|
||||
- Error handling middleware
|
||||
- Security headers middleware
|
||||
- Health check endpoint
|
||||
|
||||
**Dependencies**: None
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Application starts successfully
|
||||
- Configuration loads from environment
|
||||
- Logging outputs structured JSON
|
||||
- /health endpoint returns 200 OK
|
||||
- Security headers present on all responses
|
||||
|
||||
**Effort**: 3-5 days
|
||||
|
||||
---
|
||||
|
||||
### Database Schema & Storage Layer (S)
|
||||
**What**: SQLite schema definition and SQLAlchemy Core setup.
|
||||
|
||||
**Includes**:
|
||||
- SQLAlchemy Core connection setup
|
||||
- Schema definition (tokens, domains tables)
|
||||
- Migration approach (simple SQL files for v1.0.0)
|
||||
- Connection pooling
|
||||
- Database initialization script
|
||||
|
||||
**Dependencies**: Core Infrastructure
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Database initializes on first run
|
||||
- Tables created correctly
|
||||
- SQLAlchemy Core queries work
|
||||
- File permissions set correctly (600)
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### In-Memory Storage (XS)
|
||||
**What**: TTL-based in-memory storage for authorization codes and email verification codes.
|
||||
|
||||
**Includes**:
|
||||
- Python dict-based storage with expiration
|
||||
- Automatic cleanup of expired entries
|
||||
- Thread-safe operations (if needed)
|
||||
- Storage interface abstraction (for future Redis migration)
|
||||
|
||||
**Dependencies**: Core Infrastructure
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Codes expire after configured TTL
|
||||
- Expired codes automatically removed
|
||||
- Thread-safe operations
|
||||
- Memory usage bounded
|
||||
|
||||
**Effort**: < 1 day
|
||||
|
||||
---
|
||||
|
||||
### Email Service (S)
|
||||
**What**: SMTP-based email sending for verification codes.
|
||||
|
||||
**Includes**:
|
||||
- SMTP configuration (host, port, credentials)
|
||||
- Email template rendering
|
||||
- Verification code email generation
|
||||
- Error handling (connection failures, send failures)
|
||||
- TLS/STARTTLS support
|
||||
|
||||
**Dependencies**: Core Infrastructure
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Emails sent successfully via configured SMTP
|
||||
- Templates render correctly
|
||||
- Errors logged appropriately
|
||||
- TLS connection established
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### DNS Service (S)
|
||||
**What**: DNS TXT record verification for domain ownership.
|
||||
|
||||
**Includes**:
|
||||
- DNS query implementation (using dnspython)
|
||||
- TXT record validation logic
|
||||
- Multi-resolver consensus (Google + Cloudflare)
|
||||
- Timeout handling
|
||||
- Result caching in database
|
||||
|
||||
**Dependencies**: Database Schema
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- TXT records verified correctly
|
||||
- Multiple resolvers queried
|
||||
- Timeouts handled gracefully
|
||||
- Results cached in database
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### Domain Service (M)
|
||||
**What**: Domain ownership validation and management.
|
||||
|
||||
**Includes**:
|
||||
- Domain normalization
|
||||
- TXT record verification flow
|
||||
- Email verification flow (fallback)
|
||||
- Domain ownership caching
|
||||
- Periodic re-verification (background task)
|
||||
|
||||
**Dependencies**: Email Service, DNS Service, Database Schema
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Both verification methods work
|
||||
- TXT record preferred over email
|
||||
- Verification results cached
|
||||
- Re-verification scheduled correctly
|
||||
|
||||
**Effort**: 3-5 days
|
||||
|
||||
---
|
||||
|
||||
### Authorization Endpoint (M)
|
||||
**What**: `/authorize` endpoint implementing IndieAuth authorization flow.
|
||||
|
||||
**Includes**:
|
||||
- Request parameter validation (me, client_id, redirect_uri, state, response_type)
|
||||
- Client metadata fetching (h-app microformat parsing)
|
||||
- URL validation (open redirect prevention)
|
||||
- User consent form rendering
|
||||
- Authorization code generation
|
||||
- Redirect to client with code + state
|
||||
|
||||
**Dependencies**: Domain Service, In-Memory Storage
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- All parameters validated per spec
|
||||
- Client metadata fetched and displayed
|
||||
- User consent required
|
||||
- Authorization codes generated securely
|
||||
- Redirects work correctly
|
||||
- Errors handled per OAuth 2.0 spec
|
||||
|
||||
**Effort**: 3-5 days
|
||||
|
||||
---
|
||||
|
||||
### Token Endpoint (S)
|
||||
**What**: `/token` endpoint implementing token exchange.
|
||||
|
||||
**Includes**:
|
||||
- Request parameter validation (grant_type, code, client_id, redirect_uri, me)
|
||||
- Authorization code verification
|
||||
- Single-use code enforcement
|
||||
- Access token generation
|
||||
- Token storage (hashed)
|
||||
- JSON response formatting
|
||||
|
||||
**Dependencies**: Authorization Endpoint, Database Schema
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- All parameters validated
|
||||
- Codes verified correctly
|
||||
- Single-use enforced (replay prevention)
|
||||
- Tokens generated securely
|
||||
- Tokens stored as hashes
|
||||
- Response format per spec
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### Metadata Endpoint (XS)
|
||||
**What**: `/.well-known/oauth-authorization-server` discovery endpoint.
|
||||
|
||||
**Includes**:
|
||||
- Static JSON response
|
||||
- Endpoint URLs
|
||||
- Supported features list
|
||||
- Caching headers
|
||||
|
||||
**Dependencies**: Core Infrastructure
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Returns valid JSON per RFC 8414
|
||||
- Correct endpoint URLs
|
||||
- Cache-Control headers set
|
||||
|
||||
**Effort**: < 1 day
|
||||
|
||||
---
|
||||
|
||||
### Email Verification UI (S)
|
||||
**What**: Web forms for email verification flow.
|
||||
|
||||
**Includes**:
|
||||
- Email address input form
|
||||
- Verification code input form
|
||||
- Error message display
|
||||
- Success/failure feedback
|
||||
- Basic styling (minimal, functional)
|
||||
|
||||
**Dependencies**: Email Service, Domain Service
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Forms render correctly
|
||||
- Client-side validation
|
||||
- Error messages clear
|
||||
- Accessible (WCAG AA)
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### Authorization Consent UI (S)
|
||||
**What**: User consent screen for authorization.
|
||||
|
||||
**Includes**:
|
||||
- Client information display (name, icon, URL)
|
||||
- Domain identity display (me parameter)
|
||||
- Approve/Deny buttons
|
||||
- Security warnings (if redirect_uri differs)
|
||||
- Basic styling (minimal, functional)
|
||||
|
||||
**Dependencies**: Authorization Endpoint
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Client info displayed correctly
|
||||
- User can approve/deny
|
||||
- Security warnings shown when appropriate
|
||||
- Accessible (WCAG AA)
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### Security Hardening (S)
|
||||
**What**: Implementation of all v1.0.0 security requirements.
|
||||
|
||||
**Includes**:
|
||||
- HTTPS enforcement (production)
|
||||
- Security headers (HSTS, CSP, etc.)
|
||||
- Constant-time token comparison
|
||||
- Input sanitization
|
||||
- SQL injection prevention (parameterized queries)
|
||||
- Logging security (no PII)
|
||||
|
||||
**Dependencies**: All endpoints
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- HTTPS enforced in production
|
||||
- All security headers present
|
||||
- No timing attack vulnerabilities
|
||||
- No SQL injection vulnerabilities
|
||||
- Logs contain no PII
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### Deployment Configuration (S)
|
||||
**What**: Docker setup and deployment documentation.
|
||||
|
||||
**Includes**:
|
||||
- Dockerfile (multi-stage build)
|
||||
- docker-compose.yml (for testing)
|
||||
- Environment variable documentation
|
||||
- Backup script (SQLite file copy)
|
||||
- Health check configuration
|
||||
|
||||
**Dependencies**: All features
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Docker image builds successfully
|
||||
- Container runs properly
|
||||
- Environment variables documented
|
||||
- Backup script works
|
||||
- Health checks pass
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### Comprehensive Test Suite (L)
|
||||
**What**: 80%+ code coverage with unit, integration, and e2e tests.
|
||||
|
||||
**Includes**:
|
||||
- Unit tests for all services
|
||||
- Integration tests for endpoints
|
||||
- End-to-end IndieAuth flow tests
|
||||
- Security tests (timing attacks, injection, etc.)
|
||||
- Compliance tests (W3C spec verification)
|
||||
|
||||
**Dependencies**: All features
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- 80%+ overall coverage
|
||||
- 95%+ coverage for auth/token/security code
|
||||
- All tests passing
|
||||
- Fast execution (< 1 minute for unit tests)
|
||||
|
||||
**Effort**: 1-2 weeks (parallel with development)
|
||||
|
||||
---
|
||||
|
||||
## Post-v1.0.0 Features
|
||||
|
||||
### PKCE Support (S)
|
||||
**Priority**: P1
|
||||
**Dependencies**: Token Endpoint
|
||||
|
||||
**What**: Implement Proof Key for Code Exchange (RFC 7636) for enhanced security.
|
||||
|
||||
**Includes**:
|
||||
- Accept `code_challenge` and `code_challenge_method` in /authorize
|
||||
- Validate `code_verifier` in /token
|
||||
- Support S256 challenge method
|
||||
- Update metadata endpoint
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
**Rationale**: Deferred from v1.0.0 per ADR-003 for MVP simplicity. Should be added in v1.1.0.
|
||||
|
||||
---
|
||||
|
||||
### Token Revocation (S)
|
||||
**Priority**: P1
|
||||
**Dependencies**: Token Endpoint
|
||||
|
||||
**What**: `/token/revoke` endpoint per RFC 7009.
|
||||
|
||||
**Includes**:
|
||||
- Revocation endpoint implementation
|
||||
- Mark tokens as revoked in database
|
||||
- Return appropriate responses
|
||||
- Update metadata endpoint
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### Token Refresh (M)
|
||||
**Priority**: P1
|
||||
**Dependencies**: Token Endpoint
|
||||
|
||||
**What**: Refresh token support for long-lived sessions.
|
||||
|
||||
**Includes**:
|
||||
- Refresh token generation and storage
|
||||
- `refresh_token` grant type support
|
||||
- Rotation of refresh tokens (security best practice)
|
||||
- Expiration management
|
||||
|
||||
**Effort**: 3-5 days
|
||||
|
||||
---
|
||||
|
||||
### Rate Limiting (M)
|
||||
**Priority**: P1
|
||||
**Dependencies**: Core Infrastructure
|
||||
|
||||
**What**: Request rate limiting to prevent abuse.
|
||||
|
||||
**Includes**:
|
||||
- Redis-based rate limiting
|
||||
- Per-endpoint limits
|
||||
- Per-IP and per-client_id limits
|
||||
- Exponential backoff on failures
|
||||
- Rate limit headers (X-RateLimit-*)
|
||||
|
||||
**Effort**: 3-5 days
|
||||
|
||||
**Note**: Requires Redis, breaking single-process assumption.
|
||||
|
||||
---
|
||||
|
||||
### Admin Dashboard (L)
|
||||
**Priority**: P2
|
||||
**Dependencies**: All v1.0.0 features
|
||||
|
||||
**What**: Web-based admin interface for server management.
|
||||
|
||||
**Includes**:
|
||||
- Active tokens view
|
||||
- Domain verification status
|
||||
- Revoke tokens manually
|
||||
- View audit logs
|
||||
- Configuration management
|
||||
|
||||
**Effort**: 1-2 weeks
|
||||
|
||||
---
|
||||
|
||||
### Client Pre-Registration (M)
|
||||
**Priority**: P2
|
||||
**Dependencies**: Authorization Endpoint
|
||||
|
||||
**What**: Allow admin to pre-register known clients.
|
||||
|
||||
**Includes**:
|
||||
- Client registration UI (admin-only)
|
||||
- Store registered clients in database
|
||||
- Skip metadata fetching for registered clients
|
||||
- Manage redirect URIs per client
|
||||
|
||||
**Effort**: 3-5 days
|
||||
|
||||
**Note**: Not required per spec, but useful for trusted clients.
|
||||
|
||||
---
|
||||
|
||||
### Token Introspection (S)
|
||||
**Priority**: P1
|
||||
**Dependencies**: Token Endpoint
|
||||
|
||||
**What**: `/token/verify` endpoint for resource servers.
|
||||
|
||||
**Includes**:
|
||||
- Verify token validity
|
||||
- Return token metadata (me, client_id, scope)
|
||||
- Support Bearer authentication
|
||||
- Rate limiting
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### Scope Support (Authorization) (L)
|
||||
**Priority**: P1
|
||||
**Dependencies**: Token Endpoint, Token Introspection
|
||||
|
||||
**What**: Full OAuth 2.0 scope-based authorization.
|
||||
|
||||
**Includes**:
|
||||
- Scope validation and parsing
|
||||
- Scope consent UI (checkboxes)
|
||||
- Token scope storage and verification
|
||||
- Scope-based access control
|
||||
- Standard scopes (profile, email, create, update, delete)
|
||||
|
||||
**Effort**: 1-2 weeks
|
||||
|
||||
**Note**: Major feature, expands from authentication to authorization.
|
||||
|
||||
---
|
||||
|
||||
### GitHub/GitLab Providers (M)
|
||||
**Priority**: P2
|
||||
**Dependencies**: Domain Service
|
||||
|
||||
**What**: Alternative authentication via GitHub/GitLab (like IndieLogin).
|
||||
|
||||
**Includes**:
|
||||
- OAuth 2.0 client for GitHub/GitLab
|
||||
- Link GitHub username to domain (via profile URL)
|
||||
- Verify domain ownership via GitHub/GitLab profile
|
||||
- Provider selection UI
|
||||
|
||||
**Effort**: 3-5 days
|
||||
|
||||
**Note**: Per user request, email-only in v1.0.0. This is future enhancement.
|
||||
|
||||
---
|
||||
|
||||
### WebAuthn Support (L)
|
||||
**Priority**: P2
|
||||
**Dependencies**: Domain Service
|
||||
|
||||
**What**: Passwordless authentication via WebAuthn (FIDO2).
|
||||
|
||||
**Includes**:
|
||||
- WebAuthn registration flow
|
||||
- WebAuthn authentication flow
|
||||
- Credential storage
|
||||
- Browser compatibility
|
||||
- Fallback to email
|
||||
|
||||
**Effort**: 1-2 weeks
|
||||
|
||||
---
|
||||
|
||||
### PostgreSQL Support (S)
|
||||
**Priority**: P2
|
||||
**Dependencies**: Database Schema
|
||||
|
||||
**What**: Support PostgreSQL as alternative to SQLite.
|
||||
|
||||
**Includes**:
|
||||
- Connection configuration
|
||||
- Schema adaptation (minimal changes)
|
||||
- Migration from SQLite
|
||||
- Documentation
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
**Note**: SQLAlchemy Core makes this trivial.
|
||||
|
||||
---
|
||||
|
||||
### Prometheus Metrics (S)
|
||||
**Priority**: P2
|
||||
**Dependencies**: Core Infrastructure
|
||||
|
||||
**What**: `/metrics` endpoint for Prometheus scraping.
|
||||
|
||||
**Includes**:
|
||||
- Request counters (by endpoint, status)
|
||||
- Response time histograms
|
||||
- Token generation rate
|
||||
- Email send success rate
|
||||
- Error rate by type
|
||||
|
||||
**Effort**: 1-2 days
|
||||
|
||||
---
|
||||
|
||||
### Internationalization (M)
|
||||
**Priority**: P3
|
||||
**Dependencies**: UI components
|
||||
|
||||
**What**: Multi-language support for user-facing pages.
|
||||
|
||||
**Includes**:
|
||||
- i18n framework (Babel)
|
||||
- English (default)
|
||||
- Extract translatable strings
|
||||
- Translation workflow
|
||||
|
||||
**Effort**: 3-5 days
|
||||
|
||||
**Note**: Low priority, English-first acceptable for MVP.
|
||||
|
||||
---
|
||||
|
||||
## Technical Debt
|
||||
|
||||
Technical debt items are tracked here with a DEBT: prefix. Per project standards, each release must allocate at least 10% of effort to technical debt reduction.
|
||||
|
||||
### DEBT: Add Redis for session storage (M)
|
||||
**Created**: 2025-11-20 (architectural decision)
|
||||
**Priority**: P2
|
||||
|
||||
**Issue**: In-memory storage doesn't survive restarts.
|
||||
|
||||
**Impact**: Authorization codes and email codes lost on restart.
|
||||
|
||||
**Mitigation (current)**: Codes are short-lived (10-15 min), restart impact minimal.
|
||||
|
||||
**Effort to Fix**: 3-5 days (Redis integration, deployment changes)
|
||||
|
||||
**Plan**: Address when scaling beyond single process or when restarts become frequent.
|
||||
|
||||
---
|
||||
|
||||
### DEBT: Implement schema migrations (S)
|
||||
**Created**: 2025-11-20 (architectural decision)
|
||||
**Priority**: P2
|
||||
|
||||
**Issue**: No formal migration system, using raw SQL files.
|
||||
|
||||
**Impact**: Schema changes require manual intervention.
|
||||
|
||||
**Mitigation (current)**: Simple schema, infrequent changes acceptable for v1.0.0.
|
||||
|
||||
**Effort to Fix**: 1-2 days (Alembic integration)
|
||||
|
||||
**Plan**: Address before v1.1.0 when schema changes become more frequent.
|
||||
|
||||
---
|
||||
|
||||
## Backlog Management
|
||||
|
||||
### Adding New Features
|
||||
|
||||
When adding features to the backlog:
|
||||
1. Define clear scope and acceptance criteria
|
||||
2. Assign t-shirt size
|
||||
3. Assign priority (P0-P3)
|
||||
4. Identify dependencies
|
||||
5. Estimate effort in days
|
||||
6. Add to appropriate section
|
||||
|
||||
### Prioritization Criteria
|
||||
|
||||
Features are prioritized based on:
|
||||
1. **MVP requirement**: Is it required for v1.0.0?
|
||||
2. **Security impact**: Does it improve security?
|
||||
3. **User value**: How much does it benefit users?
|
||||
4. **Complexity**: Simpler features prioritized when value equal
|
||||
5. **Dependencies**: Features blocking others prioritized
|
||||
|
||||
### Technical Debt Policy
|
||||
|
||||
- Minimum 10% effort per release allocated to technical debt
|
||||
- Technical debt items must have:
|
||||
- Creation date
|
||||
- Issue description
|
||||
- Current impact and mitigation
|
||||
- Effort to fix
|
||||
- Resolution plan
|
||||
- Debt reviewed quarterly, re-prioritized based on impact
|
||||
|
||||
## Version Planning
|
||||
|
||||
See version-specific roadmap files:
|
||||
- `/docs/roadmap/v1.0.0.md` - MVP features and plan
|
||||
- `/docs/roadmap/v1.1.0.md` - First post-MVP release (future)
|
||||
- `/docs/roadmap/v2.0.0.md` - Major feature release (future)
|
||||
|
||||
## Estimation Accuracy
|
||||
|
||||
After each feature implementation, review estimation accuracy:
|
||||
- Compare actual effort vs. estimated
|
||||
- Update t-shirt size if significantly different
|
||||
- Document lessons learned
|
||||
- Adjust future estimates accordingly
|
||||
|
||||
Current estimation baseline: TBD (will be established after v1.0.0 completion)
|
||||
Reference in New Issue
Block a user