Authentication (Frontend Standard)

This document defines the standard authentication model for Next.js frontends acting as a BFF.

Standard model (required)

Browser ↔ Next.js

• The browser is authenticated via HttpOnly + Secure cookies.
• Cookies are automatically attached by the browser on same-site requests.
• The frontend must therefore implement CSRF protection for unsafe methods (see csrf.md).

Next.js ↔ Backend

• The backend API uses Bearer JWT authorization.
• Next.js Route Handlers read the access token server-side from HttpOnly cookies and attach it to backend requests:
  • Authorization: Bearer <access_jwt>

Rule: never expose backend access tokens to the browser (no NEXT_PUBLIC_* tokens, no localStorage/sessionStorage).

Token and session policy

• Access token: short-lived JWT.
• Refresh token: long-lived JWT with rotation (refresh token changes on refresh).
• Both tokens are stored in HttpOnly cookies.

Project repos must document:

• cookie names
• cookie TTLs
• refresh rotation rules (reuse detection, revocation behavior)

Logout standard

Logout must:

• revoke/expire the refresh token server-side (backend)
• clear cookies in the Next.js BFF

Environment variable rules

• Backend base URL is server-only (e.g., BACKEND_BASE_URL).
• Do not use NEXT_PUBLIC_* for backend internal/private URLs or any secrets.