# ADR 0005: JWT Authentication Stored in localStorage

**Date:** 2026-04-26
**Status:** Accepted

## Context

The application requires persistent authentication across browser sessions. The two main options for token storage are:

- **`localStorage`** — accessible via JavaScript; survives tab/window close; vulnerable to XSS.
- **httpOnly cookies** — inaccessible to JavaScript; protected from XSS; requires CSRF protection.

The application is not publicly accessible — it is used internally by a known, controlled user base. The attack surface for XSS is limited.

## Decision

Store the JWT token in `localStorage` under the key `jwtToken`. `JwtService` handles read/write/delete operations. `UserService` exposes `currentUser` (BehaviorSubject) and `isAuthenticated` (ReplaySubject) observables consumed by guards and the layout.

An `APP_INITIALIZER` in `app.config.ts` calls `userService.getCurrentUser()` on startup if a token exists, ensuring guards can rely on `isAuthenticated` being populated before the first navigation.

## Consequences

- **Positive:** Simple implementation. No server-side session management. Works seamlessly with Angular's functional guards.
- **Positive:** Token persists across browser restarts without requiring re-login.
- **Risk:** XSS attacks could exfiltrate the token. Acceptable given the non-public nature of the application.
- **Future consideration:** If the application becomes publicly accessible or handles sensitive data, migrate to httpOnly cookies with CSRF tokens.