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

specs/007-update-the-authentication/data-model.md

@@ -0,0 +1,97 @@
+# Data Model: Update Authentication Flow for MFA with garth
+
+## Key Entities
+
+### GarthToken
+Secure authentication tokens (OAuth1 and OAuth2) used for Garmin Connect API access
+
+**Attributes:**
+- `id`: Unique identifier for the token record
+- `user_id`: Identifier of the user this token represents
+- `access_token`: The OAuth2 access token value
+- `refresh_token`: The OAuth2 refresh token value
+- `oauth1_token`: The OAuth1 token data (dictionary format as used by garth)
+- `token_type`: Type of token (usually "Bearer")
+- `expires_in`: Time until expiration in seconds
+- `scope`: Permissions associated with this token
+- `created_at`: Timestamp when token was created
+- `last_used_at`: Timestamp of last usage
+- `mfa_verified`: Boolean indicating if MFA was completed for this token session
+- `is_active`: Boolean indicating if token is currently valid/useable
+- `device_uuid`: UUID of the device where authentication originated (for security)
+
+**Relationships:**
+- Belongs to one User (via user_id foreign key)
+
+### MFAChallenge
+Represents a multi-factor authentication request with type, expiration time, and validation status
+
+**Attributes:**
+- `id`: Unique identifier for the MFA challenge
+- `user_id`: Identifier of the user requesting authentication
+- `session_id`: Session identifier linking to the authentication attempt
+- `challenge_type`: Type of MFA challenge (push, sms, email)
+- `challenge_reference`: Reference identifier from Garmin's MFA service
+- `sent_to`: Destination where MFA was sent (phone number, email address)
+- `status`: Current status (pending, completed, expired, failed)
+- `attempts_count`: Number of attempts made to validate this challenge
+- `expires_at`: Timestamp when the challenge expires
+- `completed_at`: Timestamp when the challenge was completed (if applicable)
+- `created_at`: Timestamp when challenge was initiated
+
+### UserSession
+Represents an authenticated user session with associated garth tokens and permissions
+
+**Attributes:**
+- `id`: Unique session identifier
+- `user_id`: Identifier of the authenticated user
+- `session_token`: Secure session token for internal use
+- `garth_token_id`: Reference to the associated GarthToken
+- `is_mfa_complete`: Boolean indicating if MFA has been completed for this session
+- `mfa_completed_at`: Timestamp when MFA was completed (if applicable)
+- `created_at`: Timestamp when the session was created
+- `last_activity_at`: Timestamp of last activity with this session
+- `expires_at`: Timestamp when the session expires
+- `ip_address`: IP address from which the session was created
+- `user_agent`: User agent string of the client that created the session
+
+**Relationships:**
+- Belongs to one User (via user_id foreign key)
+- References one GarthToken (via garth_token_id foreign key)
+
+## Relationships
+
+1. **User** 1 → * **GarthToken**: A user can have multiple tokens over time (rotation, refresh, etc.)
+2. **User** 1 → * **MFAChallenge**: A user can have multiple MFA challenges (one per auth attempt)
+3. **User** 1 → * **UserSession**: A user can have multiple concurrent sessions
+4. **UserSession** 1 → 1 **GarthToken**: Each session is associated with one active token
+
+## Validation Rules
+
+From Functional Requirements:
+- **FR-005**: garth tokens must be stored securely with appropriate encryption in CentralDB
+- **FR-006**: Tokens must be validated for existence and validity before reuse
+- **FR-007**: Expired tokens must be refreshed automatically when possible, or fail gracefully
+- **FR-008**: MFA challenges must have clear status and expiration times to prevent abuse
+- **FR-009**: MFA challenge types must be properly distinguished and handled
+
+## State Transitions
+
+### MFAChallenge Status Transitions
+- `pending` → `completed` (when correct MFA code is provided)
+- `pending` → `expired` (when challenge exceeds expiration time)
+- `pending` → `failed` (when too many incorrect attempts are made)
+- `completed` → `expired` (after successful authentication has been used sufficiently)
+
+### UserSession States
+- Active session remains valid until `expires_at` timestamp
+- Session can be invalidated early by user logout or security monitoring
+- Session tokens should be invalidated when associated garth tokens are refreshed
+
+## Security Considerations
+
+- GarthToken records should be encrypted at rest in the database
+- MFAChallenge attempts should be rate-limited to prevent brute force attacks
+- Session tokens should use cryptographically secure random generation
+- Token refresh mechanisms should follow OAuth2 best practices
+- Device identification should be used to detect suspicious authentication patterns