User Story: Authentication & Session Management

Catálogo histórico

Este documento no forma parte del modo operativo. El filtro del menú lo oculta por defecto.

Estado de fase (MASTER-00): POST_MVP — documento de catálogo de producto sujeto a validación; no es alcance aprobado de Gate 0 / PoC / MVP. Gobernanza: MASTER-00.

User Story: Authentication & Session Management

---

User Story Statement

As a registered developer, architect, or engineering manager,
I want to securely log into DocuGraph via email/password or OAuth (GitHub/Google) and maintain an authenticated session across application restarts,
So that my documentation projects, cloud sync settings, and RevenueCat Pro entitlements remain secure and accessible across devices.

---

Business Rationale & User Impact

Authentication is the primary security gatekeeper for DocuGraph. It establishes identity for cloud-synchronized projects, secures API key generation for MCP server access, and links the user’s account to their RevenueCat subscription state (US-06). Without secure authentication and persistent sessions, multi-device cloud synchronization and entitlement verification described in VISION-00 cannot function.

---

User Flow & Interaction Overview

1. User launches DocuGraph client application (:docugraph-app).
2. App checks encrypted local storage for an active, valid JWT refresh token.
3. If valid, the session is silently re-authenticated, bypassing the login UI.
4. If invalid or missing, the user is presented with the Login UI (FE-01).
5. User enters email/password or selects GitHub/Google OAuth login.
6. Frontend validates input and dispatches authentication request to backend endpoint operationId: loginUser.
7. Backend validates credentials against database (table: users), returns access token (15-min TTL) and refresh token (30-day TTL).
8. Client stores tokens in platform secure storage (Android EncryptedSharedPreferences, iOS Keychain, Desktop Encrypted Store) and transitions to Project Dashboard (FE-02).

---

Acceptance Criteria (Gherkin Format)

Scenario 1: Valid Credentials Login

Given the user is on the Login Screen with valid email "architect@docugraph.io" and correct password
When the user submits the login form
Then the client dispatches a POST request to the authentication endpoint (operationId: loginUser)
And upon receiving a 200 OK HTTP response with JWT access and refresh tokens
Then the tokens are stored in the platform's secure storage
And the application navigates to the Project Dashboard screen (FE-02) with active session state

Scenario 2: Invalid Credentials Handling

Given the user enters an unregistered email or incorrect password
When the user submits the login form
Then the authentication endpoint (operationId: loginUser) returns a 401 Unauthorized response with error code "INVALID_CREDENTIALS"
And an inline error message "Invalid email or password" is displayed on the Login Screen
And no session tokens are stored in local secure storage

Scenario 3: Automatic Session Persistence across Application Restarts

Given a previously authenticated user with a valid refresh token stored in platform secure storage
When the user launches the DocuGraph application
Then the client automatically issues a silent token refresh request
And upon success, the session state is restored without prompting the user for login credentials
And the application directly displays the Project Dashboard screen (FE-02)

Scenario 4: Secure User Logout

Given an actively authenticated user session on the Project Dashboard
When the user clicks the "Logout" button in the account settings menu
Then the stored access token and refresh token are permanently revoked and wiped from platform secure storage
And the active session state is cleared from application memory
And the application immediately redirects the user back to the Login Screen (FE-01)

---

Functional Requirements & Constraints

1. Security: Passwords must be hashed server-side using Argon2id or bcrypt with a minimum work factor of 12.
2. Token Format: Access tokens must be signed RS256 JWTs containing claims for user_id, email, and entitlement.
3. Multiplatform Storage:
   • Android: EncryptedSharedPreferences via AndroidX Security library.
   • iOS: Keychain Services API.
   • Desktop JVM: Operating system native key store (Keyring / Credential Manager) with AES-256 encrypted local fallback file.

---

Downstream Atomic Mapping

This User Story serves as the direct upstream source of truth for the following downstream specifications:

• Interaction Specification: IX-01_login-flow.md (IX-01) — Step-by-step user interaction, state transitions, and UI error states.
• Backend Specification: BE-01_auth-login.md (BE-01) — Ktor route handler for POST /api/v1/auth/login.
• API Contract: openapi.yaml — Single source of truth for REST endpoint with operationId: loginUser.
• Frontend Specification: FE-01_login-form.md (FE-01) — Compose Multiplatform LoginForm composable component.
• Database Schema: 01_DATABASE_SCHEMA.md (table: users) — Relational user accounts table.

---

Traceability Index

• Upstream Dependencies:
  • docs/00_BUSINESS_VISION.md (VISION-00) — Core Business Vision & Security Gatekeeping.
• Downstream Direct Linkages (Planned M2/M3):
  • IX-01_login-flow.md (IX-01)
  • BE-01_auth-login.md (BE-01)
  • FE-01_login-form.md (FE-01)
• Related Stories:
  • US-02_create_project.md (US-02) — Project creation requiring authenticated session.
  • US-06_revenuecat_pro.md (US-06) — Entitlement verification bound to user identity.