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:

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

• 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