theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/seguridad-laravel/SKILL.md

@@ -0,0 +1,945 @@
+---
+name: seguridad-laravel
+description: Buenas prácticas de seguridad en Laravel — autenticación, autorización, seguridad en Eloquent, CSRF, prevención de XSS, seguridad de APIs y configuraciones de despliegue seguras.
+---
+
+# Buenas prácticas de seguridad en Laravel
+
+Guía integral de seguridad para aplicaciones Laravel, orientada a protegerlas contra las vulnerabilidades más comunes.
+
+## Cuándo activar
+
+- Al configurar autenticación y autorización en Laravel (Sanctum, Passport, Jetstream, Breeze)
+- Al implementar roles de usuario, permisos y policies
+- Al configurar ajustes de seguridad de producción y variables de entorno
+- Al revisar aplicaciones Laravel en busca de vulnerabilidades de seguridad
+- Al desplegar aplicaciones Laravel a producción
+- Al escribir consultas Eloquent y migraciones seguras
+
+## Configuración de producción
+
+### Ajustes esenciales de producción
+
+```php
+// config/app.php
+'env' => env('APP_ENV', 'production'),
+'debug' => (bool) env('APP_DEBUG', false), // CRÍTICO: nunca true en producción
+'key' => env('APP_KEY'), // Debe estar definida: php artisan key:generate
+
+// config/session.php
+'secure' => env('SESSION_SECURE_COOKIE', true),
+'http_only' => true,
+'same_site' => 'lax',
+
+// Verificar que APP_KEY esté definida en el arranque
+// bootstrap/app.php o un service provider
+if (empty(config('app.key'))) {
+    throw new RuntimeException('APP_KEY no está definida. Ejecuta: php artisan key:generate');
+}
+```
+
+### Seguridad del archivo de entorno
+
+```bash
+# NUNCA subas el .env al control de versiones
+# .gitignore ya incluye .env por defecto
+
+# Usa .env.example con placeholders en su lugar
+DB_PASSWORD=
+APP_KEY=
+SANCTUM_TOKEN_PREFIX=
+
+# Valida las variables requeridas en el arranque
+// En AppServiceProvider::boot()
+$requiredKeys = ['app.key', 'database.connections.mysql.database', 'database.connections.mysql.username'];
+foreach ($requiredKeys as $key) {
+    if (empty(config($key))) {
+        throw new RuntimeException("Falta la clave de configuración requerida: {$key}");
+    }
+}
+```
+
+### Forzar HTTPS
+
+```php
+// AppServiceProvider::boot() o middleware
+if (app()->environment('production')) {
+    URL::forceScheme('https');
+    request()->server->set('HTTPS', 'on');
+}
+
+// config/app.php para proxies de confianza (balanceadores de carga)
+// Usa rangos de IP específicos — * confía en todos y permite suplantar X-Forwarded-*
+// AWS: '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'
+'trusted_proxies' => ['10.0.0.0/8', '172.16.0.0/12'],
+
+// Forzar HTTPS en producción vía middleware
+// app/Http/Middleware/ForceHttps.php
+public function handle($request, Closure $next)
+{
+    if (!$request->secure() && app()->environment('production')) {
+        return redirect()->secure($request->getRequestUri());
+    }
+    return $next($request);
+}
+```
+
+## Autenticación
+
+### Sanctum (autenticación por token de API)
+
+```php
+// config/sanctum.php
+'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', sprintf(
+    '%s%s',
+    'localhost,localhost:3000,127.0.0.1,127.0.0.1:8000,::1',
+    env('APP_URL') ? ',' . parse_url(env('APP_URL'), PHP_URL_HOST) : ''
+)));
+
+'expiration' => 60 * 24, // Expiración del token en minutos (null = nunca)
+'token_prefix' => env('SANCTUM_TOKEN_PREFIX', ''),
+
+// Emitir tokens con habilidades (abilities)
+$token = $user->createToken('api-token', ['read', 'write'])->plainTextToken;
+
+// Validar habilidades en las rutas
+Route::middleware('auth:sanctum')->group(function () {
+    Route::get('/orders', function () {
+        // El usuario debe tener la habilidad 'read'
+        abort_unless(Auth::user()->tokenCan('read'), 403);
+        // ...
+    })->middleware('abilities:read');
+
+    Route::post('/orders', function () {
+        // El usuario debe tener la habilidad 'write'
+        abort_unless(Auth::user()->tokenCan('write'), 403);
+        // ...
+    })->middleware('abilities:write');
+});
+```
+
+### Seguridad de contraseñas
+
+```php
+// config/hashing.php
+// El valor por defecto es bcrypt. Argon2id es más fuerte.
+'bcrypt' => [
+    'rounds' => env('BCRYPT_ROUNDS', 12), // Aumenta para un hashing más fuerte
+],
+
+'argon' => [
+    'memory' => 65536,
+    'threads' => 4,
+    'time' => 4,
+],
+
+// Validación de contraseñas en RegisterRequest
+public function rules(): array
+{
+    return [
+        'password' => [
+            'required',
+            'confirmed',
+            Password::min(12)
+                ->letters()
+                ->mixedCase()
+                ->numbers()
+                ->symbols()
+                ->uncompromised(), // Consulta haveibeenpwned
+        ],
+    ];
+}
+
+// Limitar la tasa de intentos de inicio de sesión
+// App\Http\Controllers\Auth\AuthenticatedSessionController
+protected function authenticated(Request $request, $user)
+{
+    if ($user->wasRecentlyLockedOut()) {
+        // Notificar al usuario de un inicio de sesión sospechoso
+        $user->notify(new SuspiciousLoginNotification($request->ip()));
+    }
+}
+```
+
+### Gestión de sesiones
+
+```php
+// config/session.php
+'driver' => env('SESSION_DRIVER', 'database'), // database/redis > file
+'lifetime' => env('SESSION_LIFETIME', 120),
+'expire_on_close' => env('SESSION_EXPIRE_ON_CLOSE', false),
+'encrypt' => env('SESSION_ENCRYPT', false),
+
+// Regenerar la sesión al iniciar sesión
+// App\Http\Controllers\Auth\AuthenticatedSessionController
+public function store(LoginRequest $request): RedirectResponse
+{
+    $request->authenticate();
+    $request->session()->regenerate(); // CRÍTICO: previene la fijación de sesión
+    return redirect()->intended(RouteServiceProvider::HOME);
+}
+
+// Invalidar la sesión al cerrar sesión
+public function destroy(Request $request): RedirectResponse
+{
+    Auth::guard('web')->logout();
+    $request->session()->invalidate();
+    $request->session()->regenerateToken();
+    return redirect('/');
+}
+```
+
+## Autorización
+
+### Gates
+
+```php
+// App\Providers\AuthServiceProvider
+use App\Models\Post;
+use App\Models\User;
+use Illuminate\Support\Facades\Gate;
+
+public function boot(): void
+{
+    Gate::define('update-post', function (User $user, Post $post): bool {
+        return $user->id === $post->user_id;
+    });
+
+    Gate::define('publish-post', function (User $user): bool {
+        return $user->role === 'editor' || $user->role === 'admin';
+    });
+
+    // Usar before() para el override de super-admin
+    Gate::before(function (User $user, string $ability): ?bool {
+        if ($user->role === 'super-admin') {
+            return true; // Concede todas las habilidades
+        }
+        return null; // Continúa con las verificaciones normales
+    });
+}
+
+// Uso en controladores
+public function update(Request $request, Post $post): RedirectResponse
+{
+    Gate::authorize('update-post', $post);
+    // O: $this->authorize('update-post', $post);
+    // O: abort_unless(Auth::user()->can('update-post', $post), 403);
+    // ...
+}
+```
+
+### Policies
+
+```php
+// App\Policies\PostPolicy
+class PostPolicy
+{
+    use HandlesAuthorization;
+
+    public function viewAny(?User $user): bool
+    {
+        return true; // Listado público
+    }
+
+    public function view(?User $user, Post $post): bool
+    {
+        return $post->is_published || ($user && $user->id === $post->user_id);
+    }
+
+    public function create(User $user): bool
+    {
+        return $user->hasVerifiedEmail(); // Primero debe verificar su correo
+    }
+
+    public function update(User $user, Post $post): bool
+    {
+        return $user->id === $post->user_id;
+    }
+
+    public function delete(User $user, Post $post): bool
+    {
+        return $user->id === $post->user_id && $post->created_at->diffInDays(now()) <= 30;
+    }
+
+    public function restore(User $user, Post $post): bool
+    {
+        return $user->role === 'admin';
+    }
+
+    public function forceDelete(User $user, Post $post): bool
+    {
+        return $user->role === 'super-admin';
+    }
+}
+
+// Registrar en AuthServiceProvider
+protected $policies = [
+    Post::class => PostPolicy::class,
+];
+
+// Uso en el controlador
+public function show(Post $post): View
+{
+    $this->authorize('view', $post);
+    return view('posts.show', compact('post'));
+}
+
+// Uso en Blade
+@can('update', $post)
+    <a href="{{ route('posts.edit', $post) }}">Editar</a>
+@endcan
+
+@cannot('update', $post)
+    <span>No puedes editar esta publicación</span>
+@endcannot
+```
+
+### Autorización con middleware
+
+```php
+// Usar middleware en las rutas
+Route::put('/posts/{post}', [PostController::class, 'update'])
+    ->middleware('can:update,post');
+
+Route::get('/posts/create', [PostController::class, 'create'])
+    ->middleware('can:create,App\Models\Post');
+
+// Middleware de autorización personalizado
+// app/Http/Middleware/CheckRole.php
+class CheckRole
+{
+    public function handle(Request $request, Closure $next, string $role): mixed
+    {
+        if (!$request->user() || $request->user()->role !== $role) {
+            abort(403, 'No autorizado. Esta área requiere el rol: ' . $role);
+        }
+        return $next($request);
+    }
+}
+
+// Registrar en el Kernel
+protected $routeMiddleware = [
+    'role' => \App\Http\Middleware\CheckRole::class,
+];
+
+// Uso en rutas
+Route::middleware(['auth', 'role:admin'])->group(function () {
+    Route::get('/admin', [AdminController::class, 'index']);
+});
+```
+
+## Seguridad en Eloquent
+
+### Protección contra asignación masiva
+
+```php
+// MAL: $guarded = [] permite asignar TODAS las columnas de forma masiva
+// NUNCA uses $guarded = [] en producción
+
+// BIEN: lista blanca de atributos fillable
+final class User extends Authenticatable
+{
+    protected $fillable = [
+        'name',
+        'email',
+        'phone',
+        'avatar',
+    ];
+    // NUNCA añadas 'role', 'is_admin', 'is_verified' aquí
+}
+
+// BIEN: controla explícitamente qué campos pueden llenarse desde las requests
+public function store(StoreUserRequest $request): RedirectResponse
+{
+    $user = User::create($request->safe()->only([
+        'name', 'email', 'phone', 'avatar'
+    ]));
+    // $request->safe() usa solo datos validados
+    // $request->only() por sí solo NO es seguro sin reglas de validación
+}
+
+// MAL: crear un usuario con los datos de la request directamente
+User::create($request->all()); // ¡VULNERABLE a asignación masiva!
+
+// MEJOR: usar DTOs para la creación
+$user = User::create($request->validated()); // Solo campos validados
+```
+
+### Prevención de inyección SQL
+
+```php
+// BIEN: Eloquent parametriza las consultas automáticamente
+User::where('email', $userInput)->first();
+User::whereRaw('email = ?', [$userInput])->first();
+
+// BIEN: el Query Builder también parametriza
+DB::table('users')->where('email', $userInput)->first();
+DB::select('SELECT * FROM users WHERE email = ?', [$userInput]);
+
+// MAL: interpolación de strings en crudo
+DB::select("SELECT * FROM users WHERE email = '{$userInput}'"); // ¡VULNERABLE!
+User::whereRaw("email = '{$userInput}'")->first(); // ¡VULNERABLE!
+
+// MAL: whereRaw/orderByRaw con entrada sin escapar
+User::orderByRaw($userInput); // ¡VULNERABLE!
+User::groupByRaw($userInput); // ¡VULNERABLE!
+
+// MAL: DB::statement con concatenación
+DB::statement("INSERT INTO users (email) VALUES ('{$userInput}')"); // ¡VULNERABLE!
+```
+
+### Casting de atributos
+
+```php
+final class User extends Authenticatable
+{
+    protected $casts = [
+        'email_verified_at' => 'datetime',
+        'is_admin' => 'boolean', // El cast a booleano previene inyección de strings
+        'settings' => 'array', // json_encode/json_decode automático
+        'metadata' => 'encrypted:array', // Casting cifrado en Laravel 11+
+        'password' => 'hashed', // Laravel 10+ hashea automáticamente al asignar
+    ];
+}
+```
+
+### Seguridad del modelo
+
+```php
+final class User extends Authenticatable
+{
+    // Ocultar atributos sensibles en respuestas JSON/API
+    protected $hidden = [
+        'password',
+        'remember_token',
+        'two_factor_secret',
+        'two_factor_recovery_codes',
+    ];
+
+    // Añadir (append) solo atributos calculados seguros
+    protected $appends = ['full_name']; // seguro
+    // NUNCA añadas datos calculados sensibles
+}
+
+final class Post extends Model
+{
+    // Global scope para filtrar registros con soft delete
+    use SoftDeletes;
+
+    // Prevenir N+1 restringiendo el lazy loading (modo estricto opcional)
+    // AppServiceProvider::boot()
+    // Model::preventLazyLoading(!app()->isProduction());
+}
+```
+
+## Protección CSRF
+
+### Protección por defecto
+
+```php
+// El CSRF de Laravel está habilitado por defecto vía el middleware VerifyCsrfToken
+// app/Http/Kernel.php (protected $middlewareGroups['web'])
+
+// Todos los formularios POST/PUT/PATCH/DELETE deben incluir @csrf
+<form method="POST" action="/posts">
+    @csrf
+    <input type="text" name="title">
+    <button type="submit">Crear</button>
+</form>
+```
+
+### Excluir rutas (con cuidado)
+
+```php
+// app/Http/Middleware/VerifyCsrfToken.php
+class VerifyCsrfToken extends Middleware
+{
+    // Excluye solo rutas que tengan protección CSRF externa (webhooks, etc.)
+    protected $except = [
+        'stripe/*', // Los webhooks de Stripe usan su propia verificación de firma
+        // Evita un 'api/*' genérico — las rutas stateful de Sanctum necesitan CSRF.
+        // Excluye solo rutas específicas de webhooks/endpoints sin estado.
+    ];
+}
+```
+
+### CSRF con JavaScript
+
+```html
+<meta name="csrf-token" content="{{ csrf_token() }}">
+
+<script>
+// Ejemplo con Axios (Laravel incluye Axios)
+axios.defaults.headers.common['X-CSRF-TOKEN'] = document.querySelector(
+    'meta[name="csrf-token"]'
+).getAttribute('content');
+
+// Ejemplo con Fetch
+fetch('/posts', {
+    method: 'POST',
+    headers: {
+        'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').getAttribute('content'),
+        'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(data),
+});
+</script>
+```
+
+## Prevención de XSS
+
+### Seguridad en plantillas Blade
+
+```blade
+{{-- SEGURO: escapado automáticamente por Blade --}}
+{{ $userInput }}
+
+{{-- PELIGROSO: salida en crudo — NUNCA usar con entrada del usuario --}}
+{!! $userInput !!}
+
+{{-- SEGURO: usa {!! !!} solo con contenido de confianza que tú controlas --}}
+{!! $trustedHtmlFromYourServer !!}
+
+{{-- BIEN: usa directivas de escapado específicas --}}
+@js($data) {{-- Codifica a JSON para JavaScript --}}
+@json($data) {{-- Codifica a JSON en plantillas --}}
+
+{{-- MAL: entrada del usuario directa en HTML crudo --}}
+<div>{!! $user->bio !!}</div> {{-- VULNERABLE si el usuario provee la bio --}}
+```
+
+### Manejo seguro de HTML
+
+```php
+// Cuando debas permitir algo de HTML, usa un enfoque de lista blanca
+use HTMLPurifier; // Requiere: composer require ezyang/htmlpurifier
+
+public function sanitizeHtml(string $dirty): string
+{
+    $config = \HTMLPurifier_Config::createDefault();
+    $config->set('HTML.Allowed', 'p,b,i,a[href],ul,ol,li,br');
+    $config->set('URI.AllowedSchemes', ['http', 'https', 'mailto']);
+    $purifier = new \HTMLPurifier($config);
+    return $purifier->purify($dirty);
+}
+
+// En Blade:
+<div>{!! $sanitizedContent !!}</div> {{-- Seguro tras la purificación --}}
+```
+
+### Escapado en contexto JavaScript
+
+```blade
+{{-- SEGURO: la directiva @js de Blade escapa para el contexto JavaScript --}}
+<script>
+    const user = @js($user); // JSON + escapado para contexto JS
+    const settings = @json($settings); // Codificación JSON directa
+</script>
+
+{{-- PELIGROSO: JSON manual en contexto JS --}}
+<script>
+    const user = {{ json_encode($user) }}; // ¡NO escapado para JS!
+</script>
+```
+
+### Cabeceras HTTP para protección contra XSS
+
+```php
+// App\Http\Middleware\SecurityHeaders.php
+class SecurityHeaders
+{
+    public function handle(Request $request, Closure $next): mixed
+    {
+        $response = $next($request);
+
+        $response->headers->set('X-Content-Type-Options', 'nosniff');
+        $response->headers->set('X-Frame-Options', 'DENY');
+        $response->headers->set('X-XSS-Protection', '1; mode=block');
+        $response->headers->set('Referrer-Policy', 'strict-origin-when-cross-origin');
+        $response->headers->set(
+            'Content-Security-Policy',
+            "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'"
+        );
+
+        return $response;
+    }
+}
+
+// Registrar en el kernel
+protected $middleware = [
+    \App\Http\Middleware\SecurityHeaders::class,
+];
+```
+
+## Validación de entrada
+
+### Validación con form requests
+
+```php
+final class StorePostRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()?->can('create', Post::class) ?? false;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'title' => ['required', 'string', 'max:255', 'sanitize_html'],
+            'content' => ['required', 'string', 'max:10000'],
+            'image' => [
+                'required',
+                'image',
+                'mimes:jpg,jpeg,png,gif,webp', // Lista blanca de tipos específicos
+                'max:2048', // Máximo 2 MB
+            ],
+            'tags' => ['array'],
+            'tags.*' => ['integer', 'exists:tags,id'],
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'title.max' => 'El título no debe exceder los 255 caracteres.',
+            'image.max' => 'La imagen debe pesar menos de 2 MB.',
+        ];
+    }
+
+    // Sanitizar la entrada después de la validación
+    public function validated($key = null, $default = null): mixed
+    {
+        $validated = parent::validated();
+        $validated['title'] = strip_tags($validated['title']);
+        return $key ? ($validated[$key] ?? $default) : $validated;
+    }
+}
+```
+
+### Reglas de validación personalizadas
+
+```php
+// app/Rules/StrongPassword.php
+class StrongPassword implements Rule
+{
+    public function passes($attribute, $value): bool
+    {
+        return preg_match('/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&#^()_\-+=])[A-Za-z\d@$!%*?&#^()_\-+=]{12,}$/', $value);
+    }
+
+    public function message(): string
+    {
+        return 'El campo :attribute debe tener al menos 12 caracteres con mayúscula, minúscula, número y símbolo.';
+    }
+}
+
+// app/Rules/NotBlacklistedDomain.php
+class NotBlacklistedDomain implements Rule
+{
+    private array $blacklisted = ['mailinator.com', 'guerrillamail.com'];
+
+    public function passes($attribute, $value): bool
+    {
+        $domain = substr(strrchr($value, '@'), 1);
+        return !in_array(strtolower($domain), $this->blacklisted);
+    }
+
+    public function message(): string
+    {
+        return 'No se permiten correos de dominios desechables.';
+    }
+}
+```
+
+## Seguridad de APIs
+
+### Limitación de tasa (rate limiting)
+
+```php
+// App/Providers/RouteServiceProvider
+protected function configureRateLimiting(): void
+{
+    RateLimiter::for('api', function (Request $request) {
+        return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
+    });
+
+    RateLimiter::for('auth', function (Request $request) {
+        return Limit::perMinute(5)->by($request->ip())
+            ->response(function () {
+                return response()->json([
+                    'message' => 'Demasiados intentos de inicio de sesión. Inténtalo de nuevo en 1 minuto.',
+                ], 429);
+            });
+    });
+
+    RateLimiter::for('uploads', function (Request $request) {
+        return Limit::perHour(10)->by($request->user()?->id ?? $request->ip())
+            ->response(function () {
+                return response()->json([
+                    'message' => 'Límite de subidas alcanzado. Inténtalo más tarde.',
+                ], 429);
+            });
+    });
+}
+
+// Uso en rutas
+Route::middleware(['auth:sanctum', 'throttle:api'])->group(function () {
+    Route::apiResource('posts', PostController::class);
+});
+
+Route::post('/login', [AuthController::class, 'login'])
+    ->middleware('throttle:auth');
+```
+
+### Autenticación de API — Sanctum vs Passport
+
+```php
+// Sanctum (recomendado para la mayoría de apps — simple, first-party, SPA)
+// config/sanctum.php
+'expiration' => 60 * 24, // Los tokens expiran a las 24 horas
+'model' => User::class,
+
+// Emitir tokens con alcances (scopes)
+$token = $user->createToken('client-name', [
+    'posts:read',
+    'posts:write',
+])->plainTextToken;
+
+// Alcances vía middleware
+Route::middleware('auth:sanctum')->group(function () {
+    Route::get('/posts', [PostController::class, 'index'])
+        ->middleware('abilities:posts:read');
+
+    Route::post('/posts', [PostController::class, 'store'])
+        ->middleware('abilities:posts:write');
+});
+
+// Passport (OAuth2 — para clientes de terceros o flujos de auth complejos)
+// Instalar: composer require laravel/passport
+Passport::tokensExpireIn(now()->addDays(15));
+Passport::refreshTokensExpireIn(now()->addDays(30));
+Passport::personalAccessTokensExpireIn(now()->addMonths(6));
+```
+
+### Configuración de CORS
+
+```php
+// config/cors.php
+return [
+    'paths' => ['api/*', 'sanctum/csrf-cookie'],
+    'allowed_methods' => ['*'],
+    'allowed_origins' => explode(',', env('CORS_ALLOWED_ORIGINS', '')), // Lista blanca de orígenes específicos
+    'allowed_origins_patterns' => [],
+    'allowed_headers' => ['*'],
+    'exposed_headers' => ['X-Total-Count', 'X-Pagination-Page'],
+    'max_age' => 0,
+    'supports_credentials' => true, // Requerido para la auth SPA de Sanctum
+];
+
+// NUNCA: permitir todos los orígenes en producción salvo que sea absolutamente necesario
+// 'allowed_origins' => ['*'], // Solo para APIs verdaderamente públicas
+```
+
+## Seguridad de subida de archivos
+
+### Validación
+
+```php
+public function rules(): array
+{
+    return [
+        'document' => [
+            'required',
+            'file',
+            'mimes:pdf,doc,docx,xls,xlsx', // Lista blanca de tipos MIME específicos
+            'max:10240', // 10 MB
+            'extensions:pdf,doc,docx,xls,xlsx', // Verificar que la extensión coincida con el MIME
+        ],
+        'avatar' => [
+            'nullable',
+            'image', // Garantiza que sea una imagen válida
+            'mimes:jpg,jpeg,png,webp',
+            'max:2048',
+            'dimensions:min_width=100,min_height=100,max_width=2000,max_height=2000',
+        ],
+    ];
+}
+```
+
+### Almacenamiento seguro
+
+```php
+// Almacena los archivos fuera del directorio público
+$path = $request->file('document')->store('documents', 'local');
+// Nunca uses el disco 'public' para documentos sensibles
+
+// Usa URLs firmadas para acceso temporal a archivos
+use Illuminate\Support\Facades\Storage;
+
+public function download(Request $request, string $path)
+{
+    // Generar URL firmada temporal (expira en 15 minutos)
+    $url = Storage::temporaryUrl($path, now()->addMinutes(15));
+
+    // Validar que el usuario tenga permiso
+    $this->authorize('download', $path);
+
+    return redirect($url);
+}
+
+// Configuración de almacenamiento en la nube con cifrado
+// config/filesystems.php
+'s3' => [
+    'driver' => 's3',
+    'key' => env('AWS_ACCESS_KEY_ID'),
+    'secret' => env('AWS_SECRET_ACCESS_KEY'),
+    'region' => env('AWS_DEFAULT_REGION'),
+    'bucket' => env('AWS_BUCKET'),
+    'url' => env('AWS_URL'),
+    'endpoint' => env('AWS_ENDPOINT'),
+    'use_path_style_endpoint' => env('AWS_USE_PATH_STYLE_ENDPOINT', false),
+    'throw' => false,
+    'server_side_encryption' => 'AES256', // Cifrado en reposo
+],
+```
+
+## Dependencias y secretos
+
+### Seguridad con Composer
+
+```bash
+# Audita siempre las dependencias en CI
+composer audit
+
+# Fija las versiones mayores en composer.json
+"laravel/framework": "^11.0",
+"spatie/laravel-permission": "^6.0"
+
+# Verifica paquetes abandonados
+composer why-not
+
+# Mantén el lock file en el control de versiones (fija versiones exactas)
+# Ejecuta `composer update` de forma deliberada, nunca en CI/CD
+```
+
+### Gestión de secretos
+
+```bash
+# Archivo .env (NUNCA subirlo al repositorio)
+# .gitignore incluye .env por defecto
+
+APP_KEY=base64:abc123...
+DB_PASSWORD=secure_password
+STRIPE_KEY=sk_live_...
+SANCTUM_TOKEN_PREFIX=myapp_
+
+# Para producción: usa un gestor de secretos
+# Despliega con: env $(aws secretsmanager get-secret-value --secret-id prod/db | jq ...) php artisan serve
+
+# Valida los secretos en el arranque (AppServiceProvider::boot)
+$secrets = ['services.stripe.key', 'services.stripe.webhook_secret'];
+foreach ($secrets as $key) {
+    if (empty(config($key))) {
+        Log::critical("Falta el secreto: {$key}");
+    }
+}
+```
+
+## Seguridad de colas
+
+```php
+// Definir un rate limiter con nombre (típicamente en AppServiceProvider::boot())
+RateLimiter::for('payments', fn () => Limit::perMinute(5));
+```
+
+```php
+// Cifrar datos sensibles del job implementando la interfaz
+final class ProcessPaymentJob implements ShouldQueue, ShouldBeEncrypted
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public function __construct(
+        private readonly string $paymentIntentId, // Los IDs públicos están bien
+        private readonly string $cardFingerprint, // Cifrado vía ShouldBeEncrypted
+    ) {}
+
+    public function handle(): void
+    {
+        // Procesar el pago
+    }
+
+    // Limitar reintentos y el retraso entre intentos
+    public function retryUntil(): Carbon
+    {
+        return now()->addMinutes(5);
+    }
+
+    // Limitar cuántos jobs de este tipo pueden ejecutarse
+    public function middleware(): array
+    {
+        return [
+            new RateLimited('payments'),
+        ];
+    }
+}
+```
+
+## Registro de eventos de seguridad
+
+```php
+// config/logging.php
+'channels' => [
+    'security' => [
+        'driver' => 'single',
+        'path' => storage_path('logs/security.log'),
+        'level' => 'warning',
+    ],
+],
+
+// Helper de log de auditoría
+final class SecurityLogger
+{
+    public static function log(string $event, array $context = []): void
+    {
+        Log::channel('security')->warning($event, array_merge([
+            'user_id' => Auth::id(),
+            'ip' => request()->ip(),
+            'user_agent' => request()->userAgent(),
+            'url' => request()->fullUrl(),
+            'timestamp' => now()->toIso8601String(),
+        ], $context));
+    }
+}
+
+// Uso
+SecurityLogger::log('failed_login_attempt', ['email' => $email]);
+SecurityLogger::log('password_change');
+SecurityLogger::log('role_change', ['target_user' => $targetId, 'new_role' => 'admin']);
+SecurityLogger::log('suspicious_activity', ['reason' => 'multiple_attempts_from_different_ips']);
+```
+
+## Lista de verificación rápida de seguridad
+
+| Verificación | Descripción |
+|-------|-------------|
+| `APP_DEBUG=false` | Nunca ejecutes con debug habilitado en producción |
+| `APP_KEY` definida | Ejecuta siempre `php artisan key:generate` |
+| HTTPS forzado | Fuerza HTTPS en producción vía middleware o proxy |
+| `$fillable` en lista blanca | Nunca uses `$guarded = []` |
+| CSRF activo | `@csrf` en todos los formularios que cambian estado |
+| Sanctum/Passport configurado | Autenticación de API con abilities/scopes de token |
+| Rate limiting aplicado | Limita la tasa en endpoints de API y de autenticación |
+| Validación de entrada | FormRequest con reglas específicas, nunca `$request->all()` |
+| Restricciones de subida de archivos | Valida tipos MIME, tamaño, dimensiones |
+| `composer audit` en CI | Verifica dependencias con vulnerabilidades conocidas |
+| `password_hash` / `password_verify` | Usa el hashing integrado de Laravel (bcrypt/Argon2) |
+| Regeneración de sesión al iniciar sesión | Llama a `$request->session()->regenerate()` |
+| Middleware de cabeceras de seguridad | CSP, X-Frame-Options, X-Content-Type-Options |
+| Eventos de seguridad registrados | Log de auditoría para fallos de auth, cambios de rol, actividad sospechosa |
+| `.env` no subido al repositorio | Verifica que `.gitignore` incluya `.env` |
+
+## Skills relacionadas
+
+- `patrones-laravel` — Arquitectura Laravel, routing, Eloquent y patrones de API
+- `patrones-backend` — Patrones generales de APIs backend y bases de datos