Laravel Paseto Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require mydaniel/laravel-paseto
   

2. Publish the config:

   php artisan vendor:publish --provider="MyDaniel\Paseto\PasetoServiceProvider" --tag="config"
   

3. Generate a secret key (critical for security):

   php artisan paseto:generate-key
   

   Store the output securely (e.g., in .env as PASETO_SECRET_KEY).

4. Configure config/auth.php: Add the Paseto guard to your guards array:

   'guards' => [
       'web' => ['driver' => 'session'],
       'api' => ['driver' => 'paseto', 'provider' => 'users'],
   ],
   

First Use Case: Token Generation

Generate a token for a user (e.g., in a controller or service):

use MyDaniel\Paseto\Facades\Paseto;

$token = Paseto::generate([
    'user_id' => auth()->id(),
    'exp' => now()->addHours(24),
]);

Use the token in API requests (e.g., Authorization: Bearer <token>).

Implementation Patterns

Workflows

1. Authentication Flow:

   • Replace JWT-based auth with Paseto by extending Laravel’s AuthenticatesUsers trait.
   • Use Paseto::attempt() for manual validation:

     if (Paseto::attempt($token, ['user_id'])) {
         $user = User::find(Paseto::get('user_id'));
         auth()->login($user);
     }
     

2. Token Blacklisting:

   • Invalidate tokens on logout via the PasetoBlacklist model:

     Paseto::blacklist($token); // Manually blacklist
     

   • Automate with an event listener for Illuminate\Auth\Events\Logout.

3. Custom Claims:

   • Extend token payloads dynamically:

     $token = Paseto::generate([
         'user_id' => 1,
         'role' => 'admin',
         'exp' => now()->addMinutes(30),
     ]);
     

Integration Tips

• API Middleware: Use auth:api middleware for Paseto-protected routes.
• Sanctum/Passport: Combine with Sanctum for session-based auth or Passport for OAuth2.
• Testing: Mock Paseto facade in tests:

  Paseto::shouldReceive('attempt')->andReturn(true);
  

Gotchas and Tips

Pitfalls

1. Secret Key Management:

   • Never commit the key to version control. Use .env or a secrets manager.
   • Rotate keys periodically (e.g., via paseto:rotate-key if added in future updates).

2. Token Storage:

   • Paseto tokens are not signed-only (unlike JWT). Avoid storing them in URLs or logs.
   • Use HttpOnly cookies for web apps to prevent XSS theft.

3. Blacklist Performance:

   • Blacklisting tokens adds a database query. Cache frequently invalidated tokens (e.g., after logout).

4. Clock Skew:

   • Ensure server time is synchronized (Paseto uses exp claims). Use PASETO_LEEWAY in config for minor time drift.

Debugging

• Invalid Tokens: Check config/paseto.php for strict mode (enforces exp/nbf).
• Decryption Errors: Verify the PASETO_SECRET_KEY matches the key used to generate the token.
• Logs: Enable debug mode in config to log token generation/validation:

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

Extension Points

1. Custom Encryption:
   • Override MyDaniel\Paseto\Contracts\Paseto to implement asymmetric Paseto (v3) if needed.
2. Token Storage:
   • Extend PasetoBlacklist to support Redis for scalability.
3. Claims Validation:
   • Add custom validation logic via Paseto::validate() hooks:

     Paseto::extend(function ($token) {
         return $token->get('role') === 'admin';
     });