authentication-management

name	Authentication Management
description	Manages authentication flow for MutuaPIX (Laravel Sanctum + Next.js), handles mock mode security, and validates environment configurations
version	1.1.0
allowed-tools	["Read","Edit","Grep","Bash","mcp__chrome-devtools__*"]

Authentication Management Skill

Overview

This skill manages the complete authentication system for MutuaPIX, covering:

• Production authentication flow (Laravel Sanctum + JWT)
• Development mock mode (for frontend testing without backend)
• Environment detection and security validation
• CSRF token handling
• Session management

System Architecture

Backend: Laravel Sanctum

Authentication Flow:

1. GET /sanctum/csrf-cookie → Receives XSRF-TOKEN cookie
2. POST /api/v1/login {email, password, X-XSRF-TOKEN header}
3. Backend validates credentials
4. Returns {token, user} (token expires in 24h)
5. All requests include: Authorization: Bearer {token}

Configuration:

• Sanctum Expiration: 1440 minutes (24 hours)
• Stateful Domain: matrix.mutuapix.com
• Guard: web
• Rate Limiting: 5 requests/minute on login

Files:

• backend/routes/api/auth.php - Authentication routes
• backend/app/Http/Controllers/Auth/AuthController.php - Login/logout logic
• backend/config/sanctum.php - Sanctum configuration
• backend/config/cors.php - CORS settings

Frontend: Next.js + Zustand

State Management:

• Store: frontend/src/stores/authStore.ts
• Persistence: localStorage['auth-storage']
• Token Injection: Axios interceptor adds Authorization: Bearer {token}

Files:

• frontend/src/stores/authStore.ts - Authentication state
• frontend/src/services/auth.service.ts - API calls
• frontend/src/hooks/useAuth.ts - Authentication hook
• frontend/src/providers/AuthProvider.tsx - Auth context provider

Critical Security Issue: Mock Mode

Why Mock Mode Exists

Purpose: Allow frontend development without running backend API Problem: Implementation has security vulnerabilities if not properly configured

Mock Components

1. Environment Detection (src/lib/env.ts)

// ✅ CORRECT: Uses NEXT_PUBLIC_NODE_ENV for client-side detection
export const IS_PRODUCTION = process.env.NEXT_PUBLIC_NODE_ENV === 'production';
export const IS_DEVELOPMENT = !IS_PRODUCTION;

⚠️ WHY THIS IS CRITICAL:

• process.env.NODE_ENV is undefined in Next.js client-side code
• Only NEXT_PUBLIC_* variables are replaced at build time
• Previous code using process.env.NODE_ENV always evaluated to false (insecure!)

2. authStore Default State (CRITICAL VULNERABILITY)

File: frontend/src/stores/authStore.ts:91-96

❌ INSECURE (Current State):

user: devLocalUser,        // Mock admin user by default
token: devLocalToken,       // "local-dev-token"
isAuthenticated: true,      // Already authenticated!

✅ SECURE (Required Fix):

user: null,                 // Unauthenticated by default
token: null,
isAuthenticated: false,

3. MockLoginButton

File: frontend/src/components/auth/MockLoginButton.tsx

Status: ✅ Secured (renders null in production)

if (IS_PRODUCTION) {
  return null;  // Button not rendered in production
}

Environment Configuration

Production VPS (138.199.162.115)

File: /var/www/mutuapix-frontend-production/.env.production

# ✅ CORRECT CONFIGURATION
NEXT_PUBLIC_NODE_ENV=production
NEXT_PUBLIC_API_URL=https://api.mutuapix.com
NEXT_PUBLIC_API_BASE_URL=https://api.mutuapix.com
NEXT_PUBLIC_USE_AUTH_MOCK=false
NEXT_PUBLIC_AUTH_DISABLED=false
NEXT_PUBLIC_DEBUG=false

Critical: Must run npm run build (NOT just PM2 restart) for changes to take effect!

Local Development

File: frontend/.env.local

# ✅ RECOMMENDED CONFIGURATION
NEXT_PUBLIC_NODE_ENV=development
NEXT_PUBLIC_API_URL=http://localhost:8000    # Local backend!
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_USE_AUTH_MOCK=true              # Enable mock for dev
NEXT_PUBLIC_AUTH_DISABLED=false
NEXT_PUBLIC_DEBUG=true

⚠️ NEVER point local environment to production API!

Deployment Checklist

When deploying authentication changes:

Backend Deployment

• Verify Sanctum configuration hasn't changed
• Check CORS allows frontend domain
• Test CSRF token endpoint: curl https://api.mutuapix.com/sanctum/csrf-cookie -I
• Test login endpoint with invalid credentials (should return 401)
• Restart PM2: ssh root@49.13.26.142 'pm2 restart mutuapix-api'

Frontend Deployment

• Verify .env.production exists on VPS with correct values
• Check NEXT_PUBLIC_NODE_ENV=production is set
• Check NEXT_PUBLIC_USE_AUTH_MOCK=false is set
• CRITICAL: Delete .next cache: rm -rf .next
• Run full build: npm run build
• Restart PM2: pm2 restart mutuapix-frontend
• Verify mock button NOT visible: Use MCP Chrome DevTools
• Verify console shows IS_PRODUCTION: true
• Test login flow with real credentials

