OAuth-Plan – Step 1B Milestone: Failure & Edge Case Flows

1️⃣ Purpose of This Document

This document completes Step 1B of the OAuth-Plan. It describes how the authentication system behaves when things go wrong: popup issues, Google errors, CSRF problems, missing cookies, expired sessions, and 401 responses during normal usage.

The goal is to have a clear, stable “resilience spec”: for each scenario we define:

How it is detected (frontend + backend)
How the browser UI reacts
How the Flask API responds
What the user sees
What gets logged for future debugging

Step 1B is documentation-only. It does not necessarily mean everything is already implemented exactly like this, but it is the target behaviour specification that later phases will converge to.

2️⃣ Scope: Failure & Edge Case Scenarios

The following scenarios are considered in this milestone:

ID	Scenario	Where It Happens	Primary Symptom
E1	Popup closed before login completes	Browser / Frontend	Promise rejection: "Popup closed"
E2	Google OAuth error (redirect_uri mismatch, consent error, etc.)	Google → Flask callback	Redirect to error page or JSON error from callback
E3	CSRF / state mismatch or missing cookie	Flask callback	`{"error":"csrf_state_mismatch"}` or similar
E4	Session cookie missing/blocked at /auth/me	Browser / Flask	/auth/me returns 401, user seen as logged out
E5	Session lost/expired while user is using the app	Browser / Flask	API starts returning 401 mid-session
E6	BroadcastChannel / popup success notification never received	Browser	Main window “waits” and user experiences confusion
E7	Internal auth exceptions (e.g. parsing id_token, network issues)	Flask auth backend	5xx or structured error JSON

3️⃣ Scenario Specs (Per Error Case)

E1 – Popup Closed Before Login Completes

Frontend UX

Trigger: User closes the Google login popup manually, or the popup is blocked/closed by the browser before successful OAuth completion.
Detection (frontend): loginWithPopup() runs a timer that checks popup.closed. If the popup closes before the auth:success BroadcastChannel message is received, the Promise is rejected with new Error("Popup closed").
Backend behaviour: No request reaches the callback or token exchange; backend remains unaware.
UI behaviour:
- Auth badge remains in “Sign in” state.
- An optional non-intrusive message can be shown (toast / log line): “Sign-in was cancelled or the popup was closed.”
User-facing message (recommended): short info only, no red “error”:
“Sign-in didn’t complete because the popup was closed.”
Logging: console.error("Login failed or cancelled:", err) on the frontend.

E2 – Google OAuth Error (redirect_uri mismatch, consent errors, etc.)

Backend UX

Trigger: Google redirects back with an error, or shows an error page when redirect_uri is not registered or another OAuth configuration problem occurs.
Detection (backend):
- Flask’s google_callback sees query parameters error or fails to exchange the code.
- Authlib raises OAuthError or token exchange fails with HTTP error.
Backend behaviour:
- Return structured JSON such as: {"error":"oauth_error","detail":"..."} , or
- Redirect to a future /auth/error page for better UX (optional improvement).
Frontend behaviour:
- The popup will typically show the Google error or a minimal error page.
- Main window does not receive auth:success, so login remains “not authenticated”.
User-facing message (phase 1B target): “Sign-in with Google failed due to a configuration or consent error.”
Logging:
- Backend logs the underlying OAuth error with stack trace.
- Frontend can log that the popup closed without success.

E3 – CSRF / State Mismatch or Missing Cookie

Backend

Trigger:
- State in callback query does not match state stored in session, or
- No session cookie is present on callback.
Detection (backend):
- request.args.get("state") differs from session["oauth_state_dbg"], or
- Session cookie missing ("session" not in request.cookies).
Backend behaviour (current):
- Return {"error":"csrf_state_missing_cookie"} or {"error":"csrf_state_mismatch"} with HTTP 400.
Frontend behaviour:
- From the user’s point of view, sign-in fails; the popup may show a JSON error or a minimal error page.
- Main window never receives auth:success and stays unauthenticated.
User-facing message (future improvement): “We couldn’t complete sign-in. Please try again. If the problem persists, check that cookies are allowed for rforssen.net.”
Logging:
- Backend logs reason and state values (without leaking secrets).
- Useful for debugging cookie domain / SameSite issues.

