From c9fb92dcb1a385070b44e0437445a524abab1e0e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 5 Oct 2026 20:24:43 +0000
Subject: [PATCH 01/10] Fix two high-severity block/IP-detection bypasses

1. Unblock token bypass: a blocked IP was let through on any request with
   view=tokenunblock and an existing token. The token was neither consumed
   by such a request (e.g. option=com_users&task=user.login) nor checked for
   expiry or for belonging to the requester's block, so anyone able to get
   one token emailed (by getting their own account blocked) could keep
   guessing passwords from a blocked IP. The pass now only applies to
   com_bfstop's unblock view without a task, to an unexpired token issued
   for one of the requesting IP's own blocks. The token is no longer logged.

2. Forged client IP behind a proxy: the first public entry of the forwarding
   header was used, but proxies append to a client-supplied header, so the
   leftmost entry is attacker-controlled (block evasion, framing other
   addresses, impersonating allowlisted ones). The address is now taken from
   the right, skipping trusted proxies; several trusted proxies and CIDR
   subnets can be configured. The Forwarded header and ports are parsed, and
   an unparseable last hop falls back to REMOTE_ADDR.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 CHANGELOG                                     |  17 +++
 .../en-GB/en-GB.plg_system_bfstop.sys.ini     |   4 +-
 src/Extension/Bfstop.php                      |  31 ++--
 src/Helper/DatabaseHelper.php                 |  37 +++++
 src/Helper/IpHelper.php                       | 133 ++++++++++++++++--
 tests/Integration/BlockedRequestTest.php      |  31 ++++
 tests/Integration/IpHelperAddressTest.php     |  30 +++-
 tests/Unit/IpHelperTest.php                   |  61 ++++++++
 8 files changed, 316 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index af9b78d..e875a1d 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -40,6 +40,23 @@
     then silently never blocked anything. IP subnet matching for block and
     allow list entries is now done in PHP instead of with MySQL-only SQL
     functions, and fixed-length time windows are computed in PHP
+  - Security: an emailed unblock token no longer lets a blocked IP address
+    bypass the block. It was accepted on any request with
+    view=tokenunblock (e.g. a login), was never used up by such a request
+    and was not checked for expiry, so anyone who got a token (e.g. by
+    getting their own account blocked) could keep guessing passwords from
+    a blocked IP. Now it only passes the unblock page of com_bfstop itself,
+    only while unexpired, and only if issued for a block of the requesting
+    IP address; the token is no longer written to the log either
+  - Security: behind a proxy/load balancer, the client IP is now taken from
+    the end of the forwarding header (the entry added by the trusted proxy)
+    instead of its first public entry, which a visitor could forge to evade
+    blocking, get other addresses blocked or impersonate an allowlisted one.
+    Several trusted proxies (and CIDR subnets) can be configured, the
+    "Forwarded" header (RFC 7239) and addresses with ports are understood,
+    and private client addresses reported by the proxy are accepted. Not
+    all proxies append to an incoming header: pick a header yours sets or
+    appends to
 
 1.5.2 (2024-02-18)
   - Note: Only component changes, no plugin changes
diff --git a/language/en-GB/en-GB.plg_system_bfstop.sys.ini b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
index 1bfce70..b769b4f 100644
--- a/language/en-GB/en-GB.plg_system_bfstop.sys.ini
+++ b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
@@ -76,9 +76,9 @@ PLG_SYSTEM_BFSTOP_PROXY_FIELDSET_LABEL="Proxy / Load Balancer"
 PLG_SYSTEM_BFSTOP_USE_PROXY_LABEL="Behind a proxy / load balancer"
 PLG_SYSTEM_BFSTOP_USE_PROXY_DESC="Enable this only if your site sits behind a reverse proxy or load balancer, so that the visitor's browser never connects to Joomla! directly. When enabled, bfstop reads the visitor's IP address from the header selected below instead of from the direct TCP connection - but only for requests that actually come from the proxy IP address configured below. Leave disabled unless you have such a setup: any visitor can forge this header, so trusting it without a verified proxy IP would let an attacker get an arbitrary IP address blocked instead of their own."
 PLG_SYSTEM_BFSTOP_PROXY_HEADER_SOURCE_LABEL="Client IP header"
-PLG_SYSTEM_BFSTOP_PROXY_HEADER_SOURCE_DESC="The HTTP header your proxy/load balancer uses to report the original client IP address. Check your proxy's documentation if unsure - X-Forwarded-For is the most common choice."
+PLG_SYSTEM_BFSTOP_PROXY_HEADER_SOURCE_DESC="The HTTP header your proxy/load balancer uses to report the original client IP address. Check your proxy's documentation if unsure - X-Forwarded-For is the most common choice. The client address is taken from the end of the header, i.e. the entry added by your own proxy; entries further left are supplied by the client and ignored. Choose a header your proxy sets or appends to itself."
 PLG_SYSTEM_BFSTOP_PROXY_IP_LABEL="Proxy / load balancer IP address"
-PLG_SYSTEM_BFSTOP_PROXY_IP_DESC="The IP address of your reverse proxy or load balancer, i.e. the address Joomla! sees as REMOTE_ADDR for every legitimate request. The client IP header above is only trusted for requests coming from this address, so that a visitor cannot bypass the proxy and spoof the header directly. Required if 'Behind a proxy / load balancer' is enabled above."
+PLG_SYSTEM_BFSTOP_PROXY_IP_DESC="The IP address of your reverse proxy or load balancer, i.e. the address Joomla! sees as REMOTE_ADDR for every legitimate request. If there are several proxies in a row (e.g. a CDN in front of a load balancer), list all of them, separated by commas; subnets in CIDR notation (e.g. 10.0.0.0/8) are allowed too. The client IP header above is only trusted for requests coming from one of these addresses, so that a visitor cannot bypass the proxy and spoof the header directly. Required if 'Behind a proxy / load balancer' is enabled above."
 PLG_SYSTEM_BFSTOP_GROUP_NOTIFICATION_ENABLED_LABEL="User group notification"
 PLG_SYSTEM_BFSTOP_GROUP_NOTIFICATION_ENABLED_DESC="If enabled, the whole user group selected below will be notified in case of failed logins/banned IPs"
 PLG_SYSTEM_BFSTOP_USERGROUP_LABEL="User group"
diff --git a/src/Extension/Bfstop.php b/src/Extension/Bfstop.php
index dd828ab..a4701a7 100644
--- a/src/Extension/Bfstop.php
+++ b/src/Extension/Bfstop.php
@@ -426,18 +426,33 @@ public function onUserLogin($event)
 		$this->mydb->successfulLogin($info);
 	}
 
-	private function isUnblockRequest()
+	/**
+	 * A blocked IP may only reach com_bfstop's unblock page, and only with an
+	 * unexpired token that was issued for one of *its own* blocks. The pass
+	 * has to stay this narrow: the request is the one that consumes the token,
+	 * so it must really be the unblock view (no task, no other component).
+	 * Letting any request with view=tokenunblock through would turn a single
+	 * valid token - which the owner of any account can get emailed by getting
+	 * themselves blocked - into a reusable key around the block for logins
+	 * (e.g. option=com_users&task=user.login&view=tokenunblock&token=...).
+	 */
+	private function isUnblockRequest($blockIds)
 	{
 		$input = $this->getApplication()->input;
-		$view = $input->getString('view', '');
+		if (strcmp($input->getCmd('option', ''), 'com_bfstop') != 0 ||
+			strcmp($input->getCmd('view', ''), 'tokenunblock') != 0 ||
+			$input->getCmd('task', '') !== '')
+		{
+			return false;
+		}
 		$token = $input->getString('token', '');
-		$result = (strcmp($view, "tokenunblock") == 0 &&
-			$this->mydb->unblockTokenExists($token));
+		$result = $this->mydb->unblockTokenValidForBlocks($token, $blockIds);
 		if ($result)
 		{
-			$this->logger->log('Seeing valid unblock token ('.
-				$token.'), letting the request pass through '.
-				'to com_bfstop',
+			// deliberately not logging the token: it is a bearer secret and
+			// the log is readable in the backend
+			$this->logger->log('Seeing a valid unblock token for this IP '.
+				'address, letting the request pass through to com_bfstop',
 				Log::INFO);
 		}
 		return $result;
@@ -545,7 +560,7 @@ public function onAfterRoute($event)
 				$this->mydb->getClientString(
 					$this->getApplication()->getClientId()),
 				Log::INFO);
-			if ($this->isUnblockRequest())
+			if ($this->isUnblockRequest($blockIds))
 			{
 				return;
 			}
diff --git a/src/Helper/DatabaseHelper.php b/src/Helper/DatabaseHelper.php
index 6d4691a..e966960 100644
--- a/src/Helper/DatabaseHelper.php
+++ b/src/Helper/DatabaseHelper.php
@@ -22,6 +22,10 @@ class DatabaseHelper
 	// 10 years in minutes. For all intents here sufficiently large to stand for "forever":
 	public static $UNLIMITED_DURATION = 5256000;
 
+	// how long an emailed unblock token can be used; com_bfstop's
+	// TokenunblockModel::TokenValidDays must stay in sync with this
+	public static $UNBLOCK_TOKEN_VALID_DAYS = 3;
+
 	// how long a reverse-DNS lookup result is trusted before being redone -
 	// keeps the (potentially slow) gethostbyaddr() call to at most once per
 	// IP per TTL window, see issue #103
@@ -334,6 +338,39 @@ public function getNewUnblockToken($id, $token)
 		}
 	}
 
+	/**
+	 * Whether $token is an unexpired unblock token issued for one of the
+	 * given blocks. Used to decide if a blocked client may reach the unblock
+	 * page: a token that belongs to a different IP address's block, or one
+	 * that has outlived its validity, must not work as a pass for this one.
+	 */
+	public function unblockTokenValidForBlocks($token, array $blockIds)
+	{
+		if ($token === '' || count($blockIds) === 0)
+		{
+			return false;
+		}
+		try
+		{
+			$sql = "SELECT block_id, crdate FROM #__bfstop_unblock_token WHERE token=".
+				$this->db->quote($token);
+			$this->db->setQuery($sql);
+			$row = $this->db->loadAssoc();
+			if ($row === null || !in_array((int) $row['block_id'], $blockIds, true))
+			{
+				return false;
+			}
+			$created = strtotime($row['crdate']);
+			return $created !== false &&
+				(time() - $created) <= (self::$UNBLOCK_TOKEN_VALID_DAYS * 86400);
+		}
+		catch (\Exception $e)
+		{
+			$this->logger->log("Database exception occured: ".$e->getMessage(), Log::ERROR);
+			return false;
+		}
+	}
+
 	public function unblockTokenExists($token)
 	{
 		try
diff --git a/src/Helper/IpHelper.php b/src/Helper/IpHelper.php
index ef8b8e4..9f649ef 100644
--- a/src/Helper/IpHelper.php
+++ b/src/Helper/IpHelper.php
@@ -72,14 +72,122 @@ public static function isInSubnet($ip, $subnet)
 		return (ord($ipBin[$fullBytes]) & $mask) === (ord($subnetBin[$fullBytes]) & $mask);
 	}
 
-	private static function firstValidPublicIP($headerValue)
+	/**
+	 * Splits the trusted proxy setting into its entries. Each entry is a
+	 * single IP address or a subnet in CIDR notation; entries may be
+	 * separated by comma, semicolon or whitespace. A setting holding just one
+	 * address (the only form older versions knew) keeps working unchanged.
+	 */
+	public static function parseTrustedProxies($setting)
+	{
+		return preg_split('/[\s,;]+/', (string) $setting, -1, PREG_SPLIT_NO_EMPTY);
+	}
+
+	/**
+	 * Whether $ip is one of the $trustedProxies (see parseTrustedProxies()).
+	 * Addresses are compared in binary form, so different spellings of the
+	 * same IPv6 address match.
+	 */
+	public static function isTrustedProxy($ip, array $trustedProxies)
 	{
-		foreach (explode(',', $headerValue) as $ip)
+		$ipBin = @inet_pton((string) $ip);
+		if ($ipBin === false)
+		{
+			return false;
+		}
+		foreach ($trustedProxies as $proxy)
 		{
-			$ip = trim($ip); // just to be safe
-			if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE) !== false)
+			if (strpos($proxy, '/') !== false)
 			{
-				return $ip;
+				if (self::isInSubnet($ip, $proxy))
+				{
+					return true;
+				}
+			}
+			elseif (@inet_pton($proxy) === $ipBin)
+			{
+				return true;
+			}
+		}
+		return false;
+	}
+
+	/**
+	 * The address in one entry of a forwarding header, without the quotes,
+	 * brackets and port the various proxies decorate it with; whatever is
+	 * left is not necessarily a valid IP address.
+	 */
+	private static function normalizeHeaderEntry($entry)
+	{
+		$entry = trim(trim($entry), '"');
+		if (preg_match('/^\[([^\]]+)\](?::\d+)?$/', $entry, $m) ||
+			preg_match('/^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/', $entry, $m))
+		{
+			return $m[1];
+		}
+		return $entry;
+	}
+
+	/**
+	 * The addresses listed in a forwarding header, in the order they appear:
+	 * the leftmost one is whatever the client claimed, every further one was
+	 * appended by the proxy that handled the request next. Elements that carry
+	 * no address (e.g. a "Forwarded" element without for=) yield ''.
+	 */
+	private static function headerAddresses($headerName, $headerValue)
+	{
+		$addresses = array();
+		foreach (explode(',', $headerValue) as $element)
+		{
+			if ($headerName === 'HTTP_FORWARDED')
+			{
+				// RFC 7239: ';'-separated key=value pairs per element
+				$address = '';
+				foreach (explode(';', $element) as $pair)
+				{
+					$keyValue = explode('=', $pair, 2);
+					if (count($keyValue) === 2 && strcasecmp(trim($keyValue[0]), 'for') === 0)
+					{
+						$address = $keyValue[1];
+						break;
+					}
+				}
+				$element = $address;
+			}
+			$addresses[] = self::normalizeHeaderEntry($element);
+		}
+		return $addresses;
+	}
+
+	/**
+	 * The client address according to a forwarding header that was set by a
+	 * trusted proxy, or null if it cannot be determined reliably.
+	 *
+	 * Only the entries the trusted proxies themselves added can be believed,
+	 * and a proxy adds its entry on the right: everything to the left of that
+	 * is whatever the client (or someone upstream) put in the header, and
+	 * trivially forged. So the list is read from the right, skipping the
+	 * addresses of further trusted proxies (a CDN in front of a load
+	 * balancer, say); the first address that is not a trusted proxy is the
+	 * client. It must never be taken from further left: with a proxy that
+	 * appends to an incoming X-Forwarded-For, an attacker could otherwise
+	 * pick any address - to dodge blocking, to get another visitor's
+	 * address blocked, or to pass as an allowlisted one.
+	 */
+	public static function clientAddressFromHeader($headerName, $headerValue, array $trustedProxies)
+	{
+		$addresses = self::headerAddresses($headerName, (string) $headerValue);
+		for ($i = count($addresses) - 1; $i >= 0; --$i)
+		{
+			if (filter_var($addresses[$i], FILTER_VALIDATE_IP) === false)
+			{
+				// can't tell what this hop was; guessing from the entries
+				// further left would trust forgeable data
+				return null;
+			}
+			if (!self::isTrustedProxy($addresses[$i], $trustedProxies))
+			{
+				return $addresses[$i];
 			}
 		}
 		return null;
@@ -89,9 +197,11 @@ private static function firstValidPublicIP($headerValue)
 	 * Determine the client IP address. By default only REMOTE_ADDR (the
 	 * actual TCP peer address, which a visitor cannot forge) is used. A
 	 * reverse-proxy header is only consulted if the admin has explicitly
-	 * enabled proxy support and the request's REMOTE_ADDR matches the
-	 * configured, trusted proxy IP address - otherwise a client could bypass
-	 * the proxy entirely and spoof the header itself.
+	 * enabled proxy support and the request's REMOTE_ADDR is one of the
+	 * configured, trusted proxies - otherwise a client could bypass the proxy
+	 * entirely and spoof the header itself - and even then only the part of
+	 * the header the trusted proxies added is believed, see
+	 * clientAddressFromHeader().
 	 */
 	public static function getAddress(LoggerHelper $logger)
 	{
@@ -109,7 +219,8 @@ public static function getAddress(LoggerHelper $logger)
 		}
 
 		$proxyIpAddress = (string) $params->get('proxyIpAddress', '');
-		if ($proxyIpAddress === '' || $remoteAddr !== $proxyIpAddress)
+		$trustedProxies = self::parseTrustedProxies($proxyIpAddress);
+		if (count($trustedProxies) === 0 || !self::isTrustedProxy($remoteAddr, $trustedProxies))
 		{
 			$logger->log('Proxy/load balancer usage is enabled, but the request did not originate from the '.
 				'configured proxy IP address (configured: "'.$proxyIpAddress.'", actual: "'.$remoteAddr.
@@ -120,14 +231,14 @@ public static function getAddress(LoggerHelper $logger)
 		$proxyHeaderSource = (string) $params->get('proxyHeaderSource', 'HTTP_X_FORWARDED_FOR');
 		if (array_key_exists($proxyHeaderSource, $_SERVER))
 		{
-			$ip = self::firstValidPublicIP($_SERVER[$proxyHeaderSource]);
+			$ip = self::clientAddressFromHeader($proxyHeaderSource, $_SERVER[$proxyHeaderSource], $trustedProxies);
 			if ($ip !== null)
 			{
 				return $ip;
 			}
 		}
 		$logger->log('Proxy/load balancer usage is enabled, but header "'.$proxyHeaderSource.
-			'" was missing or did not contain a valid public IP address, falling back to REMOTE_ADDR "'.
+			'" was missing or did not end in a valid client IP address, falling back to REMOTE_ADDR "'.
 			$remoteAddr.'"!', Log::WARNING);
 		return $remoteAddr;
 	}
diff --git a/tests/Integration/BlockedRequestTest.php b/tests/Integration/BlockedRequestTest.php
index 55ffeed..3f2f8ce 100644
--- a/tests/Integration/BlockedRequestTest.php
+++ b/tests/Integration/BlockedRequestTest.php
@@ -155,6 +155,37 @@ public function testValidUnblockTokenGetsThrough()
 		$this->assertBlocked('option=com_bfstop&view=tokenunblock');
 	}
 
+	public function testUnblockTokenIsNoPassForOtherRequests()
+	{
+		// the token is consumed by the unblock page only; as a parameter of
+		// any other request (here: a login) it must not get around the block
+		$this->configure();
+		$blockId = $this->block();
+		$token = (new DatabaseHelper($this->logger))->getNewUnblockToken($blockId, str_repeat('ab', 20));
+		$this->assertBlocked('option=com_users&task=user.login&view=tokenunblock&token='.$token);
+		$this->assertBlocked('option=com_content&view=tokenunblock&token='.$token);
+		$this->assertBlocked('option=com_bfstop&task=display&view=tokenunblock&token='.$token);
+		$this->assertNotBlocked('option=com_bfstop&view=tokenunblock&token='.$token);
+	}
+
+	public function testUnblockTokenOfAnotherBlockIsNoPass()
+	{
+		$this->configure();
+		$this->block();
+		$otherBlockId = $this->block('203.0.113.99');
+		$token = (new DatabaseHelper($this->logger))->getNewUnblockToken($otherBlockId, str_repeat('cd', 20));
+		$this->assertBlocked('option=com_bfstop&view=tokenunblock&token='.$token);
+	}
+
+	public function testExpiredUnblockTokenIsNoPass()
+	{
+		$this->configure();
+		$blockId = $this->block();
+		$this->insert('#__bfstop_unblock_token', array('token' => str_repeat('ef', 20),
+			'block_id' => $blockId, 'crdate' => self::minutesAgo(4 * 24 * 60)));
+		$this->assertBlocked('option=com_bfstop&view=tokenunblock&token='.str_repeat('ef', 20));
+	}
+
 	public function testRejectedRequestsAreCounted()
 	{
 		$this->configure();
diff --git a/tests/Integration/IpHelperAddressTest.php b/tests/Integration/IpHelperAddressTest.php
index 3ffc441..83331d3 100644
--- a/tests/Integration/IpHelperAddressTest.php
+++ b/tests/Integration/IpHelperAddressTest.php
@@ -97,27 +97,43 @@ public static function trustedProxyHeaderProvider()
 	{
 		return array(
 			'single public IP'        => array('203.0.113.5', '203.0.113.5'),
-			'first public in list'    => array('203.0.113.5, 198.51.100.9', '203.0.113.5'),
-			'skips private'           => array('10.0.0.1, 192.168.1.1, 203.0.113.5', '203.0.113.5'),
-			'skips loopback/reserved' => array('127.0.0.1,0.0.0.0, 203.0.113.5', '203.0.113.5'),
+			'last entry wins'         => array('203.0.113.5, 198.51.100.9', '198.51.100.9'),
+			'forged leftmost entry'   => array('1.2.3.4, 203.0.113.5', '203.0.113.5'),
+			'private client'          => array('203.0.113.5, 10.0.0.9', '10.0.0.9'),
 			'whitespace is trimmed'   => array('   203.0.113.5   ', '203.0.113.5'),
-			'garbage is skipped'      => array('not-an-ip, 203.0.113.5', '203.0.113.5'),
 			'public IPv6'             => array('fd00::1, 2001:4860:4860::8888', '2001:4860:4860::8888'),
+			'trusted proxy hop'       => array('203.0.113.5, 198.51.100.7', '203.0.113.5'),
 		);
 	}
 
 	#[DataProvider('trustedProxyHeaderProvider')]
-	public function testTrustedProxyUsesFirstPublicIpFromHeader($header, $expected)
+	public function testTrustedProxyUsesRightmostNonProxyAddress($header, $expected)
 	{
 		$this->configure(array('useProxy' => 1, 'proxyIpAddress' => '198.51.100.7'));
 		$_SERVER['HTTP_X_FORWARDED_FOR'] = $header;
 		$this->assertSame($expected, IpHelper::getAddress($this->logger));
 	}
 
-	public function testTrustedProxyWithOnlyPrivateAddressesFallsBack()
+	public function testTrustedProxyListAndSubnets()
+	{
+		$this->configure(array('useProxy' => 1, 'proxyIpAddress' => '192.0.2.1, 198.51.100.0/24'));
+		$_SERVER['HTTP_X_FORWARDED_FOR'] = '1.2.3.4, 203.0.113.5, 192.0.2.1';
+		$this->assertSame('203.0.113.5', IpHelper::getAddress($this->logger));
+	}
+
+	public function testGarbageAsLastEntryFallsBack()
+	{
+		// nothing to the left of it can be trusted
+		$this->configure(array('useProxy' => 1, 'proxyIpAddress' => '198.51.100.7'));
+		$_SERVER['HTTP_X_FORWARDED_FOR'] = '203.0.113.5, not-an-ip';
+		$this->assertSame('198.51.100.7', IpHelper::getAddress($this->logger));
+		$this->assertTrue($this->logger->hasMessage(Log::WARNING, 'falling back to REMOTE_ADDR'));
+	}
+
+	public function testHeaderOfOnlyTrustedProxiesFallsBack()
 	{
 		$this->configure(array('useProxy' => 1, 'proxyIpAddress' => '198.51.100.7'));
-		$_SERVER['HTTP_X_FORWARDED_FOR'] = '10.1.2.3, 172.16.0.1';
+		$_SERVER['HTTP_X_FORWARDED_FOR'] = '198.51.100.7';
 		$this->assertSame('198.51.100.7', IpHelper::getAddress($this->logger));
 		$this->assertTrue($this->logger->hasMessage(Log::WARNING, 'falling back to REMOTE_ADDR'));
 	}
diff --git a/tests/Unit/IpHelperTest.php b/tests/Unit/IpHelperTest.php
index 0a23859..596a333 100644
--- a/tests/Unit/IpHelperTest.php
+++ b/tests/Unit/IpHelperTest.php
@@ -8,6 +8,7 @@
 namespace Codeling\Bfstop\Tests\Unit;
 
 use Codeling\Plugin\System\Bfstop\Helper\IpHelper;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
 class IpHelperTest extends TestCase
@@ -55,4 +56,64 @@ public function testMalformedNeverMatches()
 		$this->assertFalse(IpHelper::isInSubnet('192.0.2.1', '::/0'));
 		$this->assertFalse(IpHelper::isInSubnet('2001:db8::1', '0.0.0.0/0'));
 	}
+
+	public function testParseTrustedProxies()
+	{
+		$this->assertSame(array('192.0.2.1'), IpHelper::parseTrustedProxies('192.0.2.1'));
+		$this->assertSame(array('192.0.2.1', '198.51.100.0/24', '2001:db8::1'),
+			IpHelper::parseTrustedProxies(" 192.0.2.1,198.51.100.0/24 ;\n2001:db8::1 "));
+		$this->assertSame(array(), IpHelper::parseTrustedProxies(''));
+	}
+
+	public function testIsTrustedProxy()
+	{
+		$proxies = array('192.0.2.1', '198.51.100.0/24', '2001:db8::1');
+		$this->assertTrue(IpHelper::isTrustedProxy('192.0.2.1', $proxies));
+		$this->assertTrue(IpHelper::isTrustedProxy('198.51.100.77', $proxies));
+		// other spelling of the same IPv6 address
+		$this->assertTrue(IpHelper::isTrustedProxy('2001:0db8:0:0:0:0:0:1', $proxies));
+		$this->assertFalse(IpHelper::isTrustedProxy('192.0.2.2', $proxies));
+		$this->assertFalse(IpHelper::isTrustedProxy('not-an-ip', $proxies));
+		$this->assertFalse(IpHelper::isTrustedProxy('', $proxies));
+		$this->assertFalse(IpHelper::isTrustedProxy('192.0.2.1', array()));
+		// a malformed entry never matches
+		$this->assertFalse(IpHelper::isTrustedProxy('192.0.2.1', array('foo', '192.0.2.0/abc')));
+	}
+
+	public static function forwardedHeaderProvider()
+	{
+		$proxy = array('198.51.100.7');
+		return array(
+			'single entry'                      => array('HTTP_X_FORWARDED_FOR', '203.0.113.5', $proxy, '203.0.113.5'),
+			// the case a proxy appending to the client's own header produces:
+			// the forged entry on the left must be ignored
+			'forged leftmost entry'             => array('HTTP_X_FORWARDED_FOR', '1.2.3.4, 203.0.113.5', $proxy, '203.0.113.5'),
+			'several forged entries'            => array('HTTP_X_FORWARDED_FOR', '1.1.1.1, 2.2.2.2, 203.0.113.5', $proxy, '203.0.113.5'),
+			'forged allowlisted address'        => array('HTTP_X_FORWARDED_FOR', '192.0.2.200, 203.0.113.5', $proxy, '203.0.113.5'),
+			'trusted hops are skipped'          => array('HTTP_X_FORWARDED_FOR', '1.2.3.4, 203.0.113.5, 198.51.100.7', $proxy, '203.0.113.5'),
+			'subnet of trusted proxies'         => array('HTTP_X_FORWARDED_FOR', '1.2.3.4, 203.0.113.5, 198.51.100.9', array('198.51.100.0/24'), '203.0.113.5'),
+			'private client'                    => array('HTTP_X_FORWARDED_FOR', '203.0.113.5, 10.0.0.9', $proxy, '10.0.0.9'),
+			'whitespace'                        => array('HTTP_X_FORWARDED_FOR', '  203.0.113.5  ', $proxy, '203.0.113.5'),
+			'IPv6'                              => array('HTTP_X_FORWARDED_FOR', '1.2.3.4, 2001:db8::5', $proxy, '2001:db8::5'),
+			'IPv4 with port'                    => array('HTTP_X_FORWARDED_FOR', '203.0.113.5:4711', $proxy, '203.0.113.5'),
+			'bracketed IPv6 with port'          => array('HTTP_X_FORWARDED_FOR', '[2001:db8::5]:4711', $proxy, '2001:db8::5'),
+			'single-value header'               => array('HTTP_CLIENT_IP', '203.0.113.5', $proxy, '203.0.113.5'),
+			'Forwarded header'                  => array('HTTP_FORWARDED', 'for=1.2.3.4, for=203.0.113.5;proto=https', $proxy, '203.0.113.5'),
+			'Forwarded quoted IPv6'             => array('HTTP_FORWARDED', 'for="[2001:db8::5]:4711";by=198.51.100.7', $proxy, '2001:db8::5'),
+			'Forwarded case-insensitive key'    => array('HTTP_FORWARDED', 'For=203.0.113.5', $proxy, '203.0.113.5'),
+			// unparseable last hop: the entries to its left are not trustworthy
+			'garbage last entry'                => array('HTTP_X_FORWARDED_FOR', '203.0.113.5, not-an-ip', $proxy, null),
+			'empty last entry'                  => array('HTTP_X_FORWARDED_FOR', '203.0.113.5,', $proxy, null),
+			'obfuscated Forwarded identifier'   => array('HTTP_FORWARDED', 'for=203.0.113.5, for=_hidden', $proxy, null),
+			'Forwarded element without for'     => array('HTTP_FORWARDED', 'for=203.0.113.5, proto=https', $proxy, null),
+			'only trusted proxies'              => array('HTTP_X_FORWARDED_FOR', '198.51.100.7, 198.51.100.7', $proxy, null),
+			'empty header'                      => array('HTTP_X_FORWARDED_FOR', '', $proxy, null),
+		);
+	}
+
+	#[DataProvider('forwardedHeaderProvider')]
+	public function testClientAddressFromHeader($header, $value, $proxies, $expected)
+	{
+		$this->assertSame($expected, IpHelper::clientAddressFromHeader($header, $value, $proxies));
+	}
 }

