> ## Documentation Index
> Fetch the complete documentation index at: https://alan-ramirez-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 🔐 Autenticación y RBAC

> Gestión de identidad stateless con JWT y control de acceso basado en roles.

El núcleo de seguridad de esta API descansa sobre un modelo de autenticación *stateless* utilizando **JSON Web Tokens (JWT)** y una arquitectura estricta de **Control de Acceso Basado en Roles (RBAC)**.

## 🔑 Autenticación Stateless (JWT)

El flujo de autenticación está centralizado en el `AuthController`, diseñado para ser ligero, seguro y totalmente adaptado al cambio de idioma.

<ParamField path="POST" type="/api/v1/auth/login">
  Valida credenciales y emite un token JWT firmado si el usuario está activo y autenticado correctamente.
</ParamField>

### 🛡️ Flujo de Validación y Seguridad

1. **Verificación de Credenciales:** Valida email y contraseña cifrada usando el facade `Hash` de Laravel.
2. **Protección contra Bajas Lógicas:** Si el usuario existe pero ha sido desactivado (Soft Delete), el sistema bloquea el acceso con un código `403 Forbidden`, impidiendo la emisión del token.
3. **Prevención de Fuerza Bruta:** La ruta está protegida por un middleware perimetral (`throttle:4,1`) que bloquea la IP durante un minuto tras 4 intentos fallidos.

```php theme={null}
// Fragmento de AuthController.php validando usuarios inactivos
$user = User::withTrashed()->where('email',$request->email)->first();

if ($user->trashed()) {
    $errorMsg =$isEn 
        ? 'Your account is inactive. Contact an administrator.' 
        : 'Tu cuenta está inactiva. Contacta a un administrador.';
    return response()->json(['error' => $errorMsg], 403);
}
```

## 🛂 Control de Acceso Basado en Roles (RBAC)

Una vez emitido el token, la autorización de las rutas protegidas se delega al middleware personalizado `CheckRole`. Este componente intercepta las peticiones, extrae el perfil del usuario autenticado y verifica dinámicamente sus privilegios.

### 🚦 Lógica de Intercepción

El middleware aprovecha la relación Many-to-Many entre `User` y `Role` de Eloquent. Utiliza el operador *spread* (`...$roles`) nativo de PHP para recibir una cantidad variable de roles permitidos directamente desde la definición de la ruta.

```php theme={null}
// Fragmento de CheckRole.php
public function handle(Request $request, Closure $next, ...$roles)
{
    $user = $request->user();

    // Compara la colección de roles del usuario contra los roles exigidos
    $hasAccess = $user->roles->whereIn('name', $roles)->isNotEmpty();

    if (!$hasAccess) {
        $errorMsg = $isEn 
            ? 'Access denied. Insufficient privileges for this action.' 
            : 'Acceso denegado. Privilegios insuficientes para esta acción.';
            
        return response()->json(['error' => $errorMsg], 403);
    }

    return $next($request);
}
```

### 🛤️ Implementación Limpia en el Enrutador

Esta arquitectura permite proteger grupos completos de endpoints con una sintaxis declarativa y altamente legible en el archivo de rutas.

```php theme={null}
// Fragmento de api.php
// Ejemplo: Acceso exclusivo para administradores y auditores
Route::middleware(['auth:api', 'role:admin,auditor'])->group(function () {
    Route::get('audit-logs', [AuditLogController::class, 'index']);
});

// Ejemplo: Acceso exclusivo para administradores (Write)
Route::middleware(['auth:api', 'role:admin'])->group(function () {
    Route::post('users', [UserController::class, 'store']);
});
```