Gondulf/docs/roadmap/v1.0.0.md

# Version 1.0.0 Release Plan

## Release Overview

**Target Version**: 1.0.0
**Release Type**: Initial MVP (Minimum Viable Product)
**Target Date**: TBD (6-8 weeks from project start)
**Status**: Planning

## Release Goals

### Primary Objective
Deliver a production-ready, W3C IndieAuth-compliant authentication server that:
1. Allows users to authenticate using their domain as their identity
2. Supports email-based domain ownership verification
3. Enables any compliant IndieAuth client to authenticate successfully
4. Operates securely in a Docker-based deployment
5. Supports 10s of users with room to scale

### Success Criteria

**Functional**:
- ✅ Complete IndieAuth authentication flow (authorization + token exchange)
- ✅ Email-based domain ownership verification
- ✅ DNS TXT record verification (preferred method)
- ✅ Secure token generation and storage
- ✅ Client metadata fetching (h-app microformat)

**Quality**:
- ✅ 80%+ overall test coverage
- ✅ 95%+ coverage for authentication/token/security code
- ✅ All security best practices implemented
- ✅ Comprehensive documentation

**Operational**:
- ✅ Docker deployment ready
- ✅ Simple SQLite backup strategy
- ✅ Health check endpoint
- ✅ Structured logging

**Compliance**:
- ✅ W3C IndieAuth specification compliance
- ✅ OAuth 2.0 error responses
- ✅ Security headers and HTTPS enforcement

## Feature Scope

### Included Features (P0)

All features listed below are REQUIRED for v1.0.0 release.

| Feature | Size | Effort (days) | Dependencies |
|---------|------|---------------|--------------|
| Core Infrastructure | M | 3-5 | None |
| Database Schema & Storage Layer | S | 1-2 | Core Infrastructure |
| In-Memory Storage | XS | <1 | Core Infrastructure |
| Email Service | S | 1-2 | Core Infrastructure |
| DNS Service | S | 1-2 | Database Schema |
| Domain Service | M | 3-5 | Email, DNS, Database |
| Authorization Endpoint | M | 3-5 | Domain Service, In-Memory |
| Token Endpoint | S | 1-2 | Authorization Endpoint, Database |
| Metadata Endpoint | XS | <1 | Core Infrastructure |
| Email Verification UI | S | 1-2 | Email Service, Domain Service |
| Authorization Consent UI | S | 1-2 | Authorization Endpoint |
| Security Hardening | S | 1-2 | All endpoints |
| Deployment Configuration | S | 1-2 | All features |
| Comprehensive Test Suite | L | 10-14 | All features (parallel) |

**Total Estimated Effort**: 32-44 days of development + testing

### Explicitly Excluded Features

These features are intentionally deferred to post-v1.0.0 releases:

**Excluded (for simplicity)**:
- ❌ PKCE support (planned for v1.1.0, see ADR-003)
- ❌ Token refresh (planned for v1.1.0)
- ❌ Token revocation (planned for v1.1.0)
- ❌ Scope-based authorization (planned for v1.2.0)
- ❌ Rate limiting (planned for v1.1.0)

**Excluded (not needed for MVP)**:
- ❌ Admin dashboard (planned for v1.2.0)
- ❌ Client pre-registration (planned for v1.2.0)
- ❌ Alternative auth providers (GitHub/GitLab) (planned for v1.3.0)
- ❌ WebAuthn support (planned for v2.0.0)
- ❌ PostgreSQL support (planned for v1.2.0)
- ❌ Prometheus metrics (planned for v1.1.0)

**Rationale**: Focus on core authentication functionality with minimal complexity. Additional features add value but increase risk and development time. MVP should prove the concept and gather user feedback.

## Implementation Plan

### Phase 1: Foundation (Week 1-2)

**Goal**: Establish application foundation and core services.

**Features**:
1. Core Infrastructure (M) - 3-5 days
2. Database Schema & Storage Layer (S) - 1-2 days
3. In-Memory Storage (XS) - <1 day
4. Email Service (S) - 1-2 days
5. DNS Service (S) - 1-2 days

**Deliverables**:
- FastAPI application running
- Configuration management working
- SQLite database initialized
- Email sending functional
- DNS queries working
- Unit tests for all services (80%+ coverage)

**Risks**:
- SMTP configuration issues (mitigation: test with real SMTP early)
- DNS query timeouts (mitigation: implement retries and fallback)

