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
2026-02-06 06:21:41 +00:00 · 2025-12-19 13:08:28 -08:00
parent 05c41ff1fe
commit eebedaa57c
5 changed files with 540 additions and 0 deletions
--- a/specs/007-update-the-authentication/contracts/auth_mfa_login.yaml
+++ b/specs/007-update-the-authentication/contracts/auth_mfa_login.yaml
@@ -0,0 +1,118 @@
+openapi: 3.0.0
+info:
+  title: GarminSync Authentication API with MFA
+  version: 1.0.0
+  description: API for authenticating users with MFA support using garth
+paths:
+  /api/garmin/login:
+    post:
+      summary: Authenticate user with optional MFA
+      description: Authenticate a user with username and password, with support for MFA challenges
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - username
+                - password
+              properties:
+                username:
+                  type: string
+                  description: User's Garmin Connect username or email
+                password:
+                  type: string
+                  description: User's Garmin Connect password
+                mfa_code:
+                  type: string
+                  description: MFA code if authentication requires it
+      responses:
+        '200':
+          description: Authentication successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: true
+                  session_id:
+                    type: string
+                    description: Unique identifier for the authenticated session
+                  access_token:
+                    type: string
+                    description: Access token for API calls
+                  token_type:
+                    type: string
+                    description: Type of token (e.g., Bearer)
+                  expires_in:
+                    type: integer
+                    description: Time until token expiration in seconds
+                  mfa_required:
+                    type: boolean
+                    description: Whether MFA is required for this account
+                  mfa_challenge_id:
+                    type: string
+                    description: ID for MFA challenge if MFA is required (available in initial response)
+                  user:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        description: User identifier
+                      email:
+                        type: string
+                        description: User's email address
+        '400':
+          description: Invalid credentials or MFA code
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: false
+                  error:
+                    type: string
+                    description: Error message
+                  mfa_required:
+                    type: boolean
+                    description: Whether MFA is required
+                  mfa_challenge_id:
+                    type: string
+                    description: ID for the MFA challenge
+                  mfa_type:
+                    type: string
+                    description: Type of MFA challenge (push, sms, email)
+        '401':
+          description: Authentication failed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: false
+                  error:
+                    type: string
+                    description: Error message
+        '429':
+          description: Too many failed authentication attempts
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                    example: false
+                  error:
+                    type: string
+                    description: Error message
+                  retry_after:
+                    type: integer
+                    description: Seconds to wait before retrying