[EPIC] Security: Migrate authentication from localStorage to httpOnly cookies

[kevalyq]

🗺️ EPIC: httpOnly Cookie Authentication Migration

Original Issue: Closes #205
Priority: High
Area: Authentication, Security

Goal

Replace insecure localStorage token storage with httpOnly cookie-based authentication using Laravel Sanctum SPA mode to protect against XSS attacks.

Sub-Issues & Work Plan

Backend (api repo)

• Backend PR-1: Sanctum SPA Configuration & CORS Setup api#209 - Backend PR-1: Sanctum SPA Configuration & CORS Setup
• Backend PR-2: CSRF Token Endpoint & Security Hardening api#210 - Backend PR-2: CSRF Token Endpoint & Security Hardening
• Backend PR-3: Tests & API Documentation Update api#208 - Backend PR-3: Tests & API Documentation Update

Frontend (frontend repo)

• Frontend PR-1: localStorage Removal & httpOnly Cookie Migration #210 - Frontend PR-1: localStorage Removal & httpOnly Cookie Migration
• Frontend PR-2: CSRF Token Handling & Request Interceptor #211 - Frontend PR-2: CSRF Token Handling & Request Interceptor
• Frontend PR-3: Integration Tests & Developer Documentation (Closes Epic) #212 - Frontend PR-3: Integration Tests & Developer Documentation (Closes Epic)

Technical Context

Current State (Insecure):

// Frontend stores token in localStorage
localStorage.setItem('auth_token', token);
// Vulnerable to XSS attacks

Target State (Secure):

// Backend sends httpOnly cookie
// Frontend uses credentials: 'include'
fetch(url, { credentials: 'include' });
// Token inaccessible to JavaScript

Dependencies

Backend must implement first:

1. Laravel Sanctum SPA authentication mode
2. SANCTUM_STATEFUL_DOMAINS configuration
3. CORS configuration with credentials: true
4. CSRF token endpoint (/sanctum/csrf-cookie)

Frontend follows:

1. Remove localStorage token storage
2. Update fetch calls to use credentials: 'include'
3. Add CSRF token handling
4. Update AuthContext

Acceptance Criteria

• Backend: Sanctum SPA mode configured
• Backend: CORS allows credentials from frontend domain
• Backend: CSRF protection enabled
• Frontend: No token accessible via JavaScript
• Frontend: All auth requests include cookies
• Tests: Auth flow works end-to-end
• Tests: CSRF protection validated
• Docs: Migration guide for developers

References

• Laravel Sanctum SPA Authentication
• OWASP: Token Storage Security
• Original issue: Security: Migrate authentication from localStorage to httpOnly cookies #205

Non-Goals

• Mobile app authentication (different flow)
• API token management (separate concern)
• Session storage (using Sanctum cookies)

[github-actions]

✅ This issue has been added to the SecPal Feature Roadmap with status: 💡 Ideas

New idea - needs discussion and evaluation

Status Flow:
💡 Ideas → 💬 Discussion → 📥 Backlog → 📋 Planned → 🚧 In Progress → 👀 In Review → ✅ Done

Note: Ideas that won't be implemented should be moved to 🚫 Won't Do with a reason.