**Exit Criteria**:
- All foundation services have passing unit tests
- Application starts without errors
- Health check endpoint returns 200
- Email can be sent successfully
- DNS queries resolve correctly

---

### Phase 2: Domain Verification (Week 2-3)

**Goal**: Implement complete domain ownership verification flows.

**Features**:
1. Domain Service (M) - 3-5 days
2. Email Verification UI (S) - 1-2 days

**Deliverables**:
- TXT record verification working
- Email verification flow complete
- Domain ownership caching in database
- User-facing verification forms
- Integration tests for both verification methods

**Risks**:
- Email delivery failures (mitigation: comprehensive error handling)
- DNS propagation delays (mitigation: cache results, allow retry)
- UI/UX complexity (mitigation: keep forms minimal)

**Exit Criteria**:
- Both verification methods work end-to-end
- TXT record verification preferred when available
- Email fallback works when TXT record absent
- Verification results cached in database
- UI forms accessible and functional

---

### Phase 3: IndieAuth Protocol (Week 3-5)

**Goal**: Implement core IndieAuth endpoints (authorization and token).

**Features**:
1. Authorization Endpoint (M) - 3-5 days
2. Token Endpoint (S) - 1-2 days
3. Metadata Endpoint (XS) - <1 day
4. Authorization Consent UI (S) - 1-2 days

**Deliverables**:
- /authorize endpoint with full validation
- /token endpoint with code exchange
- /.well-known/oauth-authorization-server metadata
- Client metadata fetching (h-app)
- User consent screen
- OAuth 2.0 compliant error responses
- Integration tests for full auth flow

**Risks**:
- Client metadata fetching failures (mitigation: timeouts, fallbacks)
- Open redirect vulnerabilities (mitigation: thorough URL validation)
- State parameter handling (mitigation: clear documentation, tests)

**Exit Criteria**:
- Authorization flow completes successfully
- Tokens generated and validated
- Client metadata displayed correctly
- All parameter validation working
- Error responses compliant with OAuth 2.0
- End-to-end tests pass

---

### Phase 4: Security & Hardening (Week 5-6)

**Goal**: Ensure all security requirements met and production-ready.

**Features**:
1. Security Hardening (S) - 1-2 days
2. Security testing - 2-3 days

**Deliverables**:
- HTTPS enforcement (production)
- Security headers on all responses
- Constant-time token comparison
- Input sanitization throughout
- SQL injection prevention verified
- No PII in logs
- Security test suite (timing attacks, injection, etc.)
- Security documentation review

**Risks**:
- Undiscovered vulnerabilities (mitigation: comprehensive security testing)
- Performance impact of security measures (mitigation: benchmark)

**Exit Criteria**:
- All security tests passing
- Security headers verified
- HTTPS enforced in production
- Timing attack tests pass
- SQL injection tests pass
- No sensitive data in logs
- External security review recommended (optional but encouraged)

---

### Phase 5: Deployment & Testing (Week 6-8)

**Goal**: Prepare for production deployment with comprehensive testing.

**Features**:
1. Deployment Configuration (S) - 1-2 days
2. Comprehensive Test Suite (L) - ongoing
3. Documentation review and updates - 2-3 days
4. Integration testing with real clients - 2-3 days

**Deliverables**:
- Dockerfile with multi-stage build
- docker-compose.yml for testing
- Backup script for SQLite
- Complete environment variable documentation
- 80%+ test coverage achieved
- All documentation reviewed and updated
- Tested with at least one real IndieAuth client
- Release notes prepared

**Risks**:
- Docker build issues (mitigation: test early and often)
- Interoperability issues with clients (mitigation: test multiple clients)
- Documentation gaps (mitigation: external review)

**Exit Criteria**:
- Docker image builds successfully
- Container runs in production-like environment
- All tests passing (unit, integration, e2e, security)
- Test coverage ≥80% overall, ≥95% for critical code
- Successfully authenticates with real IndieAuth client
- Documentation complete and accurate
- Release notes approved

---

## Testing Strategy

### Test Coverage Requirements

**Overall**: 80% minimum coverage
**Critical Paths** (auth, token, security): 95% minimum coverage
**New Code**: 90% coverage required

### Test Levels

