Saltar a contenido

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.

Interaction Spec: User Authentication & Session Management Flow

1. Overview & System Goal

Goal

Authenticate user credentials via email/password or OAuth providers (GitHub, Google), issue cryptographically signed RS256 JWT access tokens (15-minute expiration) and refresh tokens (30-day expiration), securely cache tokens in platform-native encrypted storage, and maintain silent session restoration across application restarts.

Primary Actors

  • User: Software developer, architect, or engineering lead.
  • :docugraph-app Client (FE-01 LoginForm): Compose Multiplatform UI component.
  • Platform Secure Storage: Native encrypted keychain (EncryptedSharedPreferences on Android, iOS Keychain, Secret Service / Keyring on Desktop).
  • :docugraph-backend Service (BE-01 auth.login): Ktor asynchronous HTTP service handling authentication routines.
  • PostgreSQL Database (table: users): Relational user credential store (SCHEMA-01).

3. State Transition Model

stateDiagram-v2
    [*] --> Unauthenticated
    Unauthenticated --> Authenticating: Submit Form / Silent Refresh Triggered
    Authenticating --> Authenticated: HTTP 200 OK (Tokens Issued & Cached)
    Authenticating --> AuthError: HTTP 401 / Network Failure
    AuthError --> Authenticating: Retry Form Submission
    AuthError --> Unauthenticated: Form Cleared / Refresh Token Expired
    Authenticated --> Unauthenticated: User Logout / Refresh Token Revoked

State Matrix Definitions

State Name UI Form State (FE-01) Storage State Backend Connection State Next Available Actions
Unauthenticated Interactive input fields enabled; submit button active. Empty or expired refresh token. Disconnected / Idle. Enter email/password; click "Log In"; trigger OAuth.
Authenticating Form inputs disabled; loading spinner rendered on submit button. Tokens unchanged. HTTP POST /api/v1/auth/login request in flight. Cancel request.
Authenticated Form hidden; UI transitions to FE-02 ProjectDashboard. Access & Refresh JWTs stored in platform secure storage. Authenticated Bearer header attached to requests. Open workspace; access MCP tools; click "Logout".
AuthError Form re-enabled; red inline banner displayed below fields. Clear invalid tokens. HTTP 401 / 423 / 500 returned. Edit credentials; re-submit form; reset password.

4. Interaction Sequence & Data Payloads

sequenceDiagram
    autonumber
    actor User
    participant FE as FE-01 (LoginForm)
    participant Sec as Platform Secure Storage
    participant BE as BE-01 (Ktor Auth Engine)
    participant DB as DB (table: users)

    alt Startup Silent Refresh Flow
        FE->>Sec: Read cached refresh_token
        Sec-->>FE: Return refresh_token (or null)
        opt Refresh Token Present
            FE->>BE: POST /api/v1/auth/refresh { refresh_token }
            alt Valid Refresh Token
                BE-->>FE: 200 OK { access_token, refresh_token, user }
                FE->>Sec: Write updated tokens
                FE-->>User: Navigate directly to FE-02 ProjectDashboard
            else Expired / Invalid Refresh Token
                BE-->>FE: 401 Unauthorized { code: "REFRESH_EXPIRED" }
                FE->>Sec: Purge expired tokens
            end
        end
    end

    User->>FE: Input email & password, click "Log In"
    FE->>FE: Validate client-side input rules (valid email format, non-empty)
    FE->>BE: POST /api/v1/auth/login (operationId: loginUser)
    Note over FE,BE: Payload: { email, password }
    BE->>DB: SELECT * FROM users WHERE email = ?
    DB-->>BE: User Record & Argon2id Hash
    BE->>BE: Verify Argon2id password hash against input
    alt Valid Credentials
        BE-->>FE: 200 OK { access_token, refresh_token, expires_in: 900, user }
        FE->>Sec: Save access_token & refresh_token securely
        FE-->>User: Transition to Authenticated & Navigate to FE-02 ProjectDashboard
    else Invalid Credentials
        BE-->>FE: 401 Unauthorized { code: "INVALID_CREDENTIALS", message }
        FE-->>User: Display inline error banner on FE-01
    end

Data Payloads

1. Authentication Request Payload (POST /api/v1/auth/login)

{
  "email": "architect@docugraph.io",
  "password": "SecurePassword123!"
}

2. Authentication Success Response (HTTP 200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "d9f8e7c6b5a43210...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": "usr_01H123456789",
    "email": "architect@docugraph.io",
    "full_name": "Elena Rostova",
    "entitlement": "pro_tier"
  }
}

5. Error Handling Matrix

Error Code HTTP Status Cause UI Behavior on FE-01 Recovery Action
INVALID_CREDENTIALS 401 Unauthorized Email not found or Argon2id password mismatch. Show inline banner: "Invalid email or password." Highlight input fields in red. User re-enters correct email and password.
ACCOUNT_LOCKED 423 Locked 5 consecutive failed login attempts within 15 mins. Show modal warning: "Account locked for security. Retry in 15 minutes." Disable form submit button for 15 minutes.
INVALID_INPUT_FORMAT 400 Bad Request Email regex failure or password field empty. Show helper text: "Please enter a valid email address." User corrects formatting error before submitting.
NETWORK_UNAVAILABLE 0 Timeout Internet connection lost or server unreachable. Show banner: "Unable to reach server. Please check your network connection." Retry request automatically when network restores.
SERVER_ERROR 500 Internal Error Unhandled backend exception or DB connection failure. Show toast notification: "An unexpected error occurred. Please try again later." Log exception details for administrative audit.

6. Traceability Index