spa-auth-development

name	spa-auth-development
description	Activate when working on SPA authentication flow, Sanctum cookie-based auth, Vue Router guards, auth store, login/register/password reset pages, or CORS/session configuration. Covers the full auth lifecycle from CSRF cookie to protected API calls.
license	MIT
metadata	{"author":"project"}

SPA Authentication Development

This project uses a decoupled SPA architecture where Vue handles all routing and Laravel serves as a JSON API with Sanctum cookie-based authentication.

Auth Flow

1. Vue app calls GET /sanctum/csrf-cookie to get XSRF token
2. User submits login form → POST /login (Fortify handles this)
3. Laravel returns session cookie + user data
4. All subsequent API calls include the session cookie automatically (withCredentials: true)
5. Protected routes use auth:sanctum middleware

Key Files

Backend

• config/sanctum.php — Stateful domains, guards, CSRF middleware
• config/cors.php — CORS paths (api/*, login, logout, register, etc.) with supports_credentials: true
• config/fortify.php — Auth features (registration, password reset, email verification)
• app/Providers/FortifyServiceProvider.php — Binds Fortify actions and custom LoginResponse
• app/Http/Responses/LoginResponse.php — Returns JSON with user data for SPA
• app/Http/Middleware/ApplyLocale.php — Sets locale from X-Locale header
• bootstrap/app.php — statefulApi() middleware, apply_locale alias

Frontend

• stores/auth.js — Pinia store with login, register, logout, getCurrentUser
• services/AuthService.ts — API calls for auth endpoints (login, register, forgot/reset password, etc.)
• router/index.js — Navigation guards checking requiresAuth and requiresAbility route meta
• plugins/axios.js — Axios configured with withCredentials, X-Locale header, base URL from window.AppConfig

CORS Configuration

For the SPA to work, these .env values must match:

APP_URL=http://localhost:8000
SANCTUM_STATEFUL_DOMAINS=localhost:8000
SESSION_DOMAIN=localhost

Route Guards

Routes use meta fields for auth:

• requiresAuth: true — Redirects to login if not authenticated
• requiresAbility: 'ability_name' — Checks user abilities via Bouncer
• isPublicAuthPage: true — Redirects to dashboard if already authenticated
• isOwner: true — Owner-only routes

Authorization

Uses Silber Bouncer with abilities:

• Abilities defined in resources/app/stub/abilities.js (CREATE_USER, EDIT_USER, etc.)
• Checked in Vue Router guards and sidebar menu visibility
• Backend uses Gate::authorize() in controllers
• Roles seeded in database/seeders/BouncerSeeder.php