From 43e00dd4c419a471dccfb14d4541570dc06c9fdb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 5 Oct 2026 20:44:45 +0000
Subject: [PATCH 02/10] Record failed logins before delaying; hash unknown
 usernames

- Delay ordering: the failed login is now inserted, counted and checked
  against the block threshold before the configured delay, and a request
  whose IP address just got (or already is) blocked isn't delayed at all.
  Before, a burst of parallel attempts all ran before the first was counted,
  and each held a worker for the whole delay.
- Username storage: usernames of failed logins that don't belong to an
  existing account (and aren't on the common-usernames list) are stored,
  shown, logged and mailed as a keyed hash by default, since users often type
  their password into the username field. Same input gives the same value, so
  attempts are still counted together. New setting unknownUsernameMode
  (hash|plain) restores the old behaviour.
- Tests: FailedLoginTest (runs failed logins in separate processes, incl. a
  check that the attempt is recorded while the request is still delayed),
  UsernameHelperTest, and component tests for the confirmation/IP-bound
  unblock and for the escaped log view (needs com_bfstop on the same branch).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 CHANGELOG                                   |  18 +++
 src/Extension/Bfstop.php                    |  47 +++++-
 src/Helper/DatabaseHelper.php               |  18 +++
 src/Helper/RiskHelper.php                   |  25 +++-
 src/Helper/UsernameHelper.php               |  49 +++++++
 tests/Integration/ComponentTest.php         |  62 ++++++++
 tests/Integration/FailedLoginTest.php       | 153 ++++++++++++++++++++
 tests/Integration/fixtures/failed_login.php |  26 ++++
 tests/Unit/UsernameHelperTest.php           |  52 +++++++
 9 files changed, 435 insertions(+), 15 deletions(-)
 create mode 100644 src/Helper/UsernameHelper.php
 create mode 100644 tests/Integration/FailedLoginTest.php
 create mode 100644 tests/Integration/fixtures/failed_login.php
 create mode 100644 tests/Unit/UsernameHelperTest.php

diff --git a/CHANGELOG b/CHANGELOG
index e875a1d..09df556 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -57,6 +57,24 @@
     and private client addresses reported by the proxy are accepted. Not
     all proxies append to an incoming header: pick a header yours sets or
     appends to
+  - Security: a failed login is now recorded, counted and checked against
+    the block threshold before the configured delay is applied, not after
+    it, and a request whose IP address just got (or already is) blocked is
+    not delayed any more. Before, a burst of parallel login attempts all
+    ran before the first of them was counted, and every one of them held
+    on to a server worker for the whole delay
+  - Security: usernames of failed logins which do not belong to an existing
+    account (and are not on the list of common usernames) are now stored,
+    shown, logged and mailed as an unreadable hash by default, as users
+    often type their password into the username field; the hash is the same
+    for the same input, so attempts are still counted together. The new
+    setting "Usernames Not Matching an Account" restores the old behaviour.
+    Entries stored by earlier versions stay as they are - purge them in the
+    failed login and username statistics views if you want them gone
+  - Security: unblocking by the link in the notification email now needs a
+    confirmation (a POST request) and only works from the IP address which
+    was blocked, so mail security scanners or link previews which open
+    every link in a message can't unblock an attacker (see com_bfstop)
 
 1.5.2 (2024-02-18)
   - Note: Only component changes, no plugin changes
diff --git a/src/Extension/Bfstop.php b/src/Extension/Bfstop.php
index a4701a7..16e2db2 100644
--- a/src/Extension/Bfstop.php
+++ b/src/Extension/Bfstop.php
@@ -16,6 +16,7 @@
 use Codeling\Plugin\System\Bfstop\Helper\NotifierHelper;
 use Codeling\Plugin\System\Bfstop\Helper\RiskHelper;
 use Codeling\Plugin\System\Bfstop\Helper\TokenHelper;
+use Codeling\Plugin\System\Bfstop\Helper\UsernameHelper;
 use Joomla\CMS\Language\Text;
 use Joomla\CMS\Log\Log;
 use Joomla\CMS\Plugin\CMSPlugin;
@@ -361,6 +362,20 @@ private function determineBaseDelayDuration()
 		return $delayDuration;
 	}
 
+	/**
+	 * The form in which the username of a failed login is stored, mailed and
+	 * logged, see UsernameHelper.
+	 */
+	private function usernameForStorage($username)
+	{
+		$mode = $this->getStringParam('unknownUsernameMode', UsernameHelper::ModeHash);
+		$isReadable = ($mode !== UsernameHelper::ModePlain) &&
+			($this->mydb->userExists($username) ||
+				RiskHelper::isCommonUsername($this->params, $username));
+		return UsernameHelper::forStorage($username, $mode, $isReadable,
+			$this->getApplication()->get('secret', ''));
+	}
+
 	public function onUserLoginFailure($event)
 	{
 		$user = $event->getArgument(0);
@@ -383,23 +398,22 @@ public function onUserLoginFailure($event)
 		$username = mb_strimwidth($user['username'], 0, 150, "...");
 		$riskScore = RiskHelper::computeScore($this->mydb, $this->logger, $this->params, $ipAddress, $username);
 
-		$delayDuration = $this->determineDelayDuration($riskScore);
-		if ($delayDuration != 0)
-		{
-			sleep((int) round($delayDuration));
-		}
-
 		$logEntry = new \stdClass();
 		$logEntry->id = null;
 		$logEntry->ipaddress = $ipAddress;
 		$logEntry->logtime = date("Y-m-d H:i:s");
-		$logEntry->username = $username;
+		$logEntry->username = $this->usernameForStorage($username);
 		$logEntry->origin = $this->getApplication()->getClientId();
 
 		$this->logger->log('Failed login attempt from IP address '.
 			$logEntry->ipaddress, Log::DEBUG);
 
-		// insert into log:
+		// Everything is recorded and evaluated *before* the delay below. The
+		// password has been checked by now, so the delay only holds back the
+		// response; if the attempt was only counted after the sleep, a burst
+		// of parallel requests would all run before the first of them
+		// reached the block threshold, and each of them would tie up a
+		// worker for the whole delay.
 		$this->mydb->insertFailedLogin($logEntry);
 
 		$this->notifyOfRemainingAttempts($logEntry, $riskScore);
@@ -408,6 +422,23 @@ public function onUserLoginFailure($event)
 		$this->notifier->failedLogin($logEntry, $maxNumber);
 		$this->blockIfTooManyAttempts($logEntry, $riskScore);
 		$this->accountThrottleIfNeeded($logEntry);
+
+		$delayDuration = $this->determineDelayDuration($riskScore);
+		if ($delayDuration != 0)
+		{
+			// a blocked address gets nothing more out of a slow response;
+			// don't let it hold on to a worker (attackers could otherwise use
+			// the delay to exhaust the server's workers)
+			if ($this->mydb->isIPBlocked($ipAddress))
+			{
+				$this->logger->log('Not delaying the response, IP address '.
+					$ipAddress.' is blocked', Log::DEBUG);
+			}
+			else
+			{
+				sleep((int) round($delayDuration));
+			}
+		}
 	}
 
 	public function onUserLogin($event)
diff --git a/src/Helper/DatabaseHelper.php b/src/Helper/DatabaseHelper.php
index e966960..f231a9f 100644
--- a/src/Helper/DatabaseHelper.php
+++ b/src/Helper/DatabaseHelper.php
@@ -403,6 +403,24 @@ private function getUserEmailWhere($where)
 		}
 	}
 
