alrahma_sunday_school_api/docs/api_auth_controller_plan.md

AuthController plan

Scope

• Controller: app/Http/Controllers/Api/Auth/AuthController.php
• Purpose: JWT login, token refresh, current-user lookup, logout.
• Primary dependencies:
  • App\Services\Auth\ApiLoginSecurityService (rate limiting / IP blocking, attempt tracking, response builder)
  • PHPOpenSourceSaver\JWTAuth\Facades\JWTAuth (token issuance/refresh/invalidation)
  • Illuminate\Support\Facades\Auth (current user)

Routes

• Public (no /v1)
  • POST /api/login → login
• Versioned (/v1)
  • POST /api/v1/login → login
• Auth prefix (/v1/auth)
  • POST /api/v1/auth/login → login
  • POST /api/v1/auth/refresh → refresh (middleware: jwt.auth)
  • POST /api/v1/auth/logout → logout (middleware: auth:api)
  • GET /api/v1/auth/me → me (middleware: auth:api)

Authentication & authorization

• login: public; checks credentials, then issues JWT.
• refresh: requires a valid JWT via jwt.auth.
• me/logout: require auth:api (JWT/guarded user).

Request/validation expectations

• login:
  • Accepts JSON or form payload. Extracts email, password.
  • Returns 400 if missing.
  • Normalizes email to lowercase; looks up User by case-insensitive email.
• refresh:
  • Expects bearer token in request (handled by JWTAuth::parseToken()).
• logout:
  • Attempts JWT invalidation when bearer token looks like a JWT (3 dot-separated segments).
  • Also deletes currentAccessToken() when supported (supports Sanctum-style tokens if present).

Response shapes

• login success: ApiLoginSecurityService::buildLoginResponse($user, $jwtToken) (treat as canonical shape).
• login failures:
  • 400: { status:false, message:"Email and password are required." }
  • 401: { status:false, message:"Invalid email or password." }
  • 403: { status:false, message:"Account suspended. Please reset your password." }
  • 429: { status:false, message:"Too many failed attempts..." }
• refresh success (Base API shape):
  • { status:true, message:"Token refreshed.", data:{ access_token, token_type:"bearer", expires_in } }
• me success (Base API shape):
  • { status:true, message:"OK", data:{ id, firstname, lastname, email, class_section_id, class_section_name } }
• logout success (Base API shape):
  • { status:true, message:"Logged out.", data:null }

Side effects & security notes

• Logs IP attempt / failed attempt / successful login via ApiLoginSecurityService.
• Suspended users are rejected after verifying credentials (avoids email enumeration by response shape).

Error handling expectations

• refresh: any exception becomes 401 via respondError('Token refresh failed.', 401).
• logout: JWT invalidation errors are intentionally ignored.

Test plan (feature)

• Login
  • Missing email/password → 400.
  • Unknown email → 401 and IP attempt logged.
  • Wrong password → 401 and failed attempt handling invoked.
  • Suspended user with correct password → 403.
  • Successful login returns expected response shape and includes token.
  • IP blocked → 429.
• Refresh
  • Valid token refresh returns new token + expires_in.
  • Invalid/missing token returns 401.
• Me/Logout
  • Requires auth; returns 401 unauthenticated.
  • Logout returns success even if token invalidation fails.