**Unit Tests** (70% of test suite):
- All services (Domain, Email, DNS, Auth, Token)
- All utility functions
- Input validation
- Error handling
- Fast execution (<1 minute total)

**Integration Tests** (20% of test suite):
- Endpoint tests (FastAPI TestClient)
- Database operations
- Email sending (mocked SMTP)
- DNS queries (mocked resolver)
- Multi-component workflows

**End-to-End Tests** (10% of test suite):
- Complete authentication flow
- Email verification flow
- TXT record verification flow
- Error scenarios
- OAuth 2.0 error responses

**Security Tests**:
- Timing attack resistance (token verification)
- SQL injection prevention
- XSS prevention (HTML escaping)
- Open redirect prevention
- CSRF protection (state parameter)
- Input validation edge cases

**Compliance Tests**:
- W3C IndieAuth specification adherence
- OAuth 2.0 error response format
- Required parameters validation
- Optional parameters handling

### Test Execution

**Local Development**:
```bash
# All tests
uv run pytest

# With coverage
uv run pytest --cov=src/gondulf --cov-report=html --cov-report=term-missing

# Specific test level
uv run pytest -m unit
uv run pytest -m integration
uv run pytest -m e2e
uv run pytest -m security
```

**CI/CD Pipeline**:
- Run on every commit to main
- Run on all pull requests
- Block merge if tests fail
- Block merge if coverage drops
- Generate coverage reports

**Pre-release**:
- Full test suite execution
- Manual end-to-end testing
- Test with real IndieAuth clients
- Security scan (bandit, pip-audit)
- Performance baseline

---

## Risk Assessment

### High-Risk Areas

**Email Delivery**:
- **Risk**: SMTP configuration issues or delivery failures
- **Impact**: Users cannot verify domain ownership
- **Mitigation**:
  - Comprehensive error handling and logging
  - Test with real SMTP early in development
  - Provide clear error messages to users
  - Support TXT record as primary verification method
- **Contingency**: Admin can manually verify domains if email fails

**Security Vulnerabilities**:
- **Risk**: Security flaws in authentication/authorization logic
- **Impact**: Unauthorized access, data exposure
- **Mitigation**:
  - Follow OAuth 2.0 security best practices
  - Comprehensive security testing
  - External security review (recommended)
  - Conservative defaults
- **Contingency**: Rapid patch release if vulnerability found

**Interoperability**:
- **Risk**: Incompatibility with IndieAuth clients
- **Impact**: Clients cannot authenticate
- **Mitigation**:
  - Strict W3C spec compliance
  - Test with multiple clients
  - Reference implementation comparison
- **Contingency**: Fix and patch release

### Medium-Risk Areas

**Client Metadata Fetching**:
- **Risk**: Timeout or parse failures when fetching client_id
- **Impact**: Poor UX (generic client display)
- **Mitigation**:
  - Aggressive timeouts (5 seconds)
  - Fallback to domain name
  - Cache successful fetches
- **Contingency**: Display warning, continue with basic info

**DNS Resolution**:
- **Risk**: DNS query failures or timeouts
- **Impact**: TXT verification unavailable
- **Mitigation**:
  - Multiple resolvers (Google + Cloudflare)
  - Timeout handling
  - Fallback to email verification
- **Contingency**: Email verification as alternative

**Database Performance**:
- **Risk**: SQLite performance degrades with usage
- **Impact**: Slow response times
- **Mitigation**:
  - Indexes on critical columns
  - Periodic cleanup of expired tokens
  - Benchmark under load
- **Contingency**: Migrate to PostgreSQL if needed (already supported by SQLAlchemy)

### Low-Risk Areas

**Deployment**:
- **Risk**: Docker issues or configuration errors
- **Impact**: Cannot deploy
- **Mitigation**: Test deployment early, document thoroughly

**UI/UX**:
- **Risk**: Forms confusing or inaccessible
- **Impact**: User frustration
- **Mitigation**: Keep forms simple, test accessibility

---

## Release Checklist

### Pre-Release

- [ ] All P0 features implemented
- [ ] All tests passing (unit, integration, e2e, security)
- [ ] Test coverage ≥80% overall, ≥95% critical paths
- [ ] Security scan completed (bandit, pip-audit)
- [ ] Documentation complete and reviewed
- [ ] Tested with real IndieAuth client(s)
- [ ] Docker image builds successfully
- [ ] Deployment tested in production-like environment
- [ ] Environment variables documented
- [ ] Backup/restore procedure tested
- [ ] Release notes drafted
- [ ] Version bumped to 1.0.0 in pyproject.toml

