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) |