E4 – Session Cookie Missing / Blocked at /auth/me

Frontend Backend

Trigger:
- Browser privacy settings or extensions block cookies.
- Invalid domain / SameSite configuration.
- First load in a new browser with no session yet.
Detection:
- GET /api/auth/me returns 401 with {"authenticated": false}.
Backend behaviour:
- Always respond with HTTP 401 + {"authenticated": false} when no session is present.
Frontend behaviour:
- fetchAuth() treats any non-200 as “not authenticated”.
- The auth badge shows a “Sign in” button.
- Protected features that require auth remain unavailable and can show a small lock/tooltip.
UX text (optional hint): “You’re not signed in. Sign in with Google to access your content.”
Logging:
- Frontend: console.warn("Auth probe error:", e) on fetch failures.
- Backend: minimal logging; this is normal behaviour, not an error.

E5 – Session Lost / Expired While Using the App

Frontend Backend UX

Trigger:
- Flask process restarts.
- Server-side session storage cleared.
- Session times out (future policy).
Detection:
- Requests that previously worked (e.g. /api/video_server/get_directories) suddenly start returning 401.
Backend behaviour:
- For any protected endpoint, return HTTP 401 with a consistent JSON structure, e.g.:
  {"ok": false, "error":"not_authenticated","authenticated": false}
Frontend behaviour (target):
- Detect 401 in checkGetDirectoriesAuth() and similar helpers.
- Reset appState.auth to {authenticated:false}.
- Re-render auth badge to “Sign in” state.
- Show a gentle banner: e.g. “Your session has expired. Please sign in again.”
Logging:
- Frontend logs “401 during API call, treating as logged out”.
- Backend may log session expiry in debug mode, but not as a hard error.

E6 – BroadcastChannel / Popup Success Not Received

Frontend

Trigger:
- Browser blocks BroadcastChannel or it behaves inconsistently (older browsers, unusual privacy modes).
- /oauth-popup-complete.html never runs or cannot send the message.
Detection:
- Popup finishes login and closes, but main window never receives auth:success.
- User manually reloads main page and /auth/me now returns authenticated (or not).
Backend behaviour:
- Unaffected – session is correctly set if OAuth succeeded.
Frontend behaviour (target):
- loginWithPopup() currently depends on BroadcastChannel. Future robustness plan:
- After popup closure, optionally perform a fetchAuth() retry to double-check whether login actually completed.
User-facing message: “If the page doesn’t update after login, try reloading.” (optional hint in early phases)
Logging:
- Frontend: console.warn("Popup closed but no auth:success broadcast received").

E7 – Internal Auth Exceptions

Backend

Trigger:
- Network issues towards Google.
- Authlib internal exceptions (e.g. parse_id_token failure).
- Unexpected data from Google.
Detection:
- Unhandled exceptions inside google_callback.
Backend behaviour (current):
- Catch-all block returns {"error":"internal_error","detail": str(e)} with HTTP 500.
Frontend behaviour:
- Popup shows error JSON or a basic error page.
- Main window never receives auth:success.
User-facing message (future, friendlier page): “Something went wrong during sign-in. Please try again in a moment.”
Logging:
- Backend logs full stack trace + context.

4️⃣ Failure-Oriented Sequence Diagram (Mermaid Text)

Generic representation of a failed login attempt (covers E1/E2/E3/E7).

        sequenceDiagram
            participant U as User
            participant B as Browser (Main Window)
            participant P as Popup
            participant API as Flask Auth API
            participant G as Google OAuth

            U->>B: Click "Sign in"
            B->>API: GET /auth/login/google?popup=true
            API-->>G: Redirect to Google OAuth

            G-->>U: Show Google Login Page
            U->>G: Interact (login or cancel)

            alt User closes popup (E1)
                P--xB: <no auth:success>
                B-->>B: Promise reject("Popup closed")
                B-->>U: Stay logged out, show optional message
            else Google / config error (E2)
                G-->>API: Redirect with error
                API-->>P: JSON / error page (oauth_error)
                P--xB: <no auth:success>
                B-->>U: Stay logged out, optional "Sign-in failed" hint
            else CSRF / state mismatch (E3)
                G-->>API: Redirect with invalid/missing state
                API-->>P: 400 {"error":"csrf_state_mismatch"}
                P--xB: <no auth:success>
            else Internal error (E7)
                API->>API: Exception
                API-->>P: 500 {"error":"internal_error"}
                P--xB: <no auth:success>
            end

            Note over B: User remains unauthenticated