### Security Review

- [ ] HTTPS enforcement verified
- [ ] Security headers present
- [ ] No PII in logs
- [ ] Constant-time comparisons verified
- [ ] SQL injection tests pass
- [ ] Open redirect tests pass
- [ ] CSRF protection verified
- [ ] Timing attack tests pass
- [ ] Input validation comprehensive
- [ ] External security review recommended (optional)

### Documentation Review

- [ ] README.md accurate and complete
- [ ] /docs/architecture/ documents accurate
- [ ] /docs/standards/ documents followed
- [ ] Installation guide tested
- [ ] Configuration guide complete
- [ ] Deployment guide tested
- [ ] API documentation generated (OpenAPI)
- [ ] Troubleshooting guide created

### Deployment Verification

- [ ] Docker image tagged with v1.0.0
- [ ] Docker image pushed to registry
- [ ] Test deployment successful
- [ ] Health check endpoint responds
- [ ] Logging working correctly
- [ ] Backup script functional
- [ ] Environment variables set correctly
- [ ] HTTPS certificate valid

### Release Publication

- [ ] Git tag created: v1.0.0
- [ ] GitHub release created with notes
- [ ] Docker image published
- [ ] Documentation published
- [ ] Announcement prepared (optional)

---

## Post-Release Activities

### Monitoring (First Week)

- Monitor logs for errors
- Track authentication success/failure rates
- Monitor email delivery success
- Monitor DNS query failures
- Monitor response times
- Collect user feedback

### Support

- Respond to bug reports within 24 hours
- Security issues: patch within 24-48 hours
- Feature requests: triage and add to backlog
- Documentation improvements: apply quickly

### Retrospective (After 2 Weeks)

- Review actual vs. estimated effort
- Document lessons learned
- Update estimation baseline
- Identify technical debt
- Plan v1.1.0 features

---

## Version 1.1.0 Preview

Tentative features for next release:

**High Priority**:
- PKCE support (ADR-003 resolution)
- Token revocation endpoint
- Rate limiting (Redis-based)
- Token introspection endpoint

**Medium Priority**:
- Token refresh
- Prometheus metrics
- Enhanced logging

**Technical Debt**:
- Schema migrations (Alembic)
- Redis integration (if scaling needed)

**Target**: 4-6 weeks after v1.0.0 release

---

## Success Metrics

### Release Success

The v1.0.0 release is successful if:

1. **Functional**: At least one real-world user successfully authenticates
2. **Quality**: No critical bugs reported in first week
3. **Security**: No security vulnerabilities reported in first month
4. **Operational**: Server runs stably for 1 week without restarts
5. **Compliance**: Successfully interoperates with ≥2 different IndieAuth clients

### User Success

Users are successful if:

1. Can verify domain ownership (either method) in <5 minutes
2. Can complete authentication flow in <2 minutes
3. Understand what is happening at each step
4. Feel secure about the process
5. Experience no unexpected errors

### Developer Success

Development process is successful if:

1. Actual effort within 20% of estimated effort
2. No major scope changes during development
3. Test coverage goals met
4. No cutting corners on security
5. Documentation kept up-to-date during development

---

## Budget

**Total Estimated Effort**: 32-44 days of development + 10-14 days of testing (parallel)

**Breakdown**:
- Phase 1 (Foundation): 7-11 days
- Phase 2 (Domain Verification): 4-7 days
- Phase 3 (IndieAuth Protocol): 6-9 days
- Phase 4 (Security): 3-5 days
- Phase 5 (Deployment & Testing): 5-8 days
- Testing (parallel throughout): 10-14 days

**Technical Debt Allocation**: 10% = 4-5 days
- Schema migration prep
- Redis integration groundwork
- Documentation improvements

**Total Timeline**: 6-8 weeks (assuming 1 developer, ~5 days/week)

---

## Approval

This release plan requires review and approval by:

- [x] Architect (design complete)
- [ ] Developer (feasibility confirmed)
- [ ] User (scope confirmed)

Once approved, this plan becomes the binding contract for v1.0.0 development.

**Approved by**: TBD
**Approval Date**: TBD
**Development Start Date**: TBD
**Target Release Date**: TBD