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

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