Project: Stack Trading BA in Charge: Trang Nguyen Date Created: 2026-07-23 Version: v7.4 Last Updated: 2026-08-28 Document References: Tech Proposal v2.4 §9.1 (session/token rules); WBS row 150 (UC_3.1), WBS row 153 (UC_3.2); References/QnA from clients/08_AUTHENTICATION/QnA_AUTHENTICATION.md (QN-AUTH-001..012); CR-20260728-003 [CHR-15] (Remember Device 30 days + OTP error text); CR-20260822-001 [CHR-52] (Google SSO Gated by Assigned Permission)

---

UC Index

---

UC_3.1 — Trader Login — Universal Login (Auth0 OTP) [CHR-1]

1. Overview

2. Trigger

The user clicks the "Log in" button on the navigation bar.

3. Pre-conditions

• The user is on Screen Login.
• The email entered has a valid format (RFC 5322).
• The email is linked to a claimed account in the system.
• The email domain is NOT @stacktrading.com.

4. Post-conditions

• The system has issued a JWT (RS256) for the trader.
• The trader is navigated to Dashboard screen (their own dashboard).
• Strict data isolation is enforced: the trader's JWT contains their own user_id; all backend queries filter by this user_id. Traders cannot view other traders' data under any circumstances. (Source: QN-AUTH-009)
• A session is created with the shared session rules (BR-01..04): 15-min Access Token TTL, silent refresh, 5-day max idle, forced re-login past threshold.
• [CR] If the user checked "Remember this device for 30 days": an additional auth0-mf MFA Session Cookie is issued, valid for 30 days on this device/browser. See §6 Alternative Flow and BR-06. (Source: CR-20260728-003 [CHR-15])

---

5. Basic Flow

1. The user enters their email, then clicks the "Continue" button.
   • As part of this Continue-click validation, the system checks the account's Auth0 status.
     • [If the Auth0 account is blocked] → Exceptional Flow: Auth0 account blocked. The flow does not proceed to step 2.
     • [If not blocked] → continue to step 2.
2. The system runs the domain-check middleware (BR-DOMAIN-01, shared with UC_3.2) on the entered email.
   • Domain = @stacktrading.com → Alternative Flow: branch to UC_3.2 (no account-lookup step; see UC_3.2 §5 Basic Flow).
   • Domain ≠ @stacktrading.com → continue to step 3.
3. The system checks whether the entered email is linked to a claimed account (BR-ACCT-01, UC_3.1 only).
   • [If no account found] → Exceptional Flow: Account not found.
   • [If account found] → continue to step 4.
4. The system calls Auth0 Passwordless Email connection to send an OTP to the user's email inbox.
5. The system navigates the user to Screen: OTP Verification.
6. The user opens their email inbox, retrieves the OTP, and enters it on OTP verification screen.
7. [CR] The user may optionally check the "Remember this device for 30 days" checkbox before submitting. (Source: CR-20260728-003 [CHR-15])
8. The system submits the OTP to Auth0 for verification.
9. [If the OTP is valid] → The system issues an RS256 JWT for the trader. The system creates a session with the shared session rules (BR-01..04).
   • [CR] [If the "Remember this device" checkbox was checked at step 7] → Alternative Flow: Remember device for 30 days (see §6).
10. The system navigates the user to Screen: Dashboard (their own dashboard).

6. Alternative Flow

Alternative flows represent paths where the user still achieves the login goal, but through a different sequence of steps.

• [If the email domain = @stacktrading.com]

  • Context: At Basic Flow step 2, the domain-check middleware detects a @stacktrading.com email. The flow branches to UC_3.2 immediately — no account-lookup (BR-ACCT-01) is performed on this branch.
  • The system renders an inline message within UI-53-a: "As an internal employee, login with Google SSO" and a "Log in with Google" button.
  • The flow continues as UC_3.2.

