canina/docs/audit/ADR-AUTH-001.md

ADR-AUTH-001: Admin Panel Authentication Architecture & Token Management

• Status: DECIDED_HYBRID_DUAL_TOKEN
• Date: 2026-08-06
• Context: Audit finding ARCH-001 and security findings SEC-001, SEC-002, SEC-003 evaluated authentication architecture. User finalized product decision: Storefront is built with Next.js (SSR/SEO), while the Admin Panel is an isolated, standalone React SPA focused on maximum security and performance.

---

1. Context and Problem Statement

The Admin Panel application requires an enterprise-grade authentication token management strategy satisfying three key pillars:

1. Maximum Security: Complete defense against Cross-Site Scripting (XSS) token exfiltration and Cross-Site Request Forgery (CSRF) on administrative endpoints.
2. Session Resilience: Seamless session renewal via dual tokens (JWT_ACCESS_SECRET and JWT_REFRESH_SECRET) without persisting long-lived access tokens in vulnerable browser storage (localStorage).
3. API Client & Authorization Interception: Strict authorization boundary enforcement (@Roles('Admin')) via Axios request interceptors and HttpOnly cookies.

---

2. Evaluation of Options

Option A: Storefront Next.js & Admin SPA Shared Storage (localStorage)

• Assessment: REJECTED. Exposes Admin access tokens to XSS exfiltration.

Option B: Pure In-Memory Token Storage

• Assessment: REJECTED. Causes immediate logout on page refresh (F5), causing unacceptable UX degradation for admin workflows.

Option C: Dual-Token Hybrid Architecture (In-Memory Access Token + HttpOnly Refresh Cookie)

• Description:
  • POST /api/auth/verify-otp / admin login validates credentials and issues a short-lived accessToken (signed with JWT_ACCESS_SECRET) in-memory, while setting an HttpOnly, Secure, SameSite=Strict cookie containing a refreshToken (signed with JWT_REFRESH_SECRET).
  • Access tokens are held exclusively in-memory inside Zustand / Axios client closures.
  • Background silent refresh via POST /api/auth/refresh exchanges the HttpOnly cookie for a new access token on page reload or 401 expiration.
• Security Assessment: EXCELLENT. Immune to XSS exfiltration of refresh tokens. JWT_ACCESS_SECRET and JWT_REFRESH_SECRET environment variables enforced at NestJS bootstrap.
• Verdict: FINALIZED ARCHITECTURE FOR ADMIN PANEL.

---

3. Decision Outcome

Chosen Architecture: Option C — Dual-Token Hybrid Architecture for Standalone Admin Panel.

Implementation Specifications for TASK-AUTH-001 & Backend:

1. Backend Configuration (TASK-SEC-001):
   • Enforce mandatory startup validation in NestJS main.ts for TWO secrets: JWT_ACCESS_SECRET and JWT_REFRESH_SECRET (each >= 32 characters/bytes). Fail bootstrap immediately (process.exit(1)) if either secret is missing or insecure.
2. Admin Panel Client (src/ / Admin SPA):
   • Configure Axios client with withCredentials: true.
   • Store accessToken strictly in-memory (Zustand state / closure).
   • Automatically attach Authorization: Bearer <accessToken> via request interceptor.
   • Response interceptor catches HTTP 401 Unauthorized to trigger silent token renewal via /api/auth/refresh.