Post-Deployment Verification (MCP)

// 1. Navigate to production login
await mcp__chrome-devtools__navigate_page({
  url: 'https://matrix.mutuapix.com/login'
});

// 2. Check console for mock mode messages
const console = await mcp__chrome-devtools__list_console_messages();
// Should NOT contain: "🔓 Acesso liberado no modo desenvolvimento"

// 3. Take snapshot to verify mock button not rendered
const snapshot = await mcp__chrome-devtools__take_snapshot();
// Should NOT contain: "Login de Desenvolvimento" button

// 4. Monitor network requests after login
const requests = await mcp__chrome-devtools__list_network_requests({
  resourceTypes: ['xhr', 'fetch']
});
// Should call: https://api.mutuapix.com/api/v1/login
// Should NOT call: back-api-mutuapix.test (old dev URL)

Common Issues & Solutions

Issue 1: Mock Login Button Visible in Production

Symptoms:

• Button "🔓 Login de Desenvolvimento" appears on production login page
• Console shows development messages

Diagnosis:

# Check production environment file
ssh root@138.199.162.115 'cat /var/www/mutuapix-frontend-production/.env.production | grep NODE_ENV'

Solution:

1. Ensure NEXT_PUBLIC_NODE_ENV=production in .env.production
2. Delete cache: ssh root@138.199.162.115 'cd /var/www/mutuapix-frontend-production && rm -rf .next'
3. Rebuild: ssh root@138.199.162.115 'cd /var/www/mutuapix-frontend-production && npm run build'
4. Restart: ssh root@138.199.162.115 'pm2 restart mutuapix-frontend'

Issue 2: API Calls Going to Wrong URL

Symptoms:

• Network tab shows requests to back-api-mutuapix.test
• CORS errors in console

Diagnosis:

# Check if environment variables were embedded in build
ssh root@138.199.162.115 'grep -r "back-api-mutuapix.test" /var/www/mutuapix-frontend-production/.next/static/chunks/ | head -5'

Solution:

1. Same as Issue 1 - rebuild with correct .env.production
2. Verify API URL in build: grep -r "api.mutuapix.com" .next/static/chunks/ | head -1

Issue 3: Login Returns 401 Unauthorized

Symptoms:

• Valid credentials rejected
• Backend logs show "CSRF token mismatch"

Diagnosis:

# Test CSRF token endpoint
curl -I https://api.mutuapix.com/sanctum/csrf-cookie

# Check CORS headers
curl -I https://api.mutuapix.com/api/v1/login \
  -H "Origin: https://matrix.mutuapix.com"

Solution:

1. Verify backend/config/sanctum.php has matrix.mutuapix.com in stateful domains
2. Verify backend/config/cors.php allows frontend origin
3. Check cookies are being set with correct domain (.mutuapix.com)

Issue 4: User Already Authenticated Without Login

Symptoms:

• Fresh browser session shows user as logged in
• Mock admin user appears automatically

Diagnosis:

// Check authStore default state
// File: frontend/src/stores/authStore.ts:91-96

Solution:

1. Fix authStore default state to:

   user: null,
   token: null,
   isAuthenticated: false,
   

2. Rebuild and deploy frontend

Testing Procedures

Manual Testing (Production)

1. Clear State:

   // In browser console
   localStorage.clear();
   sessionStorage.clear();
   location.reload();
   

2. Verify Unauthenticated:

   • Should redirect to /login
   • Cannot access /user/dashboard or other protected routes

3. Test Login:

   • Enter valid credentials
   • Should see "Login realizado com sucesso" toast
   • Should redirect to dashboard
   • Token should be in localStorage['auth-storage']

4. Test Protected Routes:

   • Navigate to /user/dashboard
   • Should see user data (not mock data)
   • Network tab should show Authorization: Bearer {token} in headers

5. Test Logout:

   • Click logout
   • Should redirect to /login
   • localStorage['auth-storage'] should be empty

Automated Testing (MCP)

Use MCP Chrome DevTools for automated verification (see "Post-Deployment Verification" section above).

Security Best Practices

1. Never commit .env files (except .env.example)
2. Always verify environment before deployment
3. Use MCP Chrome DevTools to inspect production behavior
4. Test logout flow to ensure tokens are invalidated
5. Monitor failed login attempts via backend logs
6. Rotate Sanctum tokens if compromise suspected

Related Skills

• PIX Validation Expert - Handles PIX key email matching
• Documentation Updater - Keeps CLAUDE.md current with auth changes

Version History

• 1.1.0 (2025-10-16): Added comprehensive security audit

  • Documented mock mode vulnerabilities
  • Added MCP verification procedures
  • Included deployment checklist
  • Added troubleshooting guide

• 1.0.0 (2025-10-10): Initial authentication skill

  • Basic login/logout flow
  • Sanctum integration
  • Environment detection