whatbox / recaptcha-password-check

1.0.2 2026-09-06 22:38 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.8
• phpseclib/phpseclib: ^3.0

Requires (Dev)

• phpstan/phpstan: *
• phpunit/phpunit: *
• squizlabs/php_codesniffer: *

Suggests

• ext-scrypt: 20x faster cryptographic operations

Apache-2.0

Published on Packagist.org on 2026-09-06 23:01 UTC

README

PHP port of Google's Java API client for the reCAPTCHA Enterprise Password Check API.

A privacy-respecting solution to check username, password pairs against known breaches without leaking customer usernames or passwords to the breach database.

Similar to Have I Been Pwned, but a commercial API with fewer false positives by considering username and password together, instead of password alone.

Requirements

• PHP 8.1+
• ext-scrypt is optional, but recommended for performance

Installation

composer require whatbox/recaptcha-password-check

Usage

• Enable the "reCAPTCHA Enterprise API" in your Google Cloud project
• "Create credentials" > "API key"

<?php

use ReCaptcha\PasswordCheck\Client\ReCaptchaPasswordCheckClient;

$client = new ReCaptchaPasswordCheckClient($projectId, $apiKey);
$result = $client->checkPassword(
    $username,
    $password,

    // Optional: If you use reCAPTCHA bot protection, you can attach this password check to the
    // reCaptcha Token and feed Google additional data in exchange for more accurate bot scores
    // expectedAction: 'login',
    // eventOverrides: [
    //     'siteKey' => $siteKey,
    //     'token' => $recaptchaToken,
    // ]
);

if ($result->areCredentialsLeaked()) {
    // Prompt the user to reset their password.
}

Granular Usage

<?php

use ReCaptcha\PasswordCheck\Client\ReCaptchaPasswordCheckClient;
use ReCaptcha\PasswordCheck\PasswordCheckVerification;

$client = new ReCaptchaPasswordCheckClient($projectId, $apiKey);

// Hashing and crypto (CPU bound)
$verification = PasswordCheckVerification::create($usernameOrEmail, $password);

// Sending to Google (Network latency bound)
$result = $client->completeVerification($verification);

if ($result->areCredentialsLeaked()) {
    // Prompt the user to reset their password.
}

The $verification object holds the private key needed to decrypt Google's response, so it must be the same instance for both phases and must never be serialized to shared storage.

Running tests

composer test

Project structure

• src/Crypto – Elliptic-curve primitive, hash type enum, and supported curves.
• src/Utils – Username canonicalization, PHP Scrypt, and bit-prefix helpers.
• src/Client – High-level HTTP client for Google reCAPTCHA Password Check.
• tests/ – PHPUnit test suite mirroring the upstream reference coverage.

License

Apache 2.0 – consistent with the upstream Google reference implementations.