oldas/pwned-passwords

A library to query Troy Hunt's Pwned Passwords service to see whether or not a password has been included in a public breach.

Maintainers

Details

github.com/mzk/pwned-passwords

Source

Issues

Installs: 1

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 1

Forks: 0

Open Issues: 0

v1.0.1 2025-01-10 09:16 UTC

Requires

Requires (Dev)

MIT ceafe3a54e6702aa863b5ddd1d602d18cb8092ac

  • Olda Salek <mzk.woop@mozektevidi.net>

This package is auto-updated.

Last update: 2025-08-10 10:39:55 UTC

README

PwnedPasswords is a library that allows you to query Troy Hunt's Pwned Passwords API to determine if a password has been compromised in a public data breach.

Requirements

  • PHP >= 8.2

Installation

Install PwnedPasswords easily with Composer by running the following command in your project directory:

composer require oldas/pwned-passwords

Usage

First, include the Composer autoload.php to load the library:

require_once('vendor/autoload.php');

Then, use the core service class HaveIBeenPwnedService to interact with the Pwned Passwords API:

use Oldas\PwnedPasswords\HaveIBeenPwnedService;

// Create a service instance
$haveIBeenPwnedService = new HaveIBeenPwnedService();

$plainTextPassword = 'password'; // leaked password

// Check if the password has been compromised
$result = $haveIBeenPwnedService->isPwned($plainTextPassword); 
// Returns: true (if compromised), false (if safe), or null (in case of API timeout)

// Validate the password (throws exceptions for invalid input)
$haveIBeenPwnedService->validatePassword($plainTextPassword);  // Throws InvalidPasswordInputException, otherwise returns void

Methods Explained

isPwned(string $plainTextPassword): ?bool

This method checks whether the given password has been exposed in a public data breach by querying the Pwned Passwords API.

  • Returns:
    • true: The password was found in a breach.
    • false: The password was not found in a breach.
    • null: The API call timed out or failed.

validatePassword(string $plainTextPassword): void

This method ensures the password meets the library's input criteria. If the password is invalid, it throws an exception before performing any further operations.

  • Throws: InvalidPasswordInputException

Notes

  • The library uses the k-anonymity technique to query the API securely without revealing the full password to external services.
  • Ensure proper validation and exception handling in your implementation to cover cases such as API timeout or invalid input.

License

This project is released under the MIT License.

Resources