205 lines
10 KiB
Markdown
205 lines
10 KiB
Markdown
---
|
|
type: guide
|
|
title: Cross-Tab Authenticated Shell Invalidation
|
|
description: How logging out in one tab, or receiving an unauthorized SSE response, instantly logs out and redirects every other open tab of the SPA.
|
|
tags: [guide, auth, session, broadcast-channel, storage-event, sse, tester]
|
|
timestamp: 2026-07-22T10:32:00Z
|
|
---
|
|
|
|
# What this feature does
|
|
|
|
Before this change, `sessionStorage` was tab-scoped, so logging out in **tab A**
|
|
left any other open tabs (`/challenges`, `/scoreboard`, `/blog`, `/admin`)
|
|
**still rendering authenticated content** until they were individually closed or
|
|
reloaded. The same gap existed when the server returned `401` to the
|
|
authenticated `/api/v1/events/status` SSE stream: the offending tab knew it was
|
|
unauthenticated, but the others did not.
|
|
|
|
This change adds a same-browser **cross-tab session-invalidation channel**:
|
|
|
|
1. `AuthService` now owns a single `BroadcastChannel('hipctf.auth.v1')` plus a
|
|
`localStorage` `storage`-event fallback, registered in its constructor and
|
|
torn down on `DestroyRef`.
|
|
2. Every confirmed local session invalidation (manual `logout()`, SSE
|
|
`401`/`403`) clears state **and publishes** a fixed-shape
|
|
`session-invalidated` message containing only the broadcasting tab's
|
|
`origin` (random per-tab UUID) and a `ts` timestamp. No tokens, users, or
|
|
storage contents are broadcast.
|
|
3. Each tab listens for the message. If the `origin` differs from its own, it
|
|
treats the notification as a peer-logout: it clears its in-memory and
|
|
`sessionStorage` state **without** rebroadcasting, then notifies
|
|
subscribers.
|
|
4. `HomeComponent` subscribes to the new peer-invalidation event, resets
|
|
`UserStore`, closes any open change-password / user-menu overlays, and
|
|
navigates to `/login`. A re-entrancy flag prevents duplicate navigations
|
|
when the originating tab already navigated.
|
|
5. `AuthenticatedEventSourceService` was extended to dispatch a new
|
|
`'unauthorized'` event when the SSE fetch returns `401` or `403`. Generic
|
|
network failures still dispatch `'error'` and do **not** invalidate.
|
|
|
|
# Why a new concept doc
|
|
|
|
The change spans the auth core, the SSE transport, the event-status store, and
|
|
the shell component. It introduces a new pure module
|
|
(`auth-session-events.pure.ts`) and a new transport event type
|
|
(`'unauthorized'` on `EventSourceLike`). A tester reading the
|
|
[Authenticated Shell](/guides/authenticated-shell.md) guide should not have to
|
|
re-derive the cross-tab propagation rules, and a developer wiring a new
|
|
service should not have to read the auth service diff to learn about the
|
|
broadcast contract.
|
|
|
|
# Tester flows
|
|
|
|
> Open the SPA in **two browser tabs** of the same browser profile, signed in
|
|
> as the same user. Both tabs must be on authenticated routes (`/`,
|
|
> `/challenges`, `/scoreboard`, `/blog`, or `/admin`).
|
|
|
|
## Peer logout (manual)
|
|
|
|
1. Sign in once and navigate to `/challenges` in **Tab A**.
|
|
2. Duplicate the tab — **Tab B** opens at `/scoreboard`.
|
|
3. In **Tab A**, open the user menu (`[data-testid="user-menu-trigger"]`)
|
|
and click **Logout**.
|
|
4. **Tab A** navigates to `/login` (unchanged behavior).
|
|
5. **Tab B** clears its shell state without any user interaction and navigates
|
|
to `/login`. The event LED, countdown, and quick-tab strip are no longer
|
|
visible — the landing/login view is shown.
|
|
6. Confirm in DevTools → Application → Session Storage of **Tab B** that the
|
|
`hipctf.auth.v1` key has been removed.
|
|
|
|
## Peer logout (SSE unauthorized)
|
|
|
|
1. Sign in once and open the SPA in two tabs.
|
|
2. In **Tab A** (server side, via an admin-only tool or by manually
|
|
revoking the refresh cookie), invalidate the refresh-cookie/session.
|
|
3. Wait for `EventStatusStore` to reconnect — the SSE fetch returns `401`.
|
|
4. **Tab A** clears state and navigates to `/login`.
|
|
5. **Tab B** (still on `/challenges`) clears state and navigates to `/login`
|
|
without any SSE retry happening locally — it received the broadcast from
|
|
Tab A.
|
|
|
|
> If you instead trigger the unauthorized response in **Tab B** directly
|
|
> (e.g. by expiring the refresh cookie for that tab only), Tab B navigates
|
|
> to `/login`; Tab A is unaffected.
|
|
|
|
## Negative cases
|
|
|
|
| Action | Expected |
|
|
|---|---|
|
|
| Open the SPA in a private/incognito window in addition to a normal window | Logging out in one does **not** affect the other. `BroadcastChannel` and the `storage` event are scoped to the browser profile. |
|
|
| Trigger a generic network failure on `/api/v1/events/status` | The store dispatches `'error'`, retries, and **does not** invalidate. The shell keeps the last known event state. |
|
|
| A non-HIPCTF tab on the same browser profile writes `hipctf.auth.invalidate.v1` to `localStorage` with garbage | The payload validator (`isCrossTabInvalidationEvent`) ignores it — no state change. |
|
|
| Same tab echoes its own broadcast (test environment that delivers self-messages) | The `origin === crossTabOrigin` guard prevents self-processing and rebroadcast loops. |
|
|
|
|
# Visual / interactive elements
|
|
|
|
There are **no new UI controls**. Existing selectors continue to work and
|
|
should be exercised after a peer invalidation:
|
|
|
|
| Element | Selector | After peer invalidation |
|
|
|---|---|---|
|
|
| Shell header | `[data-testid="shell-header"]` | Removed from DOM by `Router` (route changed to `/login`). |
|
|
| Quick tabs | `[data-testid="quick-tabs"]` | Removed from DOM by `Router`. |
|
|
| User menu | `[data-testid="user-menu-trigger"]` | Removed from DOM by `Router`. |
|
|
| Event LED / countdown | `[data-testid="shell-led"]`, `[data-testid="shell-countdown"]` | Removed from DOM by `Router`. |
|
|
| Login form | `[data-testid="login-submit"]` | Becomes visible (already-tested flow). |
|
|
|
|
# How it works (developer map)
|
|
|
|
## Pure contract module
|
|
|
|
`frontend/src/app/core/services/auth-session-events.pure.ts` is a
|
|
framework-light, testable module that defines:
|
|
|
|
| Export | Purpose |
|
|
|---|---|
|
|
| `CROSS_TAB_CHANNEL_NAME = 'hipctf.auth.v1'` | Stable `BroadcastChannel` name. |
|
|
| `CROSS_TAB_STORAGE_KEY = 'hipctf.auth.invalidate.v1'` | `localStorage` fallback key. |
|
|
| `CROSS_TAB_EVENT_TYPE = 'hipctf.session.invalidated'` | Marker used by the discriminated-union guard. |
|
|
| `CrossTabInvalidationMessage` | `{ type: 'session-invalidated'; origin: string; ts: number }`. |
|
|
| `encodeInvalidationMessage(origin)` | Builds a message stamped with `Date.now()`. |
|
|
| `isCrossTabInvalidationMessage(value)` | Type-guard used by both `BroadcastChannel` and `storage` listeners. |
|
|
| `isStorageInvalidationEvent(event)` | Guards `storage` events: only accepts the namespaced key with a parseable payload. |
|
|
|
|
The payload intentionally carries **no** access token, refresh token, user id,
|
|
or `sessionStorage` content.
|
|
|
|
## `AuthService` wiring
|
|
|
|
`frontend/src/app/core/services/auth.service.ts`
|
|
|
|
* Constructor calls `installCrossTabListener()`, which:
|
|
* Feature-detects `BroadcastChannel`; if present, opens it on
|
|
`CROSS_TAB_CHANNEL_NAME` and subscribes to `'message'`.
|
|
* Always subscribes a `'storage'` listener filtered through
|
|
`isStorageInvalidationEvent`.
|
|
* `clearAndBroadcast()` is the new public invalidation entry point: calls the
|
|
existing `clear()` (which wipes `sessionStorage`), and if
|
|
`suppressBroadcast` is `false`, publishes a fresh `encodeInvalidationMessage`
|
|
on both transports.
|
|
* `logout()` now ends with `clearAndBroadcast()` instead of `clear()`.
|
|
* `handleSseUnauthorized()` calls `clearAndBroadcast()` and then synchronously
|
|
notifies peer-invalidation subscribers with the reason
|
|
`'sse-unauthorized'` so the originating tab can navigate immediately.
|
|
* `onPeerInvalidation(cb)` registers a subscriber; returns an unsubscribe
|
|
closure. Used by `HomeComponent`.
|
|
* `handlePeerInvalidation()` is the single fan-in for both transport sources:
|
|
it parses the payload, drops self-origin messages, drops messages when the
|
|
tab is already unauthenticated, and runs `clear()` under
|
|
`suppressBroadcast = true` so the listener does not echo.
|
|
* `DestroyRef.onDestroy` calls `teardownCrossTabListener()` which removes the
|
|
`'message'` and `'storage'` listeners and closes the channel.
|
|
|
|
## Authenticated SSE: `unauthorized` event
|
|
|
|
`frontend/src/app/core/services/authenticated-event-source.service.ts`
|
|
|
|
The fetch path now inspects `res.status` *before* the `ok`/`body` check. If
|
|
the status is `401` or `403`, the service dispatches a new `'unauthorized'`
|
|
`Event` and returns; the response body is **not** read and no frame parsing
|
|
runs.
|
|
|
|
`frontend/src/app/core/services/event-status.pure.ts` widens
|
|
`EventSourceLike.addEventListener` to accept `'open' | 'message' | 'error' |
|
|
'unauthorized'`.
|
|
|
|
`frontend/src/app/core/services/event-status.store.ts`
|
|
|
|
`EventStatusStore.start(createSource, onUnauthorized?)` now accepts an
|
|
optional second argument. When provided, the store attaches an
|
|
`'unauthorized'` listener that invokes `onUnauthorized()` and is detached by
|
|
`stop()` (which is already idempotent). Generic `'error'` events remain
|
|
unhandled by the store; the SPA does not navigate on transport failure.
|
|
|
|
## Shell reaction
|
|
|
|
`frontend/src/app/features/home/home.component.ts`
|
|
|
|
* `ngOnInit()` passes a second callback to `eventStatus.start(...)` that
|
|
delegates to `handleSessionInvalidated('sse-unauthorized')`.
|
|
* It also subscribes to `auth.onPeerInvalidation(...)` and stores the
|
|
unsubscribe handle on `peerInvalidationUnsubscribe`.
|
|
* `ngOnDestroy()` calls `eventStatus.stop()` and unsubscribes from
|
|
`onPeerInvalidation`.
|
|
* `handleSessionInvalidated(reason)`:
|
|
* Calls `userStore.reset()` and closes `changePasswordOpen` /
|
|
`userMenuOpen` modal signals.
|
|
* Guards re-entry with `navigatingToLogin` and short-circuits when the
|
|
router is already on `/login`.
|
|
* Otherwise awaits `router.navigateByUrl('/login')`.
|
|
|
|
## Test coverage
|
|
|
|
| File | What it pins down |
|
|
|---|---|
|
|
| `tests/frontend/auth-session-events.spec.ts` | Pure payload validation, `storage`-event filtering, `encodeInvalidationMessage` shape. |
|
|
| `tests/frontend/authenticated-event-source.spec.ts` | Extended: `401`/`403` dispatches `'unauthorized'`; generic errors still dispatch `'error'`; no body is read on the unauthorized path. |
|
|
|
|
# See also
|
|
|
|
- [Authenticated Shell](/guides/authenticated-shell.md)
|
|
- [Session Restoration on Reload](/guides/session-restoration.md)
|
|
- [Frontend Structure](/architecture/frontend-structure.md)
|
|
- [REST API Overview](/api/rest-overview.md)
|
|
- [Auth Endpoints](/api/auth.md)
|