Gondulf/docs/roadmap/backlog.md

# 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: TD-001 - FastAPI Lifespan Migration (XS)
**Created**: 2025-11-20 (Phase 1 review)
**Priority**: P2
**Component**: Core Infrastructure

**Issue**: Using deprecated `@app.on_event()` decorators instead of lifespan context manager.

**Impact**:
- Deprecation warnings in FastAPI 0.109+
- Will break in future FastAPI version
- Not following current best practices

**Current Mitigation**: Still works in current FastAPI version.

**Effort to Fix**: < 1 day
- Replace `@app.on_event("startup")` with lifespan context manager
- Update database initialization to use lifespan
- Update tests if needed

**Plan**: Address in v1.1.0 or during FastAPI upgrade.

**References**: FastAPI lifespan documentation

---

### DEBT: TD-002 - Database Migration Rollback Safety (S)
**Created**: 2025-11-20 (Phase 1 review)
**Priority**: P2
**Component**: Database Layer

**Issue**: No migration rollback capability. Migrations are one-way only.

**Impact**:
- Cannot easily roll back schema changes
- Requires manual SQL to undo migrations
- Risk during production deployments

**Current Mitigation**: Simple schema, manual SQL backups acceptable for v1.0.0.

**Effort to Fix**: 1-2 days
- Integrate Alembic for migration management
- Create rollback scripts for existing migrations
- Update deployment documentation

**Plan**: Address before v1.1.0 when schema changes become more frequent.

**References**: Alembic documentation

---

### DEBT: TD-003 - Async Email Support (S)
**Created**: 2025-11-20 (Phase 1 review)
**Priority**: P2
**Component**: Email Service

**Issue**: Synchronous SMTP blocks request thread during email sending.

**Impact**:
- Email sending delays response to user (1-5 seconds)
- Thread blocked during SMTP operation
- Poor UX during slow email delivery

**Current Mitigation**: Acceptable for low-volume v1.0.0. Timeout limits (10s) prevent long blocks.

**Effort to Fix**: 1-2 days
- Implement background task queue (FastAPI BackgroundTasks or Celery)
- Make email sending non-blocking
- Update UX to show "Sending email..." message
- Add retry logic for failed sends

**Plan**: Address in v1.1.0 when user volume increases or when UX feedback indicates issue.

**Alternative**: Use async SMTP library (aiosmtplib)

---

### DEBT: TD-004 - Add Redis for Session Storage (M)
**Created**: 2025-11-20 (architectural decision)
**Priority**: P2
**Component**: Storage Layer

**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.

---

## 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)