Auth Primitives Laravel Package

Getting Started

First Steps

1. Installation

   composer require nawasara/auth-primitives
   

   Publish the package's configuration (if available) and migrations:

   php artisan vendor:publish --provider="Nawasara\AuthPrimitives\AuthPrimitivesServiceProvider"
   php artisan migrate
   

2. Key Concepts

   • Focus on auth primitives: sessions, tokens, cookies, and CSRF protection.
   • Core classes: AuthPrimitiveManager, SessionHandler, TokenGenerator, CsrfGuard.
   • Check config/auth-primitives.php for default settings (e.g., token expiration, session drivers).

3. First Use Case: Secure Session Handling

   use Nawasara\AuthPrimitives\Facades\AuthPrimitive;
   
   // Start a session
   AuthPrimitive::session()->start();
   
   // Store user data
   AuthPrimitive::session()->put('user_id', 123);
   
   // Retrieve later
   $userId = AuthPrimitive::session()->get('user_id');
   

Implementation Patterns

Common Workflows

1. Token-Based Authentication

   // Generate a token (e.g., for API)
   $token = AuthPrimitive::token()->generate();
   
   // Validate a token
   if (AuthPrimitive::token()->validate($token)) {
       $user = AuthPrimitive::token()->getUser($token);
   }
   

2. CSRF Protection in Controllers

   use Nawasara\AuthPrimitives\Http\Middleware\VerifyCsrfToken;
   
   // Add middleware to routes/forms
   Route::post('/submit', [Controller::class, 'store'])
       ->middleware(VerifyCsrfToken::class);
   
   // Generate CSRF token in Blade
   <input type="hidden" name="_csrf" value="{{ AuthPrimitive::csrf()->token() }}">
   

3. Custom Session Drivers Extend Nawasara\AuthPrimitives\Contracts\SessionHandler:

   class RedisSessionHandler implements SessionHandler {
       public function get($key) { ... }
       public function set($key, $value) { ... }
       // ...
   }
   

   Bind it in AuthServiceProvider:

   AuthPrimitive::extend('redis', function () {
       return new RedisSessionHandler();
   });
   

4. Cookie Management

   // Set a secure cookie
   AuthPrimitive::cookie()->queue('pref_language', 'en', 60 * 24);
   
   // Retrieve in middleware
   $language = AuthPrimitive::cookie()->get('pref_language');
   

Integration Tips

• Laravel Ecosystem: Works seamlessly with Laravel’s built-in auth (e.g., Auth::user() can populate session data).
• APIs: Use AuthPrimitive::token() for stateless auth; pair with Laravel Sanctum/Passport for additional features.
• Testing: Mock AuthPrimitive in tests:

  $this->partialMock(AuthPrimitive::class, function ($mock) {
      $mock->shouldReceive('session')->andReturnSelf();
      $mock->shouldReceive('get')->with('user_id')->andReturn(1);
  });
  

Gotchas and Tips

Pitfalls

1. Session Hijacking

   • Always use same-site and secure cookie flags in production:

     AuthPrimitive::cookie()->setSecure(true);
     AuthPrimitive::cookie()->setSameSite('strict');
     

   • Avoid storing sensitive data in sessions (use encrypted payloads if needed).

2. Token Expiration

   • Default token TTL is 1 hour. Override in config:

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

   • Regenerate tokens after sensitive actions (e.g., password changes).

3. CSRF Double-Submit Cookie

   • If using SameSite=Lax cookies, ensure your frontend sends the CSRF token on every request (e.g., via fetch headers or meta tags).

4. Race Conditions

   • Session/token validation is not atomic. Use transactions for critical operations:

     DB::transaction(function () {
         if (AuthPrimitive::token()->validate($token)) {
             // Critical update
         }
     });
     

Debugging

• Log Session Data:

  \Log::debug('Session contents:', AuthPrimitive::session()->all());
  

• Token Validation Issues: Check if the token was generated with the same secret_key (configured in auth-primitives.php).
• Cookie Not Setting: Verify domain and path in config match your app’s URL.

Extension Points

1. Custom Token Payloads Extend Nawasara\AuthPrimitives\Token:

   class CustomToken extends Token {
       public function getCustomData() {
           return $this->payload['custom_data'] ?? null;
       }
   }
   

   Bind it in the service provider.

2. Event Listeners Listen for auth events (e.g., TokenGenerated):

   AuthPrimitive::token()->on('generated', function ($token) {
       \Log::info("New token created: {$token->id}");
   });
   

3. Fallback Drivers Configure fallback session drivers in config/auth-primitives.php:

   'sessions' => [
       'driver' => 'redis',
       'fallback' => 'file',
   ],
   

4. Rate Limiting Tokens Combine with Laravel’s throttle middleware:

   Route::middleware(['throttle:60,1', 'auth:token'])->post('/api/data');