FitTrack_GarminSync/specs/007-update-the-authentication/plan.md

Implementation Plan: Update Authentication Flow for MFA with garth

Branch: 007-auth-flow-mfa | Date: Thursday, December 19, 2025 | Spec: /home/sstent/Projects/FitTrack/GarminSync/specs/007-update-the-authentication/spec.md Input: Feature specification from /specs/007-update-the-authentication/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

This feature updates the authentication flow to properly handle Multi-Factor Authentication (MFA) using the garth library. The implementation will detect when MFA is required during Garmin Connect authentication, handle MFA challenge/response flow, securely manage garth tokens in CentralDB, and improve error messaging for MFA-related scenarios. This enables users with MFA-enabled Garmin Connect accounts to authenticate successfully through the CLI.

Technical Context

Language/Version: Python 3.13 (Constitution requirement: Python Modernization principle)
Primary Dependencies: garth (for Garmin authentication), garminconnect (for API calls), fastapi (for API), sqlalchemy (for CentralDB access), click (for CLI), httpx (for HTTP client)
Storage: CentralDB (PostgreSQL or SQLite) for garth token storage via SQLAlchemy ORM
Testing: pytest (Constitution requirement: TDD principle) for unit, integration, and API tests
Target Platform: Linux, macOS, Windows server environments (for backend service) and command-line environments (for CLI)
Project Type: Single service with CLI interface
Performance Goals: MFA authentication completes within 2 minutes (per spec SC-002), 95% token reuse rate (per spec SC-004)
Constraints: Secure handling of OAuth tokens, proper MFA challenge handling, resilience to network interruptions
Scale/Scope: Individual user tool with centralized token storage, designed for personal/gym use cases

Constitution Check

GATE: Must pass before Phase 0 research. Re-checked 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/api, src/models, src/services structure)
• Service-Specific Standards:
  • garminsync_service: Compliant (asynchronous processing, OAuth flows for Garmin Connect)
  • cli_interface: Compliant (using Click as required, YAML config, multiple output formats)
  • centraldb_service: Compliant (PostgreSQL/SQLite, SQLAlchemy 2.0+, FastAPI)
• API Standards: Compliant (FastAPI, auto-generated docs, structured errors, API specifications published to APISpecs directory with GarminSync prefix)
• 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 post-design.

Project Structure

Documentation (this feature)

specs/007-update-the-authentication/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

src/
├── models/
│   ├── __init__.py
│   ├── auth.py           # Authentication-related data models (GarthToken, MFACallenge, UserSession)
│   ├── base.py           # Base model with common functionality
│   └── sync_job.py       # Sync job model
├── services/
│   ├── __init__.py
│   ├── auth_service.py   # Authentication service handling garth integration and MFA flow
│   └── sync_service.py   # Sync service
├── api/
│   ├── __init__.py
│   ├── deps.py           # API dependency injection
│   ├── auth.py           # Authentication endpoints with MFA handling
│   └── sync.py           # Sync endpoints
├── db/
│   ├── __init__.py
│   ├── base.py           # Database base
│   ├── models.py         # Database models
│   └── session.py        # Database session management
└── main.py               # FastAPI application entry point

cli/
├── src/
│   ├── __init__.py
│   ├── main.py           # CLI entry point
│   ├── api_client.py     # CLI API client for communication with backend
│   └── commands/
│       ├── __init__.py
│       ├── auth_cmd.py   # Authentication CLI commands with MFA support
│       └── sync_cmd.py   # Sync CLI commands
└── requirements.txt

tests/
├── unit/
│   ├── test_auth_service.py
│   └── test_auth_api.py
├── integration/
│   ├── test_auth_flow.py
│   └── test_mfa_flow.py
└── api/
    └── test_auth_endpoints.py

Structure Decision: Following the existing project structure with enhancements to accommodate the MFA flow requirements. The auth_service will handle the garth integration and MFA challenge/response flow, with secure token storage in CentralDB.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

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