QIIUB · Session Security — Design & Audit (issues #554 / #553 / ADR-0064)

1The problem in 30 seconds

Three symptoms all read as "the session keeps closing" — but they are distinct bugs, and the audit found the shared systemic root behind them.

①

F5 logs you out in QA/prod #553 · root

Frontend and API on different hosts → the host-only CSRF cookie isn't JS-readable → refresh omits X-CSRF-Token → 401 csrf-mismatch → logout. Works locally only because ports share localhost.

RefreshCookieWriter.cs:28-39 · RefreshTokenEndpoint.cs:65-71

②

F5 logs you out in local/dev #554

Admin store is in-memory only; portal persists to sessionStorage in DEV. On F5 the admin depends 100% on the boot refresh.

③

Support (handoff) session dies in ~15 min ADR-0064

ExchangeHandoff issues only a 15-min JWT, no refresh cookie (verified: it injects neither SessionIssuer nor RefreshCookieWriter).

Plus: a multi-tab refresh race can trip reuse-detection → "random" logout (§6). And the audit surfaced the real root that ties several of these together → §2.

2Audit verdict — solid base, broken edges

Four parallel audits (token engine · all auth endpoints · JWT validation + tenant isolation · frontend both apps) verified the real code on main. The base is fundamentally solid — no rewrite.

✅ Solid & verified (don't regress)

Rotation atomicity (real transaction) + reuse detection with 5s grace.
256-bit tokens, SHA-256, unique TokenHash index; sliding+absolute expiry.
4-layer tenant isolation: mid only from signed JWT, EF filters + RLS + composite FK + physical DB.
Power-user path re-validates actor active per request.
CORS locked + prod fail-fast; magic-link + OAuth (PKCE, state) sound.
Session mgmt endpoints + admin sessions page already exist.

🔴 Broken — must fix (by root cause)

G1 (systemic): refresh drops mid/context — RotateAsync→IssueAsync(user) re-derives from scratch. Breaks handoff, ActivateMerchant, multi-merchant.
G2: handoff + ActivateMerchant don't issue/rotate a full session.
G3: cross-host cookie (#553).
G4: throttle + CSRF gaps; HTTPS/HSTS; ClockSkew/issuer/audience/alg.
G5: admin↔portal frontend inconsistency; multi-tab refresh race.
G6: merchant picker unpaginated; duplicated ReasonModal; portal has no sessions page.
G7: dead code / stale comments / AI int.TryParse on PublicId.

The linchpin is G1. The active merchant/context lives only in the ephemeral JWT; refresh rebuilds it from scratch and loses it. Fix: the session (RefreshToken) is the source of truth for context, and refresh reconstructs the JWT from it while re-validating authorization.

3How a session works (the model)

Standard short access token + rotating refresh token. The JWT never touches disk; the refresh lives in an HttpOnly cookie JS can't read.

Piece	Lifetime	Where	Purpose
Access JWT	15 min	Memory	Authorizes each API call
Refresh token	30 min sliding	`__Secure-qiiub_rt` (HttpOnly)	Renews JWT; rotates every use
CSRF nonce	= refresh	`__Secure-qiiub_csrf` (JS-readable)	Double-submit anti-CSRF
Absolute cap	12h → 8h prop.	`RefreshToken` row	Hard ceiling

One session ≠ one tab. Only a real login mints a new SessionId; a new tab refreshes into the same one. 5 tabs = 1 session.

4The correct architecture: same-origin (BFF)

OWASP: omit Domain (host-only cookies), use __Host-. So the fix isn't shared-domain cookies — it's making the frontend and its API share an origin.

✗ TODAY (QA) — different hosts

SPA · admin.qa.qiiub.com

✕ CSRF cookie can't cross

API · api.qa.qiiub.com

✓ PROPOSED — same-origin

SPA · admin.qa.qiiub.com

API under admin.qa.qiiub.com/api

Why, not shared-domain

Keeps host-only cookies (audited model).
Isolates admin↔portal (a portal XSS can't touch admin).
The recognized BFF pattern.

Where

QA/prodReverse proxy: /api → backend.

LocalVite dev proxy → fixes #554 at the root.

5The F5 (reload) flow

store boots empty

→

bootstrap

read CSRF, call /auth/refresh

→

rotate + issue

same SessionId

→

setAuth

restored

→

still in

no /login flash

Breaks today (QA): "read CSRF" returns null (other host) → 401 → /login. §4 makes that step work.

6Multiple tabs — the race & the fix

5 tabs share one session (good). But the single-flight guard is per-tab: at ~13 min (or on laptop wake) all tabs refresh at once → the 5s grace usually saves it, but a slip trips reuse detection → whole chain revoked → all tabs to /login. That's the "random" logout.

Fix: a Web-Locks leader does the refresh and broadcasts the new JWT to the others. Leader tab closes? The browser auto-releases the lock → the next tab takes over; and any tab can self-refresh as a fallback. A dying leader is, worst case, a momentary fall back to today's behavior — never a logout.

7Two access modes — "Your merchants" vs "Support"

A power user reaches a merchant in two distinct modes that must not be conflated. The /select-merchant picker shows them as two sections.

	Your merchants	Support access
Basis	real `UserMerchant` membership	power-user role, no membership (ADR-0064)
Session	Normal (8h)	Support (1h)
Reason modal	No	Yes (required, audited)
Audit	Normal	`SupportSessionStarted`

This fixes QA's real problem. QA today simulates support just to view the portal — stuck with the short cap and polluting the audit log. Instead, give QA accounts a real membership on a dedicated QA test merchant → they enter via "Your merchants" on a normal session. Support security untouched.

DB reality (verified): the system uses a single Merchant DB today (DependencyInjection.cs:129); multi-DB routing ("12–16 DBs") is designed but not built. So the QA merchant lives in the shared DB, isolated by MerchantId + RLS — exactly the isolation the tests should exercise. A physically separate DB is a future epic (routing), not needed here. Login never sees the DB; it discerns membership via UserMerchant.

8Handoff / impersonation — the fix

Scope-access, not "login as": identity kept (sub), mid added, audited. The flow works; the session lifecycle is what's broken.

The bug: ExchangeHandoff issues the JWT but writes no refresh cookie → dies in 15 min.

The fix

Exchange issues a full, independent session (refresh chain scoped to mid), with the 1h support cap.

Cap: 1 hour

Elevated cross-tenant access → tight window. If support needs longer, re-enter with a fresh reason (better audit). Idle-30m already ends forgotten support sessions.

must implement correctly Re-validate authorization on every rotation. Because refresh must now reconstruct the stored context (§2 G1 fix), it MUST also re-check the admin is still active and still has access to that merchant on every rotation — else a de-privileged admin keeps cross-tenant access. The single most important control. RefreshTokenEndpoint step 6 · SessionIssuer.RotateAsync · RefreshToken.Context/.MerchantPublicId

9Timeouts — OWASP-aligned, configurable

Timeout	Today	Proposed	OWASP
Access JWT	15 min	15 min ✓	short — standard
Idle	30 min	30 min (config)	15–30 min
Absolute (prod, normal)	12h	8h	4–8h workday
Absolute (QA, normal)	12h	8–12h	QA uses normal membership
Support session	—	1h	elevated → tight

Timeouts move to per-environment config with a hard server-side ceiling prod can't exceed, and lifetime becomes a per-issuance parameter — the guardrail that makes "Remember me" additive later.

Close & reopen the browser

The refresh cookie is persistent, so it survives a restart. Reopen within ~30 min → auto signed-in; after → re-login. (Deliberate for a money app.)

"Remember me" (future)

Off by default; opt-in, separate revocable longer-lived session. Never for support sessions. Salesforce/Auth0 model — see §16.

10QA direct login & the scalable picker

QA logs directly into the portal (Microsoft Entra) and lands on a filterable picker. Two things make it work at scale:

Server-side search + pagination

Today /auth/merchants returns all merchants and filters client-side — breaks at 500–1000. Fix: server-side search + pagination together (debounced typeahead; empty query → first page).

ListUserMerchantsEndpoint.cs:101-120 · MerchantPicker.tsx:53-61

Membership, not support-sim

QA gets a seeded membership on the QA test merchant (§7) → "Your merchants", normal session. No 1h cap, no reason, no audit noise.

11Threat model — can the session be stolen?

Attack	Copy the session?	Why / control
Read refresh token via XSS/JS	No	`HttpOnly` — JS can't read it; XSS can't exfiltrate it.
Abuse in-memory JWT via XSS	While script runs	Inherent to SPAs. Mitigated by CSP, SAST, same-origin isolation. No portable copy (no refresh cookie).
Sniff the network	No	`Secure` + HTTPS everywhere.
Copy cookies (malware/device theft)	Possible, but detected	Rotation + reuse detection revoke the whole chain on replay; absolute cap bounds it.
Cross-site forgery (CSRF)	No	`SameSite=Strict` + double-submit nonce (kept even same-origin).
Read the CSRF cookie	Useless alone	Just a nonce; worthless without the HttpOnly refresh.

Honest gap (future hardening): no device/IP binding — a copied cookie from another IP works until reuse-detection or the cap catches it. OWASP notes the usability cost; documented as optional future work.

Net effect of this work: theft risk goes down — same-origin isolation, shorter prod cap, __Host- option, memory-only broadcast.

12Security invariants & guardrails

Must stay true (don't regress)

✓

Refresh token HttpOnly+Secure+SameSite=Strict+Path=/api/auth+__Host-.

✓

JWT in memory only; never localStorage/persistent cookie.

✓

mid/pid only from the signed JWT.

✓

Rotation + reuse detection + per-session CSRF nonce.

✓

MerchantId first filter; RLS per connection.

New guardrails (implement correctly)

▲

Refresh re-validates power-user authz every rotation, scoped to stored mid (§8).

▲

QA long timeout bounded by a hard server-side ceiling; can't reach prod.

▲

Keep SameSite=Strict + CSRF even under same-origin.

▲

Cross-tab JWT broadcast stays same-origin + in-memory.

13What already exists (don't rebuild)

exists Expiry warning modal

SessionWarningDialog + useIdleTimer in both apps (30m idle → 2m countdown → "Stay signed in", cross-tab synced). Not seen today only because the bugs kill the session first.

exists Sessions & merchant switcher

Admin /profile/sessions (list/revoke/logout-all) + MerchantPicker + /select-merchant + TopNav switcher. Portal lacks the sessions page → ported in P6.

14Phases P0–P6

7 phases — P0 is groundwork (ADR + threat model + test harness; no behavior change), P1–P6 are the six build phases. P1 is the gate (highlighted): nothing after it is correct until context-on-refresh is fixed.

Design lock — ADR (reviewed by JJ) + STRIDE + cross-tenant test harness + test matrix.

Design

Session-context foundation (load-bearing) — refresh reconstructs context + re-validates authz; ActivateMerchant rotates; handoff full session + 1h cap; timeouts to config.

Backend

Same-origin (BFF) — reverse proxy + Vite proxy; __Host- cookie. Fixes #553/#554.

Infra

Endpoint hardening — throttle + CSRF; HTTPS/HSTS; ClockSkew/issuer/audience/alg; AI PublicId fix.

Backend

Frontend consistency — unify 401/logout; multi-tab leader-elected refresh (Web Locks).

Frontend

Support UX — unified ReasonModal in @qiiub/ui; two-section picker; server-side search+pagination; QA membership.

Full-stack

Sessions parity + docs — port sessions page to portal; finalize public + internal docs; fix glossary drift.

Frontend

Sequencing: P0 → P1 → P2 → (P3+P4) → P5 → P6. P1 is the gate — nothing after it is correct until context-on-refresh is fixed.

Bug / gate Correct behavior Already exists Must implement correctly

Future (separate ADRs)

Remember-me (guardrail set in P1) · MFA/step-up for sensitive actions · new-device email alerts · device/IP binding · in-app admin session-config UI.

15Decisions (resolved 2026-07-02)

Support cap1h (re-enter with a fresh reason if longer).

QA capNormal 8–12h — QA uses real membership, not support mode.

PickerServer-side search + pagination, together.

PR orderP0 → P1 → P2 → (P3+P4) → P5 → P6.

ADR reviewJJ (deputy); Mike on doubt.

Breaking OKPre-production — no backward-compat shims.

16References & companion artifacts

Standards

OWASP Session Management (timeout ranges, server-side).
OWASP Cookie Attributes (omit Domain, __Host-).
OWASP Authentication (remember-me = separate token).
BCPOS security-audit SAST (Mike) — STRIDE + multi-tenant.

Remember-me vendors

Salesforce — timeout still governs; admin-disable.
Google/Microsoft — long session + risk-based step-up.
Auth0 — separate cookie, off by default.
Banking/POS — usually none.

The full record spans four files: session-security-design.md (spec/decisions) · session-security-plan.md (phased plan) · this HTML (technical explainer) · token-security-explained.html (friendly primer → public help). When ported: this becomes docs/design/session-security.md + docs/html/, §11 becomes docs/security/session-threat-model.md.

17Glossary

Term	Definition
Access token (JWT)	Short-lived signed token proving identity per call; in memory only. 15 min (glossary drift: repo says "30 min" — that's the refresh sliding window).
BFF / same-origin proxy	API served under the frontend host (`/api`) so cookies stay host-only and CSRF works.
Bootstrap / rehydrate	On load/F5 the app silently calls `/auth/refresh` to restore the session before routing to /login.
Cookie prefixes	`__Secure-` requires HTTPS; `__Host-` also forbids `Domain` + requires `Path=/` — strictest, unlocked by same-origin.
CSRF nonce / SameSite	Random per-session value echoed in a header (double-submit) + `SameSite=Strict` — blocks cross-site forgery.
Handoff / scope-access	ADR-0064 power-user merchant entry: identity kept, `mid` added — not "login as".
Leader election (Web Locks)	One tab holds a browser lock and refreshes for all, broadcasting the JWT; auto-released if it closes.
Refresh token	Opaque single-use token in an `HttpOnly` cookie; exchanged at `/auth/refresh` for a fresh JWT.
Rotation / reuse detection	Each refresh revokes the old token; replaying a rotated token (past 5s grace) revokes the whole chain.
Session / `SessionId`	One continuous sign-in — a chain of rotating refresh tokens. Created only by a real login, not a new tab.
Sliding vs absolute	Sliding (30m) extends on use; absolute is the hard ceiling regardless of activity.
STRIDE	Microsoft's threat-modeling framework — six categories you walk each critical flow against: Spoofing (identity), Tampering (integrity), Repudiation (deniability), Information disclosure (confidentiality), Denial of service, Elevation of privilege. The full STRIDE-per-flow pass lives in the design spec (→ `docs/security/session-threat-model.md`); §11 here shows its session-theft result. It catches design-level flaws a code audit misses.