adastra_app/docs/decisions/0005-jwt-authentication-localstorage.md

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.