Security Laravel Package

Getting Started

Minimal Steps

1. Installation Run the package installer:

   composer require moox/security
   php artisan mooxsecurity:install
   

   This handles migrations, config publishing, and service provider registration.

2. First Use Case Secure a route with basic authentication:

   use Moox\Security\Facades\Security;
   
   Route::get('/admin', function () {
       return 'Admin Dashboard';
   })->middleware(Security::class);
   

   Verify the config/security.php for available middleware options.

3. Where to Look First

   • Config File: config/security.php (published via vendor:publish).
   • Middleware: Check app/Http/Middleware/ for auto-generated middleware.
   • Migrations: Review database/migrations/ for security-related tables (e.g., users, roles, or permissions).

Implementation Patterns

Usage Patterns

1. Role-Based Access Control (RBAC) Define roles and assign permissions in migrations or seeders:

   use Moox\Security\Models\Role;
   
   Role::create(['name' => 'admin', 'permissions' => ['create_user', 'delete_user']]);
   

   Enforce in controllers:

   public function __construct() {
       $this->middleware('can:delete_user')->only(['destroy']);
   }
   

2. API Token Authentication Generate and validate tokens via facade:

   // Generate token for user
   $token = Security::generateToken(auth()->user());
   
   // Validate token in API
   $user = Security::validateToken($token);
   

3. Rate Limiting Apply rate limits to routes:

   Route::middleware(['throttle:60,1'])->group(function () {
       // Rate-limited endpoints
   });
   

Workflows

1. User Registration Flow

   • Use Security::register() to create users with hashed passwords.
   • Assign roles via Security::assignRole($user, 'admin').

2. Password Reset

   • Trigger resets with Security::sendPasswordResetLink($email).
   • Validate tokens in reset routes:

     $user = Security::validateResetToken($token);
     

3. Audit Logging Enable logging in config/security.php:

   'logging' => [
       'enabled' => true,
       'model' => \Moox\Security\Models\AuditLog::class,
   ],
   

   Log actions automatically:

   Security::log('user.created', ['user_id' => $user->id]);
   

Integration Tips

• Laravel Fortify/Passport: Combine with moox/security for hybrid auth:

  use Moox\Security\Facades\Security;
  use Laravel\Fortify\Fortify;
  
  Fortify::authenticate(function () {
      Security::checkPermission('edit_content');
  });
  

• SPA Integration: Use token-based auth for frontend:

  // Store token in localStorage after login
  localStorage.setItem('auth_token', response.token);
  
  // Attach to API requests
  axios.defaults.headers.common['Authorization'] = `Bearer ${localStorage.getItem('auth_token')}`;
  

Gotchas and Tips

Pitfalls

1. Middleware Caching Clear cached routes after adding new middleware:

   php artisan route:clear
   

   Or disable caching in config/security.php:

   'middleware' => [
       'cache' => false,
   ],
   

2. Permission Caching Avoid stale permission checks by clearing cache:

   php artisan cache:clear
   

   Or use Security::refreshPermissions() in critical paths.

3. Token Expiry Default token TTL is 1 hour. Customize in config:

   'tokens' => [
       'ttl' => 24 * 60, // 24 hours
   ],
   

Debugging

• Failed Auth Attempts: Check failed_jobs table for throttled requests.
• Permission Denied: Enable debug mode in config:

  'debug' => env('APP_DEBUG', false),
  

  Logs will show denied actions in storage/logs/laravel.log.

Config Quirks

1. Default Guard Override the default guard in config/auth.php:

   'defaults' => [
       'guard' => 'moox',
   ],
   

   Ensure moox guard is defined:

   'guards' => [
       'moox' => [
           'driver' => 'session',
           'provider' => 'users',
       ],
   ],
   

2. Custom Models Extend default models in config/security.php:

   'models' => [
       'user' => \App\Models\CustomUser::class,
       'role' => \App\Models\CustomRole::class,
   ],
   

   Run php artisan mooxsecurity:publish to update stubs.

Extension Points

1. Custom Policies Create policies in app/Policies/ and bind them:

   use Moox\Security\Facades\Security;
   
   Security::extendPolicy('post', \App\Policies\PostPolicy::class);
   

2. Event Listeners Listen for security events (e.g., user.logged_in):

   use Moox\Security\Events\UserLoggedIn;
   
   UserLoggedIn::listen(function ($event) {
       // Send welcome email
   });
   

3. API Resources Extend Moox\Security\Http\Resources\UserResource for custom fields:

   namespace App\Http\Resources;
   
   use Moox\Security\Http\Resources\UserResource as BaseUserResource;
   
   class UserResource extends BaseUserResource {
       public function toArray($request) {
           $array = parent::toArray($request);
           $array['custom_field'] = $this->custom_field;
           return $array;
       }
   }