adastra_api/docs/decisions/0006-jwt-authentication.md

ADR 0006: Authentication — JWT with express-jwt

Date: 2026-04-26 Status: Accepted

Context

The API must authenticate requests from the Angular frontend. Options considered:

• Session-based auth — server stores session state; requires sticky sessions or shared session store in multi-instance deployments.
• JWT (JSON Web Tokens) — stateless; token carries the user identity; no server-side session storage.

Given that the application is currently single-instance with no horizontal scaling requirement, either would work. JWT is simpler to operate and aligns with the frontend's existing token-based auth flow.

Decision

Use JWT for authentication:

• Tokens are issued by the API on successful login (jsonwebtoken library, bcrypt for password hashing).
• Incoming requests are validated by the express-jwt middleware, which populates req.auth with the decoded token payload.
• The src/middlewares/auth.js middleware wraps express-jwt and handles role-based access control (Admin role required for protected admin routes).

The frontend stores the token in localStorage and sends it as Authorization: Token <jwt> (see frontend ADR 0005).

Consequences

• Positive: Stateless — no session store needed. Horizontally scalable without sticky sessions.
• Positive: Single middleware handles auth for all routes.
• Negative: Tokens cannot be invalidated server-side before expiry. Acceptable for this use case (internal application, low revocation risk).
• Security: Passwords are hashed with bcrypt. The JWT secret must be kept in environment configuration, never committed.