FitTrack_GarminSync/specs/006-cli-auth-sync-mfa/data-model.md

Data Model: CLI App for API Interaction with MFA

Key Entities

User Session

Represents an authenticated user session with associated tokens and permissions

Attributes:

• session_id: Unique identifier for the session
• user_id: Identifier for the authenticated user
• access_token: JWT or API token for authenticated requests
• refresh_token: Token used to refresh the access token
• expires_at: Timestamp when the access token expires
• mfa_enabled: Boolean indicating if MFA is required for this session
• created_at: Timestamp when the session was created
• last_used_at: Timestamp of last activity with this session

Sync Job

Represents an initiated sync operation with status, progress, and metadata

Attributes:

• job_id: Unique identifier for the sync job
• user_id: Identifier of the user who initiated the job
• status: Current status (pending, running, completed, failed, cancelled)
• progress: Percentage of completion (0-100)
• start_time: Timestamp when the sync started
• end_time: Timestamp when the sync completed (if completed)
• sync_type: Type of sync (activities, health, workouts, etc.)
• error_message: Error details if the job failed
• total_items: Total number of items to sync
• processed_items: Number of items processed so far

Authentication Token

Secure credential used to access the API on behalf of the user

Attributes:

• token_id: Unique identifier for the token
• user_id: Identifier of the user this token represents
• access_token: The actual access token value
• token_type: Type of token (Bearer, etc.)
• 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

Relationships

1. User Session 1 → * Sync Job: A user session can have multiple sync jobs
2. Authentication Token 1 → 1 User Session: Each session is associated with one primary auth token

Validation Rules

From Functional Requirements:

• FR-005: Authentication tokens must be stored securely with appropriate file permissions
• FR-008: Expired tokens must be refreshed automatically when possible
• FR-007: All operations must provide clear feedback on success or failure

State Transitions

Sync Job Status Transitions

• pending → running (when sync starts)
• running → completed (when sync finishes successfully)
• running → failed (when sync encounters an error)
• pending → cancelled (when user cancels before start)
• running → cancelled (when user cancels during execution)

Session Expiration

• Active session remains valid until expires_at timestamp
• Session marked as invalid after expiration
• Automatic refresh attempted if refresh token exists