Password Exposed Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require jord-jd/password_exposed
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       JordJd\PasswordExposed\PasswordExposedServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="JordJd\PasswordExposed\PasswordExposedServiceProvider"
   

   Update config/password_exposed.php with your Have I Been Pwned (HIBP) API key (free tier available).

3. First Use Case Check if a password is exposed in a registration or login flow:

   use JordJd\PasswordExposed\Facades\PasswordExposed;
   
   $isExposed = PasswordExposed::check('password123');
   if ($isExposed) {
       return back()->withErrors(['password' => 'This password has been exposed in a data breach.']);
   }
   

Implementation Patterns

Common Workflows

1. Registration Validation Integrate with Laravel’s validation pipeline:

   use Illuminate\Support\Facades\Validator;
   
   $validator = Validator::make($request->all(), [
       'password' => [
           'required',
           'string',
           'min:8',
           'confirmed',
           'password_exposed', // Custom rule
       ],
   ]);
   

   Register the rule in AppServiceProvider@boot():

   Validator::extend('password_exposed', function ($attribute, $value, $parameters) {
       return !PasswordExposed::check($value);
   });
   

2. Password Reset Flow Check exposed passwords before resetting:

   public function update(Request $request) {
       $request->validate([
           'password' => ['required', 'password_exposed'],
       ]);
   
       // Reset logic...
   }
   

3. Bulk Checks (Admin Panel) Use the checkMultiple() method for batch validation (e.g., user imports):

   $exposedPasswords = PasswordExposed::checkMultiple([
       'password1', 'password2', 'password3'
   ]);
   // Returns associative array: ['password1' => true/false, ...]
   

4. Rate Limiting Cache results to avoid API abuse (e.g., 5-minute cache):

   $isExposed = Cache::remember("password_exposed_{$password}", now()->addMinutes(5), function() use ($password) {
       return PasswordExposed::check($password);
   });
   

Integration Tips

• Localization: Customize error messages in resources/lang/en/validation.php:

  'password_exposed' => 'The :attribute has been exposed in a data breach.',
  

• Logging: Log exposed passwords (anonymized) for analytics:

  if ($isExposed) {
      \Log::warning("Exposed password detected: {$request->password}");
  }
  

• Fallback: Use a local fallback list if the API fails:

  PasswordExposed::setFallbackList(['password', '123456']);
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • HIBP’s free tier has strict limits (~1,000 checks/day). Exceeding this may temporarily block your IP.
   • Fix: Implement caching aggressively or upgrade to a paid plan.

2. False Positives

   • Common passwords (e.g., qwerty) may trigger unnecessarily.
   • Fix: Whitelist known-safe passwords in config:

     'whitelist' => ['correcthorsebatterystaple'],
     

3. Performance

   • Each API call adds latency (~100–300ms). Avoid checking passwords in loops.
   • Fix: Pre-check passwords during registration/login, not during every request.

4. Privacy Compliance

   • Storing exposed password flags may violate GDPR/CCPA.
   • Fix: Store only hashed flags or use ephemeral checks.

Debugging

• Enable Debug Mode:

  PasswordExposed::setDebug(true); // Logs API responses to storage/logs/password_exposed.log
  

• Mock API Responses (for testing):

  PasswordExposed::setMockResponse(true); // Returns hardcoded results
  

Extension Points

1. Custom Data Sources Extend the JordJd\PasswordExposed\Contracts\PasswordExposedContract to integrate with other breach databases (e.g., DeHashed):

   class CustomPasswordExposed implements PasswordExposedContract {
       public function check(string $password): bool {
           // Custom logic...
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(PasswordExposedContract::class, CustomPasswordExposed::class);
   

2. Event Listeners Trigger actions when exposed passwords are detected:

   PasswordExposed::addListener(function ($password, $isExposed) {
       if ($isExposed) {
           event(new ExposedPasswordDetected($password));
       }
   });
   

3. Configuration Overrides Dynamically adjust sensitivity (e.g., disable checks for admins):

   if (auth()->user()->isAdmin()) {
       PasswordExposed::setEnabled(false);
   }