parsa/canina
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f4cdca4ed1
canina/docs/audit/ADR-AUTH-001.md
parsaaghayi f4cdca4ed1
Some checks failed
Deploy Canina / deploy (push) Failing after 29s
Details
docs(audit): finalize Phase 3 Master Task Backlog and audit planning artifacts
2026-08-06 20:54:44 +03:30

3.2 KiB
Raw Blame History

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.