FitTrack_GarminSync/specs/003-loginimprovements-use-the/spec.md

Feature Specification: Garmin Login Improvements

Feature Branch: 003-loginimprovements-use-the
Created: Friday, October 10, 2025
Status: Draft
Input: User description: "Rework the garmin authentication for this app. I want the app to: allow providing a user/pass via the /login endpoint; the app should store the resulting auth tokens and user/pass in the centralDB; the api caller should not need a cookie - all state should be global for the Garmin Sync service"

User Scenarios & Testing (mandatory)

User Story 1 - Initial Garmin Account Setup (Priority: P1)

A user wants to link their Garmin account to the FitTrack Garmin Sync service for the first time. They provide their Garmin credentials via the /login endpoint. The system successfully authenticates with Garmin, stores the credentials and tokens, and confirms the link.

Why this priority: This is the core functionality enabling users to connect their Garmin accounts, which is fundamental to the service.

Independent Test: Can be fully tested by calling the /login endpoint with valid Garmin credentials and verifying that the credentials and tokens are stored in the centralDB and subsequent Garmin Sync operations can proceed.

Acceptance Scenarios:

1. Given the FitTrack Garmin Sync service is running, When a user sends a POST request to /login with valid Garmin username and password, Then the system successfully authenticates with Garmin, stores the Garmin username, plaintext password, and authentication tokens in the centralDB, and returns a success response.
2. Given the FitTrack Garmin Sync service is running, When a user sends a POST request to /login with invalid Garmin username or password, Then the system returns an error response indicating authentication failure and does not store any credentials or tokens.

---

User Story 2 - Automatic Garmin Token Refresh (Priority: P1)

After initial setup, the system automatically manages the Garmin authentication tokens, refreshing them as needed without user intervention, to ensure continuous synchronization with Garmin.

Why this priority: Ensures the service remains operational and data synchronization is uninterrupted, providing a seamless user experience.

Independent Test: Can be tested by simulating an expired token scenario and verifying that the system successfully refreshes the token during a subsequent Garmin API call.

Acceptance Scenarios:

1. Given valid Garmin credentials and tokens are stored in the centralDB, and the current Garmin authentication token is nearing expiration or has expired, When the Garmin Sync service attempts to perform an operation requiring Garmin authentication, Then the system automatically refreshes the Garmin authentication token using the stored credentials, updates the centralDB with the new tokens, and successfully completes the Garmin operation.
2. Given valid Garmin credentials and tokens are stored in the centralDB, and the current Garmin authentication token is valid, When the Garmin Sync service attempts to perform an operation requiring Garmin authentication, Then the system uses the existing valid token without attempting a refresh.

---

User Story 3 - Stateless Garmin Sync Operations (Priority: P1)

The Garmin Sync service operates without relying on session cookies. For every operation requiring Garmin access, it retrieves the necessary authentication tokens from the centralDB based on the single-user context.

Why this priority: This is a core architectural requirement for the service to be stateless and not rely on client-side cookies.

Independent Test: Can be tested by performing multiple Garmin Sync operations (e.g., activity download, health metric sync) and verifying that each operation successfully retrieves credentials from the centralDB and completes without requiring a prior session.

Acceptance Scenarios:

1. Given valid Garmin credentials and tokens are stored in the centralDB, When any Garmin Sync operation is initiated, Then the service retrieves the necessary Garmin authentication tokens from the centralDB for the single user and uses them to authenticate with Garmin.
2. Given no valid Garmin credentials or tokens are stored in the centralDB, When any Garmin Sync operation is initiated, Then the service returns an error indicating that Garmin authentication is required.

Requirements (mandatory)

Functional Requirements

• FR-001: The system MUST expose a /login endpoint that accepts a Garmin username and password.
• FR-002: The system MUST authenticate with Garmin using the provided username and password.
• FR-003: Upon successful Garmin authentication, the system MUST store the Garmin username, plaintext password, and authentication tokens in the centralDB.
• FR-004: The system MUST automatically refresh Garmin authentication tokens when they are expired or nearing expiration.
• FR-005: The system MUST update the centralDB with newly refreshed Garmin authentication tokens.
• FR-006: The system MUST retrieve Garmin authentication tokens from the centralDB for all Garmin Sync operations. The client is not required to send any authentication header for these operations.
• FR-007: The system MUST return an error response to the API caller if Garmin authentication fails (initial login or token refresh).
• FR-008: The system MUST operate as a single-user system, using the single set of stored Garmin credentials for all operations.
• FR-009: The /login endpoint MUST be publicly accessible without prior authentication.

Clarifications

Session 2025-10-10

• Q: How should the client authenticate for subsequent sync operations (e.g., /api/sync/garmin/activities) given that the spec states "the api caller should not need a cookie" and "all state should be global for the Garmin Sync service", but the contract for sync_garmin_activities shows an Authorization: Bearer <token> header? → A: No authentication header is required; the backend implicitly uses the single stored Garmin credentials.

Key Entities (include if feature involves data)

• GarminCredentials: Represents the stored Garmin authentication information.
  • Attributes: garmin_username (string), garmin_password_plaintext (string), access_token (string), access_token_secret (string), token_expiration_date (datetime).
  • Relationship: Stored in centralDB.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Users can successfully link their Garmin account via the /login endpoint within 10 seconds.
• SC-002: Garmin data synchronization operations (e.g., activity download) complete without interruption due to expired tokens for 99.9% of attempts.
• SC-003: The /login endpoint correctly handles invalid Garmin credentials, returning an error response within 2 seconds.
• SC-004: The system maintains continuous Garmin connectivity for 99% of the time without requiring manual re-authentication.