• [CR] [If the user checks "Remember this device for 30 days" and completes OTP] (Source: CR-20260728-003 [CHR-15])

  • Context: At Basic Flow step 7, the user checks the "Remember this device for 30 days" checkbox before submitting the OTP. The OTP is then verified successfully at step 9.
  • Stage 1 — At Minute 0 (Initial Login): After the OTP is verified, Auth0 issues three artifacts:
    • Access Token: valid for 15 minutes (BR-01).
    • SSO Session Cookie: manages the user's logged-in state on Auth0's server.
    • MFA Session Cookie (auth0-mf): browser cookie marking this device as trusted for MFA, valid for 30 days (BR-06).
  • Stage 2 — At Minute 15 (Access Token Expiration): The 15-minute Access Token expires; API requests using it return 401 Unauthorized. The client application silently requests a new Access Token in the background (Refresh Token or Silent Authentication via hidden iframe to Auth0's /authorize endpoint) per BR-02. The user notices nothing and continues working without interruption.
  • Stage 3 — Between Days 1 and 30 (Re-Authentication): If the user closes the browser, clears app state, or the Auth0 primary session expires, the user must log in again (email + Continue). The OTP challenge is skipped entirely — Auth0 reads the valid auth0-mf cookie from the browser, verifies the trusted device, and issues new tokens without prompting for an OTP.
  • Stage 4 — After 30 Days (MFA Trust Expiration): The auth0-mf cookie expires. The next time the user's primary session expires or they log in from scratch, Auth0 requires the user to complete the OTP challenge again (back to Basic Flow step 4) before issuing new tokens.

---

7. Exceptional Flow

Exceptional flows represent paths where the login goal is NOT achieved — the system blocks, rejects, or interrupts the login attempt due to an error, violation, or business rule.

• [If the email format is invalid]

  • The system highlights the email input border in red and displays the error at the error banner with the text: "Please enter a valid email address"
  • The domain-check (Basic Flow step 2) does not fire. The login attempt does not proceed.
  • The user can correct and retry.
  • Source: QN-AUTH-006.

• [If the account is not found]

  • Context: At Basic Flow step 3 (domain ≠ @stacktrading.com branch only), the system queries the account store and finds no claimed account linked to the entered email.
  • The system displays the error at the error banner with the text: "Account not found. Please try again."
  • The login attempt does not proceed. The user can retry.
  • Source: QN-AUTH-006.

• [If the OTP code is invalid or has expired]

  • The system displays the error at the error banner with the text: "Invalid One-Time Passcode entered."
  • The system allows retry. The failed-attempt counter increments.
  • The system does NOT resend a new OTP automatically on each failed attempt.

• [If 3 consecutive OTP failures occur]

  • The system terminates the current login session.
  • The system briefly displays a "Resend Code" button. Source: QN-AUTH-003.
  • The system navigates the user to Screen: Authentication Terminated, displaying the error at the error banner with the text: "TOO MANY FAILURE ATTEMPTS" .
  • The login attempt fails. The user cannot retry the same OTP session.

• [If the user navigates back to the OTP screen after termination (browser-back)]

  • The system detects no live OTP or active session.
  • The system re-renders Screen: Authentication Terminated. It does NOT silently re-render the OTP verification screen with a stale OTP.

• [If the activation link has expired] (cross-reference only)

  • The system displays the error at the error banner with the text: "Expired Link. Please retry."
  • The system displays "Restart Login" button, which navigates user to Log in - enter email screen.

• [If the user's Auth0 account is blocked]

  • Context: At Basic Flow step 1 (email entry, on Continue click), the system checks the account's Auth0 status as part of the Continue-click validation. Auth0 reports the user's account as blocked.
  • The system displays the error at the error banner on Screen Login (email entry screen) with the text: "Your account has been blocked. Please contact support."
  • The login attempt does not proceed — the flow does not continue to the domain-check (step 2) or account-lookup (step 3); no OTP is dispatched and no session/JWT is issued.
  • The user cannot retry this login attempt.

---

8. Business Rule

BR-01: Access Token Time-To-Live (TTL)

The Access Token issued by Auth0 is valid for 15 minutes from the moment of issuance. After 15 minutes, the token is considered expired and any request bearing it must be rejected by the backend. See Tech Proposal v2.4 §9.1 line 278.

(Identical to UC_3.2 BR-01 — shared rule.)

BR-02: Silent Token Refresh

When the Access Token expires after 15 minutes, the system automatically refreshes it in the background using Auth0's silent refresh mechanism (hidden iframe). The refresh occurs seamlessly without interrupting the user's active session — no UI change, no redirect, no user action required. If a request is in flight when the token expires, the request is queued and retried with the new token. See Tech Proposal v2.4 §9.1 line 278–282.

(Identical to UC_3.2 BR-02 — shared rule.)

BR-03: Maximum Idle Time and Forced Re-Login

The Refresh Token has an absolute lifetime of 5 days. After 5 days of inactivity (no successful refresh within the window), the Refresh Token is invalidated by Auth0. The user must perform a full re-login (start over from UI-53-a). This rule balances session persistence with security against long-lived stolen tokens. See Tech Proposal v2.4 §9.1 line 286.

(Identical to UC_3.2 BR-03 — shared rule.)

BR-04: OTP Failure Cap — 3 Consecutive Failed Attempts → Termination

After 3 consecutive failed OTP verification attempts within a single login session, the system:

1. Terminates the current login session.
2. Displays Screen: Authentication Terminated.
3. The user cannot retry the same OTP session.

The 3-attempt cap is the authoritative value per BA decision 2026-07-23. (Source: QN-AUTH-001)

BR-05: OTP Validity Period

Each OTP sent to the trader's email is valid for 3 minutes from the moment it is sent. After 3 minutes, the OTP is invalidated by Auth0. The user must request a new OTP (by restarting from UI-53-a) if the OTP expires before they enter it. (Source: QN-AUTH-002, Auth0 default)

[CR] BR-06: MFA Trust Cookie (auth0-mf) — 30-Day Device Trust

When the user checks "Remember this device for 30 days" on UI-53-b before submitting a valid OTP, Auth0 issues an additional MFA Session Cookie (auth0-mf) with a 30-day TTL, scoped to the current browser/device.

• While auth0-mf is valid, any subsequent re-authentication on the same device (triggered by primary session expiry, browser close, or cleared app state) skips the OTP challenge — Auth0 verifies the cookie and issues new tokens directly.
• The Access Token TTL (BR-01, 15 min) and Refresh Token max idle time (BR-03, 5 days) rules are unaffected and continue to apply independently of auth0-mf.
• After 30 days, auth0-mf expires. The next re-authentication attempt requires the full OTP challenge again (Basic Flow step 4 onward).
• This rule applies only to UC_3.1 (Trader OTP login). UC_3.2 (Internal Employee — Google SSO + Passkey MFA) does not use OTP and is out of scope for this rule.

(Source: CR-20260728-003 [CHR-15])

---

9. Wireframe / UI

• Screen UI-53-a: Login (Email Entry) — shared entry for both flows. A Back icon is rendered at the top of the screen; clicking it navigates the user to the site Homepage (/), same tab.

  • Default state: Log in.png
  • Invalid email format: Log in (Error).png
  • Account not found: Log in (No account found) in.png

• Screen UI-53-b: OTP Verification — UC_3.1 only. A Back icon is rendered at the top of the screen; clicking it navigates the user to the site Homepage (/), same tab.

  • OTP success (OTP variant): Log in Success (OPT variant).png
  • OTP failure (incorrect / expired code): Log in Failure (OPT variant).png
  • [CR] Remember this device checkbox state: Remember device in 30 days).png (Source: CR-20260728-003 [CHR-15])

• Screen UI-53-c: Authentication Terminated — UC_3.1 only (after 3-fail cap). A Back icon is rendered at the top of the screen; clicking it navigates the user to the site Homepage (/), same tab. Log in Failure(OPT variant too many attempts).png

• Screen: Activation Link Expired — Expired.png

Note: only PNG mockups exist in References/Wireframe/Authentication/ as of 2026-07-24; there is no .svg source file in this folder.

---

10. Screen Description and Business Rules

---

END OF UC_3.1

---

UC_3.2 — Internal Employee Login — Google SSO (+ MFA Passkey) [CHR-2]

1. Overview

⚠️ User decision 2026-07-26: UC_3.2's Basic Flow no longer performs an account-lookup (claim) check. On Continue click, the system checks only the email domain (@stacktrading.com) and, if matched, opens the Google login modal directly. Claimed-account verification (BR-ACCT-01) exists only in UC_3.1.

2. Trigger

The user clicks the "Log in" button on the navigation bar, enters their email on Screen UI-53-a, and clicks Continue.

QN-AUTH-010 — confirmed 2026-07-24 (BA clarification): "MFA for internal employee is one step after user click continue with Google." The MFA Passkey challenge fires immediately as the next authentication step — not deferred, not post-callback-only.

3. Pre-conditions

• The user is on Screen UI-53-a: Login.
• The email entered has a valid format (RFC 5322).
• The email domain equals @stacktrading.com (verified by domain-check middleware).
• The user has a valid Google Workspace account at @stacktrading.com.
• [CR] The user's Google Workspace account has an assigned group/permission mapped to an allowed role (verified via Auth0 Post-Login Action). (Source: CR-20260822-001 [CHR-52])
• The user has previously registered a Passkey (FIDO2 / Google Authenticator) for MFA.

4. Post-conditions

• The system has issued an RS256 JWT for the internal employee.
• [CR] JWT issuance is additionally gated by the Workspace permission/group check (Ref: BR-08) — a domain-matched employee with no assigned group/permission never reaches this post-condition. (Source: CR-20260822-001 [CHR-52])
• The user is navigated to the Internal Employee Dashboard.
• A session is created with the shared session rules (BR-01..04, identical to UC_3.1): 15-min Access Token TTL, silent refresh, 5-day max idle, forced re-login past threshold.

---

5. Basic Flow

1. The user enters their email on UI-53-a, then clicks the "Continue" button.
2. The system runs the domain-check middleware (BR-DOMAIN-01, shared with UC_3.1) directly on the entered email. Domain equals @stacktrading.com → branch to UC_3.2.
3. The system renders an inline message within UI-53-a: "As an internal employee, login with Google SSO" and a "Log in with Google" button.
4. The user clicks "Log in with Google". The Google login modal opens.
5. The system initiates the Google OAuth flow via Auth0 and redirects the user to Google's consent screen (inside the modal).
6. The user reviews the consent screen (scopes: openid, email, profile) and approves.
7. Immediately after the Log in with Google click (per QN-AUTH-010), the system triggers the MFA Passkey challenge as the next authentication step. The Auth0 passkey modal appears for user to verify with their registered Passkey (FIDO2 / Google Authenticator).
8. The user completes the Passkey verification on their authenticator device.
   • [If the Passkey is invalid] → Auth0 handles the failure on its side (this UC does not need to cover it, Ref: §6 Alternative Flow).
   • [If the Passkey is valid] → continue to step 9.
9. [CR] After the Passkey is successfully verified, the Auth0 Post-Login Action checks the user's Workspace group/permission (Ref: BR-08) against the groups claim fetched from Google Workspace. (Source: BA direct instruction, 2026-08-28 — permission check confirmed to run after MFA verification, not before.)
   • [If an assigned group/permission is found] → continue to step 10.
   • [If no assigned group/permission is found] → Exceptional Flow: Google SSO denied — no assigned permission. The flow does not proceed to step 10.
10. Auth0 issues an RS256 JWT for the internal employee. The system creates a session with the shared session rules (BR-01..04).
11. The system navigates the user to the Internal Employee Dashboard.

6. Alternative Flow

N/A — Auth0 handles unauthorized/mismatched Google account cases entirely on its side (Google OAuth consent + Auth0 rules); this UC does not need to cover it. (Client instruction, 2026-08-06)

---

7. Exceptional Flow

Exceptional flows represent paths where the login goal is NOT achieved — the system blocks, rejects, or interrupts the login attempt due to an error, violation, or business rule.

• [If the email format is invalid]

  • The system highlights the email input border in red and displays the error at the error banner with the text: "Please enter a valid email address"
  • The domain-check (Basic Flow step 2) does not fire.
  • The login attempt does not proceed. The user can correct and retry.
  • Source: QN-AUTH-006.

• [CR] [If the email domain matches @stacktrading.com, MFA Passkey succeeds, but the user has no assigned Workspace group/permission]

  • Context: At Basic Flow step 9 (after successful Passkey verification), the Auth0 Post-Login Action evaluates the user's groups claim and finds no assigned group/permission mapped to an allowed role.
  • The system returns a 403 Forbidden response. Auth0 handles the error/denial presentation on its side — this UC does not define a custom error banner or UI copy for this case.
  • The login attempt does not proceed — no JWT/session is issued.
  • Source: BA direct instruction, 2026-08-28 (Ref: CR-20260822-001 [CHR-52]).

---

8. Business Rule

BR-01: Access Token Time-To-Live (TTL)

The Access Token issued by Auth0 is valid for 15 minutes from the moment of issuance. After 15 minutes, the token is considered expired and any request bearing it must be rejected by the backend. See Tech Proposal v2.4 §9.1 line 278.

(Identical to UC_3.1 BR-01 — shared rule.)

BR-02: Silent Token Refresh

When the Access Token expires after 15 minutes, the system automatically refreshes it in the background using Auth0's silent refresh mechanism (hidden iframe). The refresh occurs seamlessly without interrupting the user's active session — no UI change, no redirect, no user action required. If a request is in flight when the token expires, the request is queued and retried with the new token. See Tech Proposal v2.4 §9.1 line 278–282.

(Identical to UC_3.1 BR-02 — shared rule.)

BR-03: Maximum Idle Time and Forced Re-Login

The Refresh Token has an absolute lifetime of 5 days. After 5 days of inactivity (no successful refresh within the window), the Refresh Token is invalidated by Auth0. The user must perform a full re-login (start over from UI-53-a). This rule balances session persistence with security against long-lived stolen tokens. See Tech Proposal v2.4 §9.1 line 286.

(Identical to UC_3.1 BR-03 — shared rule.)

BR-04: Refresh Token Rotation and Breach Isolation

Auth0 is configured with Refresh Token Rotation enabled. Each time a Refresh Token is used, Auth0 issues a new Refresh Token and invalidates the old one. If a previously-used (rotated) Refresh Token is replayed (indicating potential theft), Auth0 triggers breach isolation and invalidates the entire token family tree for that user. The user is immediately force-logged-out and must re-authenticate from the beginning.

(Identical to UC_3.1 BR-04 — shared rule.)

---

9. Wireframe / UI

• Screen UI-53-a: Login (Email Entry) — shared with UC_3.1. A Back icon is rendered at the top of the screen; clicking it navigates the user to the site Homepage (/), same tab. Default state: Log in.png
• Screen UI-53-a (SSO variant): "Log in with Google" button state — rendered inside UI-53-a when domain = @stacktrading.com: Log in with GG.png

Note: only PNG mockups exist in References/Wireframe/Authentication/ as of 2026-07-24; there is no dedicated UI-56 mockup file — the Google SSO entry point is captured via the shared Log in with GG.png state of UI-53-a.

---

10. Screen Description and Business Rules

---

Update History

END OF UC_3.2