# Data Model: Garmin Authentication State

**Date**: 2025-12-22

This document defines the data model for storing a user's persisted Garmin Connect authentication state, as required by the `Persist Garmin Authentication for Stateless Sync` feature.

## Entity: `GarminAuthenticationState`

This entity represents a user's authenticated session with Garmin Connect. It is designed to be stored in the CentralDB and is associated with a single application user.

### Fields

| Field Name        | Data Type     | Nullable | Description                                                                                              |
| ----------------- | ------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `user_id`           | Foreign Key   | False    | The unique identifier for the application user this authentication state belongs to.                     |
| `session_data`      | Text / Blob   | True     | The serialized, possibly encrypted, session data from the `garth` library. Null if no session is stored. |
| `mfa_pending`       | Boolean       | False    | A flag indicating if the authentication process is currently paused, awaiting an MFA code from the user.   |
| `last_validated`    | Timestamp     | True     | The timestamp when the session was last successfully used to communicate with the Garmin API.            |
| `created_at`        | Timestamp     | False    | The timestamp when this record was created.                                                              |
| `updated_at`        | Timestamp     | False    | The timestamp when this record was last updated.                                                         |

### Relationships

-   **Belongs to**: `User`. A one-to-one relationship exists between a `User` and their `GarminAuthenticationState`.

### State Transitions

The `GarminAuthenticationState` entity can transition through several states:

1.  **Non-existent**: No record exists for the user. This is the initial state.
2.  **MFA Pending**: A record exists with `mfa_pending = true` and `session_data` is likely `null`. This occurs after an initial login attempt triggers an MFA challenge.
3.  **Active / Persisted**: A record exists with `mfa_pending = false` and `session_data` is populated. This is the state for a successfully authenticated user, allowing for stateless background syncs.
4.  **Invalid / Stale**: The `session_data` is present but no longer valid for authentication with Garmin's servers, and it could not be refreshed. This state is not explicitly stored but is determined at runtime, leading to the clearing of the `session_data`.

### Validation Rules

-   `user_id` must correspond to an existing user in the `users` table.
-   `session_data` should be stored in an encrypted format to protect sensitive session information. [NEEDS CLARIFICATION: The encryption method and key management strategy needs to be defined during implementation.]
-   `last_validated` should be updated after every successful background sync or API call to Garmin Connect.