Backend PR-1: Sanctum SPA Configuration & CORS Setup

[kevalyq]

Summary

Configures Laravel Sanctum for SPA authentication mode and sets up CORS to allow credential-based requests from the frontend domain. This replaces insecure localStorage token storage with httpOnly cookie-based authentication.

Related Issues

Fixes #209
Part of: SecPal/frontend#208

Changes

Configuration

• Sanctum SPA Mode: Published Sanctum config with stateful domains (localhost:5173, localhost:3000, production domains)
• Session Driver: Changed from database to cookie for SPA authentication
• Cookie Security: Configured httpOnly, secure (production), and sameSite=lax
• CORS Setup: Allow credentials from frontend domains with explicit origin whitelist

Environment Variables

Added to .env.example:

• SANCTUM_STATEFUL_DOMAINS - Frontend domains for stateful auth
• SESSION_DRIVER=cookie - Cookie-based sessions
• SESSION_HTTP_ONLY=true - JavaScript cannot access cookies
• SESSION_SAME_SITE=lax - CSRF protection
• CORS_ALLOWED_ORIGINS - Frontend domains
• CORS_SUPPORTS_CREDENTIALS=true - Allow cookies in CORS requests
• CORS_ALLOWED_HEADERS - Include X-XSRF-TOKEN for CSRF

Testing

• New comprehensive test suite: SanctumSpaConfigTest
• Verifies Sanctum configuration (stateful domains, CSRF middleware, guards)
• Verifies session configuration (cookie driver, httpOnly, sameSite)
• All existing tests pass (452 tests, 1403 assertions)

Acceptance Criteria

• config/sanctum.php configured with SANCTUM_STATEFUL_DOMAINS
• .env.example updated with required Sanctum variables
• config/cors.php allows credentials (supports_credentials: true)
• CORS configuration allows frontend domain (localhost:5173 for dev, secpal.app for prod)
• API routes use auth:sanctum middleware (already in place)
• Tests verify Sanctum middleware works
• PHPStan passes
• Pint passes
• All existing tests pass

Security Considerations

✅ httpOnly cookies: Token inaccessible to JavaScript (XSS protection)
✅ sameSite=lax: CSRF attack mitigation
✅ Explicit CORS origins: No wildcard * when credentials enabled
✅ CSRF token endpoint: /sanctum/csrf-cookie for state-changing requests

Next Steps

• Backend PR-2: CSRF Token Endpoint & Security Hardening (Backend PR-2: CSRF Token Endpoint & Security Hardening #210)
• Backend PR-3: Tests & API Documentation Update (Backend PR-3: Tests & API Documentation Update #208)
• Frontend migration (after backend complete)

Testing Commands

ddev exec php artisan test --filter=SanctumSpaConfigTest
ddev exec php artisan test  # All tests
ddev exec vendor/bin/phpstan analyze
ddev exec vendor/bin/pint --test --dirty

References

• Laravel Sanctum SPA Authentication
• CORS with Credentials

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR configures Laravel Sanctum for SPA authentication mode, replacing insecure localStorage token storage with httpOnly cookie-based authentication. The changes include publishing Sanctum config with stateful domains, updating session configuration for cookie-based storage, configuring CORS to allow credential-based requests, and adding comprehensive test coverage.

Key Changes:

• Published Sanctum configuration with stateful domains for SPA authentication
• Changed session driver from database to cookie-based storage
• Configured CORS to support credentials with explicit origin whitelist
• Added comprehensive test suite to verify Sanctum and session configuration

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
config/sanctum.php	New Sanctum configuration with stateful domains, guards, and middleware for SPA authentication
config/cors.php	New CORS configuration allowing credentials from frontend domains with explicit origin whitelist
bootstrap/app.php	Added empty CSRF exception list with clarifying comment about Sanctum handling CSRF
.env.example	Updated with session cookie settings and new Sanctum/CORS environment variables
tests/Feature/Auth/SanctumSpaConfigTest.php	New comprehensive test suite verifying Sanctum configuration, session settings, and CORS setup