README

Password breach check for the Yii2 framework, backed by the Have I Been Pwned Pwned Passwords API.

Checks whether a password appears in known data breaches without ever sending the password (or its full hash) anywhere — only the first 5 characters of the SHA-1 hash are transmitted (k-anonymity model), and the match is performed locally.

Features

k-anonymity — only a 5-character hash prefix leaves your application
Yii component — configure once, inject anywhere (DI container friendly)
Shared HTTP client — reuses the GuzzleHttp\ClientInterface from your DI container when one is registered; falls back to a default Guzzle client otherwise
Response padding — optional Add-Padding mode so even the response size leaks nothing
Breach count — getHits() returns how many times the password was seen in breaches
Zero configuration — sensible defaults, override only what you need

Requirements

PHP >= 8.0
yiisoft/yii2 ~2.0
guzzlehttp/guzzle ^7.4

Installation

composer require tuzelko/yii2-pwned-passwords

Quick start

use tuzelko\yii\pwnedpasswords\PwnedPasswords;

$pwned = new PwnedPasswords();

$pwned->isPwned('password');  // true — seen in millions of breaches
$pwned->getHits('password');  // e.g. 9659365 — number of breach occurrences

Or register it as an application component:

// config/web.php
'components' => [
    'pwnedPasswords' => [
        'class'   => \tuzelko\yii\pwnedpasswords\PwnedPasswords::class,
        'padding' => true,
    ],
],

if (Yii::$app->pwnedPasswords->isPwned($form->password)) {
    $form->addError('password', 'This password has been found in a data breach.');
}

Usage in a validator

A typical place for a breach check is a password policy validator on a form:

use tuzelko\yii\pwnedpasswords\PwnedPasswords;
use yii\validators\Validator;

class PasswordBreachValidator extends Validator
{
    public function validateAttribute($model, $attribute): void
    {
        try {
            $pwned = Yii::$container->get(PwnedPasswords::class);
            if ($pwned->isPwned($model->$attribute)) {
                $this->addError($model, $attribute, 'This password has been found in a data breach. Please choose a different one.');
            }
        } catch (\Throwable) {
            // Decide your fail-open / fail-closed policy here
            $this->addError($model, $attribute, 'Unable to verify password against breach database. Please try again later.');
        }
    }
}

Configuration

Property	Type	Default	Description
`apiUrl`	`string`	`https://api.pwnedpasswords.com`	API base URL (override for a proxy or a self-hosted mirror)
`padding`	`bool`	`false`	Send `Add-Padding: true` so responses are padded with fake zero-hit entries and their size leaks nothing about the requested range
`requestOptions`	`array`	`[]`	Extra Guzzle request options merged into every API call (timeouts, proxy, headers, ...)

$pwned = new PwnedPasswords([
    'apiUrl'         => 'https://hibp-mirror.internal',
    'padding'        => true,
    'requestOptions' => ['timeout' => 5, 'connect_timeout' => 2],
]);

HTTP client resolution

On init() the component looks for a GuzzleHttp\ClientInterface definition in Yii::$container:

registered — your application's client is reused (with its base timeouts, middleware, etc.);
not registered — a plain GuzzleHttp\Client is created.

// config/main.php — share one configured client across the application
'container' => [
    'singletons' => [
        \GuzzleHttp\ClientInterface::class => static fn () => new \GuzzleHttp\Client([
            'timeout'         => 30,
            'connect_timeout' => 10,
        ]),
    ],
],

Error handling

Condition	Result
Empty password	`InvalidArgumentException`
Transport / HTTP error (4xx, 5xx, timeout)	`GuzzleHttp\Exception\GuzzleException`
Unexpected non-200 success status	`RuntimeException`

The component never fails silently — decide at the call site whether a check failure should block the user (fail-closed) or be ignored (fail-open).

How k-anonymity works

The password is hashed with SHA-1 locally.
Only the first 5 characters of the hash are sent: GET /range/5BAA6.
The API returns every known hash suffix in that range (~800–1000 entries) with breach counts.
The full hash is matched against the list locally.

The API operator never learns the password, its hash, or even whether a match occurred.

Running tests

make test

Tests run inside Docker (PHP 8.3) with no local setup required and no real HTTP calls (Guzzle mock handler).

License

MIT — see LICENSE.

tuzelko / yii2-pwned-passwords

Maintainers

Package info

Statistics

Security