Security Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require adimeo-data-suite/security
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Adimeo\DataSuite\Security\SecurityServiceProvider" --tag="config"
   

2. First Use Case: Basic Authentication Middleware Register the middleware in app/Http/Kernel.php:

   protected $routeMiddleware = [
       'auth.security' => \Adimeo\DataSuite\Security\Middleware\Authenticate::class,
   ];
   

   Apply it to a route:

   Route::get('/secure', function () {
       return response()->json(['message' => 'Secure endpoint']);
   })->middleware('auth.security');
   

3. Configuration Check config/security.php for default settings (e.g., token expiration, encryption keys). Override as needed:

   'tokens' => [
       'expiration' => env('SECURITY_TOKEN_EXPIRATION', 60), // minutes
   ],
   

Implementation Patterns

Core Workflows

1. Token-Based Authentication Generate and validate tokens via the Security facade:

   use Adimeo\DataSuite\Security\Facades\Security;
   
   // Generate token
   $token = Security::generateToken(['user_id' => 1]);
   
   // Validate token
   $payload = Security::validateToken($token);
   

2. Role-Based Access Control (RBAC) Define roles in config/security.php:

   'roles' => [
       'admin' => ['create', 'read', 'update', 'delete'],
       'user' => ['read', 'update'],
   ],
   

   Apply role checks in middleware or controllers:

   if (!Security::hasPermission('update')) {
       abort(403);
   }
   

3. API Rate Limiting Use the built-in rate limiter:

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

Integration Tips

• Laravel Sanctum/Passport: Combine with existing auth systems by extending the Authenticate middleware.
• Custom Guards: Extend \Adimeo\DataSuite\Security\Guards\TokenGuard for non-standard token storage (e.g., Redis).
• Event Listeners: Listen for token.created or token.revoked events to log or notify users.

Gotchas and Tips

Pitfalls

1. Token Storage

   • By default, tokens are stored in the database (security_tokens table). For high-scale apps, consider Redis:

     'tokens' => [
         'driver' => 'redis',
     ],
     

   • Gotcha: Forgetting to run migrations (php artisan migrate) will break token validation.

2. CORS Issues

   • Ensure your CORS middleware allows the Authorization header if using API tokens:

     'headers' => ['Authorization', 'X-Requested-With', 'Content-Type'],
     

3. Token Expiration

   • Tokens expire by default after config('security.tokens.expiration') minutes. Set this to null for persistent tokens (not recommended for security).

Debugging

• Token Validation Failures: Check the security_tokens table for revoked/expired tokens. Use Tinker to debug:

  php artisan tinker
  >>> \Adimeo\DataSuite\Security\Facades\Security::validateToken($token);
  

• Permission Denied: Verify roles/permissions in config/security.php and clear cached config:

  php artisan config:clear
  

Extension Points

1. Custom Token Payloads Extend the TokenPayload class to add metadata:

   namespace App\Extensions;
   
   use Adimeo\DataSuite\Security\Contracts\TokenPayload as BasePayload;
   
   class CustomTokenPayload implements BasePayload {
       public function getPayload(): array {
           return [
               'user_id' => auth()->id(),
               'custom_field' => 'value',
           ];
       }
   }
   

   Bind it in AppServiceProvider:

   Security::extend('custom', function () {
       return new CustomTokenPayload();
   });
   

2. Token Revocation Manually revoke tokens via the facade:

   Security::revokeToken($token);
   

   Or trigger revocation on user logout:

   event(new \Adimeo\DataSuite\Security\Events\TokenRevoked($token));
   

3. Logging Enable token-related logging in config/security.php:

   'logging' => [
       'enabled' => true,
       'channel' => 'single',
   ],