auth badge still shows "Sign in"

Figure: Failure-Oriented Sequence Diagram

5️⃣ Session Loss & 401 Handling (Mermaid Text)

This diagram shows mid-session expiry (E5) when the user is already inside the app.

    sequenceDiagram
    participant U as User
    participant B as Browser App
    participant API as Flask API

    U->>B: Interacts with app (clicks "Refresh directories")
    B->>API: GET /api/video_server/get_directories (with cookie)
    API-->>B: 200 OK (authenticated)

    Note over B: Time passes, server restarts or session expires

    U->>B: Interacts again (refresh, analyze, etc.)
    B->>API: GET /api/video_server/get_directories (old cookie)
    API-->>B: 401 {"ok":false, "error":"not_authenticated"}

    B-->>B: Treat user as logged out
    B-->>U: Show banner "Session expired, please sign in again"
    B->>API: (optional) GET /auth/me
    API-->>B: 401 {"authenticated":false}

Figure: PlantUML Popup Authentication Flow

6️⃣ PlantUML – Error Flow Variants

Consolidated PlantUML sequence that shows success vs error branches.

        @startuml
        title OAuth Login - Success vs Failure Variants

        actor User
        participant "Browser (Main Window)" as B
        participant "Popup Window" as P
        participant "Flask API" as API
        participant "Google OAuth" as G

        User -> B: Click "Sign in"
        B -> API: GET /auth/login/google?popup=true
        API -> G: Redirect to Google OAuth
        G -> User: Login / Consent Screen

        alt SUCCESS
        User -> G: Accept / login
        G -> API: Redirect with code
        API -> G: Exchange code -> token
        G -> API: Token + user info
        API -> API: Store session
        API -> P: Redirect /oauth-popup-complete.html
        P -> B: Broadcast auth:success
        B -> API: GET /auth/me
        API -> B: 200 authenticated
        B -> User: UI shows "Signed in"
        else POPUP CLOSED (E1)
        User -> P: Close window
        P -x B: <no auth:success>
        B -> B: Promise reject("Popup closed")
        B -> User: Stay logged out, optional info
        else OAUTH ERROR (E2)
        G -> API: Redirect with error
        API -> P: Show {"error":"oauth_error"}
        P -x B: <no auth:success>
        B -> User: "Sign-in failed"
        else CSRF / STATE MISMATCH (E3)
        G -> API: Redirect with invalid state
        API -> P: 400 {"error":"csrf_state_mismatch"}
        P -x B: <no auth:success>
        else INTERNAL ERROR (E7)
        API -> API: Exception
        API -> P: 500 {"error":"internal_error"}
        P -x B: <no auth:success>
        end

        @enduml

Figure: OAuth Login - Success vs Failure Variants

7️⃣ Behaviour Invariants

To keep behaviour predictable and easy to reason about, the following invariants are defined:

Invariant 1: /api/auth/me is the single source of truth for “is the user authenticated?”.
Invariant 2: Any protected API endpoint that sees no valid session returns HTTP 401 with a stable JSON schema (e.g. {"ok": false, "error": "not_authenticated"}).
Invariant 3: The frontend never tries to guess auth state; it always bases it on fetchAuth() or API responses.
Invariant 4: Popup success is signalled via BroadcastChannel, but the system should tolerate the broadcast failing (future robustness: retry /auth/me upon popup close).
Invariant 5: CSRF/state-related errors are treated as hard failures: user must re-initiate login.

8️⃣ Milestone Status

Step 1B of the OAuth-Plan is now documented.
All major failure and edge-case flows have:

A named scenario ID (E1–E7)
Defined detection behaviour
Defined backend and frontend responses
Mermaid and PlantUML representations for future diagrams

Implementation can now be aligned with this spec, and deviations can be treated as bugs or future design changes.

Next milestone: Step 1C – Environment Split & Redirect-URI / Config Strategy.

OAuth-Plan – Step 1B Milestone

Failure & Edge Case Flow Documentation