FitTrack_GarminSync/specs/008-centraldb-mfa-tokens/plan.md

Implementation Plan: CentralDB Extension for MFA Token Management

Branch: 008-centraldb-mfa-tokens | Date: Thursday, December 19, 2025 | Spec: /home/sstent/Projects/FitTrack/GarminSync/specs/008-centraldb-mfa-tokens/spec.md Input: Feature specification from /specs/008-centraldb-mfa-tokens/spec.md

Summary

This feature extends CentralDB to support secure storage and management of garth OAuth tokens and MFA challenges required for the updated GarminSync authentication flow with MFA support. The implementation adds new database tables, API endpoints, and security measures to handle garth tokens and MFA challenges properly.

Technical Context

Language/Version: Python 3.13 (Constitution requirement: Python Modernization principle)
Primary Dependencies: SQLAlchemy 2.0+ for ORM, FastAPI for API endpoints, cryptography for token encryption, pydantic for data validation
Storage: PostgreSQL or SQLite (consistent with centraldb_service standards) for encrypted garth token storage
Testing: pytest (Constitution requirement: TDD principle) for unit, integration, and API tests
Target Platform: Linux server environments (for CentralDB service)
Project Type: Backend service extension
Performance Goals: Token operations complete within 100ms (per spec SC-002), MFA operations within 200ms (per spec SC-003)
Constraints: Secure token encryption, proper access controls, audit logging for security
Scale/Scope: Multi-tenant token storage supporting 10,000+ concurrent users (per spec SC-004)

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Python Modernization: Compliant (Python 3.13 with type hints)
• Virtual Environment Isolation: Compliant (uses .venv, dependencies pinned)
• Test-Driven Development: Compliant (pytest for testing as required)
• Containerization Standards: Compliant (Docker Compose V3, multi-stage builds)
• Project Structure Standards: Compliant (follows src/models, src/api, src/services structure)
• Service-Specific Standards:
  • centraldb_service: Compliant (PostgreSQL/SQLite, SQLAlchemy 2.0+, FastAPI)
• API Standards: Compliant (FastAPI, auto-generated docs, structured errors)
• Code Quality Standards: Compliant (Black, Flake8, Mypy, Isort as required)
• Dependency Management: Compliant (requirements.txt with pinned dependencies)

All constitution gates pass. No violations detected.

Project Structure

Documentation (this feature)

specs/008-centraldb-mfa-tokens/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (not created by /speckit.plan)
├── data-model.md        # Phase 1 output (not created by /speckit.plan)
├── quickstart.md        # Phase 1 output (not created by /speckit.plan)
├── contracts/           # Phase 1 output (not created by /speckit.plan)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root - extends existing CentralDB)

src/
├── models/
│   ├── __init__.py
│   ├── garth_token.py      # Garth OAuth token model with encryption
│   ├── mfa_challenge.py    # MFA challenge tracking model
│   └── user_session.py     # User session state model for MFA flows
├── services/
│   ├── __init__.py
│   ├── token_service.py    # Garth token management service
│   └── mfa_service.py      # MFA challenge management service
├── api/
│   ├── __init__.py
│   ├── deps.py             # API dependency injection
│   ├── garth_tokens.py     # API endpoints for garth token management
│   └── mfa_challenges.py   # API endpoints for MFA challenge handling
└── db/
    ├── __init__.py
    ├── base.py             # Database base
    ├── models.py           # Database models
    └── session.py          # Database session management
└── encryption.py           # Token encryption utilities

Structure Decision: Extending the existing CentralDB service with new models, services, and API endpoints to support garth token storage and MFA challenge tracking. Following existing project patterns and architecture.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
(None)	(None)	(None)