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)