Authentication & Security

The HRMS uses cookie-based SPA authentication powered by Laravel Sanctum. This provides secure session management without requiring the frontend to store or manage tokens.

Authentication Flow

Browser (localhost:3000)                     Laravel (localhost:8000)
────────────────────────                     ────────────────────────

1. GET /sanctum/csrf-cookie             ──►  Sets XSRF-TOKEN cookie
   ◄── 204 No Content                  ◄──

2. POST /login { email, password }      ──►  Validates credentials
   (X-XSRF-TOKEN header)                    Creates session
   ◄── 200 { message: "Logged in" }    ◄──  Sets session cookie

3. GET /api/me                          ──►  Reads session cookie
   (cookies sent automatically)              Returns user + roles + permissions
   ◄── 200 { data: { user... } }       ◄──

4. POST /logout                         ──►  Destroys session
   ◄── 200 { message: "Logged out" }   ◄──  Clears cookies

Step-by-Step Explanation

1. CSRF Cookie — Before login, the frontend requests a CSRF token by calling /sanctum/csrf-cookie. Laravel responds with a 204 No Content and sets an XSRF-TOKEN cookie.

2. Login — The frontend sends credentials to POST /login along with the X-XSRF-TOKEN header (read from the CSRF cookie). On success, Laravel creates an encrypted session cookie.

3. Authenticated Requests — All subsequent API calls automatically include the session cookie. The frontend calls GET /api/me to retrieve the current user's profile, roles, and permissions.

4. Logout — Calling POST /logout destroys the server-side session, regenerates the CSRF token, and clears the session cookie.

Cookie Configuration

Setting	Value	Purpose
SESSION_DRIVER	cookie	Session stored in encrypted cookie (stateless server)
SESSION_DOMAIN	localhost	Cookie shared between API and frontend on localhost
SANCTUM_STATEFUL_DOMAINS	localhost:3000	Frontend origin allowed for cookie auth
CORS allowed_origins	FRONTEND_URL	Only allows requests from the frontend origin

Frontend Auth Implementation

The frontend implements an AuthProvider React context that:

1. Calls GET /api/me on mount to check if the user has an active session.
2. Exposes can(permission) and hasRole(role) helpers for conditional rendering.
3. Provides signIn() and signOut() methods.
4. Redirects unauthenticated users to /login.
5. Supports ?next= query parameter for post-login redirect.

Security Features

Feature	Implementation
CSRF protection	XSRF-TOKEN cookie + X-XSRF-TOKEN header on every state-changing request
Session fixation prevention	Session ID is regenerated after successful login
Credential storage	Passwords are hashed with bcrypt; plain-text passwords are never stored
Cookie encryption	Session cookies are encrypted by Laravel; cannot be read or modified client-side
CORS restriction	Only the configured frontend origin can make API calls
Protected file downloads	Employee attachments, KPI evidence, and probation signatures require authenticated session

Error Responses

HTTP Code	Meaning	When It Occurs
401	Unauthenticated	No valid session cookie, expired session
403	Forbidden	User lacks required permission or role
422	Validation Error	Invalid login credentials, failed form validation

Password Requirements

• Minimum 8 characters
• Must include uppercase letter, lowercase letter, number, and symbol
• Current password must be provided when changing password

Self-Service Password Reset

Self-service password reset (forgot password flow) is planned for a future update. Currently, users must contact their Admin or HR representative to reset a password.