Add specification for CentralDB extension to support MFA token management

- Define requirements for garth token storage in CentralDB
- Specify MFA challenge tracking functionality
- Outline database schema changes needed
- Define API endpoints for token management

specs/008-centraldb-mfa-tokens/checklists/requirements.md

@@ -0,0 +1,34 @@
+# Specification Quality Checklist: CentralDB Extension for MFA Token Management
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: Thursday, December 19, 2025
+**Feature**: [/home/sstent/Projects/FitTrack/GarminSync/specs/008-centraldb-mfa-tokens/spec.md](spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs) 
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items have been completed and validated.

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

@@ -0,0 +1,87 @@
+# 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) |

specs/008-centraldb-mfa-tokens/spec.md

@@ -0,0 +1,101 @@
+# Feature Specification: CentralDB Extension for MFA Token Management
+
+**Feature Branch**: `008-centraldb-mfa-tokens`  
+**Created**: Thursday, December 19, 2025  
+**Status**: Draft  
+**Input**: Requirement to extend CentralDB to support garth token management for MFA flow in garminsync
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Secure Garth Token Storage (Priority: P1)
+
+As a GarminSync service, I want to securely store garth authentication tokens (OAuth1/OAuth2) in CentralDB so that users can maintain authenticated sessions across service restarts and authenticate with MFA-enabled accounts.
+
+**Why this priority**: This is fundamental to the entire MFA authentication flow. Without secure token storage, users would need to re-authenticate on every service restart, defeating the purpose of persistent authentication sessions.
+
+**Independent Test**: Can be fully tested by authenticating a user with garth tokens, restarting the service, and verifying that tokens are still available for that user.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user successfully authenticates with garth, **When** tokens are received from garth, **Then** tokens are securely stored in CentralDB with appropriate encryption
+2. **Given** garth tokens exist for a user in CentralDB, **When** the service requests tokens for that user, **Then** the tokens are retrieved and decrypted appropriately
+3. **Given** invalid or expired garth tokens in CentralDB, **When** the service attempts to use them, **Then** appropriate error handling occurs and re-authentication is required
+4. **Given** a user requests logout, **When** the logout process begins, **Then** associated garth tokens are securely removed from CentralDB
+
+### User Story 2 - MFA Challenge Tracking (Priority: P2)
+
+As an administrator of the CentralDB service, I want to track MFA challenges so that the system can properly manage multi-factor authentication flows and prevent abuse.
+
+**Why this priority**: Critical for security and proper MFA flow management. Enables tracking of authentication attempts and prevents brute-force attacks.
+
+**Independent Test**: Can be fully tested by initiating multiple MFA challenges and verifying they are properly tracked, validated, and cleaned up.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user initiates MFA authentication, **When** the challenge is created, **Then** the challenge is stored in CentralDB with appropriate expiration time
+2. **Given** an MFA challenge exists in CentralDB, **When** the correct MFA code is provided, **Then** the challenge is marked as completed and can be consumed
+3. **Given** an MFA challenge exists in CentralDB, **When** the challenge expires, **Then** the challenge is no longer valid and cleaned up automatically
+4. **Given** multiple failed MFA attempts for a challenge, **When** the limit is reached, **Then** the challenge is invalidated and the user must restart authentication
+
+### User Story 3 - Session Management for MFA Flows (Priority: P3)
+
+As a user of the GarminSync service, I want to have my MFA state preserved during the authentication flow so that the system properly tracks my authentication progress.
+
+**Why this priority**: Improves user experience by maintaining authentication state across requests during MFA flow, especially for longer-running flows.
+
+**Independent Test**: Can be fully tested by initiating an MFA flow, checking that the system properly tracks the state, and then completing the flow successfully.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user begins MFA authentication, **When** the session is created, **Then** MFA state is properly recorded in CentralDB
+2. **Given** an MFA session exists in CentralDB, **When** MFA is completed successfully, **Then** the session is updated to reflect MFA completion
+3. **Given** an MFA session exists in CentralDB, **When** MFA fails or times out, **Then** the session is properly cleaned up
+
+### Edge Cases
+
+- What happens when garth token encryption/decryption fails in CentralDB?
+- How does the system handle concurrent MFA attempts for the same user?
+- What occurs if CentralDB is temporarily unavailable during authentication?
+- How does the system handle very large numbers of MFA challenges (potential DoS)?
+- What happens when garth token storage exceeds allocated quotas?
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: CentralDB MUST provide secure storage for garth OAuth1 and OAuth2 tokens with encryption at rest
+- **FR-002**: CentralDB MUST provide API endpoints for storing, retrieving, and deleting garth tokens 
+- **FR-003**: CentralDB MUST track MFA challenges with type, expiration time, and validation status
+- **FR-004**: CentralDB MUST enforce MFA challenge expiration and limit retry attempts
+- **FR-005**: CentralDB MUST associate garth tokens with specific user accounts for proper access control
+- **FR-006**: CentralDB MUST provide API endpoints for MFA challenge creation and validation
+- **FR-007**: CentralDB MUST maintain user session state during MFA authentication flows
+- **FR-008**: CentralDB MUST securely delete garth tokens when users log out or tokens expire
+- **FR-009**: CentralDB MUST prevent replay attacks of valid MFA codes
+- **FR-010**: CentralDB MUST log authentication attempts for security auditing purposes
+
+### Key Entities
+
+- **GarthToken**: Securely stored OAuth tokens (encrypted) with user association and metadata
+- **MFAChallenge**: Tracks authentication challenges including type, destination, status, and expiration
+- **UserSession**: Maintains session state during authentication flows, particularly MFA
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 100% of garth tokens are stored encrypted in CentralDB with FIPS-compliant encryption
+- **SC-002**: Token retrieval operations complete within 100ms for 95% of requests
+- **SC-003**: MFA challenge validation completes within 200ms for 95% of requests
+- **SC-004**: CentralDB handles MFA flows for 10,000 concurrent users without performance degradation
+- **SC-005**: MFA challenge security mechanisms prevent 99.9% of replay and brute-force attempts
+- **SC-006**: 99.9% uptime for token storage/retrieval operations during MFA flows
+
+## Assumptions
+
+- CentralDB uses PostgreSQL or SQLite with appropriate security configurations
+- garth token data follows standard OAuth token formats
+- Encryption at rest is implemented using library-appropriate mechanisms
+- Network communication between GarminSync service and CentralDB is secured
+- Proper access controls exist between services to prevent unauthorized token access
+- GarminSync service has appropriate permissions to access token storage endpoints