+	public function userExists($username)
+	{
+		try
+		{
+			// LOWER: Joomla treats usernames case-insensitively on login
+			// (MySQL's default collations do, PostgreSQL's don't)
+			$sql = "SELECT COUNT(*) FROM #__users WHERE LOWER(username) = LOWER(".
+				$this->db->quote($username).")";
+			$this->db->setQuery($sql);
+			return ((int) $this->db->loadResult()) > 0;
+		}
+		catch (\Exception $e)
+		{
+			$this->logger->log("Database exception occured: ".$e->getMessage(), Log::ERROR);
+			return false;
+		}
+	}
+
 	public function getUserEmailByID($uid)
 	{
 		return $this->getUserEmailWhere("id=".((int)$uid));
diff --git a/src/Helper/RiskHelper.php b/src/Helper/RiskHelper.php
index 9c7ae04..913decd 100644
--- a/src/Helper/RiskHelper.php
+++ b/src/Helper/RiskHelper.php
@@ -52,22 +52,33 @@ private static function knownIpScore(DatabaseHelper $db, LoggerHelper $logger, R
 		return 0;
 	}
 
-	private static function commonUsernameScore(Registry $params, $username)
+	/**
+	 * Whether $username is on the admin's list of common/high-value
+	 * usernames (case-insensitive).
+	 */
+	public static function isCommonUsername(Registry $params, $username)
 	{
-		if (!self::getBoolParam($params, 'riskCommonUsernameEnabled', true))
-		{
-			return 0;
-		}
 		$list = (string) $params->get('riskCommonUsernames', '');
 		$candidates = array_filter(array_map('trim', explode("\n", str_replace("\r", '', $list))));
 		foreach ($candidates as $candidate)
 		{
 			if ($candidate !== '' && strcasecmp($candidate, $username) === 0)
 			{
-				return self::getIntParam($params, 'riskCommonUsernamePoints', 2);
+				return true;
 			}
 		}
-		return 0;
+		return false;
+	}
+
+	private static function commonUsernameScore(Registry $params, $username)
+	{
+		if (!self::getBoolParam($params, 'riskCommonUsernameEnabled', true))
+		{
+			return 0;
+		}
+		return self::isCommonUsername($params, $username)
+			? self::getIntParam($params, 'riskCommonUsernamePoints', 2)
+			: 0;
 	}
 
 	private static function userAgentScore(Registry $params)
diff --git a/src/Helper/UsernameHelper.php b/src/Helper/UsernameHelper.php
new file mode 100644
index 0000000..e84e4a3
--- /dev/null
+++ b/src/Helper/UsernameHelper.php
@@ -0,0 +1,49 @@
+<?php
+/*
+ * @package BFStop Plugin (bfstop) for Joomla!
+ * @author Bernhard Froehler
+ * @copyright (C) Bernhard Froehler
+ * @license GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
+**/
+
+namespace Codeling\Plugin\System\Bfstop\Helper;
+
+defined('_JEXEC') or die;
+
+/**
+ * What of a failed login's username field gets stored.
+ *
+ * Users regularly type their password into the username field. Storing it
+ * verbatim would keep those passwords in the failed login table and the
+ * per-username statistics (which are not purged automatically), show them
+ * in the backend and mail them to the administrators. So by default only
+ * usernames that are not a secret in the first place - existing accounts
+ * and the well-known names an admin configured as "common usernames" - are
+ * stored readably; any other value is replaced by a keyed hash. The hash is
+ * still the same for the same input, so attempts against one unknown name
+ * are still counted together (e.g. for the account throttle and the
+ * username statistics), but the input cannot be read back from it.
+ */
+class UsernameHelper
+{
+	public const ModeHash = 'hash';
+	public const ModePlain = 'plain';
+
+	/**
+	 * @param string $username      the username as entered
+	 * @param string $mode          ModeHash or ModePlain
+	 * @param bool   $isReadable    whether this username may be stored as is
+	 *                              (existing account, common username)
+	 * @param string $secret        site-specific key for the hash
+	 */
+	public static function forStorage($username, $mode, $isReadable, $secret)
+	{
+		if ($mode === self::ModePlain || $isReadable)
+		{
+			return $username;
+		}
+		return '[unknown:'.
+			substr(hash_hmac('sha256', mb_strtolower($username), (string) $secret), 0, 16).
+			']';
+	}
+}
diff --git a/tests/Integration/ComponentTest.php b/tests/Integration/ComponentTest.php
index 8803724..ed40cd3 100644
--- a/tests/Integration/ComponentTest.php
+++ b/tests/Integration/ComponentTest.php
@@ -120,6 +120,68 @@ public function testUnblockViaEmailToken()
 		$this->assertSame(0, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_unblock_token'));
 	}
 
+	public function testTokenUnblockNeedsConfirmationAndTheBlockedIp()
+	{
+		$ip = '203.0.113.5';
+		$blockId = $this->insert('#__bfstop_bannedip', array('ipaddress' => $ip, 'crdate' => self::minutesAgo(0), 'duration' => 60), 'id');
+		$this->insert('#__bfstop_unblock_token', array('token' => 'valid', 'block_id' => $blockId, 'crdate' => self::minutesAgo(60)));
+		$helper = new DatabaseHelper($this->logger);
+		$model = $this->model(TokenunblockModel::class);
+		$tokens = 'SELECT COUNT(*) FROM #__bfstop_unblock_token';
+
+		$this->assertSame(TokenunblockModel::ResultInvalid, $model->process('', true, $ip, $this->logger));
+
+		// opening the link (what a mail scanner does) changes nothing
+		$this->assertSame(TokenunblockModel::ResultConfirm, $model->process('valid', false, $ip, $this->logger));
+		$this->assertTrue($helper->isIPBlocked($ip));
+		$this->assertSame(1, (int) $this->queryValue($tokens));
+
+		// confirming from another IP address doesn't unblock either
+		$this->assertSame(TokenunblockModel::ResultWrongIp, $model->process('valid', true, '198.51.100.9', $this->logger));
+		$this->assertTrue($helper->isIPBlocked($ip));
+		$this->assertSame(1, (int) $this->queryValue($tokens));
+
+		// neither does an unknown token
+		$this->assertSame(TokenunblockModel::ResultFailed, $model->process('unknown', true, $ip, $this->logger));
+		$this->logger->errors = array(); // expected: "token not found" error
+		$this->assertTrue($helper->isIPBlocked($ip));
+
+		$this->assertSame(TokenunblockModel::ResultUnblocked, $model->process('valid', true, $ip, $this->logger));
+		$this->assertFalse($helper->isIPBlocked($ip));
+		$this->assertSame(0, (int) $this->queryValue($tokens));
+	}
+
+	public function testTokenUnblockComparesIpv6AddressesNotSpellings()
+	{
+		$blockId = $this->insert('#__bfstop_bannedip', array('ipaddress' => '2001:db8::1', 'crdate' => self::minutesAgo(0), 'duration' => 60), 'id');
+		$this->insert('#__bfstop_unblock_token', array('token' => 'valid', 'block_id' => $blockId, 'crdate' => self::minutesAgo(1)));
+		$model = $this->model(TokenunblockModel::class);
+		$this->assertSame(TokenunblockModel::ResultWrongIp, $model->process('valid', true, '2001:db8::2', $this->logger));
+		$this->assertSame(TokenunblockModel::ResultUnblocked, $model->process('valid', true, '2001:0DB8:0:0:0:0:0:1', $this->logger));
+	}
+
+	public function testLogViewEscapesLogContents()
+	{
+		// the message of a log entry can contain what a visitor sent (e.g. a username)
+		$view = new class {
+			public $items;
+			public function escape($string)
+			{
+				return htmlspecialchars((string) $string, ENT_QUOTES, 'UTF-8');
+			}
+		};
+		$view->items = array((object) array('date' => '2026-01-01T00:00:00+00:00',
+			'priority' => 'DEBUG', 'message' => 'Unknown user (<script>alert(1)</script>) blocked'));
+		ob_start();
+		(function ()
+		{
+			include getenv('COM_BFSTOP_ROOT').'/admin/tmpl/log/default_body.php';
+		})->call($view);
+		$html = ob_get_clean();
+		$this->assertStringNotContainsString('<script>', $html);
+		$this->assertStringContainsString('&lt;script&gt;alert(1)&lt;/script&gt;', $html);
+	}
+
 	public function testWarnsAboutAdminUserCaseInsensitively()
 	{
 		// tests/ci/install-joomla.sh creates the super user as "Admin"
diff --git a/tests/Integration/FailedLoginTest.php b/tests/Integration/FailedLoginTest.php
new file mode 100644
index 0000000..1b9d7d6
--- /dev/null
+++ b/tests/Integration/FailedLoginTest.php
@@ -0,0 +1,153 @@
+<?php
+/*
+ * @package BFStop Plugin (bfstop) for Joomla!
+ * @author Bernhard Froehler
+ * @copyright (C) Bernhard Froehler
+ * @license GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
+**/
+namespace Codeling\Bfstop\Tests\Integration;
+
+use Joomla\CMS\Factory;
+
+/**
+ * How the plugin handles a failed login, with the settings it reads from the
+ * database: each failed login runs in a separate process (see
+ * fixtures/failed_login.php), as it would in a real request.
+ */
+class FailedLoginTest extends IntegrationTestCase
+{
+	private const Ip = '203.0.113.51';
+
+	private static $originalParams;
+
+	public static function setUpBeforeClass(): void
+	{
+		parent::setUpBeforeClass();
+		$db = Factory::getDbo();
+		$db->setQuery("SELECT params FROM #__extensions WHERE type='plugin' AND element='bfstop'");
+		self::$originalParams = $db->loadResult();
+	}
+
+	public static function tearDownAfterClass(): void
+	{
+		if (self::$originalParams !== null)
+		{
+			$db = Factory::getDbo();
+			$db->setQuery('UPDATE #__extensions SET params='.$db->quote(self::$originalParams).
+				" WHERE type='plugin' AND element='bfstop'");
+			$db->execute();
+		}
+	}
+
+	private function configure(array $params = array())
+	{
+		$this->setPluginParams(json_encode($params + array(
+			'blockMode' => 'full',
+			'blockNumber' => 15,
+			'riskMinBlockNumber' => 1,
+			'riskBlockNumberReductionPerPoint' => 0,
+			'riskDelaySecondsPerPoint' => 0,
+			'checkInterval' => 60,
+			'blockDuration' => 60,
+			'delayDuration' => 0,
+			'accountThrottleEnabled' => 0,
+			'notifyBlockedNumber' => 0,
+			'riskCommonUsernames' => "root\nadministrator",
+			'logLevel' => 8, // errors only
+		)));
+	}
+
+	private function command($username, $ip = self::Ip)
+	{
+		return escapeshellarg(PHP_BINARY).' '.escapeshellarg(__DIR__.'/fixtures/failed_login.php').' '.
+			escapeshellarg($ip).' '.escapeshellarg($username);
+	}
+
+	private function failedLogin($username, $ip = self::Ip)
+	{
+		exec($this->command($username, $ip).' 2>&1', $output, $exitCode);
+		$output = implode("\n", $output);
+		$this->assertSame(0, $exitCode, $output);
+		$this->assertStringContainsString('DONE', $output);
+	}
+
+	private function storedUsernames()
+	{
+		$this->db->setQuery('SELECT username FROM #__bfstop_failedlogin ORDER BY id');
+		return $this->db->loadColumn();
+	}
+
+	public function testFailedLoginIsRecordedBeforeTheDelay()
+	{
+		// the delay only holds back the response; the attempt has to count
+		// right away, or a burst of parallel requests all start before the
+		// first one reaches the block threshold
+		$this->configure(array('delayDuration' => 5));
+		$process = proc_open($this->command('Admin'),
+			array(1 => array('pipe', 'w'), 2 => array('pipe', 'w')), $pipes);
+		$this->assertIsResource($process);
+		try
+		{
+			$recorded = false;
+			for ($i = 0; $i < 40 && !$recorded; ++$i)
+			{
+				usleep(100000);
+				$recorded = ((int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_failedlogin')) === 1;
+			}
+			$this->assertTrue($recorded, 'failed login was not recorded within 4s (the delay is 5s)');
+			$this->assertTrue(proc_get_status($process)['running'],
+				'the request should still be delayed at this point');
+		}
+		finally
+		{
+			proc_terminate($process);
+			proc_close($process);
+		}
+	}
+
+	public function testBlockedAddressIsNotDelayed()
+	{
+		$this->configure(array('delayDuration' => 5, 'blockNumber' => 1));
+		$start = microtime(true);
+		$this->failedLogin('Admin');
+		$this->assertLessThan(4.0, microtime(true) - $start, 'a request that got its address blocked must not wait for the delay');
+		$this->assertSame(self::Ip, $this->queryValue('SELECT ipaddress FROM #__bfstop_bannedip'));
+	}
+
+	public function testExistingAndCommonUsernamesAreStoredReadably()
+	{
+		$this->configure();
+		$this->failedLogin('Admin');
+		$this->failedLogin('admin'); // as typed
+		$this->failedLogin('ROOT');
+		$this->assertSame(array('Admin', 'admin', 'ROOT'), $this->storedUsernames());
+		$this->assertSame(3, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_username_stats'));
+	}
+
+	public function testOtherUsernamesAreStoredHashed()
+	{
+		// e.g. a password typed into the username field
+		$this->configure();
+		$this->failedLogin('hunter2-S3cret!');
+		$this->failedLogin('HUNTER2-s3cret!');
+		$this->failedLogin('another-one');
+		$stored = $this->storedUsernames();
+		foreach ($stored as $username)
+		{
+			$this->assertMatchesRegularExpression('/^\[unknown:[0-9a-f]{16}\]$/', $username);
+		}
+		$this->assertSame($stored[0], $stored[1], 'the same input has to give the same value, to count attempts together');
+		$this->assertNotSame($stored[0], $stored[2]);
+		$this->assertSame(2, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_username_stats'));
+		$this->assertSame(2, (int) $this->queryValue('SELECT attempts FROM #__bfstop_username_stats WHERE username='.
+			$this->db->quote($stored[0])));
+		$this->assertSame(0, (int) $this->queryValue("SELECT COUNT(*) FROM #__bfstop_username_stats WHERE username LIKE '%hunter%'"));
+	}
+
+	public function testPlainModeStoresEveryUsername()
+	{
+		$this->configure(array('unknownUsernameMode' => 'plain'));
+		$this->failedLogin('someone-unknown');
+		$this->assertSame(array('someone-unknown'), $this->storedUsernames());
+	}
+}
diff --git a/tests/Integration/fixtures/failed_login.php b/tests/Integration/fixtures/failed_login.php
new file mode 100644
index 0000000..a6bceff
--- /dev/null
+++ b/tests/Integration/fixtures/failed_login.php
@@ -0,0 +1,26 @@
+<?php
+/*
+ * @package BFStop Plugin (bfstop) for Joomla!
+ * @author Bernhard Froehler
+ * @copyright (C) Bernhard Froehler
+ * @license GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
+**/
+// Simulates a failed login with the username given as second argument from
+// the IP address given as first argument, as far as the plugin is concerned:
+// dispatches onUserLoginFailure to the plugin, which reads its settings from
+// the database as it does in a real request (and may delay or block).
+// Used by FailedLoginTest; needs the same environment as the tests.
+
+use Joomla\CMS\Factory;
+use Joomla\CMS\Plugin\PluginHelper;
+use Joomla\Event\Event;
+
+require dirname(__DIR__, 2).'/bootstrap.php';
+
+$_SERVER['REMOTE_ADDR'] = $argv[1];
+$_SERVER['HTTP_USER_AGENT'] = 'Mozilla/5.0';
+$app = Factory::getApplication();
+PluginHelper::importPlugin('system', 'bfstop', true, $app->getDispatcher());
+$app->getDispatcher()->dispatch('onUserLoginFailure',
+	new Event('onUserLoginFailure', array(array('username' => $argv[2], 'status' => 4), array())));
+echo "DONE\n";
diff --git a/tests/Unit/UsernameHelperTest.php b/tests/Unit/UsernameHelperTest.php
new file mode 100644
index 0000000..8366398
--- /dev/null
+++ b/tests/Unit/UsernameHelperTest.php
@@ -0,0 +1,52 @@
+<?php
+/*
+ * @package BFStop Plugin (bfstop) for Joomla!
+ * @author Bernhard Froehler
+ * @copyright (C) Bernhard Froehler
+ * @license GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
+**/
+namespace Codeling\Bfstop\Tests\Unit;
+
+use Codeling\Plugin\System\Bfstop\Helper\UsernameHelper;
+use PHPUnit\Framework\TestCase;
+
+class UsernameHelperTest extends TestCase
+{
+	public function testReadableUsernamesAreKept()
+	{
+		$this->assertSame('Admin', UsernameHelper::forStorage('Admin', UsernameHelper::ModeHash, true, 'key'));
+	}
+
+	public function testPlainModeKeepsEverything()
+	{
+		$this->assertSame('hunter2', UsernameHelper::forStorage('hunter2', UsernameHelper::ModePlain, false, 'key'));
+	}
+
+	public function testUnknownUsernamesAreHashed()
+	{
+		$stored = UsernameHelper::forStorage('hunter2', UsernameHelper::ModeHash, false, 'key');
+		$this->assertMatchesRegularExpression('/^\[unknown:[0-9a-f]{16}\]$/', $stored);
+		$this->assertStringNotContainsString('hunter2', $stored);
+	}
+
+	public function testHashIsStableAndCaseInsensitive()
+	{
+		$a = UsernameHelper::forStorage('Hunter2', UsernameHelper::ModeHash, false, 'key');
+		$this->assertSame($a, UsernameHelper::forStorage('hunter2', UsernameHelper::ModeHash, false, 'key'));
+		$this->assertNotSame($a, UsernameHelper::forStorage('hunter3', UsernameHelper::ModeHash, false, 'key'));
+	}
+
+	public function testHashDependsOnTheSiteKey()
+	{
+		// so values can't be matched against a precomputed table of passwords
+		$this->assertNotSame(
+			UsernameHelper::forStorage('hunter2', UsernameHelper::ModeHash, false, 'key1'),
+			UsernameHelper::forStorage('hunter2', UsernameHelper::ModeHash, false, 'key2'));
+	}
+
+	public function testMultibyteUsername()
+	{
+		$this->assertMatchesRegularExpression('/^\[unknown:[0-9a-f]{16}\]$/',
+			UsernameHelper::forStorage('Пароль🔑', UsernameHelper::ModeHash, false, 'key'));
+	}
+}

From a6063d575edcb46c1da3da6fd58c02215cbf9d0a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 5 Oct 2026 21:02:15 +0000
Subject: [PATCH 03/10] Fix remaining low-severity findings

- .htaccess: only valid IP addresses/subnets are written (a prefix like
  "1e1" passed the old validation and made Apache reject the file), the 403
  message is escaped, and read-modify-write cycles hold a lock so that
  concurrent blocks don't overwrite each other.
- Block page: never cached (Cache-Control: no-store), HTTP 403 by default.
- IPv6: failed logins and blocks are tracked per network (default /64,
  setting ipv6PrefixLength); IPv4-mapped, NAT64, 6to4 and Teredo addresses
  stay per address.
- Bounded growth: log rotation at 5 MB; username statistics capped at
  10000 rows, trimmed by the daily maintenance.
- Maintenance only updates its own lastPurge value in the stored settings
  instead of writing back a possibly stale copy of all of them, and runs
  even if no purge age is set.
- GeoIP database path: no stream wrappers.
- SECURITY.md: supported versions and how to report.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 CHANGELOG                                  | 28 +++++++
 SECURITY.md                                | 38 ++++++++-
 src/Extension/Bfstop.php                   | 56 ++++++++++---
 src/Helper/DatabaseHelper.php              | 95 ++++++++++++++++++++--
 src/Helper/GeoHelper.php                   |  7 ++
 src/Helper/HtaccessHelper.php              | 87 ++++++++++++++++++--
 src/Helper/IpHelper.php                    | 60 +++++++++++++-
 src/Helper/LoggerHelper.php                | 31 ++++++-
 tests/Integration/BlockedRequestTest.php   | 28 +++++++
 tests/Integration/ComponentTest.php        | 45 ++++++++++
 tests/Integration/DatabaseHelperTest.php   | 32 +++++++-
 tests/Integration/FailedLoginTest.php      | 50 ++++++++++++
 tests/Integration/GeoHelperTest.php        |  9 ++
 tests/Integration/HtaccessHelperTest.php   | 66 +++++++++++++++
 tests/Integration/IpValidateHelperTest.php |  6 ++
 tests/Integration/LoggerHelperTest.php     | 76 +++++++++++++++++
 tests/Integration/fixtures/deny_ip.php     | 24 ++++++
 tests/Integration/fixtures/request.php     |  6 ++
 tests/Unit/IpHelperTest.php                | 75 +++++++++++++++++
 19 files changed, 785 insertions(+), 34 deletions(-)
 create mode 100644 tests/Integration/LoggerHelperTest.php
 create mode 100644 tests/Integration/fixtures/deny_ip.php

diff --git a/CHANGELOG b/CHANGELOG
index 09df556..256ed98 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -75,6 +75,34 @@
     confirmation (a POST request) and only works from the IP address which
     was blocked, so mail security scanners or link previews which open
     every link in a message can't unblock an attacker (see com_bfstop)
+  - Security: IPv6 clients are now tracked per network (default: /64, see
+    the new "IPv6 Tracking Granularity" setting) instead of per address:
+    failed logins are counted and blocks apply to the whole network, so an
+    attacker can no longer start over by switching to another address in
+    their /64. IPv4-mapped, NAT64, 6to4 and Teredo addresses, which embed
+    unrelated clients' IPv4 addresses, are still tracked individually
+  - Security: the block page is never cached (Cache-Control: no-store) and,
+    if no setting says otherwise, answers with the HTTP status 403 instead of
+    200, so a caching proxy/CDN can't serve it to other visitors
+  - Security: only a valid IP address or subnet is written to the .htaccess
+    file (before, a value like "192.0.2.0/1e1" passed the backend validation
+    and made Apache reject the whole file); the 403 message is escaped; and
+    changes of the file are done while holding a lock, so that clients
+    getting blocked at the same time don't overwrite each other's lines
+  - Security: the plugin's log file is rotated at 5 MB, and the username
+    statistics (which aren't purged by age) are limited to 10000 usernames,
+    removing those with the fewest attempts first, so a visitor can't fill up
+    disk or database by making up usernames
+  - Security: the periodic maintenance (once a day) only updates its own
+    timestamp in the plugin's stored settings, instead of writing back all
+    settings as they were when the request started, which could undo a
+    change an administrator saved in the meantime; and it now also runs if
+    no purge age is configured
+  - Security (component): sending the test email now needs the permission to
+    change the settings; the .htaccess path and GeoIP database path settings
+    are validated (no stream wrappers like phar://, a .mmdb file name)
+  - Added SECURITY.md with the supported versions and how to report
+    vulnerabilities
 
 1.5.2 (2024-02-18)
   - Note: Only component changes, no plugin changes
diff --git a/SECURITY.md b/SECURITY.md
index 67fb6e9..6350ec2 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1 +1,37 @@
-With information on security vulnerabilities, please contact me via security@bfstop.de.
+# Security Policy
+
+## Supported versions
+
+Security fixes are made for the latest release of the BFStop plugin
+(`plg_system_bfstop`) and the BFStop component (`com_bfstop`). The two are
+released together and need to be on the same major and minor version, so
+please update both.
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities by email to **security@bfstop.de**
+rather than in a public issue or pull request, so that a fix can be
+available before details are public.
+
+It helps to include:
+
+- the affected version(s) of plugin and component, and the Joomla! and PHP
+  versions,
+- the relevant settings (blocking mode, proxy settings, ...),
+- steps to reproduce, or a proof of concept, and what an attacker gains.
+
+## What is and isn't in scope
+
+BFStop sits in front of the login of a Joomla! site and decides which
+requests to reject, so these are the kind of reports which are most useful:
+
+- ways around a block or the failed-login counting (for example by faking
+  the client address, or by reusing an unblock link),
+- ways to get someone else blocked, or to make the plugin tie up the server,
+- ways to read or change data (settings, blocks, logged usernames) without
+  the necessary permissions, and cross-site scripting in the backend views.
+
+Settings are changed by users with the `core.admin` permission for
+`com_bfstop`. They can, among other things, choose the directory in which the
+plugin writes its `.htaccess` file, so grant that permission only to people
+you trust with the web server's configuration for your site.
diff --git a/src/Extension/Bfstop.php b/src/Extension/Bfstop.php
index 16e2db2..8c48528 100644
--- a/src/Extension/Bfstop.php
+++ b/src/Extension/Bfstop.php
@@ -31,6 +31,9 @@ class Bfstop extends CMSPlugin implements SubscriberInterface
 	private LoggerHelper $logger;
 	private NotifierHelper $notifier;
 	private DatabaseHelper $mydb;
+	// the client's actual address while handling a failed login; the failed
+	// login entry holds the key it is tracked under instead (IPv6: its network)
+	private ?string $clientAddress = null;
 
 	public static function getSubscribedEvents(): array
 	{
@@ -98,7 +101,7 @@ private function block($logEntry, $duration)
 		}
 		// if the IP address is blocked we actually shouldn't be here in
 		// the first place I guess, but just to make sure
-		if ($this->mydb->isIPBlocked($logEntry->ipaddress))
+		if ($this->mydb->isIPBlocked($this->clientAddress ?? $logEntry->ipaddress))
 		{
 			$this->logger->log('IP '.$logEntry->ipaddress.
 				' is already blocked!', Log::ERROR);
@@ -362,6 +365,11 @@ private function determineBaseDelayDuration()
 		return $delayDuration;
 	}
 
+	private function trackedAddress($ipAddress)
+	{
+		return IpHelper::trackedAddress($ipAddress, $this->getIntParam('ipv6PrefixLength', 64));
+	}
+
 	/**
 	 * The form in which the username of a failed login is stored, mailed and
 	 * logged, see UsernameHelper.
@@ -400,7 +408,8 @@ public function onUserLoginFailure($event)
 
 		$logEntry = new \stdClass();
 		$logEntry->id = null;
-		$logEntry->ipaddress = $ipAddress;
+		$this->clientAddress = $ipAddress;
+		$logEntry->ipaddress = $this->trackedAddress($ipAddress);
 		$logEntry->logtime = date("Y-m-d H:i:s");
 		$logEntry->username = $this->usernameForStorage($username);
 		$logEntry->origin = $this->getApplication()->getClientId();
@@ -454,7 +463,7 @@ public function onUserLogin($event)
 		$info->username = $user['username'];
 		$this->logger->log('Successful login by '.$info->username.
 			' from IP address '.$info->ipaddress, Log::DEBUG);
-		$this->mydb->successfulLogin($info);
+		$this->mydb->successfulLogin($info, $this->trackedAddress($info->ipaddress));
 	}
 
 	/**
@@ -546,19 +555,40 @@ public function onAfterInitialise($event)
 		{
 			return;
 		}
-		$purgeAge = $this->getIntParam('deleteOld', 0);
-		if ($purgeAge > 0)
+		// periodic maintenance, at most once a day
+		$purgeInterval = 86400; // = 24*60*60 => one day
+		$lastPurge = $this->params->get('lastPurge', 0);
+		$now = time();
+		if ($now > ($lastPurge + $purgeInterval))
 		{
-			$purgeInterval = 86400; // = 24*60*60 => one day
-			$lastPurge = $this->params->get('lastPurge', 0);
-			$now = time();
-			if ($now > ($lastPurge + $purgeInterval))
+			$purgeAge = $this->getIntParam('deleteOld', 0);
+			if ($purgeAge > 0)
 			{
 				$this->mydb->purgeOldEntries($purgeAge);
-				$this->params->set('lastPurge', $now);
-				$this->mydb->saveParams($this->params);
 			}
+			// regardless of the purge age setting: these are not deleted by age
+			$this->mydb->trimUsernameStats();
+			$this->params->set('lastPurge', $now);
+			$this->mydb->saveLastPurge($now);
+		}
+	}
+
+	/**
+	 * The headers of the page shown to a blocked client.
+	 *
+	 * It must never be cached: a cache (browser, proxy, CDN) which kept it
+	 * would show it to other visitors of the same URL.
+	 */
+	public static function blockedResponseHeaders($useHttpError)
+	{
+		$headers = array();
+		if ($useHttpError)
+		{
+			$headers[] = 'HTTP/1.0 403 Forbidden';
 		}
+		$headers[] = 'Cache-Control: no-store, no-cache, must-revalidate, private';
+		$headers[] = 'Pragma: no-cache';
+		return $headers;
 	}
 
 	/**
@@ -607,9 +637,9 @@ public function onAfterRoute($event)
 				return;
 			}
 			$this->mydb->recordBlockedAttempt($blockIds);
-			if ($this->getBoolParam('useHttpError', false))
+			foreach (self::blockedResponseHeaders($this->getBoolParam('useHttpError', true)) as $header)
 			{
-				header('HTTP/1.0 403 Forbidden');
+				header($header);
 			}
 			$message = $this->params->get('blockedMessage',
 				Text::_('PLG_SYSTEM_BFSTOP_BLOCKED_IP_MESSAGE'));
diff --git a/src/Helper/DatabaseHelper.php b/src/Helper/DatabaseHelper.php
index f231a9f..abbb9b4 100644
--- a/src/Helper/DatabaseHelper.php
+++ b/src/Helper/DatabaseHelper.php
@@ -10,6 +10,7 @@
 
 defined('_JEXEC') or die;
 
+use Joomla\CMS\Cache\CacheControllerFactoryInterface;
 use Joomla\CMS\Factory;
 use Joomla\CMS\Language\Text;
 use Joomla\CMS\Log\Log;
@@ -26,6 +27,11 @@ class DatabaseHelper
 	// TokenunblockModel::TokenValidDays must stay in sync with this
 	public static $UNBLOCK_TOKEN_VALID_DAYS = 3;
 
+	// upper bound for the rows of the username statistics, which (unlike
+	// the failed logins) are not purged by age: an attacker can make up as
+	// many usernames as they like
+	public static $USERNAME_STATS_MAX_ROWS = 10000;
+
 	// how long a reverse-DNS lookup result is trusted before being redone -
 	// keeps the (potentially slow) gethostbyaddr() call to at most once per
 	// IP per TTL window, see issue #103
@@ -520,9 +526,18 @@ public function setFailedLoginHandled($info, $restrictOnUsername)
 		}
 	}
 
-	public function successfulLogin($info)
+	/**
+	 * @param object      $info           ipaddress (the client's address) and username
+	 * @param string|null $trackedAddress the key failed logins of this client
+	 *                                    are recorded under (see
+	 *                                    IpHelper::trackedAddress()), if different
+	 */
+	public function successfulLogin($info, $trackedAddress = null)
 	{
-		$this->setFailedLoginHandled($info, true);
+		$handled = new \stdClass();
+		$handled->ipaddress = $trackedAddress ?? $info->ipaddress;
+		$handled->username = $info->username;
+		$this->setFailedLoginHandled($handled, true);
 		$this->recordKnownIpUsername($info->ipaddress, $info->username);
 	}
 
@@ -686,18 +701,84 @@ public function purgeOldEntries($purgeAgeWeeks)
 		}
 	}
 
-	public function saveParams($params)
+	/**
+	 * Remembers when the periodic maintenance last ran.
+	 *
+	 * Only this one value is changed in the plugin's stored settings, which
+	 * are read from the database right now: writing back the settings the
+	 * request was started with would undo whatever an administrator saved in
+	 * the meantime.
+	 */
+	public function saveLastPurge($timestamp)
 	{
 		try
 		{
-			$query = $this->db->getQuery(true);
+			$where = function ($query)
+			{
+				$query->where($this->db->quoteName('type').' = '.$this->db->quote('plugin'))
+					->where($this->db->quoteName('folder').' = '.$this->db->quote('system'))
+					->where($this->db->quoteName('element').' = '.$this->db->quote('bfstop'));
+				return $query;
+			};
+			$query = $where($this->db->getQuery(true)
+				->select($this->db->quoteName('params'))
+				->from($this->db->quoteName('#__extensions')));
+			$this->db->setQuery($query);
+			$params = json_decode((string) $this->db->loadResult(), true);
+			if (!is_array($params))
+			{
+				$params = array();
+			}
+			$params['lastPurge'] = (int) $timestamp;
 			// no table alias here: PostgreSQL doesn't allow qualified column
 			// names in the SET clause (issue #206)
-			$query->update($this->db->quoteName('#__extensions'));
-			$query->set($this->db->quoteName('params').' = '. $this->db->quote((string)$params));
-			$query->where($this->db->quoteName('element').' = '.$this->db->quote('bfstop'));
+			$query = $where($this->db->getQuery(true)
+				->update($this->db->quoteName('#__extensions'))
+				->set($this->db->quoteName('params').' = '.$this->db->quote(json_encode($params))));
 			$this->db->setQuery($query);
 			$this->db->execute();
+			// the plugin list (with the settings) is cached
+			Factory::getContainer()->get(CacheControllerFactoryInterface::class)
+				->createCacheController('callback', array('defaultgroup' => 'com_plugins'))
+				->clean();
+		}
+		catch (\Exception $e)
+		{
+			$this->logger->log("Database exception occured: ".$e->getMessage(), Log::ERROR);
+		}
+	}
+
+	/**
+	 * Keeps the username statistics below $maxRows by deleting the entries of
+	 * the usernames with the fewest attempts, the longest ago first.
+	 */
+	public function trimUsernameStats($maxRows = null)
+	{
+		$maxRows = $maxRows ?? self::$USERNAME_STATS_MAX_ROWS;
+		try
+		{
+			for ($round = 0; $round < 1000; ++$round)
+			{
+				$this->db->setQuery('SELECT COUNT(*) FROM #__bfstop_username_stats');
+				$excess = ((int) $this->db->loadResult()) - $maxRows;
+				if ($excess <= 0)
+				{
+					return;
+				}
+				$query = $this->db->getQuery(true)
+					->select($this->db->quoteName('username'))
+					->from($this->db->quoteName('#__bfstop_username_stats'))
+					->order($this->db->quoteName('attempts').' ASC, '.$this->db->quoteName('last_attempt').' ASC');
+				$this->db->setQuery($query, 0, min($excess, 1000));
+				$usernames = $this->db->loadColumn();
+				if (count($usernames) === 0)
+				{
+					return;
+				}
+				$this->db->setQuery('DELETE FROM #__bfstop_username_stats WHERE username IN ('.
+					implode(',', array_map(array($this->db, 'quote'), $usernames)).')');
+				$this->db->execute();
+			}
 		}
 		catch (\Exception $e)
 		{
diff --git a/src/Helper/GeoHelper.php b/src/Helper/GeoHelper.php
index d108ecf..ae68610 100644
--- a/src/Helper/GeoHelper.php
+++ b/src/Helper/GeoHelper.php
@@ -69,6 +69,13 @@ private static function lookup(LoggerHelper $logger, $dbPath, $ipaddress)
 		{
 			return null;
 		}
+		// a plain file of the file system only: is_readable() and the reader
+		// would also open stream wrappers (phar://, ftp://, ...)
+		if (preg_match('#^[a-z][a-z0-9+.-]*://#i', $dbPath))
+		{
+			$logger->log('GeoHelper: GeoIP database path is not a plain file name: '.$dbPath, Log::WARNING);
+			return null;
+		}
 		if (!is_readable($dbPath))
 		{
 			$logger->log('GeoHelper: GeoIP database file not readable: '.$dbPath, Log::WARNING);
diff --git a/src/Helper/HtaccessHelper.php b/src/Helper/HtaccessHelper.php
index 0de774f..2fa6ed9 100644
--- a/src/Helper/HtaccessHelper.php
+++ b/src/Helper/HtaccessHelper.php
@@ -80,7 +80,7 @@ public function checkRequirements()
 	{
 		$result = array(
 			'apacheserver' =>
-				strstr(preg_replace("/[^a-z]+/", "", strtolower($_SERVER['SERVER_SOFTWARE'])), 'apache'),
+				strstr(preg_replace("/[^a-z]+/", "", strtolower($_SERVER['SERVER_SOFTWARE'] ?? '')), 'apache'),
 			'found'		=> file_exists($this->path),
 			'readable'	=> is_readable($this->path),
 			'writeable'	=> is_writeable($this->path)
@@ -113,7 +113,23 @@ public function getDeniedIPs()
 	 */
 	public function denyIP($IP)
 	{
-		return $this->addLine(self::BlockPrefix . $IP);
+		// the value ends up in a web server configuration file as is: a
+		// newline or anything but an address/subnet in it would add
+		// arbitrary directives (or make Apache reject the whole file, taking
+		// the site down)
+		if (!IpHelper::isValidIpOrSubnet($IP))
+		{
+			if (!is_null($this->logger))
+			{
+				$this->logger->log("Refusing to write invalid IP address '".
+					addcslashes((string) $IP, "\0..\37\177")."' to .htaccess!", Log::ERROR);
+			}
+			return false;
+		}
+		return $this->locked(function () use ($IP)
+		{
+			return $this->addLine(self::BlockPrefix . $IP);
+		});
 	}
 
 	/**
@@ -124,7 +140,10 @@ public function denyIP($IP)
 	 */
 	public function undenyIP($IP)
 	{
-		return $this->removeLine(self::BlockPrefix . $IP);
+		return $this->locked(function () use ($IP)
+		{
+			return $this->removeLine(self::BlockPrefix . $IP);
+		});
 	}
 
 	/**
@@ -139,14 +158,26 @@ public function edit403Message($message)
 		{
 			return $this->remove403Message();
 		}
+		// a line break would start a new directive
+		if (preg_match('/[\x00-\x1f\x7f]/', $message))
+		{
+			if (!is_null($this->logger))
+			{
+				$this->logger->log("Refusing to write a 403 message containing control characters to .htaccess!", Log::ERROR);
+			}
+			return false;
+		}
 
-		$line = 'ErrorDocument 403 "' . $message . '"';
+		$line = 'ErrorDocument 403 "' . addcslashes($message, '"\\') . '"';
 
-		$otherLines = $this->getLines('ErrorDocument 403 ', true, true);
+		return $this->locked(function () use ($line)
+		{
+			$otherLines = $this->getLines('ErrorDocument 403 ', true, true);
 
-		$insertion = array_merge($this->getHeader(), array($line), $otherLines, $this->getFooter());
+			$insertion = array_merge($this->getHeader(), array($line), $otherLines, $this->getFooter());
 
-		return $this->insert($insertion);
+			return $this->insert($insertion);
+		});
 	}
 
 	/**
@@ -156,7 +187,47 @@ public function edit403Message($message)
 	 */
 	public function remove403Message()
 	{
-		return $this->removeLine('', 'ErrorDocument 403 ');
+		return $this->locked(function ()
+		{
+			return $this->removeLine('', 'ErrorDocument 403 ');
+		});
+	}
+
+	/**
+	 * Runs a read-modify-write cycle of the .htaccess file while holding an
+	 * exclusive lock, so that concurrent requests (several clients getting
+	 * blocked at once is exactly when this happens) don't overwrite each
+	 * other's changes: each of them would otherwise read the file, add its
+	 * line and write the result back, losing the lines the others added in
+	 * between. The lock is a file in the temporary directory, not the
+	 * .htaccess itself, which is replaced as a whole when written. If no lock
+	 * can be taken the change is done anyway, as before.
+	 */
+	private function locked(callable $change)
+	{
+		$lockFile = sys_get_temp_dir().'/bfstop-htaccess-'.md5($this->path).'.lock';
+		$handle = @fopen($lockFile, 'c');
+		if ($handle === false || !flock($handle, LOCK_EX))
+		{
+			if (!is_null($this->logger))
+			{
+				$this->logger->log("Could not lock '$lockFile', changing .htaccess without it", Log::WARNING);
+			}
+			if ($handle !== false)
+			{
+				fclose($handle);
+			}
+			return $change();
+		}
+		try
+		{
+			return $change();
+		}
+		finally
+		{
+			flock($handle, LOCK_UN);
+			fclose($handle);
+		}
 	}
 
 	/**
diff --git a/src/Helper/IpHelper.php b/src/Helper/IpHelper.php
index 9f649ef..61e1976 100644
--- a/src/Helper/IpHelper.php
+++ b/src/Helper/IpHelper.php
@@ -43,7 +43,7 @@ class IpHelper
 	public static function isInSubnet($ip, $subnet)
 	{
 		$parts = explode('/', $subnet);
-		if (count($parts) !== 2 || !preg_match('/^[0-9]{1,3}$/', $parts[1]))
+		if (count($parts) !== 2 || !preg_match('/^[0-9]{1,3}\z/', $parts[1]))
 		{
 			return false;
 		}
@@ -72,6 +72,64 @@ public static function isInSubnet($ip, $subnet)
 		return (ord($ipBin[$fullBytes]) & $mask) === (ord($subnetBin[$fullBytes]) & $mask);
 	}
 
+	/**
+	 * Whether $value is a single IP address or a subnet in CIDR notation
+	 * (prefix length a plain number within range for the address family) -
+	 * and nothing else: no whitespace, no further text. Used before anything
+	 * is written to a configuration file.
+	 */
+	public static function isValidIpOrSubnet($value)
+	{
+		$parts = explode('/', (string) $value);
+		if (count($parts) > 2 || filter_var($parts[0], FILTER_VALIDATE_IP) === false)
+		{
+			return false;
+		}
+		if (count($parts) === 1)
+		{
+			return true;
+		}
+		return preg_match('/^[0-9]{1,3}\z/', $parts[1]) === 1 &&
+			(int) $parts[1] <= (strpos($parts[0], ':') !== false ? 128 : 32);
+	}
+
+	private static function prefixMask($bits)
+	{
+		$mask = str_repeat("\xff", intdiv($bits, 8));
+		if ($bits % 8 > 0)
+		{
+			$mask .= chr((0xff << (8 - $bits % 8)) & 0xff);
+		}
+		return str_pad($mask, 16, "\x00");
+	}
+
+	/**
+	 * The key under which failed logins and blocks of a client are tracked.
+	 *
+	 * For IPv4 that is the address itself. An IPv6 client usually controls a
+	 * whole /64 (or more) and can switch to another address in it at will -
+	 * tracking single addresses would let it start over with every request -
+	 * so a global unicast IPv6 address is tracked as its network in CIDR
+	 * notation (e.g. "2001:db8:1:2::/64") if $prefixLength is between 32 and
+	 * 127. Left alone are IPv6 addresses that merely carry an IPv4 address or
+	 * a transition mechanism's prefix (IPv4-mapped, NAT64, 6to4, Teredo):
+	 * aggregating those would put unrelated clients, all over the world,
+	 * under one key.
+	 */
+	public static function trackedAddress($ip, $prefixLength)
+	{
+		$prefixLength = (int) $prefixLength;
+		$bin = @inet_pton((string) $ip);
+		if ($bin === false || strlen($bin) !== 16 || $prefixLength < 32 || $prefixLength > 127 ||
+			(ord($bin[0]) & 0xe0) !== 0x20 ||          // not 2000::/3 (global unicast)
+			substr($bin, 0, 2) === "\x20\x02" ||       // 6to4, 2002::/16
+			substr($bin, 0, 4) === "\x20\x01\x00\x00")  // Teredo, 2001::/32
+		{
+			return $ip;
+		}
+		return inet_ntop($bin & self::prefixMask($prefixLength)).'/'.$prefixLength;
+	}
+
 	/**
 	 * Splits the trusted proxy setting into its entries. Each entry is a
 	 * single IP address or a subnet in CIDR notation; entries may be
diff --git a/src/Helper/LoggerHelper.php b/src/Helper/LoggerHelper.php
index e54ef69..b5277cc 100644
--- a/src/Helper/LoggerHelper.php
+++ b/src/Helper/LoggerHelper.php
@@ -10,6 +10,7 @@
 
 defined('_JEXEC') or die;
 
+use Joomla\CMS\Factory;
 use Joomla\CMS\Log\Log;
 
 class LoggerHelper
@@ -17,6 +18,10 @@ class LoggerHelper
 	private $log_level;
 	public const LogCategory = 'bfstop';
 	public const Disabled = -1;
+	public const LogFile = 'plg_system_bfstop.log.php';
+	// the log is rotated once it exceeds this size, so it can't fill up the
+	// disk (a visitor can make the plugin log by failing logins)
+	public const MaxLogFileBytes = 5242880;
 
 	public function __construct($log_level)
 	{
@@ -24,8 +29,9 @@ public function __construct($log_level)
 		$priorities = Log::ALL;
 		if ($log_level > self::Disabled)
 		{
+			self::rotateIfTooBig();
 			Log::addLogger(array(
-				'text_file' => 'plg_system_bfstop.log.php',
+				'text_file' => self::LogFile,
 				'text_entry_format' =>
 					'{DATETIME} {PRIORITY} {MESSAGE}'
 			),
@@ -34,6 +40,29 @@ public function __construct($log_level)
 		}
 	}
 
+	/**
+	 * Moves the log file out of the way once it is too big, keeping one
+	 * previous generation. The old file keeps a .php extension (the file
+	 * names end in .log.php) as the web server must not hand out its contents.
+	 */
+	public static function rotateIfTooBig($maxBytes = self::MaxLogFileBytes)
+	{
+		try
+		{
+			$logPath = Factory::getApplication()->get('log_path');
+			$file = $logPath.'/'.self::LogFile;
+			clearstatcache(true, $file);
+			if ($logPath && is_file($file) && filesize($file) > $maxBytes)
+			{
+				@rename($file, $logPath.'/'.str_replace('.log.php', '.1.log.php', self::LogFile));
+			}
+		}
+		catch (\Throwable $e)
+		{
+			// never let housekeeping of the log get in the way of the request
+		}
+	}
+
 	public function isEnabled($priority = Log::ERROR)
 	{
 		return $priority <= $this->log_level;
diff --git a/tests/Integration/BlockedRequestTest.php b/tests/Integration/BlockedRequestTest.php
index 3f2f8ce..d1f96ec 100644
--- a/tests/Integration/BlockedRequestTest.php
+++ b/tests/Integration/BlockedRequestTest.php
@@ -7,6 +7,7 @@
 **/
 namespace Codeling\Bfstop\Tests\Integration;
 
+use Codeling\Plugin\System\Bfstop\Extension\Bfstop;
 use Codeling\Plugin\System\Bfstop\Helper\DatabaseHelper;
 use Joomla\CMS\Factory;
 
@@ -101,6 +102,33 @@ public function testBlockIsEnforcedOnlyAfterRouting()
 		$this->assertBlocked();
 	}
 
+	public function testBlockPageIsNeverCached()
+	{
+		foreach (array(true, false) as $useHttpError)
+		{
+			$headers = Bfstop::blockedResponseHeaders($useHttpError);
+			$this->assertContains('Cache-Control: no-store, no-cache, must-revalidate, private', $headers);
+			$this->assertContains('Pragma: no-cache', $headers);
+			$this->assertSame($useHttpError, in_array('HTTP/1.0 403 Forbidden', $headers, true));
+		}
+	}
+
+	public function testBlockPageIsAnErrorByDefault()
+	{
+		$this->configure();
+		$this->block();
+		$this->assertMatchesRegularExpression('/^STATUS: 403$/m', $this->request());
+	}
+
+	public function testErrorStatusCanBeSwitchedOff()
+	{
+		$this->configure(array('useHttpError' => 0));
+		$this->block();
+		$output = $this->request();
+		$this->assertStringContainsString(self::BlockedMessage, $output);
+		$this->assertDoesNotMatchRegularExpression('/^STATUS: 403$/m', $output);
+	}
+
 	public function testBlockedMessageCanShowIp()
 	{
 		$this->configure(array('blockedMsgShowIP' => 1));
diff --git a/tests/Integration/ComponentTest.php b/tests/Integration/ComponentTest.php
index ed40cd3..379a401 100644
--- a/tests/Integration/ComponentTest.php
+++ b/tests/Integration/ComponentTest.php
@@ -182,6 +182,51 @@ public function escape($string)
 		$this->assertStringContainsString('&lt;script&gt;alert(1)&lt;/script&gt;', $html);
 	}
 
+	public function testTokenUnblockForBlockedIpv6Network()
+	{
+		$blockId = $this->insert('#__bfstop_bannedip', array('ipaddress' => '2001:db8:1:2::/64', 'crdate' => self::minutesAgo(0), 'duration' => 60), 'id');
+		$this->insert('#__bfstop_unblock_token', array('token' => 'valid', 'block_id' => $blockId, 'crdate' => self::minutesAgo(1)));
+		$model = $this->model(TokenunblockModel::class);
+		$this->assertSame(TokenunblockModel::ResultWrongIp, $model->process('valid', true, '2001:db8:1:3::1', $this->logger));
+		$this->assertSame(TokenunblockModel::ResultWrongIp, $model->process('valid', true, '203.0.113.5', $this->logger));
+		$this->assertSame(TokenunblockModel::ResultUnblocked, $model->process('valid', true, '2001:db8:1:2:abcd::77', $this->logger));
+	}
+
+	private function formRuleResult($ruleFile, $class, $value, $blockMode = 'full')
+	{
+		require_once getenv('COM_BFSTOP_ROOT').'/admin/rules/'.$ruleFile;
+		$rule = new $class();
+		return $rule->test(new \SimpleXMLElement('<field name="x" />'), $value, null,
+			new \Joomla\Registry\Registry(array('params' => array('blockMode' => $blockMode))));
+	}
+
+	public function testHtaccessPathRule()
+	{
+		$test = fn ($value, $mode = 'full') => $this->formRuleResult('htaccesspath.php', 'JFormRuleHtaccesspath', $value, $mode);
+		$this->assertTrue($test(''));
+		$this->assertTrue($test(sys_get_temp_dir(), 'htaccess'));
+		$this->assertTrue($test('/does/not/exist', 'full'), 'only has to exist if .htaccess is used for blocking');
+		$this->assertInstanceOf(\UnexpectedValueException::class, $test('/does/not/exist', 'htaccess'));
+		foreach (array('phar:///tmp/x.phar', 'ftp://example.org/', "/tmp\n", "/tmp\0") as $path)
+		{
+			$this->assertInstanceOf(\UnexpectedValueException::class, $test($path, 'full'), $path);
+			$this->assertInstanceOf(\UnexpectedValueException::class, $test($path, 'htaccess'), $path);
+		}
+	}
+
+	public function testGeoDbPathRule()
+	{
+		$test = fn ($value) => $this->formRuleResult('geodbpath.php', 'JFormRuleGeodbpath', $value);
+		$this->assertTrue($test(''));
+		$this->assertTrue($test('/var/lib/GeoLite2-City.mmdb'));
+		$this->assertTrue($test('relative/path/GeoLite2-Country.MMDB'));
+		foreach (array('/var/lib/GeoLite2.txt', '/etc/passwd', 'phar:///tmp/x.phar/y.mmdb', 'file:///etc/x.mmdb',
+			"/x/y.mmdb\n", "/x/y.mmdb\0.txt", '/x/y.mmdb.php') as $path)
+		{
+			$this->assertInstanceOf(\UnexpectedValueException::class, $test($path), $path);
+		}
+	}
+
 	public function testWarnsAboutAdminUserCaseInsensitively()
 	{
 		// tests/ci/install-joomla.sh creates the super user as "Admin"
diff --git a/tests/Integration/DatabaseHelperTest.php b/tests/Integration/DatabaseHelperTest.php
index c2b9fc3..3d9359a 100644
--- a/tests/Integration/DatabaseHelperTest.php
+++ b/tests/Integration/DatabaseHelperTest.php
@@ -211,17 +211,43 @@ public function testPurgeOldEntries()
 		$this->assertSame('203.0.113.78', $this->queryValue('SELECT ipaddress FROM #__bfstop_dnscache'));
 	}
 
-	public function testSaveParams()
+	public function testSaveLastPurgeChangesOnlyThatValue()
 	{
 		$original = $this->getPluginParams();
 		try
 		{
-			$this->helper->saveParams(new Registry(array('marker' => 'saved-by-test')));
-			$this->assertStringContainsString('saved-by-test', $this->getPluginParams());
+			// what an administrator saved after the request started must survive
+			$this->setPluginParams(json_encode(array('blockNumber' => 7, 'lastPurge' => 1)));
+			$this->helper->saveLastPurge(1700000000);
+			$saved = json_decode($this->getPluginParams(), true);
+			$this->assertSame(array('blockNumber' => 7, 'lastPurge' => 1700000000), $saved);
 		}
 		finally
 		{
 			$this->setPluginParams($original);
 		}
 	}
+
+	public function testTrimUsernameStatsKeepsTheMostAttackedAndMostRecent()
+	{
+		$names = array(
+			// username => [attempts, minutes since last attempt]
+			'many-old'   => array(50, 5000),
+			'few-old'    => array(1, 5000),
+			'few-older'  => array(1, 9000),
+			'few-recent' => array(1, 10),
+			'some'       => array(5, 100),
+		);
+		foreach ($names as $name => $data)
+		{
+			$this->insert('#__bfstop_username_stats', array('username' => $name, 'attempts' => $data[0],
+				'first_attempt' => self::minutesAgo($data[1] + 1), 'last_attempt' => self::minutesAgo($data[1])));
+		}
+		$this->helper->trimUsernameStats(10);
+		$this->assertSame(5, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_username_stats'));
+
+		$this->helper->trimUsernameStats(3);
+		$this->db->setQuery('SELECT username FROM #__bfstop_username_stats ORDER BY username');
+		$this->assertSame(array('few-recent', 'many-old', 'some'), $this->db->loadColumn());
+	}
 }
diff --git a/tests/Integration/FailedLoginTest.php b/tests/Integration/FailedLoginTest.php
index 1b9d7d6..0e7b87b 100644
--- a/tests/Integration/FailedLoginTest.php
+++ b/tests/Integration/FailedLoginTest.php
@@ -150,4 +150,54 @@ public function testPlainModeStoresEveryUsername()
 		$this->failedLogin('someone-unknown');
 		$this->assertSame(array('someone-unknown'), $this->storedUsernames());
 	}
+
+	private function requestFrom($ip)
+	{
+		$command = escapeshellarg(PHP_BINARY).' '.escapeshellarg(__DIR__.'/fixtures/request.php').' '.escapeshellarg($ip).' 2>&1';
+		exec($command, $output, $exitCode);
+		$this->assertSame(0, $exitCode, implode("\n", $output));
+		return implode("\n", $output);
+	}
+
+	public function testIpv6ClientsAreTrackedAndBlockedByNetwork()
+	{
+		// switching to another address in its /64 must not reset an attacker
+		$this->configure(array('blockNumber' => 3, 'blockedMessage' => 'BFSTOP TEST: blocked'));
+		$this->failedLogin('Admin', '2001:db8:1:2::1');
+		$this->failedLogin('Admin', '2001:db8:1:2:aaaa::2');
+		$this->assertSame(0, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'));
+		$this->failedLogin('Admin', '2001:db8:1:2:bbbb::3');
+
+		$this->assertSame('2001:db8:1:2::/64', $this->queryValue('SELECT ipaddress FROM #__bfstop_bannedip'));
+		$this->assertSame(1, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'));
+		$this->assertStringContainsString('BFSTOP TEST: blocked', $this->requestFrom('2001:db8:1:2:cccc::4'));
+		$this->assertStringContainsString('NOT BLOCKED', $this->requestFrom('2001:db8:1:3::1'), 'a different /64');
+		$this->assertStringContainsString('NOT BLOCKED', $this->requestFrom('203.0.113.7'));
+	}
+
+	public function testBlockedNetworkIsNotBlockedAgain()
+	{
+		$this->configure(array('blockNumber' => 1));
+		$this->failedLogin('Admin', '2001:db8:1:2::1');
+		$this->failedLogin('Admin', '2001:db8:1:2::2'); // its network is blocked already
+		$this->assertSame(1, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'));
+	}
+
+	public function testIpv6PrefixCanBeSwitchedOff()
+	{
+		$this->configure(array('blockNumber' => 2, 'ipv6PrefixLength' => 128));
+		$this->failedLogin('Admin', '2001:db8:1:2::1');
+		$this->failedLogin('Admin', '2001:db8:1:2::2');
+		$this->assertSame(0, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'));
+		$this->failedLogin('Admin', '2001:db8:1:2::2');
+		$this->assertSame('2001:db8:1:2::2', $this->queryValue('SELECT ipaddress FROM #__bfstop_bannedip'));
+	}
+
+	public function testIpv4MappedAddressesAreNotLumpedTogether()
+	{
+		$this->configure(array('blockNumber' => 2));
+		$this->failedLogin('Admin', '::ffff:203.0.113.7');
+		$this->failedLogin('Admin', '::ffff:203.0.113.8');
+		$this->assertSame(0, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'));
+	}
 }
diff --git a/tests/Integration/GeoHelperTest.php b/tests/Integration/GeoHelperTest.php
index 1901075..d3d81e3 100644
--- a/tests/Integration/GeoHelperTest.php
+++ b/tests/Integration/GeoHelperTest.php
@@ -43,4 +43,13 @@ public function testCorruptDbReturnsNullWithWarning()
 			unlink($file);
 		}
 	}
+
+	public function testStreamWrapperPathsAreRefused()
+	{
+		foreach (array('phar:///tmp/x.phar/GeoLite2.mmdb', 'file:///etc/GeoLite2.mmdb', 'ftp://example.org/GeoLite2.mmdb') as $path)
+		{
+			$this->assertNull(GeoHelper::getCountryCode($this->logger, $path, '203.0.113.5'));
+		}
+		$this->assertTrue($this->logger->hasMessage(Log::WARNING, 'not a plain file name'));
+	}
 }
diff --git a/tests/Integration/HtaccessHelperTest.php b/tests/Integration/HtaccessHelperTest.php
index 17b10ef..3c7ae5e 100644
--- a/tests/Integration/HtaccessHelperTest.php
+++ b/tests/Integration/HtaccessHelperTest.php
@@ -10,6 +10,7 @@
 
 use Codeling\Plugin\System\Bfstop\Helper\HtaccessHelper;
 use Joomla\CMS\Log\Log;
+use PHPUnit\Framework\Attributes\DataProvider;
 
 class HtaccessHelperTest extends IntegrationTestCase
 {
@@ -135,6 +136,71 @@ public function test403Message()
 		$this->assertSame(array('203.0.113.5'), array_values($h->getDeniedIPs()));
 	}
 
+	public static function invalidAddressProvider()
+	{
+		return array(
+			'injected directive' => array("192.0.2.1\nSetHandler application/x-httpd-php"),
+			'exponent prefix'    => array('192.0.2.0/1e1'),
+			'prefix too long'    => array('192.0.2.0/33'),
+			'trailing newline'   => array("192.0.2.1\n"),
+			'host name'          => array('example.org'),
+			'empty'              => array(''),
+		);
+	}
+
+	#[DataProvider('invalidAddressProvider')]
+	public function testDenyRefusesAnythingButAnAddress($address)
+	{
+		$h = $this->helper();
+		$h->denyIP('192.0.2.7');
+		$before = $this->content();
+		$this->assertFalse($h->denyIP($address));
+		$this->assertSame($before, $this->content(), 'file must stay untouched');
+		$this->assertTrue($this->logger->hasMessage(Log::ERROR, 'Refusing to write'));
+		$this->logger->errors = array(); // expected
+	}
+
+	public function test403MessageIsSanitised()
+	{
+		$h = $this->helper();
+		$this->assertFalse($h->edit403Message("Go away\nSetHandler application/x-httpd-php"));
+		$this->assertFalse($h->edit403Message("Go away\r"));
+		$this->assertFileDoesNotExist($this->dir.'/.htaccess');
+		$this->logger->errors = array(); // expected
+		$this->assertNotFalse($h->edit403Message('Say "hi" \\ bye'));
+		$this->assertStringContainsString('ErrorDocument 403 "Say \"hi\" \\\\ bye"'."\n", $this->content());
+	}
+
+	public function testConcurrentChangesDontLoseEntries()
+	{
+		// each request which blocks an IP address reads the file, adds a line
+		// and writes it back; without a lock around that cycle, parallel
+		// requests overwrite each other's lines
+		$count = 24;
+		$processes = array();
+		for ($i = 1; $i <= $count; ++$i)
+		{
+			$command = escapeshellarg(PHP_BINARY).' '.escapeshellarg(__DIR__.'/fixtures/deny_ip.php').' '.
+				escapeshellarg($this->dir).' '.escapeshellarg('198.51.100.'.$i);
+			$processes[$i] = proc_open($command, array(1 => array('pipe', 'w'), 2 => array('pipe', 'w')), $pipes[$i]);
+		}
+		foreach ($processes as $i => $process)
+		{
+			stream_get_contents($pipes[$i][1]);
+			stream_get_contents($pipes[$i][2]);
+			proc_close($process);
+		}
+		$denied = $this->helper()->getDeniedIPs();
+		sort($denied);
+		$expected = array();
+		for ($i = 1; $i <= $count; ++$i)
+		{
+			$expected[] = '198.51.100.'.$i;
+		}
+		sort($expected);
+		$this->assertSame($expected, $denied);
+	}
+
 	public function testCorruptMarkersAreNotOverwritten()
 	{
 		$corrupt = "# BEGIN BFStop Blocks\nRequire not ip 192.0.2.1\n";
diff --git a/tests/Integration/IpValidateHelperTest.php b/tests/Integration/IpValidateHelperTest.php
index 9b6ae64..3cde0d5 100644
--- a/tests/Integration/IpValidateHelperTest.php
+++ b/tests/Integration/IpValidateHelperTest.php
@@ -96,6 +96,12 @@ public static function invalidRangeProvider()
 			'negative subnet'       => array('203.0.113.0/-1', 'COM_BFSTOP_IP_INVALID_SUBNET', '-1'),
 			'non-numeric subnet'    => array('203.0.113.0/abc', 'COM_BFSTOP_IP_INVALID_SUBNET', 'abc'),
 			'empty subnet'          => array('203.0.113.0/', 'COM_BFSTOP_IP_INVALID_SUBNET', ''),
+			// is_numeric() accepts these; they must not get as far as a config file
+			'exponent subnet'       => array('203.0.113.0/1e1', 'COM_BFSTOP_IP_INVALID_SUBNET', '1e1'),
+			'hex subnet'            => array('203.0.113.0/0x8', 'COM_BFSTOP_IP_INVALID_SUBNET', '0x8'),
+			'fractional subnet'     => array('203.0.113.0/8.5', 'COM_BFSTOP_IP_INVALID_SUBNET', '8.5'),
+			'padded subnet'         => array('203.0.113.0/ 8', 'COM_BFSTOP_IP_INVALID_SUBNET', ' 8'),
+			'subnet with newline'   => array("203.0.113.0/8\n", 'COM_BFSTOP_IP_INVALID_SUBNET', "8\n"),
 			'not an address'        => array('foo.bar', 'COM_BFSTOP_IP_INVALID_ADDRESS', 'foo.bar'),
 			'octet out of range'    => array('203.0.113.256', 'COM_BFSTOP_IP_INVALID_ADDRESS', '203.0.113.256'),
 			'empty'                 => array('', 'COM_BFSTOP_IP_INVALID_ADDRESS', ''),
diff --git a/tests/Integration/LoggerHelperTest.php b/tests/Integration/LoggerHelperTest.php
new file mode 100644
index 0000000..8cd765f
--- /dev/null
+++ b/tests/Integration/LoggerHelperTest.php
@@ -0,0 +1,76 @@
+<?php
+/*
+ * @package BFStop Plugin (bfstop) for Joomla!
+ * @author Bernhard Froehler
+ * @copyright (C) Bernhard Froehler
+ * @license GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
+**/
+namespace Codeling\Bfstop\Tests\Integration;
+
+use Codeling\Plugin\System\Bfstop\Helper\LoggerHelper;
+use Joomla\CMS\Factory;
+
+class LoggerHelperTest extends IntegrationTestCase
+{
+	private $file;
+	private $rotated;
+	private $backup;
+
+	protected function setUp(): void
+	{
+		parent::setUp();
+		$logPath = Factory::getApplication()->get('log_path');
+		$this->file = $logPath.'/'.LoggerHelper::LogFile;
+		$this->rotated = $logPath.'/plg_system_bfstop.1.log.php';
+		$this->backup = array();
+		foreach (array($this->file, $this->rotated) as $file)
+		{
+			$this->backup[$file] = is_file($file) ? file_get_contents($file) : null;
+			@unlink($file);
+		}
+	}
+
+	protected function tearDown(): void
+	{
+		foreach ($this->backup as $file => $content)
+		{
+			@unlink($file);
+			if ($content !== null)
+			{
+				file_put_contents($file, $content);
+			}
+		}
+	}
+
+	public function testBigLogFileIsRotated()
+	{
+		file_put_contents($this->file, str_repeat('x', LoggerHelper::MaxLogFileBytes + 1));
+		new LoggerHelper(8);
+		$this->assertFileDoesNotExist($this->file);
+		$this->assertSame(LoggerHelper::MaxLogFileBytes + 1, filesize($this->rotated));
+		$this->assertStringEndsWith('.php', $this->rotated, 'must stay a PHP file, not served as text');
+	}
+
+	public function testSmallLogFileIsKept()
+	{
+		file_put_contents($this->file, 'small');
+		new LoggerHelper(8);
+		$this->assertSame('small', file_get_contents($this->file));
+		$this->assertFileDoesNotExist($this->rotated);
+	}
+
+	public function testOnlyOnePreviousGenerationIsKept()
+	{
+		file_put_contents($this->rotated, 'older');
+		file_put_contents($this->file, str_repeat('y', 100));
+		LoggerHelper::rotateIfTooBig(50);
+		$this->assertSame(str_repeat('y', 100), file_get_contents($this->rotated));
+	}
+
+	public function testDisabledLoggingDoesntTouchTheFile()
+	{
+		file_put_contents($this->file, str_repeat('x', LoggerHelper::MaxLogFileBytes + 1));
+		new LoggerHelper(LoggerHelper::Disabled);
+		$this->assertFileExists($this->file);
+	}
+}
diff --git a/tests/Integration/fixtures/deny_ip.php b/tests/Integration/fixtures/deny_ip.php
new file mode 100644
index 0000000..8d5023a
--- /dev/null
+++ b/tests/Integration/fixtures/deny_ip.php
@@ -0,0 +1,24 @@
+<?php
+/*
+ * @package BFStop Plugin (bfstop) for Joomla!
+ * @author Bernhard Froehler
+ * @copyright (C) Bernhard Froehler
+ * @license GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
+**/
+// Adds the IP address given as second argument to the .htaccess file in the
+// directory given as first argument, like the plugin does when it blocks an
+// address. Needs only the plugin's own classes, not Joomla.
+// Used by HtaccessHelperTest.
+
+define('_JEXEC', 1);
+spl_autoload_register(function ($class)
+{
+	$prefix = 'Codeling\\Plugin\\System\\Bfstop\\';
+	if (strncmp($class, $prefix, strlen($prefix)) === 0)
+	{
+		require dirname(__DIR__, 3).'/src/'.str_replace('\\', '/', substr($class, strlen($prefix))).'.php';
+	}
+});
+
+$result = (new Codeling\Plugin\System\Bfstop\Helper\HtaccessHelper($argv[1], null))->denyIP($argv[2]);
+exit($result === false ? 1 : 0);
diff --git a/tests/Integration/fixtures/request.php b/tests/Integration/fixtures/request.php
index 4581166..2601aad 100644
--- a/tests/Integration/fixtures/request.php
+++ b/tests/Integration/fixtures/request.php
@@ -25,6 +25,12 @@
 {
 	$app->input->set($name, $value);
 }
+// the plugin ends a blocked request with exit(), so report the response
+// status it set when the script ends
+register_shutdown_function(function ()
+{
+	echo "\nSTATUS: ".http_response_code()."\n";
+});
 PluginHelper::importPlugin('system', 'bfstop', true, $app->getDispatcher());
 $app->getDispatcher()->dispatch('onAfterInitialise', new Event('onAfterInitialise', array()));
 // blocking is enforced after routing (SEF URLs only yield option/view then)
diff --git a/tests/Unit/IpHelperTest.php b/tests/Unit/IpHelperTest.php
index 596a333..6c2d5e5 100644
--- a/tests/Unit/IpHelperTest.php
+++ b/tests/Unit/IpHelperTest.php
@@ -116,4 +116,79 @@ public function testClientAddressFromHeader($header, $value, $proxies, $expected
 	{
 		$this->assertSame($expected, IpHelper::clientAddressFromHeader($header, $value, $proxies));
 	}
+
+	public static function ipOrSubnetProvider()
+	{
+		return array(
+			'IPv4'                    => array('192.0.2.1', true),
+			'IPv4 subnet'             => array('192.0.2.0/24', true),
+			'IPv4 /32'                => array('192.0.2.1/32', true),
+			'IPv4 /0'                 => array('0.0.0.0/0', true),
+			'IPv6'                    => array('2001:db8::1', true),
+			'IPv6 subnet'             => array('2001:db8::/32', true),
+			'IPv6 /128'               => array('2001:db8::1/128', true),
+			'prefix too long (IPv4)'  => array('192.0.2.0/33', false),
+			'prefix too long (IPv6)'  => array('2001:db8::/129', false),
+			'exponent as prefix'      => array('192.0.2.0/1e1', false),
+			'fraction as prefix'      => array('192.0.2.0/8.0', false),
+			'negative prefix'         => array('192.0.2.0/-1', false),
+			'signed prefix'           => array('192.0.2.0/+8', false),
+			'empty prefix'            => array('192.0.2.0/', false),
+			'hex prefix'              => array('192.0.2.0/0x8', false),
+			'trailing newline'        => array("192.0.2.1\n", false),
+			'trailing newline prefix' => array("192.0.2.0/8\n", false),
+			'injected directive'      => array("192.0.2.1\nSetHandler application/x-httpd-php", false),
+			'leading space'           => array(' 192.0.2.1', false),
+			'two prefixes'            => array('192.0.2.0/8/8', false),
+			'host name'               => array('example.org', false),
+			'empty'                   => array('', false),
+		);
+	}
+
+	#[DataProvider('ipOrSubnetProvider')]
+	public function testIsValidIpOrSubnet($value, $expected)
+	{
+		$this->assertSame($expected, IpHelper::isValidIpOrSubnet($value));
+	}
+
+	public static function trackedAddressProvider()
+	{
+		return array(
+			'IPv4 stays'                 => array('192.0.2.7', 64, '192.0.2.7'),
+			'IPv6 to its /64'            => array('2001:db8:1:2:aaaa:bbbb:cccc:dddd', 64, '2001:db8:1:2::/64'),
+			'same /64, other address'    => array('2001:db8:1:2::1', 64, '2001:db8:1:2::/64'),
+			'other /64'                  => array('2001:db8:1:3::1', 64, '2001:db8:1:3::/64'),
+			'/48'                        => array('2001:db8:1:2::1', 48, '2001:db8:1::/48'),
+			'/56 not on a byte border'   => array('2001:db8:1:ff7f::1', 56, '2001:db8:1:ff00::/56'),
+			'/60 not on a byte border'   => array('2001:db8:1:20ff::1', 60, '2001:db8:1:20f0::/60'),
+			'upper case input'           => array('2001:DB8:1:2::ABCD', 64, '2001:db8:1:2::/64'),
+			'128 means per address'      => array('2001:db8:1:2::1', 128, '2001:db8:1:2::1'),
+			'0 means per address'        => array('2001:db8:1:2::1', 0, '2001:db8:1:2::1'),
+			'absurdly short prefix'      => array('2001:db8:1:2::1', 16, '2001:db8:1:2::1'),
+			'IPv4-mapped stays'          => array('::ffff:192.0.2.7', 64, '::ffff:192.0.2.7'),
+			'NAT64 stays'                => array('64:ff9b::192.0.2.7', 64, '64:ff9b::192.0.2.7'),
+			'6to4 stays'                 => array('2002:c000:207::1', 64, '2002:c000:207::1'),
+			'Teredo stays'               => array('2001:0:4136:e378:8000:63bf:3fff:fdd2', 64, '2001:0:4136:e378:8000:63bf:3fff:fdd2'),
+			'unique local stays'         => array('fd00::1', 64, 'fd00::1'),
+			'link local stays'           => array('fe80::1', 64, 'fe80::1'),
+			'loopback stays'             => array('::1', 64, '::1'),
+			'garbage stays'              => array('not-an-ip', 64, 'not-an-ip'),
+		);
+	}
+
+	#[DataProvider('trackedAddressProvider')]
+	public function testTrackedAddress($ip, $prefix, $expected)
+	{
+		$this->assertSame($expected, IpHelper::trackedAddress($ip, $prefix));
+	}
+
+	public function testTrackedNetworkContainsTheAddress()
+	{
+		// what gets stored as the block has to match the client afterwards
+		$tracked = IpHelper::trackedAddress('2001:db8:1:2:aaaa:bbbb:cccc:dddd', 64);
+		$this->assertTrue(IpHelper::isInSubnet('2001:db8:1:2:aaaa:bbbb:cccc:dddd', $tracked));
+		$this->assertTrue(IpHelper::isInSubnet('2001:db8:1:2::99', $tracked));
+		$this->assertFalse(IpHelper::isInSubnet('2001:db8:1:3::99', $tracked));
+		$this->assertTrue(IpHelper::isValidIpOrSubnet($tracked));
+	}
 }

From b94df60616e5c1960f34290401d118e86f889f6b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 5 Oct 2026 21:20:43 +0000
Subject: [PATCH 04/10] Explain what the "Use HTTP Error" setting is for

The block page is now never cached whatever this is set to, so the setting
only decides the status code (403 or 200). Say that 403 is the right choice
unless the web server, CDN or firewall replaces 403 pages with its own error
page (so blocked users would never see the block message).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 language/de-DE/de-DE.plg_system_bfstop.sys.ini | 2 +-
 language/en-GB/en-GB.plg_system_bfstop.sys.ini | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/language/de-DE/de-DE.plg_system_bfstop.sys.ini b/language/de-DE/de-DE.plg_system_bfstop.sys.ini
index 2f11ec7..46c7d48 100644
--- a/language/de-DE/de-DE.plg_system_bfstop.sys.ini
+++ b/language/de-DE/de-DE.plg_system_bfstop.sys.ini
@@ -29,7 +29,7 @@ PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_DESC="Schaltet die Benachrichtigung
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_LABEL="Benutzer-Block-Nachricht"
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="Wenn eingeschaltet, wird an die in der Datenbank hinterlegte Email-Adresse eine Nachricht hinterlegt, wenn eine IP-Adresse gesperrt wird (sofern der Benutzername, mit dem das Login versucht wurde, ein existierender war)"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_LABEL="Verwende HTTP-Fehler"
-PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="Wenn aktiviert, wird der HTTP Statuscode 403 (Forbidden) gesendet wenn die IP-Addresse eines Benutzers gesperrt ist."
+PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="Wenn aktiviert (empfohlen), beantwortet bfstop Anfragen einer gesperrten IP-Adresse mit dem HTTP-Statuscode 403 (Forbidden). Deaktiviere dies nur, wenn dein Webserver, CDN oder deine Firewall 403-Seiten durch eine eigene Fehlerseite ersetzt und gesperrte Benutzer die Sperrmeldung deshalb nie zu sehen bekommen: Sie wird dann mit dem Statuscode 200 gesendet. In beiden Fällen wird die Seite nie zwischengespeichert."
 PLG_SYSTEM_BFSTOP_ENABLED="aktiviert"
 PLG_SYSTEM_BFSTOP_DISABLED="deaktiviert"
 PLG_SYSTEM_BFSTOP_NOTIFY_UNLIMITED="unbegrenzt"
diff --git a/language/en-GB/en-GB.plg_system_bfstop.sys.ini b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
index b769b4f..3a57575 100644
--- a/language/en-GB/en-GB.plg_system_bfstop.sys.ini
+++ b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
@@ -31,7 +31,7 @@ PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_DESC="Enables or disables notificati
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_LABEL="User Block Message"
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="When turned on, in case of a blocked IP address, a notification will be sent to the user which tried to log in (only of course in case it is an existing username)."
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_LABEL="Use HTTP Error"
-PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="If enabled, bfstop will send a status code 403 (Forbidden) if the users' IP address is blocked"
+PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="If enabled (recommended), bfstop answers requests from a blocked IP address with the status code 403 (Forbidden). Switch this off only if your web server, CDN or firewall replaces 403 pages with its own error page, so that blocked users never get to see the block message: it is then sent with status 200 instead. Either way, the page is never cached."
 PLG_SYSTEM_BFSTOP_ENABLED="enabled"
 PLG_SYSTEM_BFSTOP_DISABLED="disabled"
 PLG_SYSTEM_BFSTOP_NOTIFY_UNLIMITED="unlimited"

From 271e5680ab2498b8da41f960143bc47720ef22b9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 5 Oct 2026 21:25:50 +0000
Subject: [PATCH 05/10] Don't send the unblock link if other accounts were
 attacked from the IP

The unblock email goes to the owner of the account of the last failed login.
If the failed logins from the blocked IP which led to the block also went
against other existing accounts, an attacker with an account of their own
could end each series of guesses at those with an attempt at their own,
receive the link and continue. The link is now only sent if all those
attempts were for that account or for names which don't exist (typos).
Logins by email address count as attempts at the account too.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 CHANGELOG                                     |  7 ++
 .../de-DE/de-DE.plg_system_bfstop.sys.ini     |  2 +-
 .../en-GB/en-GB.plg_system_bfstop.sys.ini     |  2 +-
 src/Extension/Bfstop.php                      | 24 ++++-
 src/Helper/DatabaseHelper.php                 | 46 +++++++++-
 tests/Integration/FailedLoginTest.php         | 92 +++++++++++++++++++
 6 files changed, 165 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index 256ed98..4d5894f 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -75,6 +75,13 @@
     confirmation (a POST request) and only works from the IP address which
     was blocked, so mail security scanners or link previews which open
     every link in a message can't unblock an attacker (see com_bfstop)
+  - Security: the "User Block Message" with the unblock link is no longer
+    sent if the failed logins from the blocked IP address which led to the
+    block also went against other existing accounts. The link goes to the
+    owner of the account of the last attempt, so an attacker with an account
+    of their own could otherwise end every series of guesses at other
+    accounts with an attempt at their own, get the link and continue.
+    Attempts against names which don't exist (e.g. typos) don't count
   - Security: IPv6 clients are now tracked per network (default: /64, see
     the new "IPv6 Tracking Granularity" setting) instead of per address:
     failed logins are counted and blocks apply to the whole network, so an
diff --git a/language/de-DE/de-DE.plg_system_bfstop.sys.ini b/language/de-DE/de-DE.plg_system_bfstop.sys.ini
index 46c7d48..a13f0c5 100644
--- a/language/de-DE/de-DE.plg_system_bfstop.sys.ini
+++ b/language/de-DE/de-DE.plg_system_bfstop.sys.ini
@@ -27,7 +27,7 @@ PLG_SYSTEM_BFSTOP_BLOCK_DURATION_DESC="Bestimmt wie lange die IP-Sperre aufrecht
 PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_LABEL="Übrige Versuche"
 PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_DESC="Schaltet die Benachrichtigung über verbleibende Versuche ein; wenn aktiviert, wird im Login-Formular nach einem fehlgeschlagenen Login-Versuch eine Nachricht mit den verbleibenden Login-Versuchen angezeigt. Diese Einstellung wird nur dann berücksichtigt, wenn Sperren eingeschaltet ist (wenn es nicht eingeschaltet ist, gibt es ja auch keine 'verbleibenden' Versuche)"
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_LABEL="Benutzer-Block-Nachricht"
-PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="Wenn eingeschaltet, wird an die in der Datenbank hinterlegte Email-Adresse eine Nachricht hinterlegt, wenn eine IP-Adresse gesperrt wird (sofern der Benutzername, mit dem das Login versucht wurde, ein existierender war)"
+PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="Wenn eingeschaltet, wird an die in der Datenbank hinterlegte Email-Adresse eine Nachricht hinterlegt, wenn eine IP-Adresse gesperrt wird (sofern der Benutzername, mit dem das Login versucht wurde, ein existierender war und die fehlgeschlagenen Logins von dieser IP-Adresse, die zur Sperre geführt haben, nicht auch gegen andere existierende Konten gerichtet waren: Die Nachricht enthält einen Link, der die Adresse entsperrt, und darf deshalb nicht an den Inhaber eines Kontos gehen, wenn von dort aus Konten anderer angegriffen wurden)"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_LABEL="Verwende HTTP-Fehler"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="Wenn aktiviert (empfohlen), beantwortet bfstop Anfragen einer gesperrten IP-Adresse mit dem HTTP-Statuscode 403 (Forbidden). Deaktiviere dies nur, wenn dein Webserver, CDN oder deine Firewall 403-Seiten durch eine eigene Fehlerseite ersetzt und gesperrte Benutzer die Sperrmeldung deshalb nie zu sehen bekommen: Sie wird dann mit dem Statuscode 200 gesendet. In beiden Fällen wird die Seite nie zwischengespeichert."
 PLG_SYSTEM_BFSTOP_ENABLED="aktiviert"
diff --git a/language/en-GB/en-GB.plg_system_bfstop.sys.ini b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
index 3a57575..fef2ab6 100644
--- a/language/en-GB/en-GB.plg_system_bfstop.sys.ini
+++ b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
@@ -29,7 +29,7 @@ PLG_SYSTEM_BFSTOP_BLOCK_DURATION_DESC="Determines how long an IP address is bloc
 PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_LABEL="Remaining attempts"
 PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_DESC="Enables or disables notifications about remaining attempts; if enabled, the user will, after each failed login attempt, see a message in the login form about how many login attempts still are available before the IP address will be blocked. This setting is only active if blocking is enabled (if blocking is disabled, 'remaining' entries wouldn't make sense)."
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_LABEL="User Block Message"
-PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="When turned on, in case of a blocked IP address, a notification will be sent to the user which tried to log in (only of course in case it is an existing username)."
+PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="When turned on, in case of a blocked IP address, a notification will be sent to the user which tried to log in (only of course in case it is an existing username, and only if the failed logins from that IP address which led to the block were not also against other existing accounts: the message contains a link which unblocks the address, so it must not go to the owner of an account if somebody else's accounts were being attacked from there)."
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_LABEL="Use HTTP Error"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="If enabled (recommended), bfstop answers requests from a blocked IP address with the status code 403 (Forbidden). Switch this off only if your web server, CDN or firewall replaces 403 pages with its own error page, so that blocked users never get to see the block message: it is then sent with status 200 instead. Either way, the page is never cached."
 PLG_SYSTEM_BFSTOP_ENABLED="enabled"
diff --git a/src/Extension/Bfstop.php b/src/Extension/Bfstop.php
index 8c48528..b59e98d 100644
--- a/src/Extension/Bfstop.php
+++ b/src/Extension/Bfstop.php
@@ -144,6 +144,12 @@ private function block($logEntry, $duration)
 			$this->logger->log('htaccessPath empty, setting it to '.JPATH_ROOT, Log::INFO);
 			$htaccessPath = JPATH_ROOT;
 		}
+		// has to be found out before blocking, which marks these failed logins
+		// as handled
+		$targetedOtherAccounts = $this->getBoolParam('notifyBlockedUser', false) &&
+			$this->mydb->hasFailedLoginsForOtherAccounts(
+				$this->getRealDurationFromDBDuration($this->getIntParam('checkInterval', NotifierHelper::$ONE_DAY)),
+				$logEntry->ipaddress, $logEntry->username, $logEntry->logtime);
 		$id = $this->mydb->blockIP($logEntry, $duration, $usehtaccess, $htaccessPath);
 
 		$this->logger->log('Inserted IP address '.$logEntry->ipaddress.
@@ -155,7 +161,21 @@ private function block($logEntry, $duration)
 		if ($this->getBoolParam('notifyBlockedUser', false))
 		{
 			$userEmail = $this->mydb->getUserEmailByName($logEntry->username);
-			if ($userEmail != null)
+			if ($userEmail != null && $targetedOtherAccounts)
+			{
+				// The link unblocks this IP address, and it goes to the owner
+				// of the account of the last failed login. If the attempts
+				// which got the address blocked also went against other
+				// accounts, whoever caused that could just as well own this
+				// account - and would get to continue with the other
+				// accounts by following the link.
+				$this->logger->log("Existing user '".
+					$logEntry->username."' was blocked, but the failed ".
+					"logins from this address also targeted other accounts - ".
+					"not sending unblock instructions",
+					Log::INFO);
+			}
+			elseif ($userEmail != null)
 			{
 				$this->logger->log("Existing user '".
 					$logEntry->username.
@@ -378,7 +398,7 @@ private function usernameForStorage($username)
 	{
 		$mode = $this->getStringParam('unknownUsernameMode', UsernameHelper::ModeHash);
 		$isReadable = ($mode !== UsernameHelper::ModePlain) &&
-			($this->mydb->userExists($username) ||
+			($this->mydb->accountExists($username) ||
 				RiskHelper::isCommonUsername($this->params, $username));
 		return UsernameHelper::forStorage($username, $mode, $isReadable,
 			$this->getApplication()->get('secret', ''));
diff --git a/src/Helper/DatabaseHelper.php b/src/Helper/DatabaseHelper.php
index abbb9b4..68d1f75 100644
--- a/src/Helper/DatabaseHelper.php
+++ b/src/Helper/DatabaseHelper.php
@@ -409,15 +409,19 @@ private function getUserEmailWhere($where)
 		}
 	}
 
-	public function userExists($username)
+	/**
+	 * Whether $login is the username or the email address of an existing
+	 * account (Joomla! can be set up to accept either at the login).
+	 */
+	public function accountExists($login)
 	{
 		try
 		{
 			// LOWER: Joomla treats usernames case-insensitively on login
 			// (MySQL's default collations do, PostgreSQL's don't)
-			$sql = "SELECT COUNT(*) FROM #__users WHERE LOWER(username) = LOWER(".
-				$this->db->quote($username).")";
-			$this->db->setQuery($sql);
+			$quoted = "LOWER(".$this->db->quote($login).")";
+			$this->db->setQuery("SELECT COUNT(*) FROM #__users WHERE LOWER(username) = ".$quoted.
+				" OR LOWER(email) = ".$quoted);
 			return ((int) $this->db->loadResult()) > 0;
 		}
 		catch (\Exception $e)
@@ -427,6 +431,40 @@ public function userExists($username)
 		}
 	}
 
+	/**
+	 * Whether the failed logins which count towards blocking $ipaddress (those
+	 * within $interval minutes before $logtime that haven't been handled yet)
+	 * include attempts against an existing account other than $username.
+	 * Attempts against usernames which don't exist don't count: they can't
+	 * get an attacker anywhere. If that can't be determined, it is assumed
+	 * that there are.
+	 */
+	public function hasFailedLoginsForOtherAccounts($interval, $ipaddress, $username, $logtime)
+	{
+		try
+		{
+			$this->db->setQuery("SELECT DISTINCT username FROM #__bfstop_failedlogin".
+				" WHERE ipaddress = ".$this->db->quote($ipaddress).
+				" AND handled = 0 AND logtime BETWEEN ".
+				$this->db->quote(self::minutesBefore($logtime, $interval)).
+				" AND ".$this->db->quote($logtime));
+			foreach ($this->db->loadColumn() as $attempted)
+			{
+				if (mb_strtolower($attempted) !== mb_strtolower($username) &&
+					$this->accountExists($attempted))
+				{
+					return true;
+				}
+			}
+			return false;
+		}
+		catch (\Exception $e)
+		{
+			$this->logger->log("Database exception occured: ".$e->getMessage(), Log::ERROR);
+			return true;
+		}
+	}
+
 	public function getUserEmailByID($uid)
 	{
 		return $this->getUserEmailWhere("id=".((int)$uid));
diff --git a/tests/Integration/FailedLoginTest.php b/tests/Integration/FailedLoginTest.php
index 0e7b87b..b5a3465 100644
--- a/tests/Integration/FailedLoginTest.php
+++ b/tests/Integration/FailedLoginTest.php
@@ -19,6 +19,7 @@ class FailedLoginTest extends IntegrationTestCase
 	private const Ip = '203.0.113.51';
 
 	private static $originalParams;
+	private $createdUsers = array();
 
 	public static function setUpBeforeClass(): void
 	{
@@ -39,6 +40,23 @@ public static function tearDownAfterClass(): void
 		}
 	}
 
+	protected function tearDown(): void
+	{
+		foreach ($this->createdUsers as $id)
+		{
+			$this->db->setQuery('DELETE FROM #__users WHERE id='.(int) $id);
+			$this->db->execute();
+		}
+	}
+
+	private function createUser($username)
+	{
+		$id = $this->insert('#__users', array('name' => $username, 'username' => $username,
+			'email' => $username.'@example.org', 'password' => '', 'registerDate' => self::minutesAgo(0),
+			'params' => '{}'), 'id');
+		$this->createdUsers[] = $id;
+	}
+
 	private function configure(array $params = array())
 	{
 		$this->setPluginParams(json_encode($params + array(
@@ -200,4 +218,78 @@ public function testIpv4MappedAddressesAreNotLumpedTogether()
 		$this->failedLogin('Admin', '::ffff:203.0.113.8');
 		$this->assertSame(0, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'));
 	}
+
+	// The unblock token is created when the email with the link is prepared,
+	// so whether a token exists tells whether the link would be sent.
+	private function unblockLinkIssued()
+	{
+		return ((int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_unblock_token')) === 1;
+	}
+
+	private function blockedAfter(array $usernames)
+	{
+		$this->configure(array('blockNumber' => count($usernames), 'notifyBlockedUser' => 1));
+		foreach ($usernames as $username)
+		{
+			$this->failedLogin($username);
+		}
+		$this->assertSame(1, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'), 'blocked');
+	}
+
+	public function testUnblockLinkIsIssuedIfOnlyThatAccountWasTargeted()
+	{
+		$this->blockedAfter(array('Admin', 'Admin', 'Admin'));
+		$this->assertTrue($this->unblockLinkIssued());
+	}
+
+	public function testNoUnblockLinkIfAnotherAccountWasTargeted()
+	{
+		// the link goes to whoever owns the account of the last attempt: an
+		// attacker who owns one account mustn't get unblocked after going
+		// after other accounts from the same address
+		$this->createUser('victim');
+		$this->blockedAfter(array('victim', 'victim', 'Admin'));
+		$this->assertFalse($this->unblockLinkIssued());
+	}
+
+	public function testNoUnblockLinkIfAnotherAccountWasTargetedByEmailAddress()
+	{
+		$this->createUser('victim');
+		$this->blockedAfter(array('victim@example.org', 'victim@example.org', 'Admin'));
+		$this->assertFalse($this->unblockLinkIssued());
+	}
+
+	public function testMistypedUsernamesDontPreventTheUnblockLink()
+	{
+		// attempts against names which aren't an account harm nobody
+		$this->blockedAfter(array('adm1n', 'Admn', 'Admin'));
+		$this->assertTrue($this->unblockLinkIssued());
+	}
+
+	public function testMistypedUsernamesInPlainModeDontPreventTheUnblockLink()
+	{
+		$this->configure(array('blockNumber' => 3, 'notifyBlockedUser' => 1, 'unknownUsernameMode' => 'plain'));
+		foreach (array('nobody', 'nobody-else', 'Admin') as $username)
+		{
+			$this->failedLogin($username);
+		}
+		$this->assertTrue($this->unblockLinkIssued());
+	}
+
+	public function testOtherSpellingOfTheSameAccountIsTheSameAccount()
+	{
+		$this->blockedAfter(array('admin', 'ADMIN', 'Admin'));
+		$this->assertTrue($this->unblockLinkIssued());
+	}
+
+	public function testOnlyAttemptsOfTheSameAddressCount()
+	{
+		$this->createUser('victim');
+		$this->configure(array('blockNumber' => 2, 'notifyBlockedUser' => 1));
+		$this->failedLogin('victim', '203.0.113.99'); // somebody else
+		$this->failedLogin('Admin');
+		$this->failedLogin('Admin');
+		$this->assertSame(self::Ip, $this->queryValue('SELECT ipaddress FROM #__bfstop_bannedip'));
+		$this->assertTrue($this->unblockLinkIssued());
+	}
 }

From 37d4835679466c0e4e51b268d5acbec0b4429bf5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 6 Oct 2026 15:00:06 +0000
Subject: [PATCH 06/10] Limit the unblock emails a user can be made to receive

Anybody can make the plugin send an unblock email to a user, by failing to
log in with that username from an address until it is blocked. The
notifyBlockedUser setting now has three values:

- 0: off.
- 1 (what "enabled" now means): only if the user has logged in successfully
  from the blocked IP address before (for IPv6: from its network), which an
  attacker's address never has.
- 2 (the former "enabled"): for any address, but a user gets at most one
  unblock link at a time which can still be used (not expired, not used up).

The username an unblock link was sent to is stored with its token
(unblock_token.username). 2.0.0 is not released yet, so the column is part of
the 2.0.0 install and update scripts.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 CHANGELOG                                     |  12 ++
 .../de-DE/de-DE.plg_system_bfstop.sys.ini     |   4 +-
 .../en-GB/en-GB.plg_system_bfstop.sys.ini     |   4 +-
 sql/install.mysql.utf8.sql                    |   2 +
 sql/install.postgresql.utf8.sql               |   2 +
 sql/updates/2.0.0.sql                         |   3 +
 src/Extension/Bfstop.php                      |  43 +++++-
 src/Helper/DatabaseHelper.php                 |  57 +++++++-
 tests/Integration/DatabaseHelperTest.php      |   8 ++
 tests/Integration/FailedLoginTest.php         | 126 +++++++++++++++++-
 10 files changed, 252 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index 4d5894f..f624bf9 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -82,6 +82,18 @@
     of their own could otherwise end every series of guesses at other
     accounts with an attempt at their own, get the link and continue.
     Attempts against names which don't exist (e.g. typos) don't count
+  - Security: anybody can make the plugin send the "User Block Message" to
+    a user, by failing to log in with that username from an address until it
+    is blocked - a way to flood somebody's inbox. The setting now has three
+    values: disabled; enabled only if the user has logged in from the
+    blocked IP address (or, for IPv6, its network) before, which is the
+    case for somebody locking themselves out but never for an attacker's
+    address; and enabled for any IP address, where a user gets at most one
+    unblock link at a time which can still be used (not yet expired or used
+    up). Note that the previous "enabled" now means the first of these; the
+    old behaviour is the third. Known IP addresses are recorded at
+    successful logins, so users get the message again after having logged
+    in once. The username a link was sent to is recorded with its token
   - Security: IPv6 clients are now tracked per network (default: /64, see
     the new "IPv6 Tracking Granularity" setting) instead of per address:
     failed logins are counted and blocks apply to the whole network, so an
diff --git a/language/de-DE/de-DE.plg_system_bfstop.sys.ini b/language/de-DE/de-DE.plg_system_bfstop.sys.ini
index a13f0c5..984dc26 100644
--- a/language/de-DE/de-DE.plg_system_bfstop.sys.ini
+++ b/language/de-DE/de-DE.plg_system_bfstop.sys.ini
@@ -27,7 +27,9 @@ PLG_SYSTEM_BFSTOP_BLOCK_DURATION_DESC="Bestimmt wie lange die IP-Sperre aufrecht
 PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_LABEL="Übrige Versuche"
 PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_DESC="Schaltet die Benachrichtigung über verbleibende Versuche ein; wenn aktiviert, wird im Login-Formular nach einem fehlgeschlagenen Login-Versuch eine Nachricht mit den verbleibenden Login-Versuchen angezeigt. Diese Einstellung wird nur dann berücksichtigt, wenn Sperren eingeschaltet ist (wenn es nicht eingeschaltet ist, gibt es ja auch keine 'verbleibenden' Versuche)"
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_LABEL="Benutzer-Block-Nachricht"
-PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="Wenn eingeschaltet, wird an die in der Datenbank hinterlegte Email-Adresse eine Nachricht hinterlegt, wenn eine IP-Adresse gesperrt wird (sofern der Benutzername, mit dem das Login versucht wurde, ein existierender war und die fehlgeschlagenen Logins von dieser IP-Adresse, die zur Sperre geführt haben, nicht auch gegen andere existierende Konten gerichtet waren: Die Nachricht enthält einen Link, der die Adresse entsperrt, und darf deshalb nicht an den Inhaber eines Kontos gehen, wenn von dort aus Konten anderer angegriffen wurden)"
+PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="Wenn eingeschaltet, erhält ein Benutzer, dessen Benutzername bei fehlgeschlagenen Logins von einer später gesperrten IP-Adresse verwendet wurde, eine Email mit einem Link zum Entsperren dieser Adresse. Es wird nichts gesendet, wenn der Benutzername nicht existiert oder wenn die fehlgeschlagenen Logins von dieser Adresse auch gegen andere existierende Konten gerichtet waren (der Link darf nicht an den Inhaber eines Kontos gehen, wenn von dort aus andere angegriffen werden). Jeder kann eine solche Email auslösen, indem er sich erfolglos als dieser Benutzer anmeldet: 'Nur wenn sich der Benutzer schon von dieser IP-Adresse aus angemeldet hat' (empfohlen) verhindert, dass dies gegen deine Benutzer eingesetzt wird; wird die Email für jede IP-Adresse gesendet, bekommt ein Benutzer höchstens einen noch verwendbaren Link auf einmal."
+PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_KNOWN="eingeschaltet, nur wenn sich der Benutzer schon von dieser IP-Adresse aus angemeldet hat (empfohlen)"
+PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_ANY="eingeschaltet, für jede IP-Adresse (jeder kann damit eine Email an einen Benutzer auslösen)"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_LABEL="Verwende HTTP-Fehler"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="Wenn aktiviert (empfohlen), beantwortet bfstop Anfragen einer gesperrten IP-Adresse mit dem HTTP-Statuscode 403 (Forbidden). Deaktiviere dies nur, wenn dein Webserver, CDN oder deine Firewall 403-Seiten durch eine eigene Fehlerseite ersetzt und gesperrte Benutzer die Sperrmeldung deshalb nie zu sehen bekommen: Sie wird dann mit dem Statuscode 200 gesendet. In beiden Fällen wird die Seite nie zwischengespeichert."
 PLG_SYSTEM_BFSTOP_ENABLED="aktiviert"
diff --git a/language/en-GB/en-GB.plg_system_bfstop.sys.ini b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
index fef2ab6..fbf5390 100644
--- a/language/en-GB/en-GB.plg_system_bfstop.sys.ini
+++ b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
@@ -29,7 +29,9 @@ PLG_SYSTEM_BFSTOP_BLOCK_DURATION_DESC="Determines how long an IP address is bloc
 PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_LABEL="Remaining attempts"
 PLG_SYSTEM_BFSTOP_NOTIFY_REMAINING_ATTEMPTS_DESC="Enables or disables notifications about remaining attempts; if enabled, the user will, after each failed login attempt, see a message in the login form about how many login attempts still are available before the IP address will be blocked. This setting is only active if blocking is enabled (if blocking is disabled, 'remaining' entries wouldn't make sense)."
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_LABEL="User Block Message"
-PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="When turned on, in case of a blocked IP address, a notification will be sent to the user which tried to log in (only of course in case it is an existing username, and only if the failed logins from that IP address which led to the block were not also against other existing accounts: the message contains a link which unblocks the address, so it must not go to the owner of an account if somebody else's accounts were being attacked from there)."
+PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="When turned on, a user whose username was used in failed logins from an IP address which then got blocked receives an email with a link to unblock that address. Nothing is sent if the username does not exist, or if the failed logins from that address also went against other existing accounts (the link must not go to the owner of one account if somebody is attacking others from there). Anybody can cause such an email by failing to log in as that user: 'only if the user has logged in from that IP address before' (recommended) keeps this from being used against your users; if emails are sent for any IP address, at most one link which can still be used is sent to a user at a time."
+PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_KNOWN="enabled, only if the user has logged in from that IP address before (recommended)"
+PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_ANY="enabled, for any IP address (anybody can make this send an email to a user)"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_LABEL="Use HTTP Error"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="If enabled (recommended), bfstop answers requests from a blocked IP address with the status code 403 (Forbidden). Switch this off only if your web server, CDN or firewall replaces 403 pages with its own error page, so that blocked users never get to see the block message: it is then sent with status 200 instead. Either way, the page is never cached."
 PLG_SYSTEM_BFSTOP_ENABLED="enabled"
diff --git a/sql/install.mysql.utf8.sql b/sql/install.mysql.utf8.sql
index 5937842..b005fb0 100644
--- a/sql/install.mysql.utf8.sql
+++ b/sql/install.mysql.utf8.sql
@@ -41,10 +41,12 @@ CREATE TABLE IF NOT EXISTS #__bfstop_unblock (
 
 -- stores randomized tokens for unblocking an IP via an email
 -- to the blocked user
+-- username: the user the unblock link was sent to, to limit the links per user
 CREATE TABLE IF NOT EXISTS #__bfstop_unblock_token (
 	token varchar(40) NOT NULL,
 	block_id int(10) NOT NULL,
 	crdate datetime NOT NULL,
+	username varchar(150) NULL DEFAULT NULL,
 	PRIMARY KEY (token)
 ) DEFAULT CHARSET=utf8mb4 DEFAULT COLLATE=utf8mb4_unicode_ci;
 
diff --git a/sql/install.postgresql.utf8.sql b/sql/install.postgresql.utf8.sql
index f63d4fc..f5adb44 100644
--- a/sql/install.postgresql.utf8.sql
+++ b/sql/install.postgresql.utf8.sql
@@ -40,10 +40,12 @@ CREATE TABLE IF NOT EXISTS "#__bfstop_unblock" (
 );
 
 
+-- username: the user the unblock link was sent to, to limit the links per user
 CREATE TABLE IF NOT EXISTS "#__bfstop_unblock_token" (
   "token" varchar(40) NOT NULL,
   "block_id" integer NOT NULL,
   "crdate" timestamp without time zone NOT NULL,
+  "username" varchar(150) NULL DEFAULT NULL,
   PRIMARY KEY ("token")
 );
 
diff --git a/sql/updates/2.0.0.sql b/sql/updates/2.0.0.sql
index f1c2f3a..a076ba0 100755
--- a/sql/updates/2.0.0.sql
+++ b/sql/updates/2.0.0.sql
@@ -17,6 +17,9 @@ ALTER TABLE `#__bfstop_unblock` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4
 
 ALTER TABLE `#__bfstop_unblock_token` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 
+-- the user an unblock link was sent to, to limit the links per user
+ALTER TABLE `#__bfstop_unblock_token` ADD COLUMN username varchar(150) NULL DEFAULT NULL;
+
 ALTER TABLE `#__bfstop_allowlist` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 
 -- tables introduced in 2.0.0, see install.mysql.utf8.sql for details
diff --git a/src/Extension/Bfstop.php b/src/Extension/Bfstop.php
index b59e98d..cd5bdd7 100644
--- a/src/Extension/Bfstop.php
+++ b/src/Extension/Bfstop.php
@@ -28,6 +28,10 @@ class Bfstop extends CMSPlugin implements SubscriberInterface
 {
 	protected $autoloadLanguage = true;
 
+	// values of the "notifyBlockedUser" setting besides 0 (off) and 1 (only to
+	// users who logged in from the blocked address before)
+	private const NotifyBlockedAnyAddress = 2;
+
 	private LoggerHelper $logger;
 	private NotifierHelper $notifier;
 	private DatabaseHelper $mydb;
@@ -70,10 +74,10 @@ private static function endsWith($haystack, $needle)
 		return (substr($haystack, -$length) === $needle);
 	}
 
-	private function getUnblockLink($id)
+	private function getUnblockLink($id, $username)
 	{
 		$token = $this->mydb->getNewUnblockToken($id,
-			TokenHelper::getToken($this->logger));
+			TokenHelper::getToken($this->logger), $username);
 		$link = 'index.php?option=com_bfstop'.
 			'&view=tokenunblock'.
 			'&token='.$token;
@@ -175,6 +179,12 @@ private function block($logEntry, $duration)
 					"not sending unblock instructions",
 					Log::INFO);
 			}
+			elseif ($userEmail != null && ($withheld = $this->whyNoUnblockMail($logEntry)) !== null)
+			{
+				$this->logger->log("Existing user '".$logEntry->username.
+					"' was blocked, but ".$withheld." - not sending unblock instructions",
+					Log::INFO);
+			}
 			elseif ($userEmail != null)
 			{
 				$this->logger->log("Existing user '".
@@ -183,7 +193,7 @@ private function block($logEntry, $duration)
 					"instructions",
 					Log::INFO);
 				$this->notifier->sendUnblockMail($userEmail,
-					$this->getUnblockLink($id));
+					$this->getUnblockLink($id, $logEntry->username));
 			}
 			else
 			{
@@ -195,6 +205,33 @@ private function block($logEntry, $duration)
 		}
 	}
 
+	/**
+	 * Anybody can make the plugin send an unblock email to a user: by failing
+	 * to log in with that username from an IP address until it is blocked.
+	 * To keep that from being used to flood somebody's inbox:
+	 *
+	 * - by default (mode 1) the email is only sent if the user has logged in
+	 *   from the blocked IP address before - which is where somebody
+	 *   locking themselves out comes from, but never an attacker's address;
+	 * - if it is to go to any address (mode 2), at most one email which can
+	 *   still be used is out for a user at any time.
+	 *
+	 * @return string|null why no email is sent, null if it may be
+	 */
+	private function whyNoUnblockMail($logEntry)
+	{
+		if ($this->getIntParam('notifyBlockedUser', 0) === self::NotifyBlockedAnyAddress)
+		{
+			return $this->mydb->hasCurrentUnblockToken($logEntry->username)
+				? 'there already is an unblock link for this user which can be used'
+				: null;
+		}
+		return $this->mydb->hasLoggedInFrom($this->clientAddress ?? $logEntry->ipaddress,
+			$logEntry->username, $this->getIntParam('ipv6PrefixLength', 64))
+			? null
+			: 'the user has never logged in from this IP address';
+	}
+
 	private function getRealDurationFromDBDuration($duration)
 	{
 		return ($duration <= 0)
diff --git a/src/Helper/DatabaseHelper.php b/src/Helper/DatabaseHelper.php
index 68d1f75..918e7b5 100644
--- a/src/Helper/DatabaseHelper.php
+++ b/src/Helper/DatabaseHelper.php
@@ -321,7 +321,10 @@ public function blockIP($logEntry, $duration, $usehtaccess, $htaccessPath)
 		}
 	}
 
-	public function getNewUnblockToken($id, $token)
+	/**
+	 * @param string|null $username the user the link is sent to, if any
+	 */
+	public function getNewUnblockToken($id, $token, $username = null)
 	{
 		try
 		{
@@ -329,6 +332,7 @@ public function getNewUnblockToken($id, $token)
 			$tokenEntry->token = $token;
 			$tokenEntry->block_id = $id;
 			$tokenEntry->crdate = date("Y-m-d H:i:s");
+			$tokenEntry->username = $username;
 			if (!$this->db->insertObject('#__bfstop_unblock_token', $tokenEntry))
 			{
 				// maybe check if duplicate token (=PRIMARY KEY violation) and retry?
@@ -377,6 +381,27 @@ public function unblockTokenValidForBlocks($token, array $blockIds)
 		}
 	}
 
+	/**
+	 * Whether an unblock link which can still be used was sent to $username:
+	 * one that hasn't expired and wasn't used (a used token is deleted).
+	 */
+	public function hasCurrentUnblockToken($username)
+	{
+		try
+		{
+			$this->db->setQuery("SELECT COUNT(*) FROM #__bfstop_unblock_token".
+				" WHERE LOWER(username) = LOWER(".$this->db->quote($username).")".
+				" AND crdate >= ".$this->db->quote(date("Y-m-d H:i:s",
+					time() - self::$UNBLOCK_TOKEN_VALID_DAYS * 86400)));
+			return ((int) $this->db->loadResult()) > 0;
+		}
+		catch (\Exception $e)
+		{
+			$this->logger->log("Database exception occured: ".$e->getMessage(), Log::ERROR);
+			return true;
+		}
+	}
+
 	public function unblockTokenExists($token)
 	{
 		try
@@ -596,6 +621,36 @@ public function isKnownIpUsername($ipaddress, $username)
 		}
 	}
 
+	/**
+	 * Whether $username has logged in successfully from $ipaddress before -
+	 * or, for an IPv6 client tracked by its network (see
+	 * IpHelper::trackedAddress()), from another address of the same network:
+	 * IPv6 clients commonly switch addresses within their network.
+	 */
+	public function hasLoggedInFrom($ipaddress, $username, $ipv6PrefixLength)
+	{
+		try
+		{
+			$this->db->setQuery("SELECT ipaddress FROM #__bfstop_knownip".
+				" WHERE LOWER(username) = LOWER(".$this->db->quote($username).")");
+			$network = IpHelper::trackedAddress($ipaddress, $ipv6PrefixLength);
+			foreach ($this->db->loadColumn() as $known)
+			{
+				if (strcasecmp($known, $ipaddress) === 0 ||
+					($network !== $ipaddress && IpHelper::trackedAddress($known, $ipv6PrefixLength) === $network))
+				{
+					return true;
+				}
+			}
+			return false;
+		}
+		catch (\Exception $e)
+		{
+			$this->logger->log("Database exception occured: ".$e->getMessage(), Log::ERROR);
+			return false;
+		}
+	}
+
 	/**
 	 * Returns false if there is no (unexpired) cached entry for this IP - the
 	 * caller should do a live lookup and cache it via cacheHostname().
diff --git a/tests/Integration/DatabaseHelperTest.php b/tests/Integration/DatabaseHelperTest.php
index 3d9359a..95275d5 100644
--- a/tests/Integration/DatabaseHelperTest.php
+++ b/tests/Integration/DatabaseHelperTest.php
@@ -167,6 +167,14 @@ public function testAllowList()
 	public function testUnblockToken()
 	{
 		$this->assertSame('tokenA', $this->helper->getNewUnblockToken(1, 'tokenA'));
+		$this->assertNull($this->queryValue("SELECT username FROM #__bfstop_unblock_token WHERE token='tokenA'"));
+		$this->assertFalse($this->helper->hasCurrentUnblockToken('Someone'));
+		$this->assertSame('tokenU', $this->helper->getNewUnblockToken(2, 'tokenU', 'Someone'));
+		$this->assertTrue($this->helper->hasCurrentUnblockToken('someone'), 'case-insensitive');
+		$this->assertFalse($this->helper->hasCurrentUnblockToken('Somebody-else'));
+		$this->insert('#__bfstop_unblock_token', array('token' => 'tokenOld', 'block_id' => 3,
+			'crdate' => self::minutesAgo(4 * 24 * 60), 'username' => 'Expired'));
+		$this->assertFalse($this->helper->hasCurrentUnblockToken('Expired'), 'an expired token is not current');
 		$this->assertTrue($this->helper->unblockTokenExists('tokenA'));
 		$this->assertFalse($this->helper->unblockTokenExists('tokenB'));
 	}
diff --git a/tests/Integration/FailedLoginTest.php b/tests/Integration/FailedLoginTest.php
index b5a3465..560dccb 100644
--- a/tests/Integration/FailedLoginTest.php
+++ b/tests/Integration/FailedLoginTest.php
@@ -228,7 +228,7 @@ private function unblockLinkIssued()
 
 	private function blockedAfter(array $usernames)
 	{
-		$this->configure(array('blockNumber' => count($usernames), 'notifyBlockedUser' => 1));
+		$this->configure(array('blockNumber' => count($usernames), 'notifyBlockedUser' => 2));
 		foreach ($usernames as $username)
 		{
 			$this->failedLogin($username);
@@ -268,7 +268,7 @@ public function testMistypedUsernamesDontPreventTheUnblockLink()
 
 	public function testMistypedUsernamesInPlainModeDontPreventTheUnblockLink()
 	{
-		$this->configure(array('blockNumber' => 3, 'notifyBlockedUser' => 1, 'unknownUsernameMode' => 'plain'));
+		$this->configure(array('blockNumber' => 3, 'notifyBlockedUser' => 2, 'unknownUsernameMode' => 'plain'));
 		foreach (array('nobody', 'nobody-else', 'Admin') as $username)
 		{
 			$this->failedLogin($username);
@@ -285,11 +285,131 @@ public function testOtherSpellingOfTheSameAccountIsTheSameAccount()
 	public function testOnlyAttemptsOfTheSameAddressCount()
 	{
 		$this->createUser('victim');
-		$this->configure(array('blockNumber' => 2, 'notifyBlockedUser' => 1));
+		$this->configure(array('blockNumber' => 2, 'notifyBlockedUser' => 2));
 		$this->failedLogin('victim', '203.0.113.99'); // somebody else
 		$this->failedLogin('Admin');
 		$this->failedLogin('Admin');
 		$this->assertSame(self::Ip, $this->queryValue('SELECT ipaddress FROM #__bfstop_bannedip'));
 		$this->assertTrue($this->unblockLinkIssued());
 	}
+
+	private function knownIp($ip, $username)
+	{
+		$this->insert('#__bfstop_knownip', array('ipaddress' => $ip, 'username' => $username,
+			'first_success' => self::minutesAgo(100), 'last_success' => self::minutesAgo(10)));
+	}
+
+	private function tokenCount($where = '1=1')
+	{
+		return (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_unblock_token WHERE '.$where);
+	}
+
+	private function blockWith($mode, $username = 'Admin', $ip = self::Ip)
+	{
+		$this->configure(array('blockNumber' => 3, 'notifyBlockedUser' => $mode));
+		for ($i = 0; $i < 3; ++$i)
+		{
+			$this->failedLogin($username, $ip);
+		}
+	}
+
+	public function testNoUnblockLinkIfSwitchedOff()
+	{
+		$this->blockWith(0);
+		$this->assertSame(1, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'));
+		$this->assertSame(0, $this->tokenCount());
+	}
+
+	// mode 1: only for IP addresses the user has logged in from
+
+	public function testKnownAddressModeSendsLinkIfTheUserLoggedInFromThere()
+	{
+		$this->knownIp(self::Ip, 'Admin');
+		$this->blockWith(1);
+		$this->assertSame(1, $this->tokenCount("username = 'Admin'"));
+	}
+
+	public function testKnownAddressModeNeverSendsToAnAttackersAddress()
+	{
+		// nobody ever logged in as Admin from here
+		$this->blockWith(1);
+		$this->assertSame(1, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'));
+		$this->assertSame(0, $this->tokenCount());
+	}
+
+	public function testKnownAddressModeIgnoresLoginsOfOtherUsersAndAddresses()
+	{
+		$this->knownIp(self::Ip, 'someone-else');
+		$this->knownIp('203.0.113.77', 'Admin');
+		$this->blockWith(1);
+		$this->assertSame(0, $this->tokenCount());
+	}
+
+	public function testKnownAddressModeIsCaseInsensitiveForTheUsername()
+	{
+		$this->knownIp(self::Ip, 'admin');
+		$this->blockWith(1);
+		$this->assertSame(1, $this->tokenCount());
+	}
+
+	public function testKnownAddressModeRecognisesTheNetworkOfAnIpv6Client()
+	{
+		// IPv6 clients switch to other addresses in their network all the time
+		$this->knownIp('2001:db8:1:2:aaaa:bbbb:cccc:9', 'Admin');
+		$this->blockWith(1, 'Admin', '2001:db8:1:2::1');
+		$this->assertSame(1, $this->tokenCount());
+	}
+
+	public function testKnownAddressModeDoesntRecogniseAnotherIpv6Network()
+	{
+		$this->knownIp('2001:db8:1:3:aaaa::9', 'Admin');
+		$this->blockWith(1, 'Admin', '2001:db8:1:2::1');
+		$this->assertSame(0, $this->tokenCount());
+	}
+
+	public function testKnownAddressModeDoesntLumpIpv4MappedAddressesTogether()
+	{
+		$this->knownIp('::ffff:203.0.113.8', 'Admin');
+		$this->blockWith(1, 'Admin', '::ffff:203.0.113.7');
+		$this->assertSame(0, $this->tokenCount());
+	}
+
+	// mode 2: any address, but only one usable link per user
+
+	public function testAnyAddressModeSendsOnlyOneUsableLinkAtATime()
+	{
+		$this->blockWith(2);
+		$this->assertSame(1, $this->tokenCount("username = 'Admin'"));
+		// the same user, from another address (another botnet member)
+		$this->blockWith(2, 'Admin', '203.0.113.52');
+		$this->assertSame(2, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_bannedip'), 'blocked');
+		$this->assertSame(1, $this->tokenCount(), 'no second link');
+	}
+
+	public function testAnyAddressModeSendsAnotherLinkOnceTheOldOneExpired()
+	{
+		$this->insert('#__bfstop_unblock_token', array('token' => str_repeat('ab', 20), 'block_id' => 1,
+			'crdate' => self::minutesAgo(4 * 24 * 60), 'username' => 'Admin'));
+		$this->blockWith(2);
+		$this->assertSame(2, $this->tokenCount("username = 'Admin'"));
+	}
+
+	public function testAnyAddressModeSendsAnotherLinkOnceTheOldOneWasUsed()
+	{
+		// a token which was used up is deleted, so there is none left
+		$this->blockWith(2);
+		$this->db->setQuery('DELETE FROM #__bfstop_unblock_token');
+		$this->db->execute();
+		$this->blockWith(2, 'Admin', '203.0.113.52');
+		$this->assertSame(1, $this->tokenCount("username = 'Admin'"));
+	}
+
+	public function testAnyAddressModeLimitsPerUser()
+	{
+		$this->createUser('victim');
+		$this->insert('#__bfstop_unblock_token', array('token' => str_repeat('cd', 20), 'block_id' => 1,
+			'crdate' => self::minutesAgo(10), 'username' => 'victim'));
+		$this->blockWith(2);
+		$this->assertSame(1, $this->tokenCount("username = 'Admin'"), 'the link for victim has no bearing on Admin');
+	}
 }

From 04c49f97ff60b369d8ab2147aa9d11426f13be58 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 6 Oct 2026 15:16:38 +0000
Subject: [PATCH 07/10] Remember known IPv6 clients by network; forget old
 known IPs

- Successful logins are remembered under the key the client is tracked by
  (the address for IPv4, the network for IPv6), like failed logins. An IPv6
  client switching to a new privacy address every day stays a known client
  and no longer adds a row per address. The lookup (hasLoggedInFrom(), which
  replaces isKnownIpUsername() and is used by the risk score and the unblock
  message) still finds entries recorded per address, in another spelling or
  at another granularity, and ignores the case of the username.
- Known IP addresses are forgotten a year after the last login from them,
  and the table is kept below 100000 rows, oldest first, by the daily
  maintenance, which now also runs if no purge age is configured.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 CHANGELOG                                |   8 ++
 src/Extension/Bfstop.php                 |   1 +
 src/Helper/DatabaseHelper.php            | 124 +++++++++++++++++------
 src/Helper/RiskHelper.php                |   2 +-
 tests/Integration/BlockedRequestTest.php |  33 ++++++
 tests/Integration/DatabaseHelperTest.php |  87 +++++++++++++++-
 tests/Integration/PluginEventsTest.php   |  20 ++++
 tests/Integration/RiskHelperTest.php     |  29 +++++-
 8 files changed, 264 insertions(+), 40 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index f624bf9..125c3d2 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -94,6 +94,14 @@
     old behaviour is the third. Known IP addresses are recorded at
     successful logins, so users get the message again after having logged
     in once. The username a link was sent to is recorded with its token
+  - The addresses users logged in from (used for the risk score and for the
+    unblock message) are remembered by network for IPv6 clients, as failed
+    logins are, so a client whose address changes within its /64 every day
+    stays a known one and doesn't add a row per address; the lookup ignores
+    the case of the username. They are forgotten a year after the last login
+    from them (and the table is limited to 100000 rows, oldest first). This
+    maintenance, like the limit of the username statistics, runs once a day
+    whatever the purge age is set to
   - Security: IPv6 clients are now tracked per network (default: /64, see
     the new "IPv6 Tracking Granularity" setting) instead of per address:
     failed logins are counted and blocks apply to the whole network, so an
diff --git a/src/Extension/Bfstop.php b/src/Extension/Bfstop.php
index cd5bdd7..b56ee3a 100644
--- a/src/Extension/Bfstop.php
+++ b/src/Extension/Bfstop.php
@@ -625,6 +625,7 @@ public function onAfterInitialise($event)
 			}
 			// regardless of the purge age setting: these are not deleted by age
 			$this->mydb->trimUsernameStats();
+			$this->mydb->pruneKnownIps();
 			$this->params->set('lastPurge', $now);
 			$this->mydb->saveLastPurge($now);
 		}
diff --git a/src/Helper/DatabaseHelper.php b/src/Helper/DatabaseHelper.php
index 918e7b5..6d3e53e 100644
--- a/src/Helper/DatabaseHelper.php
+++ b/src/Helper/DatabaseHelper.php
@@ -32,6 +32,13 @@ class DatabaseHelper
 	// many usernames as they like
 	public static $USERNAME_STATS_MAX_ROWS = 10000;
 
+	// known IP addresses (where a user logged in from) are forgotten after
+	// this long without a login from them, and the table is kept below this
+	// number of rows, oldest first: a visitor with an account can log in from
+	// as many addresses as they like
+	public static $KNOWN_IP_MAX_AGE_DAYS = 365;
+	public static $KNOWN_IP_MAX_ROWS = 100000;
+
 	// how long a reverse-DNS lookup result is trusted before being redone -
 	// keeps the (potentially slow) gethostbyaddr() call to at most once per
 	// IP per TTL window, see issue #103
@@ -591,53 +598,64 @@ public function setFailedLoginHandled($info, $restrictOnUsername)
 
 	/**
 	 * @param object      $info           ipaddress (the client's address) and username
-	 * @param string|null $trackedAddress the key failed logins of this client
-	 *                                    are recorded under (see
-	 *                                    IpHelper::trackedAddress()), if different
+	 * @param string|null $trackedAddress the key this client is tracked by (see
+	 *                                    IpHelper::trackedAddress(): for IPv6 its
+	 *                                    network), if not its address. Failed
+	 *                                    logins are recorded, and logins
+	 *                                    remembered, under this key
 	 */
 	public function successfulLogin($info, $trackedAddress = null)
 	{
+		$key = $trackedAddress ?? $info->ipaddress;
 		$handled = new \stdClass();
-		$handled->ipaddress = $trackedAddress ?? $info->ipaddress;
+		$handled->ipaddress = $key;
 		$handled->username = $info->username;
 		$this->setFailedLoginHandled($handled, true);
-		$this->recordKnownIpUsername($info->ipaddress, $info->username);
-	}
-
-	public function isKnownIpUsername($ipaddress, $username)
-	{
-		try
-		{
-			$sql = "SELECT COUNT(*) FROM #__bfstop_knownip WHERE ".
-				"ipaddress = ".$this->db->quote($ipaddress).
-				" AND username = ".$this->db->quote($username);
-			$this->db->setQuery($sql);
-			return ((int) $this->db->loadResult()) > 0;
-		}
-		catch (\Exception $e)
-		{
-			$this->logger->log("Database exception occured: ".$e->getMessage(), Log::ERROR);
-			return false;
-		}
+		$this->recordKnownIpUsername($key, $info->username);
 	}
 
 	/**
-	 * Whether $username has logged in successfully from $ipaddress before -
-	 * or, for an IPv6 client tracked by its network (see
-	 * IpHelper::trackedAddress()), from another address of the same network:
-	 * IPv6 clients commonly switch addresses within their network.
+	 * Whether $username has logged in successfully from $ipaddress before.
+	 *
+	 * Logins are remembered under the key the client is tracked by (see
+	 * IpHelper::trackedAddress()): an IPv4 address itself, an IPv6 address by
+	 * its network, as IPv6 clients commonly switch addresses within it. So
+	 * is a login from any address of the network a login from this one.
 	 */
 	public function hasLoggedInFrom($ipaddress, $username, $ipv6PrefixLength)
 	{
 		try
 		{
-			$this->db->setQuery("SELECT ipaddress FROM #__bfstop_knownip".
-				" WHERE LOWER(username) = LOWER(".$this->db->quote($username).")");
-			$network = IpHelper::trackedAddress($ipaddress, $ipv6PrefixLength);
+			$key = IpHelper::trackedAddress($ipaddress, $ipv6PrefixLength);
+			$user = "LOWER(".$this->db->quote($username).")";
+			$this->db->setQuery("SELECT COUNT(*) FROM #__bfstop_knownip WHERE ".
+				"ipaddress IN (".$this->db->quote($key).", ".$this->db->quote($ipaddress).")".
+				" AND LOWER(username) = ".$user);
+			if (((int) $this->db->loadResult()) > 0)
+			{
+				return true;
+			}
+			if (strpos($ipaddress, ':') === false)
+			{
+				return false;
+			}
+			// IPv6: look for entries under another spelling of the address,
+			// or recorded at another granularity (the setting was changed)
+			$this->db->setQuery("SELECT ipaddress FROM #__bfstop_knownip WHERE LOWER(username) = ".$user);
+			$ipBin = @inet_pton($ipaddress);
 			foreach ($this->db->loadColumn() as $known)
 			{
-				if (strcasecmp($known, $ipaddress) === 0 ||
-					($network !== $ipaddress && IpHelper::trackedAddress($known, $ipv6PrefixLength) === $network))
+				if (strpos($known, '/') !== false)
+				{
+					$match = IpHelper::isInSubnet($ipaddress, $known);
+				}
+				else
+				{
+					$knownBin = @inet_pton($known);
+					$match = $knownBin !== false &&
+						($knownBin === $ipBin || IpHelper::trackedAddress($known, $ipv6PrefixLength) === $key);
+				}
+				if ($match)
 				{
 					return true;
 				}
@@ -727,7 +745,7 @@ private function recordKnownIpUsername($ipaddress, $username)
 			$now = date("Y-m-d H:i:s");
 			$sql = "SELECT id FROM #__bfstop_knownip WHERE ".
 				"ipaddress = ".$this->db->quote($ipaddress).
-				" AND username = ".$this->db->quote($username);
+				" AND LOWER(username) = LOWER(".$this->db->quote($username).")";
 			$this->db->setQuery($sql);
 			$id = $this->db->loadResult();
 			if ($id)
@@ -841,6 +859,48 @@ public function saveLastPurge($timestamp)
 		}
 	}
 
+	/**
+	 * Forgets the addresses users logged in from longer ago than $maxAgeDays,
+	 * and, oldest first, as many more as needed to keep at most $maxRows.
+	 */
+	public function pruneKnownIps($maxAgeDays = null, $maxRows = null)
+	{
+		$maxAgeDays = $maxAgeDays ?? self::$KNOWN_IP_MAX_AGE_DAYS;
+		$maxRows = $maxRows ?? self::$KNOWN_IP_MAX_ROWS;
+		try
+		{
+			$this->db->setQuery('DELETE FROM #__bfstop_knownip WHERE last_success < '.
+				$this->db->quote(date("Y-m-d H:i:s", time() - $maxAgeDays * 86400)));
+			$this->db->execute();
+			for ($round = 0; $round < 1000; ++$round)
+			{
+				$this->db->setQuery('SELECT COUNT(*) FROM #__bfstop_knownip');
+				$excess = ((int) $this->db->loadResult()) - $maxRows;
+				if ($excess <= 0)
+				{
+					return;
+				}
+				$query = $this->db->getQuery(true)
+					->select($this->db->quoteName('id'))
+					->from($this->db->quoteName('#__bfstop_knownip'))
+					->order($this->db->quoteName('last_success').' ASC');
+				$this->db->setQuery($query, 0, min($excess, 1000));
+				$ids = $this->db->loadColumn();
+				if (count($ids) === 0)
+				{
+					return;
+				}
+				$this->db->setQuery('DELETE FROM #__bfstop_knownip WHERE id IN ('.
+					implode(',', array_map('intval', $ids)).')');
+				$this->db->execute();
+			}
+		}
+		catch (\Exception $e)
+		{
+			$this->logger->log("Database exception occured: ".$e->getMessage(), Log::ERROR);
+		}
+	}
+
 	/**
 	 * Keeps the username statistics below $maxRows by deleting the entries of
 	 * the usernames with the fewest attempts, the longest ago first.
diff --git a/src/Helper/RiskHelper.php b/src/Helper/RiskHelper.php
index 913decd..67c818e 100644
--- a/src/Helper/RiskHelper.php
+++ b/src/Helper/RiskHelper.php
@@ -40,7 +40,7 @@ private static function knownIpScore(DatabaseHelper $db, LoggerHelper $logger, R
 		}
 		try
 		{
-			if ($db->isKnownIpUsername($ipaddress, $username))
+			if ($db->hasLoggedInFrom($ipaddress, $username, self::getIntParam($params, 'ipv6PrefixLength', 64)))
 			{
 				return -self::getIntParam($params, 'riskKnownIpPoints', 5);
 			}
diff --git a/tests/Integration/BlockedRequestTest.php b/tests/Integration/BlockedRequestTest.php
index d1f96ec..93b9e85 100644
--- a/tests/Integration/BlockedRequestTest.php
+++ b/tests/Integration/BlockedRequestTest.php
@@ -102,6 +102,39 @@ public function testBlockIsEnforcedOnlyAfterRouting()
 		$this->assertBlocked();
 	}
 
+	private function knownIps()
+	{
+		$this->db->setQuery('SELECT ipaddress FROM #__bfstop_knownip ORDER BY ipaddress');
+		return $this->db->loadColumn();
+	}
+
+	private function knownIp($ip, $daysAgo)
+	{
+		$this->insert('#__bfstop_knownip', array('ipaddress' => $ip, 'username' => 'bob',
+			'first_success' => self::minutesAgo($daysAgo * 1440 + 1), 'last_success' => self::minutesAgo($daysAgo * 1440)));
+	}
+
+	public function testDailyMaintenancePrunesAndRemembersWhenItRan()
+	{
+		// purge age 0: nothing is purged by age, but this has to happen regardless
+		$this->configure(array('deleteOld' => 0, 'blockNumber' => 7));
+		$this->knownIp('203.0.113.1', 400);
+		$this->knownIp('203.0.113.2', 1);
+		$this->assertNotBlocked();
+		$this->assertSame(array('203.0.113.2'), $this->knownIps());
+		$saved = json_decode($this->getPluginParams(), true);
+		$this->assertGreaterThan(time() - 60, $saved['lastPurge']);
+		$this->assertSame(7, $saved['blockNumber'], 'the other settings are left alone');
+	}
+
+	public function testMaintenanceRunsOnlyOncePerDay()
+	{
+		$this->configure(array('lastPurge' => time() - 3600));
+		$this->knownIp('203.0.113.1', 400);
+		$this->assertNotBlocked();
+		$this->assertSame(array('203.0.113.1'), $this->knownIps(), 'ran an hour ago already');
+	}
+
 	public function testBlockPageIsNeverCached()
 	{
 		foreach (array(true, false) as $useHttpError)
diff --git a/tests/Integration/DatabaseHelperTest.php b/tests/Integration/DatabaseHelperTest.php
index 95275d5..fcfadbb 100644
--- a/tests/Integration/DatabaseHelperTest.php
+++ b/tests/Integration/DatabaseHelperTest.php
@@ -184,12 +184,93 @@ public function testKnownIpUsername()
 		$login = (object) array('ipaddress' => '203.0.113.5', 'username' => 'bob');
 		$this->helper->successfulLogin($login);
 		$this->helper->successfulLogin($login); // second time: update instead of insert
-		$this->assertTrue($this->helper->isKnownIpUsername('203.0.113.5', 'bob'));
-		$this->assertFalse($this->helper->isKnownIpUsername('203.0.113.5', 'eve'));
-		$this->assertFalse($this->helper->isKnownIpUsername('203.0.113.6', 'bob'));
+		$this->assertTrue($this->helper->hasLoggedInFrom('203.0.113.5', 'bob', 64));
+		$this->assertFalse($this->helper->hasLoggedInFrom('203.0.113.5', 'eve', 64));
+		$this->assertFalse($this->helper->hasLoggedInFrom('203.0.113.6', 'bob', 64));
 		$this->assertSame(1, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_knownip'));
 	}
 
+	private function knownRows()
+	{
+		$this->db->setQuery('SELECT ipaddress, username FROM #__bfstop_knownip ORDER BY id');
+		return array_map(fn ($row) => $row->ipaddress.' '.$row->username, $this->db->loadObjectList());
+	}
+
+	public function testIpv6ClientsAreRememberedByNetwork()
+	{
+		// the privacy extensions give an IPv6 client a new address every day:
+		// one row per address would pile up, and none of them match tomorrow
+		$net = '2001:db8:1:2::/64';
+		$this->helper->successfulLogin((object) array('ipaddress' => '2001:db8:1:2:aaaa::1', 'username' => 'bob'), $net);
+		$this->helper->successfulLogin((object) array('ipaddress' => '2001:db8:1:2:bbbb::2', 'username' => 'bob'), $net);
+		$this->assertSame(array($net.' bob'), $this->knownRows());
+		$this->assertTrue($this->helper->hasLoggedInFrom('2001:db8:1:2:cccc::3', 'bob', 64), 'a third address of the network');
+		$this->assertFalse($this->helper->hasLoggedInFrom('2001:db8:1:3::1', 'bob', 64), 'another network');
+		$this->assertFalse($this->helper->hasLoggedInFrom('2001:db8:1:2:cccc::3', 'eve', 64), 'another user');
+	}
+
+	public function testKnownIpUsernameIsCaseInsensitive()
+	{
+		$this->helper->successfulLogin((object) array('ipaddress' => '203.0.113.5', 'username' => 'Bob'));
+		$this->helper->successfulLogin((object) array('ipaddress' => '203.0.113.5', 'username' => 'bob'));
+		$this->assertSame(array('203.0.113.5 Bob'), $this->knownRows(), 'one row, not one per spelling');
+		$this->assertTrue($this->helper->hasLoggedInFrom('203.0.113.5', 'BOB', 64));
+	}
+
+	public function testSuccessfulLoginHandlesFailuresRecordedUnderTheNetwork()
+	{
+		$net = '2001:db8:1:2::/64';
+		$this->failedLogin($net, 'bob', 0);
+		$this->failedLogin($net, 'eve', 0);
+		$this->helper->successfulLogin((object) array('ipaddress' => '2001:db8:1:2::9', 'username' => 'bob'), $net);
+		$this->assertSame(1, (int) $this->queryValue("SELECT COUNT(*) FROM #__bfstop_failedlogin WHERE handled=0"), 'only bob\'s');
+	}
+
+	public function testEarlierRecordingsAreStillRecognised()
+	{
+		$row = fn ($ip) => $this->insert('#__bfstop_knownip', array('ipaddress' => $ip, 'username' => 'bob',
+			'first_success' => self::minutesAgo(10), 'last_success' => self::minutesAgo(5)));
+		// recorded by address (earlier version), now looked up by network
+		$row('2001:db8:1:2:aaaa::1');
+		$this->assertTrue($this->helper->hasLoggedInFrom('2001:db8:1:2:bbbb::2', 'bob', 64));
+		$this->assertFalse($this->helper->hasLoggedInFrom('2001:db8:1:3::2', 'bob', 64));
+		// the same address in another spelling
+		$this->assertTrue($this->helper->hasLoggedInFrom('2001:0DB8:1:2:AAAA:0:0:1', 'bob', 128));
+		// recorded by network, then the setting was changed to single addresses
+		$row('2001:db8:5:6::/64');
+		$this->assertTrue($this->helper->hasLoggedInFrom('2001:db8:5:6::77', 'bob', 128));
+		$this->assertFalse($this->helper->hasLoggedInFrom('2001:db8:5:7::77', 'bob', 128));
+		// IPv4 is only ever matched exactly
+		$row('203.0.113.5');
+		$this->assertTrue($this->helper->hasLoggedInFrom('203.0.113.5', 'bob', 64));
+		$this->assertFalse($this->helper->hasLoggedInFrom('203.0.113.6', 'bob', 64));
+	}
+
+	public function testPruneKnownIpsForgetsOldLogins()
+	{
+		$row = fn ($ip, $daysAgo) => $this->insert('#__bfstop_knownip', array('ipaddress' => $ip, 'username' => 'bob',
+			'first_success' => self::minutesAgo($daysAgo * 1440 + 1), 'last_success' => self::minutesAgo($daysAgo * 1440)));
+		$row('203.0.113.1', 400);
+		$row('203.0.113.2', 364);
+		$row('203.0.113.3', 1);
+		$this->helper->pruneKnownIps();
+		$this->assertSame(array('203.0.113.2 bob', '203.0.113.3 bob'), $this->knownRows());
+	}
+
+	public function testPruneKnownIpsKeepsTheNewestRows()
+	{
+		$row = fn ($ip, $daysAgo) => $this->insert('#__bfstop_knownip', array('ipaddress' => $ip, 'username' => 'bob',
+			'first_success' => self::minutesAgo($daysAgo * 1440 + 1), 'last_success' => self::minutesAgo($daysAgo * 1440)));
+		$row('203.0.113.1', 30);
+		$row('203.0.113.2', 10);
+		$row('203.0.113.3', 20);
+		$row('203.0.113.4', 5);
+		$this->helper->pruneKnownIps(365, 10);
+		$this->assertCount(4, $this->knownRows(), 'below the limit');
+		$this->helper->pruneKnownIps(365, 2);
+		$this->assertSame(array('203.0.113.2 bob', '203.0.113.4 bob'), $this->knownRows());
+	}
+
 	public function testDnsCache()
 	{
 		$this->assertFalse($this->helper->getCachedHostname('203.0.113.5'), 'not cached');
diff --git a/tests/Integration/PluginEventsTest.php b/tests/Integration/PluginEventsTest.php
index 30eed89..edc1230 100644
--- a/tests/Integration/PluginEventsTest.php
+++ b/tests/Integration/PluginEventsTest.php
@@ -121,4 +121,24 @@ public function testSuccessfulLoginRecordsKnownIp()
 		$this->dispatch('onUserLogin', array(array('username' => 'Admin'), array()));
 		$this->assertSame('Admin', $this->queryValue("SELECT username FROM #__bfstop_knownip WHERE ipaddress='203.0.113.30'"));
 	}
+
+	public function testSuccessfulLoginOfAnIpv6ClientIsRememberedByNetwork()
+	{
+		$_SERVER['REMOTE_ADDR'] = '2001:db8:1:2::77';
+		$this->dispatch('onUserLogin', array(array('username' => 'Admin'), array()));
+		$_SERVER['REMOTE_ADDR'] = '2001:db8:1:2:abcd::1'; // the next day's privacy address
+		$this->dispatch('onUserLogin', array(array('username' => 'Admin'), array()));
+		$this->assertSame(1, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_knownip'));
+		$this->assertSame('2001:db8:1:2::/64', $this->queryValue('SELECT ipaddress FROM #__bfstop_knownip'));
+	}
+
+	public function testSuccessfulLoginHandlesTheFailedLoginsOfItsNetwork()
+	{
+		$this->failedLogin('2001:db8:1:2::1', 'Admin');
+		$this->failedLogin('2001:db8:1:2::2', 'Admin');
+		$this->assertSame(2, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_failedlogin WHERE handled=0'));
+		$_SERVER['REMOTE_ADDR'] = '2001:db8:1:2::3';
+		$this->dispatch('onUserLogin', array(array('username' => 'Admin'), array()));
+		$this->assertSame(0, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_failedlogin WHERE handled=0'));
+	}
 }
diff --git a/tests/Integration/RiskHelperTest.php b/tests/Integration/RiskHelperTest.php
index 2f43117..c25406c 100644
--- a/tests/Integration/RiskHelperTest.php
+++ b/tests/Integration/RiskHelperTest.php
@@ -47,14 +47,14 @@ private static function allOff(array $overrides = array())
 	private function db($knownIp = false)
 	{
 		$db = $this->createMock(DatabaseHelper::class);
-		$db->method('isKnownIpUsername')->willReturn($knownIp);
+		$db->method('hasLoggedInFrom')->willReturn($knownIp);
 		return $db;
 	}
 
 	public function testAllSignalsDisabledScoresZero()
 	{
 		$db = $this->createMock(DatabaseHelper::class);
-		$db->expects($this->never())->method('isKnownIpUsername');
+		$db->expects($this->never())->method('hasLoggedInFrom');
 		$db->expects($this->never())->method('getCachedHostname');
 		$_SERVER['HTTP_USER_AGENT'] = '';
 		$this->assertSame(0, RiskHelper::computeScore($db, $this->logger, self::allOff(), '203.0.113.5', 'admin'));
@@ -79,7 +79,7 @@ public function testKnownIpReducesScore()
 	public function testKnownIpLookupFailureFailsSafe()
 	{
 		$db = $this->createMock(DatabaseHelper::class);
-		$db->method('isKnownIpUsername')->willThrowException(new \RuntimeException('db down'));
+		$db->method('hasLoggedInFrom')->willThrowException(new \RuntimeException('db down'));
 		$logger = $this->logger;
 		$params = self::allOff(array('riskKnownIpEnabled' => 1));
 		$this->assertSame(0, RiskHelper::computeScore($db, $logger, $params, '203.0.113.5', 'jdoe'));
@@ -148,10 +148,31 @@ public function testSignalsAreSummed()
 			'riskReverseDnsEnabled' => 1,
 		));
 		$db = $this->createMock(DatabaseHelper::class);
-		$db->method('isKnownIpUsername')->willReturn(true);
+		$db->method('hasLoggedInFrom')->willReturn(true);
 		$db->method('getCachedHostname')->willReturn(null);
 		unset($_SERVER['HTTP_USER_AGENT']);
 		// known IP -5, common username +2, no user agent +2, no rDNS +2
 		$this->assertSame(1, RiskHelper::computeScore($db, $this->logger, $params, '203.0.113.5', 'admin'));
 	}
+
+	public function testKnownIpScoreRecognisesTheNetworkOfAnIpv6Client()
+	{
+		// logins are remembered by network (see DatabaseHelper::successfulLogin()),
+		// so an IPv6 client switching addresses is still a known one
+		$db = new DatabaseHelper($this->logger);
+		$db->successfulLogin((object) array('ipaddress' => '2001:db8:1:2::5', 'username' => 'bob'), '2001:db8:1:2::/64');
+		$params = self::allOff(array('riskKnownIpEnabled' => 1, 'riskKnownIpPoints' => 5));
+		$this->assertSame(-5, RiskHelper::computeScore($db, $this->logger, $params, '2001:db8:1:2:aaaa::9', 'bob'));
+		$this->assertSame(0, RiskHelper::computeScore($db, $this->logger, $params, '2001:db8:1:3::9', 'bob'), 'another network');
+		$this->assertSame(0, RiskHelper::computeScore($db, $this->logger, $params, '2001:db8:1:2:aaaa::9', 'eve'), 'another user');
+	}
+
+	public function testKnownIpScoreHonoursTheConfiguredNetworkSize()
+	{
+		$db = new DatabaseHelper($this->logger);
+		$db->successfulLogin((object) array('ipaddress' => '2001:db8:1:2::5', 'username' => 'bob'), '2001:db8:1:2::5');
+		$params = self::allOff(array('riskKnownIpEnabled' => 1, 'riskKnownIpPoints' => 5, 'ipv6PrefixLength' => 128));
+		$this->assertSame(-5, RiskHelper::computeScore($db, $this->logger, $params, '2001:db8:1:2::5', 'bob'));
+		$this->assertSame(0, RiskHelper::computeScore($db, $this->logger, $params, '2001:db8:1:2::6', 'bob'));
+	}
 }

From 6bed20277cc190829799caa97eb73d9b79314371 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 6 Oct 2026 15:22:29 +0000
Subject: [PATCH 08/10] Make a username statistics assertion independent of the
 collation

On MySQL/MariaDB the username column's collation is case-insensitive, so
"Admin" and "admin" share a row in the username statistics; on PostgreSQL
they don't. Count the attempts instead of the rows.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 tests/Integration/FailedLoginTest.php | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/tests/Integration/FailedLoginTest.php b/tests/Integration/FailedLoginTest.php
index 560dccb..39546ae 100644
--- a/tests/Integration/FailedLoginTest.php
+++ b/tests/Integration/FailedLoginTest.php
@@ -139,7 +139,11 @@ public function testExistingAndCommonUsernamesAreStoredReadably()
 		$this->failedLogin('admin'); // as typed
 		$this->failedLogin('ROOT');
 		$this->assertSame(array('Admin', 'admin', 'ROOT'), $this->storedUsernames());
-		$this->assertSame(3, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_username_stats'));
+		// MySQL's collation is case-insensitive, so "Admin" and "admin" share a
+		// row there, PostgreSQL's isn't: what has to hold on both is that every
+		// attempt is counted
+		$this->assertSame(3, (int) $this->queryValue('SELECT SUM(attempts) FROM #__bfstop_username_stats'));
+		$this->assertSame(1, (int) $this->queryValue("SELECT COUNT(*) FROM #__bfstop_username_stats WHERE username = 'ROOT'"));
 	}
 
 	public function testOtherUsernamesAreStoredHashed()

From c3ecae69a5efe8d2b5658747e1aabc5e82718f6c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 6 Oct 2026 19:14:25 +0000
Subject: [PATCH 09/10] Review: set the block page status with
 http_response_code(); purge expired tokens

- The status line "HTTP/1.0 403 Forbidden" hard-coded the protocol version
  (and HTTP/2 has no status line); use http_response_code(403) instead.
- Unblock tokens which have expired were only deleted when somebody visited
  the unblock page or if a purge age is configured; the daily maintenance now
  deletes them regardless.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 CHANGELOG                                |  5 ++++
 src/Extension/Bfstop.php                 | 33 +++++++++++++++++-------
 src/Helper/DatabaseHelper.php            | 20 ++++++++++++++
 tests/Integration/BlockedRequestTest.php | 22 ++++++++++++----
 tests/Integration/DatabaseHelperTest.php | 11 ++++++++
 5 files changed, 76 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index 125c3d2..467cb3f 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -102,6 +102,11 @@
     from them (and the table is limited to 100000 rows, oldest first). This
     maintenance, like the limit of the username statistics, runs once a day
     whatever the purge age is set to
+  - Unblock tokens which have expired are deleted by the daily maintenance too
+    (before: only when somebody visited the unblock page, or by the purge by
+    age if one is configured). The status code of the block page is set with
+    http_response_code() instead of a raw "HTTP/1.0 403" header, which hard-coded
+    the protocol version
   - Security: IPv6 clients are now tracked per network (default: /64, see
     the new "IPv6 Tracking Granularity" setting) instead of per address:
     failed logins are counted and blocks apply to the whole network, so an
diff --git a/src/Extension/Bfstop.php b/src/Extension/Bfstop.php
index b56ee3a..0535c15 100644
--- a/src/Extension/Bfstop.php
+++ b/src/Extension/Bfstop.php
@@ -626,27 +626,35 @@ public function onAfterInitialise($event)
 			// regardless of the purge age setting: these are not deleted by age
 			$this->mydb->trimUsernameStats();
 			$this->mydb->pruneKnownIps();
+			$this->mydb->purgeExpiredUnblockTokens();
 			$this->params->set('lastPurge', $now);
 			$this->mydb->saveLastPurge($now);
 		}
 	}
 
+	/**
+	 * The status code of the page shown to a blocked client, or null for none
+	 * (which makes it 200). Set with http_response_code(), not as a raw
+	 * "HTTP/1.x 403 ..." header: that would hard-code the protocol version,
+	 * which is the web server's business (HTTP/2 doesn't even have a status line).
+	 */
+	public static function blockedResponseCode($useHttpError)
+	{
+		return $useHttpError ? 403 : null;
+	}
+
 	/**
 	 * The headers of the page shown to a blocked client.
 	 *
 	 * It must never be cached: a cache (browser, proxy, CDN) which kept it
 	 * would show it to other visitors of the same URL.
 	 */
-	public static function blockedResponseHeaders($useHttpError)
+	public static function blockedResponseHeaders()
 	{
-		$headers = array();
-		if ($useHttpError)
-		{
-			$headers[] = 'HTTP/1.0 403 Forbidden';
-		}
-		$headers[] = 'Cache-Control: no-store, no-cache, must-revalidate, private';
-		$headers[] = 'Pragma: no-cache';
-		return $headers;
+		return array(
+			'Cache-Control: no-store, no-cache, must-revalidate, private',
+			'Pragma: no-cache',
+		);
 	}
 
 	/**
@@ -695,7 +703,12 @@ public function onAfterRoute($event)
 				return;
 			}
 			$this->mydb->recordBlockedAttempt($blockIds);
-			foreach (self::blockedResponseHeaders($this->getBoolParam('useHttpError', true)) as $header)
+			$status = self::blockedResponseCode($this->getBoolParam('useHttpError', true));
+			if ($status !== null)
+			{
+				http_response_code($status);
+			}
+			foreach (self::blockedResponseHeaders() as $header)
 			{
 				header($header);
 			}
diff --git a/src/Helper/DatabaseHelper.php b/src/Helper/DatabaseHelper.php
index 6d3e53e..dcf0d7e 100644
--- a/src/Helper/DatabaseHelper.php
+++ b/src/Helper/DatabaseHelper.php
@@ -859,6 +859,26 @@ public function saveLastPurge($timestamp)
 		}
 	}
 
+	/**
+	 * Deletes the unblock tokens which can't be used any more. A used token is
+	 * deleted when it is used, and the unblock page deletes the expired ones
+	 * when somebody visits it - but nobody may, and the purge by age only runs
+	 * if a purge age is configured.
+	 */
+	public function purgeExpiredUnblockTokens()
+	{
+		try
+		{
+			$this->db->setQuery('DELETE FROM #__bfstop_unblock_token WHERE crdate < '.
+				$this->db->quote(date("Y-m-d H:i:s", time() - self::$UNBLOCK_TOKEN_VALID_DAYS * 86400)));
+			$this->db->execute();
+		}
+		catch (\Exception $e)
+		{
+			$this->logger->log("Database exception occured: ".$e->getMessage(), Log::ERROR);
+		}
+	}
+
 	/**
 	 * Forgets the addresses users logged in from longer ago than $maxAgeDays,
 	 * and, oldest first, as many more as needed to keep at most $maxRows.
diff --git a/tests/Integration/BlockedRequestTest.php b/tests/Integration/BlockedRequestTest.php
index 93b9e85..af8a77e 100644
--- a/tests/Integration/BlockedRequestTest.php
+++ b/tests/Integration/BlockedRequestTest.php
@@ -120,8 +120,14 @@ public function testDailyMaintenancePrunesAndRemembersWhenItRan()
 		$this->configure(array('deleteOld' => 0, 'blockNumber' => 7));
 		$this->knownIp('203.0.113.1', 400);
 		$this->knownIp('203.0.113.2', 1);
+		// unblock tokens nobody can use any more
+		$this->insert('#__bfstop_unblock_token', array('token' => str_repeat('ab', 20), 'block_id' => 1,
+			'crdate' => self::minutesAgo(4 * 24 * 60)));
+		$this->insert('#__bfstop_unblock_token', array('token' => str_repeat('cd', 20), 'block_id' => 2,
+			'crdate' => self::minutesAgo(60)));
 		$this->assertNotBlocked();
 		$this->assertSame(array('203.0.113.2'), $this->knownIps());
+		$this->assertSame(array(str_repeat('cd', 20)), $this->db->setQuery('SELECT token FROM #__bfstop_unblock_token')->loadColumn());
 		$saved = json_decode($this->getPluginParams(), true);
 		$this->assertGreaterThan(time() - 60, $saved['lastPurge']);
 		$this->assertSame(7, $saved['blockNumber'], 'the other settings are left alone');
@@ -137,15 +143,21 @@ public function testMaintenanceRunsOnlyOncePerDay()
 
 	public function testBlockPageIsNeverCached()
 	{
-		foreach (array(true, false) as $useHttpError)
+		$headers = Bfstop::blockedResponseHeaders();
+		$this->assertContains('Cache-Control: no-store, no-cache, must-revalidate, private', $headers);
+		$this->assertContains('Pragma: no-cache', $headers);
+		foreach ($headers as $header)
 		{
-			$headers = Bfstop::blockedResponseHeaders($useHttpError);
-			$this->assertContains('Cache-Control: no-store, no-cache, must-revalidate, private', $headers);
-			$this->assertContains('Pragma: no-cache', $headers);
-			$this->assertSame($useHttpError, in_array('HTTP/1.0 403 Forbidden', $headers, true));
+			$this->assertStringStartsNotWith('HTTP/', $header, 'the status is set with http_response_code()');
 		}
 	}
 
+	public function testBlockedResponseCode()
+	{
+		$this->assertSame(403, Bfstop::blockedResponseCode(true));
+		$this->assertNull(Bfstop::blockedResponseCode(false));
+	}
+
 	public function testBlockPageIsAnErrorByDefault()
 	{
 		$this->configure();
diff --git a/tests/Integration/DatabaseHelperTest.php b/tests/Integration/DatabaseHelperTest.php
index fcfadbb..c8c386a 100644
--- a/tests/Integration/DatabaseHelperTest.php
+++ b/tests/Integration/DatabaseHelperTest.php
@@ -271,6 +271,17 @@ public function testPruneKnownIpsKeepsTheNewestRows()
 		$this->assertSame(array('203.0.113.2 bob', '203.0.113.4 bob'), $this->knownRows());
 	}
 
+	public function testPurgeExpiredUnblockTokens()
+	{
+		$this->insert('#__bfstop_unblock_token', array('token' => 'tokenOld', 'block_id' => 1,
+			'crdate' => self::minutesAgo(3 * 24 * 60 + 5)));
+		$this->insert('#__bfstop_unblock_token', array('token' => 'tokenNew', 'block_id' => 2,
+			'crdate' => self::minutesAgo(3 * 24 * 60 - 5)));
+		$this->helper->purgeExpiredUnblockTokens();
+		$this->db->setQuery('SELECT token FROM #__bfstop_unblock_token');
+		$this->assertSame(array('tokenNew'), $this->db->loadColumn());
+	}
+
 	public function testDnsCache()
 	{
 		$this->assertFalse($this->helper->getCachedHostname('203.0.113.5'), 'not cached');

From a655f7165e449d880ce4140393072128b401dd87 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 6 Oct 2026 19:44:00 +0000
Subject: [PATCH 10/10] Test the unblock page over HTTP; document its error
 statuses

- UnblockPageHttpTest runs the installed Joomla site on PHP's built-in web
  server and checks the real status and headers of every outcome of the
  unblock page (400 without a token, 200 for the confirmation whatever the
  token, 403 for another IP address, 404 for an unknown or used token, 200 on
  success, 200 for all of them with "Use HTTP Error" off, and the cache,
  referrer and robots headers). Status and headers can't be observed from a
  CLI process.
- Component tests for the new outcome (not found vs. failed) and the status
  mapping.
- The help text of "Use HTTP Error" mentions the unblock page.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q
---
 CHANGELOG                                     |   7 +
 .../de-DE/de-DE.plg_system_bfstop.sys.ini     |   2 +-
 .../en-GB/en-GB.plg_system_bfstop.sys.ini     |   2 +-
 tests/Integration/ComponentTest.php           |  26 ++-
 tests/Integration/UnblockPageHttpTest.php     | 197 ++++++++++++++++++
 tests/README.md                               |   7 +
 6 files changed, 238 insertions(+), 3 deletions(-)
 create mode 100644 tests/Integration/UnblockPageHttpTest.php

diff --git a/CHANGELOG b/CHANGELOG
index 467cb3f..1a14bfd 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -107,6 +107,13 @@
     age if one is configured). The status code of the block page is set with
     http_response_code() instead of a raw "HTTP/1.0 403" header, which hard-coded
     the protocol version
+  - The unblock page of com_bfstop answers with an error status if the link
+    can't be used (400 without a token, 403 from another IP address, 404 for
+    an unknown, expired or used token, 500 if unblocking failed), unless "Use
+    HTTP Error" is switched off; opening the link (a GET request) stays a 200
+    for every token. The page is not cached and tells browsers not to send
+    its address (which contains the token) to other sites and search engines
+    not to index it
   - Security: IPv6 clients are now tracked per network (default: /64, see
     the new "IPv6 Tracking Granularity" setting) instead of per address:
     failed logins are counted and blocks apply to the whole network, so an
diff --git a/language/de-DE/de-DE.plg_system_bfstop.sys.ini b/language/de-DE/de-DE.plg_system_bfstop.sys.ini
index 984dc26..658e7a8 100644
--- a/language/de-DE/de-DE.plg_system_bfstop.sys.ini
+++ b/language/de-DE/de-DE.plg_system_bfstop.sys.ini
@@ -31,7 +31,7 @@ PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="Wenn eingeschaltet, erhält ein Benu
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_KNOWN="eingeschaltet, nur wenn sich der Benutzer schon von dieser IP-Adresse aus angemeldet hat (empfohlen)"
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_ANY="eingeschaltet, für jede IP-Adresse (jeder kann damit eine Email an einen Benutzer auslösen)"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_LABEL="Verwende HTTP-Fehler"
-PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="Wenn aktiviert (empfohlen), beantwortet bfstop Anfragen einer gesperrten IP-Adresse mit dem HTTP-Statuscode 403 (Forbidden). Deaktiviere dies nur, wenn dein Webserver, CDN oder deine Firewall 403-Seiten durch eine eigene Fehlerseite ersetzt und gesperrte Benutzer die Sperrmeldung deshalb nie zu sehen bekommen: Sie wird dann mit dem Statuscode 200 gesendet. In beiden Fällen wird die Seite nie zwischengespeichert."
+PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="Wenn aktiviert (empfohlen), beantwortet bfstop Anfragen einer gesperrten IP-Adresse mit dem HTTP-Statuscode 403 (Forbidden) und die Entsperrseite des Links in der Benachrichtigungs-Email mit einem Fehlerstatus, wenn der Link nicht verwendet werden kann (400, 403, 404 oder 500). Deaktiviere dies nur, wenn dein Webserver, CDN oder deine Firewall Fehlerseiten durch eigene ersetzt und Benutzer die Meldung deshalb nie zu sehen bekommen: Sie wird dann mit dem Statuscode 200 gesendet. In beiden Fällen werden die Seiten nie zwischengespeichert."
 PLG_SYSTEM_BFSTOP_ENABLED="aktiviert"
 PLG_SYSTEM_BFSTOP_DISABLED="deaktiviert"
 PLG_SYSTEM_BFSTOP_NOTIFY_UNLIMITED="unbegrenzt"
diff --git a/language/en-GB/en-GB.plg_system_bfstop.sys.ini b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
index fbf5390..7a2b7d2 100644
--- a/language/en-GB/en-GB.plg_system_bfstop.sys.ini
+++ b/language/en-GB/en-GB.plg_system_bfstop.sys.ini
@@ -33,7 +33,7 @@ PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_DESC="When turned on, a user whose usernam
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_KNOWN="enabled, only if the user has logged in from that IP address before (recommended)"
 PLG_SYSTEM_BFSTOP_NOTIFY_BLOCKED_USER_ANY="enabled, for any IP address (anybody can make this send an email to a user)"
 PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_LABEL="Use HTTP Error"
-PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="If enabled (recommended), bfstop answers requests from a blocked IP address with the status code 403 (Forbidden). Switch this off only if your web server, CDN or firewall replaces 403 pages with its own error page, so that blocked users never get to see the block message: it is then sent with status 200 instead. Either way, the page is never cached."
+PLG_SYSTEM_BFSTOP_USE_HTTP_ERROR_DESC="If enabled (recommended), bfstop answers requests from a blocked IP address with the status code 403 (Forbidden), and the unblock page of the link in the notification email with an error status when the link can't be used (400, 403, 404 or 500). Switch this off only if your web server, CDN or firewall replaces error pages with its own, so that users never get to see the message: it is then sent with status 200 instead. Either way, the pages are never cached."
 PLG_SYSTEM_BFSTOP_ENABLED="enabled"
 PLG_SYSTEM_BFSTOP_DISABLED="disabled"
 PLG_SYSTEM_BFSTOP_NOTIFY_UNLIMITED="unlimited"
diff --git a/tests/Integration/ComponentTest.php b/tests/Integration/ComponentTest.php
index 379a401..2f19a34 100644
--- a/tests/Integration/ComponentTest.php
+++ b/tests/Integration/ComponentTest.php
@@ -142,7 +142,7 @@ public function testTokenUnblockNeedsConfirmationAndTheBlockedIp()
 		$this->assertSame(1, (int) $this->queryValue($tokens));
 
 		// neither does an unknown token
-		$this->assertSame(TokenunblockModel::ResultFailed, $model->process('unknown', true, $ip, $this->logger));
+		$this->assertSame(TokenunblockModel::ResultNotFound, $model->process('unknown', true, $ip, $this->logger));
 		$this->logger->errors = array(); // expected: "token not found" error
 		$this->assertTrue($helper->isIPBlocked($ip));
 
@@ -151,6 +151,30 @@ public function testTokenUnblockNeedsConfirmationAndTheBlockedIp()
 		$this->assertSame(0, (int) $this->queryValue($tokens));
 	}
 
+	public function testTokenUnblockHttpStatus()
+	{
+		$this->assertSame(400, TokenunblockModel::httpStatus(TokenunblockModel::ResultInvalid));
+		$this->assertSame(403, TokenunblockModel::httpStatus(TokenunblockModel::ResultWrongIp));
+		$this->assertSame(404, TokenunblockModel::httpStatus(TokenunblockModel::ResultNotFound));
+		$this->assertSame(500, TokenunblockModel::httpStatus(TokenunblockModel::ResultFailed));
+		// opening the link only asks for confirmation, whatever the token is
+		$this->assertSame(200, TokenunblockModel::httpStatus(TokenunblockModel::ResultConfirm));
+		$this->assertSame(200, TokenunblockModel::httpStatus(TokenunblockModel::ResultUnblocked));
+	}
+
+	public function testExpiredAndUsedTokensAreNotFound()
+	{
+		$ip = '203.0.113.5';
+		$blockId = $this->insert('#__bfstop_bannedip', array('ipaddress' => $ip, 'crdate' => self::minutesAgo(0), 'duration' => 60), 'id');
+		$this->insert('#__bfstop_unblock_token', array('token' => 'expired', 'block_id' => $blockId, 'crdate' => self::minutesAgo(4 * 24 * 60)));
+		$this->insert('#__bfstop_unblock_token', array('token' => 'used', 'block_id' => $blockId, 'crdate' => self::minutesAgo(10)));
+		$model = $this->model(TokenunblockModel::class);
+		$this->assertSame(TokenunblockModel::ResultUnblocked, $model->process('used', true, $ip, $this->logger));
+		$this->assertSame(TokenunblockModel::ResultNotFound, $model->process('used', true, $ip, $this->logger), 'used up');
+		$this->assertSame(TokenunblockModel::ResultNotFound, $model->process('expired', true, $ip, $this->logger));
+		$this->logger->errors = array(); // expected: "token not found" errors
+	}
+
 	public function testTokenUnblockComparesIpv6AddressesNotSpellings()
 	{
 		$blockId = $this->insert('#__bfstop_bannedip', array('ipaddress' => '2001:db8::1', 'crdate' => self::minutesAgo(0), 'duration' => 60), 'id');
diff --git a/tests/Integration/UnblockPageHttpTest.php b/tests/Integration/UnblockPageHttpTest.php
new file mode 100644
index 0000000..68f2cf9
--- /dev/null
+++ b/tests/Integration/UnblockPageHttpTest.php
@@ -0,0 +1,197 @@
+<?php
+/*
+ * @package BFStop Plugin (bfstop) for Joomla!
+ * @author Bernhard Froehler
+ * @copyright (C) Bernhard Froehler
+ * @license GNU/GPLv3 http://www.gnu.org/licenses/gpl-3.0.html
+**/
+namespace Codeling\Bfstop\Tests\Integration;
+
+use Joomla\CMS\Factory;
+
+/**
+ * The unblock page of the component as a visitor gets it: the status and the
+ * headers of the response can't be observed from within a PHP CLI process, so
+ * PHP's built-in web server runs the Joomla site and the requests are real
+ * HTTP requests (from 127.0.0.1). Unlike the other tests, this runs the
+ * plugin and the component as installed in the Joomla site, not the source
+ * checkouts.
+ */
+class UnblockPageHttpTest extends IntegrationTestCase
+{
+	private const Query = 'option=com_bfstop&view=tokenunblock';
+
+	private static $originalParams;
+	private $server;
+	private $port;
+
+	public static function setUpBeforeClass(): void
+	{
+		parent::setUpBeforeClass();
+		if (!getenv('COM_BFSTOP_ROOT'))
+		{
+			self::markTestSkipped('COM_BFSTOP_ROOT not set, see tests/README.md');
+		}
+		$db = Factory::getDbo();
+		$db->setQuery("SELECT params FROM #__extensions WHERE type='plugin' AND element='bfstop'");
+		self::$originalParams = $db->loadResult();
+	}
+
+	public static function tearDownAfterClass(): void
+	{
+		if (self::$originalParams !== null)
+		{
+			$db = Factory::getDbo();
+			$db->setQuery('UPDATE #__extensions SET params='.$db->quote(self::$originalParams).
+				" WHERE type='plugin' AND element='bfstop'");
+			$db->execute();
+		}
+	}
+
+	protected function setUp(): void
+	{
+		parent::setUp();
+		$this->configure();
+		$listener = stream_socket_server('tcp://127.0.0.1:0');
+		$this->port = (int) substr(strrchr(stream_socket_get_name($listener, false), ':'), 1);
+		fclose($listener);
+		// exec: the shell must be replaced by the server, or terminating the
+		// process in tearDown() would leave the server running
+		$this->server = proc_open('exec '.escapeshellarg(PHP_BINARY).' -S 127.0.0.1:'.$this->port.' -t '.
+			escapeshellarg(getenv('JOOMLA_ROOT')), array(0 => array('file', '/dev/null', 'r'),
+			1 => array('file', '/dev/null', 'w'), 2 => array('file', '/dev/null', 'w')), $pipes);
+		for ($i = 0; $i < 50; ++$i)
+		{
+			if (($socket = @fsockopen('127.0.0.1', $this->port)) !== false)
+			{
+				fclose($socket);
+				return;
+			}
+			usleep(100000);
+		}
+		$this->markTestSkipped('could not start the PHP web server');
+	}
+
+	protected function tearDown(): void
+	{
+		if ($this->server)
+		{
+			proc_terminate($this->server);
+			proc_close($this->server);
+		}
+	}
+
+	private function configure(array $params = array())
+	{
+		$this->setPluginParams(json_encode($params + array('blockMode' => 'full', 'logLevel' => 8)));
+	}
+
+	/** @return array [status, lower-cased headers, body] */
+	private function request($method, $query, $post = '')
+	{
+		$context = stream_context_create(array('http' => array('method' => $method, 'ignore_errors' => true,
+			'follow_location' => 0, 'content' => $post,
+			'header' => $method === 'POST' ? 'Content-Type: application/x-www-form-urlencoded' : '')));
+		$body = file_get_contents('http://127.0.0.1:'.$this->port.'/index.php?'.$query, false, $context);
+		$headers = array();
+		foreach ($http_response_header as $line)
+		{
+			if (preg_match('#^HTTP/\S+ (\d+)#', $line, $m))
+			{
+				$status = (int) $m[1];
+			}
+			elseif (strpos($line, ':') !== false)
+			{
+				list($name, $value) = explode(':', $line, 2);
+				$headers[strtolower($name)][] = trim($value);
+			}
+		}
+		return array($status, $headers, $body);
+	}
+
+	private function token($token, $blockedIp = '203.0.113.9')
+	{
+		$blockId = $this->insert('#__bfstop_bannedip', array('ipaddress' => $blockedIp,
+			'crdate' => self::minutesAgo(0), 'duration' => 60), 'id');
+		$this->insert('#__bfstop_unblock_token', array('token' => $token, 'block_id' => $blockId, 'crdate' => self::minutesAgo(1)));
+		return $blockId;
+	}
+
+	private function tokenCount()
+	{
+		return (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_unblock_token');
+	}
+
+	public function testLinkWithoutTokenIsABadRequest()
+	{
+		list($status, , $body) = $this->request('GET', self::Query);
+		$this->assertSame(400, $status);
+		$this->assertStringContainsString('Invalid call', $body);
+	}
+
+	public function testOpeningTheLinkAsksForConfirmationWhateverTheToken()
+	{
+		$this->token('realtoken');
+		foreach (array('realtoken', 'unknowntoken') as $token)
+		{
+			list($status, , $body) = $this->request('GET', self::Query.'&token='.$token);
+			$this->assertSame(200, $status, $token);
+			$this->assertStringContainsString('Unblock my IP address', $body);
+		}
+		$this->assertSame(1, $this->tokenCount(), 'nothing was used up');
+	}
+
+	public function testWrongIpAddressIsForbidden()
+	{
+		$this->token('realtoken', '203.0.113.9'); // the request comes from 127.0.0.1
+		list($status, , $body) = $this->request('POST', self::Query, 'token=realtoken');
+		$this->assertSame(403, $status);
+		$this->assertStringContainsString('only unblock the IP address it was issued for', $body, 'the message is still shown');
+		$this->assertSame(1, $this->tokenCount());
+	}
+
+	public function testUnknownTokenIsNotFound()
+	{
+		list($status, , $body) = $this->request('POST', self::Query, 'token=unknowntoken');
+		$this->assertSame(404, $status);
+		$this->assertStringContainsString('Could not unblock', $body);
+	}
+
+	public function testUnblockSucceeds()
+	{
+		$blockId = $this->token('realtoken', '127.0.0.1');
+		list($status, , $body) = $this->request('POST', self::Query, 'token=realtoken');
+		$this->assertSame(200, $status);
+		$this->assertStringContainsString('Successfully unblocked', $body);
+		$this->assertSame(0, $this->tokenCount());
+		$this->assertSame(1, (int) $this->queryValue('SELECT COUNT(*) FROM #__bfstop_unblock WHERE block_id='.$blockId));
+		// and using the link again finds nothing
+		list($status) = $this->request('POST', self::Query, 'token=realtoken');
+		$this->assertSame(404, $status);
+	}
+
+	public function testErrorStatusesFollowTheUseHttpErrorSetting()
+	{
+		$this->configure(array('useHttpError' => 0));
+		$this->token('realtoken', '203.0.113.9');
+		foreach (array(array('GET', self::Query, ''), array('POST', self::Query, 'token=unknowntoken'),
+			array('POST', self::Query, 'token=realtoken')) as $request)
+		{
+			list($status, , $body) = $this->request(...$request);
+			$this->assertSame(200, $status, 'the message must reach the user: '.implode(' ', $request));
+			$this->assertNotSame('', trim(strip_tags($body)));
+		}
+	}
+
+	public function testTheLinkIsKeptSecret()
+	{
+		$this->token('realtoken');
+		foreach (array(array('GET', self::Query.'&token=realtoken', ''), array('POST', self::Query, 'token=unknowntoken')) as $request)
+		{
+			list(, $headers) = $this->request(...$request);
+			$this->assertStringContainsString('no-store', implode(',', $headers['cache-control'] ?? array()), 'not cached');
+			$this->assertSame(array('no-referrer'), $headers['referrer-policy'] ?? null);
+			$this->assertSame(array('noindex, nofollow'), $headers['x-robots-tag'] ?? null);
+		}
+	}
+}
diff --git a/tests/README.md b/tests/README.md
index c941dde..dffdf7d 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -8,6 +8,13 @@
   to Joomla events as on a live site (failed logins, requests from blocked
   addresses). Skipped if `JOOMLA_ROOT` is not set.
 
+One integration test, `UnblockPageHttpTest`, makes real HTTP requests to PHP's
+built-in web server running the Joomla site (the status and headers of a
+response can't be seen from a CLI process): it tests the plugin and component
+as *installed* in the site, so after changing them, copy them there first
+(`./deploy.sh <joomla dir>` in each checkout, or run
+`tests/ci/install-joomla.sh` again).
+
 The classes under test are always loaded from this checkout (and the
 component checkout), not from the copies installed into the Joomla site, so
 the site only needs to be set up again when the database schema changes.