mirror of
https://github.com/sstent/FitTrack_GarminSync.git
synced 2026-02-05 22:11:44 +00:00
Complete implementation planning for MFA authentication with garth
- Created detailed implementation plan with technical context - Developed data models for GarthToken, MFAChallenge, and UserSession entities - Defined API contracts for MFA authentication flow - Created quickstart guide for implementation - Updated agent context with new technology stack - Verified constitution compliance for all design decisions
This commit is contained in:
112
specs/007-update-the-authentication/plan.md
Normal file
112
specs/007-update-the-authentication/plan.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# 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) |
|
||||
Reference in New Issue
Block a user