refactor(auth): configure the breach lookup with one DSN

Replaces `_APP_PWNED_PASSWORDS_ADAPTER` and `_APP_PWNED_PASSWORDS_ENDPOINT`
with a single `_APP_PWNED_PASSWORDS_DSN`, following how storage, logging
and the database connections are configured. The scheme picks the
adapter and the rest carries whatever that adapter needs.

- `hibp://localhost` reads no details, like `local://localhost` does for
  storage.
- `appwrite://SECRET@HOST[:PORT][/PATH][?tls=true]` carries the host and
  the JWT secret the service shares, so the secret is no longer borrowed
  from `_APP_OPENSSL_KEY_V1`. The path defaults to `v1/detection`.
- `mock://localhost` is new. It reports a fixed list of passwords as
  breached without leaving the process, and is refused on a production
  server because it would report every real password as safe.

The test stack now uses the mock adapter, which lets the mock range route
in `app/controllers/mock.php` go away. E2E covers the policy, the adapter
unit tests cover each protocol.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matej BačoandClaude Opus 5 committed 2026-09-15 15:42:54 +02:00
1 parent 84f3c39d73
commit 21d36f8425
13 files changed
+169 -98

No files matched your search

+1 -2
View File
@@ -175,8 +175,7 @@ _APP_MIGRATIONS_FIREBASE_CLIENT_SECRET=
_APP_PROJECT_REGIONS=default
_APP_GEO_SECRET=your-secret-key
_APP_GEO_ENDPOINT=http://appwrite-geo/v1
_APP_PWNED_PASSWORDS_ADAPTER=hibp
_APP_PWNED_PASSWORDS_ENDPOINT=http://localhost/v1/mock/tests/general/pwned-passwords
_APP_PWNED_PASSWORDS_DSN=mock://localhost
_APP_VCS_GITHUB_APP_ID=
_APP_VCS_GITHUB_APP_NAME=
_APP_VCS_GITHUB_CLIENT_ID=
+3 -12
View File
@@ -485,19 +485,10 @@ return [
'filter' => 'token'
],
[
'name' => '_APP_PWNED_PASSWORDS_ADAPTER',
'description' => 'Service the password pwned project policy asks whether a password has been breached. `hibp` calls the Have I Been Pwned range API and only ever sends the first five characters of the password SHA-1 hash. `appwrite` calls an [Appwrite Pwned](https://github.com/appwrite-labs/pwned) service you run yourself, which caches answers and can front a detector of your choice, but receives the whole password inside a JWT signed with `_APP_OPENSSL_KEY_V1`, so only point it at a service on your own network.',
'name' => '_APP_PWNED_PASSWORDS_DSN',
'description' => "DSN of the service the password pwned project policy asks whether a password has been breached. The scheme picks the adapter.\n\nExamples:\n- Have I Been Pwned: `hibp://localhost` — the public range API, which only ever receives the first five characters of the password SHA-1 hash. No other detail is read from the DSN\n- [Appwrite Pwned](https://github.com/appwrite-labs/pwned): `appwrite://SECRET@appwrite-pwned/v1/detection` — a service you run yourself, which caches answers and can front a detector of your choice. It receives the whole password inside a JWT signed with `SECRET`, which must match the service's `APPWRITE_PWNED_JWT_SECRET`, so only point it at a service on your own network. The path defaults to `v1/detection` and the connection is plain HTTP unless you add `?tls=true`\n- Testing: `mock://localhost` — reports a fixed list of passwords as breached without leaving the process. Refused on a production server, since it would report every real password as safe",
'introduction' => 'TBD',
'default' => 'hibp',
'required' => false,
'question' => '',
'filter' => ''
],
[
'name' => '_APP_PWNED_PASSWORDS_ENDPOINT',
'description' => 'Address the adapter chosen in `_APP_PWNED_PASSWORDS_ADAPTER` calls. Leave empty to use that adapter\'s default, which is `https://api.pwnedpasswords.com/range` for `hibp` and `http://appwrite-pwned/v1/detection` for `appwrite`.',
'introduction' => 'TBD',
'default' => '',
'default' => 'hibp://localhost',
'required' => false,
'question' => '',
'filter' => ''
-32
View File
@@ -501,35 +501,3 @@ Http::shutdown()
$response->dynamic(new Document(['result' => \implode(',', $methods) . ':' . $route->getPath() . ':passed']), Response::MODEL_MOCK);
});
Http::get('/v1/mock/tests/general/pwned-passwords/:prefix')
->desc('Pwned Passwords range')
->groups(['mock'])
->label('scope', 'public')
->label('docs', false)
->label('mock', true)
->param('prefix', '', new Text(5, 5), 'First five characters of the SHA-1 password hash.')
->inject('response')
->action(function (string $prefix, Response $response) {
// Mirrors the Have I Been Pwned range API: every leaked hash sharing the
// requested prefix comes back as `SUFFIX:COUNT`, one per line.
$leaked = [
'pwned-fixture-common' => 12345,
'pwned-fixture-uncommon' => 678,
'pwned-fixture-rare' => 9,
];
$prefix = \strtoupper($prefix);
$lines = [];
foreach ($leaked as $password => $count) {
$hash = \strtoupper(\sha1($password));
if (\str_starts_with($hash, $prefix)) {
$lines[] = \substr($hash, 5) . ':' . $count;
}
}
// Padded entries carry a count of 0 and must never be treated as a breach
$lines[] = \str_repeat('0', 35) . ':0';
$response->text(\implode("\r\n", $lines));
});
+11 -6
View File
@@ -5,6 +5,7 @@ use Ahc\Jwt\JWTException;
use Appwrite\Auth\Key;
use Appwrite\Auth\Pwned\Appwrite as PwnedAppwrite;
use Appwrite\Auth\Pwned\HIBP as PwnedHIBP;
use Appwrite\Auth\Pwned\Mock as PwnedMock;
use Appwrite\Auth\Validator\PasswordPwned;
use Appwrite\Database\Factory as DatabaseFactory;
use Appwrite\Databases\TransactionState;
@@ -52,6 +53,7 @@ use Utopia\Database\Query;
use Utopia\Database\Validator\Authorization;
use Utopia\DI\Container;
use Utopia\Domains\Domain;
use Utopia\DSN\DSN;
use Utopia\Http\Http;
use Utopia\Locale\Locale;
use Utopia\Lock\Distributed as DistributedLock;
@@ -677,13 +679,16 @@ return function (Container $context): void {
}, ['user', 'store', 'proofForToken']);
$context->set('pwnedPasswords', function (Document $project, Cache $cache) {
$endpoint = System::getEnv('_APP_PWNED_PASSWORDS_ENDPOINT', '');
$name = \strtolower(System::getEnv('_APP_PWNED_PASSWORDS_ADAPTER', 'hibp'));
$dsn = new DSN(System::getEnv('_APP_PWNED_PASSWORDS_DSN', 'hibp://localhost'));
$adapter = match ($name) {
'hibp' => new PwnedHIBP($endpoint, $cache),
'appwrite' => new PwnedAppwrite($endpoint, System::getEnv('_APP_OPENSSL_KEY_V1', '')),
default => throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Unknown _APP_PWNED_PASSWORDS_ADAPTER: ' . $name),
$adapter = match ($dsn->getScheme()) {
'hibp' => new PwnedHIBP($cache),
'appwrite' => new PwnedAppwrite($dsn),
// Reports almost every password as safe, so it must never be reachable on a real server
'mock' => Http::isProduction()
? throw new Exception(Exception::GENERAL_SERVER_ERROR, 'The mock breach adapter cannot be used in production.')
: new PwnedMock(),
default => throw new Exception(Exception::GENERAL_SERVER_ERROR, 'Unknown _APP_PWNED_PASSWORDS_DSN scheme: ' . $dsn->getScheme()),
};
return new PasswordPwned($adapter, $project->getAttribute('auths', [])['passwordPwned'] ?? []);
+1 -2
View File
@@ -254,8 +254,7 @@ services:
- _APP_MIGRATION_HOST
- _APP_GEO_SECRET
- _APP_GEO_ENDPOINT
- _APP_PWNED_PASSWORDS_ADAPTER
- _APP_PWNED_PASSWORDS_ENDPOINT
- _APP_PWNED_PASSWORDS_DSN
- _APP_LIMIT_DATABASE_BATCH
- _APP_DOCUMENTSDB
- _APP_VECTORSDB
+18 -20
View File
@@ -8,31 +8,17 @@ use Utopia\Fetch\Client;
/**
* Looks a password up in a database of known data breaches.
*
* Adapters differ in what leaves the server and where it goes, so read the
* concrete class before choosing one. Pick the adapter with
* `_APP_PWNED_PASSWORDS_ADAPTER` and the address with
* `_APP_PWNED_PASSWORDS_ENDPOINT`.
* The adapter and its details both come from `_APP_PWNED_PASSWORDS_DSN`, whose
* scheme picks the adapter. Adapters differ in what leaves the server and where
* it goes, so read the concrete class before choosing one.
*/
abstract class Pwned
{
protected const CONNECT_TIMEOUT = 3 * 1000; // milliseconds
protected const REQUEST_TIMEOUT = 5 * 1000; // milliseconds
protected string $endpoint;
protected Client $client;
public function __construct(string $endpoint, ?Client $client = null)
{
$this->endpoint = \rtrim($endpoint, '/');
$this->client = $client ?? (new Client())
->setConnectTimeout(self::CONNECT_TIMEOUT)
->setTimeout(self::REQUEST_TIMEOUT)
->setAllowRedirects(false)
->setUserAgent('Appwrite');
}
private const CONNECT_TIMEOUT = 3 * 1000; // milliseconds
private const REQUEST_TIMEOUT = 5 * 1000; // milliseconds
/**
* Adapter name, as accepted by `_APP_PWNED_PASSWORDS_ADAPTER`.
* Adapter name, matching the DSN scheme that selects it.
*/
abstract public function getName(): string;
@@ -43,6 +29,18 @@ abstract class Pwned
*/
abstract public function isPwned(string $password): bool;
/**
* A client with the timeouts a password check can afford to wait.
*/
protected function client(?Client $client = null): Client
{
return $client ?? (new Client())
->setConnectTimeout(self::CONNECT_TIMEOUT)
->setTimeout(self::REQUEST_TIMEOUT)
->setAllowRedirects(false)
->setUserAgent('Appwrite');
}
/**
* A password is never silently accepted when the lookup did not happen.
*
+18 -7
View File
@@ -4,6 +4,7 @@ namespace Appwrite\Auth\Pwned;
use Ahc\Jwt\JWT;
use Appwrite\Auth\Pwned;
use Utopia\DSN\DSN;
use Utopia\Fetch\Client;
/**
@@ -11,25 +12,35 @@ use Utopia\Fetch\Client;
*
* The service answers for a whole password rather than a hash prefix, so unlike
* `HIBP` this sends the password itself. It travels inside a short-lived JWT
* signed with a secret shared with the service, which is only safe on a network
* you control. In exchange the service caches answers and can front Have I Been
* Pwned or another detector without the server knowing which.
* signed with a secret the service shares, which is only safe on a network you
* control. In exchange the service caches answers and can front Have I Been
* Pwned or another detector without this server knowing which.
*
* DSN: `appwrite://SECRET@HOST[:PORT][/PATH][?tls=true]`. The secret must match
* the service's `APPWRITE_PWNED_JWT_SECRET`, the path defaults to
* `v1/detection`, and the connection is plain HTTP unless `tls=true`.
*/
class Appwrite extends Pwned
{
public const ENDPOINT = 'http://appwrite-pwned/v1/detection';
private const PATH = 'v1/detection';
// The service decodes with the same window
private const TOKEN_EXPIRY = 900; // seconds
private const TOKEN_LEEWAY = 10; // seconds
protected string $endpoint;
protected string $secret;
protected Client $client;
public function __construct(string $endpoint = '', string $secret = '', ?Client $client = null)
public function __construct(DSN $dsn, ?Client $client = null)
{
parent::__construct($endpoint ?: self::ENDPOINT, $client);
$scheme = $dsn->getParam('tls') === 'true' ? 'https' : 'http';
$port = $dsn->getPort() !== null ? ':' . $dsn->getPort() : '';
$path = $dsn->getPath();
$this->secret = $secret;
$this->endpoint = $scheme . '://' . $dsn->getHost() . $port . '/' . ($path === '' || $path === null ? self::PATH : $path);
$this->secret = $dsn->getUser() ?? '';
$this->client = $this->client($client);
}
public function getName(): string
+7 -3
View File
@@ -13,6 +13,8 @@ use Utopia\Fetch\Client;
* leave the server, and the candidate suffixes that come back are compared
* locally. Range responses are cached per prefix, so a busy project does not
* ask the service the same question twice.
*
* DSN: `hibp://localhost`, no details are read.
*/
class HIBP extends Pwned
{
@@ -22,12 +24,14 @@ class HIBP extends Pwned
private const PREFIX_LENGTH = 5;
protected ?Cache $cache;
protected Client $client;
protected string $endpoint;
public function __construct(string $endpoint = '', ?Cache $cache = null, ?Client $client = null)
public function __construct(?Cache $cache = null, ?Client $client = null, string $endpoint = self::ENDPOINT)
{
parent::__construct($endpoint ?: self::ENDPOINT, $client);
$this->cache = $cache;
$this->client = $this->client($client);
$this->endpoint = \rtrim($endpoint, '/');
}
public function getName(): string
+36
View File
@@ -0,0 +1,36 @@
<?php
namespace Appwrite\Auth\Pwned;
use Appwrite\Auth\Pwned;
/**
* Reports a fixed set of passwords as breached, without leaving the process.
*
* Lets the test suite exercise the policy without depending on a breach
* service. Selecting it on a production server is refused, because it would
* quietly report every real password as safe.
*
* DSN: `mock://localhost`, no details are read.
*/
class Mock extends Pwned
{
/**
* The passwords this adapter reports as breached.
*/
public const BREACHED = [
'pwned-fixture-common',
'pwned-fixture-uncommon',
'pwned-fixture-rare',
];
public function getName(): string
{
return 'mock';
}
public function isPwned(string $password): bool
{
return \in_array($password, self::BREACHED, true);
}
}
@@ -12,15 +12,15 @@ use Utopia\Database\Helpers\ID;
use Utopia\Database\Query;
/**
* The stack points `_APP_PWNED_PASSWORDS_ENDPOINT` at the mock range endpoint in
* `app/controllers/mock.php`, so no request ever reaches the real Have I Been Pwned service.
* The stack sets `_APP_PWNED_PASSWORDS_DSN` to `mock://localhost`, so the breach
* lookup answers from a fixed list in process and never reaches a real service.
*/
final class PoliciesPasswordPwnedIntegrationTest extends Scope
{
use ProjectCustom;
use SideServer;
// Reported as breached by the mock range endpoint
// Reported as breached by the mock adapter, see Appwrite\Auth\Pwned\Mock
private const PWNED_PASSWORD = 'pwned-fixture-common';
public function testDefaultsOnNewProject(): void
+24 -3
View File
@@ -8,6 +8,7 @@ use Ahc\Jwt\JWT;
use Appwrite\Auth\Pwned\Appwrite;
use Appwrite\Extend\Exception;
use PHPUnit\Framework\TestCase;
use Utopia\DSN\DSN;
use Utopia\Fetch\Adapter;
use Utopia\Fetch\Client;
use Utopia\Fetch\Options\Request as RequestOptions;
@@ -16,8 +17,8 @@ use Utopia\Fetch\Response;
final class AppwriteTest extends TestCase
{
private const PASSWORD = 'Password123!';
private const ENDPOINT = 'https://pwned.test/v1/detection';
private const SECRET = 'shared-with-the-service';
private const DSN = 'appwrite://' . self::SECRET . '@pwned.test/v1/detection';
public function testLeakedPasswordIsReported(): void
{
@@ -41,7 +42,7 @@ final class AppwriteTest extends TestCase
$this->assertCount(1, $fetch->requests);
$this->assertSame('POST', $fetch->requests[0]['method']);
$this->assertSame(self::ENDPOINT, $fetch->requests[0]['url']);
$this->assertSame('http://pwned.test/v1/detection', $fetch->requests[0]['url']);
$sent = \json_decode($fetch->requests[0]['body'], true);
$this->assertIsArray($sent);
@@ -113,9 +114,29 @@ final class AppwriteTest extends TestCase
}
}
public function testTheDsnDescribesWhereAndHowToConnect(): void
{
$cases = [
'appwrite://secret@pwned.test/v1/detection' => 'http://pwned.test/v1/detection',
// The path the service exposes is assumed when the DSN leaves it out
'appwrite://secret@pwned.test' => 'http://pwned.test/v1/detection',
'appwrite://secret@pwned.test:8088' => 'http://pwned.test:8088/v1/detection',
'appwrite://secret@pwned.test/custom/path' => 'http://pwned.test/custom/path',
'appwrite://secret@pwned.test?tls=true' => 'https://pwned.test/v1/detection',
];
foreach ($cases as $dsn => $expected) {
$fetch = new DetectionFetch(body: '{"leaked":false}');
(new Appwrite(new DSN($dsn), new Client($fetch)))->isPwned(self::PASSWORD);
$this->assertSame($expected, $fetch->requests[0]['url'], $dsn);
}
}
private function adapter(DetectionFetch $fetch): Appwrite
{
return new Appwrite(self::ENDPOINT, self::SECRET, new Client($fetch));
return new Appwrite(new DSN(self::DSN), new Client($fetch));
}
}
+8 -8
View File
@@ -79,8 +79,8 @@ final class HIBPTest extends TestCase
$fetch = new RangeFetch(body: $this->range([self::LEAKED => 42]));
$cache = new Cache(new Memory());
$this->assertTrue((new HIBP(self::ENDPOINT, $cache, new Client($fetch)))->isPwned(self::LEAKED));
$this->assertTrue((new HIBP(self::ENDPOINT, $cache, new Client($fetch)))->isPwned(self::LEAKED));
$this->assertTrue((new HIBP($cache, new Client($fetch), self::ENDPOINT))->isPwned(self::LEAKED));
$this->assertTrue((new HIBP($cache, new Client($fetch), self::ENDPOINT))->isPwned(self::LEAKED));
$this->assertCount(1, $fetch->urls);
}
@@ -90,8 +90,8 @@ final class HIBPTest extends TestCase
$fetch = new RangeFetch(body: $this->range([self::LEAKED => 42]));
$cache = new Cache(new Memory());
(new HIBP('https://one.test/range', $cache, new Client($fetch)))->isPwned(self::LEAKED);
(new HIBP('https://two.test/range', $cache, new Client($fetch)))->isPwned(self::LEAKED);
(new HIBP($cache, new Client($fetch), 'https://one.test/range'))->isPwned(self::LEAKED);
(new HIBP($cache, new Client($fetch), 'https://two.test/range'))->isPwned(self::LEAKED);
$this->assertCount(2, $fetch->urls);
}
@@ -100,8 +100,8 @@ final class HIBPTest extends TestCase
{
$fetch = new RangeFetch(body: '');
(new HIBP('https://server.test/range', null, new Client($fetch)))->isPwned(self::LEAKED);
(new HIBP('https://other.test/range/', null, new Client($fetch)))->isPwned(self::LEAKED);
(new HIBP(null, new Client($fetch), 'https://server.test/range'))->isPwned(self::LEAKED);
(new HIBP(null, new Client($fetch), 'https://other.test/range/'))->isPwned(self::LEAKED);
$this->assertStringStartsWith('https://server.test/range/', $fetch->urls[0]);
$this->assertStringStartsWith('https://other.test/range/', $fetch->urls[1]);
@@ -131,7 +131,7 @@ final class HIBPTest extends TestCase
public function testFailedLookupIsNotCached(): void
{
$fetch = new RangeFetch(failure: new \RuntimeException('connection refused'));
$adapter = new HIBP(self::ENDPOINT, new Cache(new Memory()), new Client($fetch));
$adapter = new HIBP(new Cache(new Memory()), new Client($fetch), self::ENDPOINT);
foreach ([1, 2] as $attempt) {
try {
@@ -146,7 +146,7 @@ final class HIBPTest extends TestCase
private function adapter(RangeFetch $fetch): HIBP
{
return new HIBP(self::ENDPOINT, null, new Client($fetch));
return new HIBP(null, new Client($fetch), self::ENDPOINT);
}
/**
+39
View File
@@ -0,0 +1,39 @@
<?php
declare(strict_types=1);
namespace Tests\Unit\Auth\Pwned;
use Appwrite\Auth\Pwned\Mock;
use PHPUnit\Framework\TestCase;
final class MockTest extends TestCase
{
public function testFixturesAreReportedAsBreached(): void
{
$adapter = new Mock();
foreach (Mock::BREACHED as $password) {
$this->assertTrue($adapter->isPwned($password), $password);
}
}
public function testAnythingElseIsReportedAsSafe(): void
{
$adapter = new Mock();
$this->assertFalse($adapter->isPwned('some-other-password'));
$this->assertFalse($adapter->isPwned(''));
}
public function testMatchingIsExact(): void
{
$adapter = new Mock();
$fixture = Mock::BREACHED[0];
// A fixture that merely contains or resembles a breached one is not breached
$this->assertFalse($adapter->isPwned(\strtoupper($fixture)));
$this->assertFalse($adapter->isPwned($fixture . '!'));
$this->assertFalse($adapter->isPwned(\substr($fixture, 1)));
}
}