Security hardening: block bypasses, unblock mails, usernames, IPv6, .htaccess

[codeling]

What this does

Fixes the findings of a security review of the plugin and the component. The component side is in codeling/com_bfstop#15.

High severity

• Unblock token bypass: any request with view=tokenunblock and an existing token let a blocked IP through, and such a request never used the token up, so anybody who got one emailed (e.g. 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 written to the log.
• Forged client IP behind a proxy: the first public entry of X-Forwarded-For was used, but proxies append to what the client sent, so it was attacker-controlled (block evasion, framing other addresses, impersonating an allowlisted one). 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; an unparseable last hop falls back to REMOTE_ADDR.

Medium severity

• Delay before recording: the failed login is now recorded, counted and checked against the threshold before the delay, and a request whose IP just got (or is) blocked isn't delayed. Before, a burst of parallel attempts all ran before the first was counted and each held a worker for the whole delay.
• Passwords typed as usernames: usernames that don't belong to an account (and aren't on the common-usernames list) are stored, shown, logged and mailed as a keyed hash by default. New setting unknownUsernameMode (hash|plain).
• Unblock mails: no unblock link if the failed logins that led to the block also went against other existing accounts; the notifyBlockedUser setting now has three values (off / only if the user has logged in from the blocked IP or its IPv6 network before / any IP, but at most one usable link per user at a time). The username a link was sent to is stored with its token (unblock_token.username).

Low severity

• .htaccess: only valid IPs/subnets are written, the 403 message is escaped, and read-modify-write cycles hold a lock (24 parallel writers lost entries without it).
• Block page: never cached (Cache-Control: no-store), HTTP 403 by default, set with http_response_code() (not a raw HTTP/1.0 status line, which hard-coded the protocol version).
• IPv6 clients are tracked per network (default /64, setting ipv6PrefixLength); IPv4-mapped, NAT64, 6to4 and Teredo addresses stay per address.
• Log rotation at 5 MB; username statistics capped at 10000 rows; expired unblock tokens are deleted by the daily maintenance (before: only if somebody visited the unblock page, or by the purge by age, which is off by default).
• The daily maintenance only updates its own lastPurge value instead of writing back stale settings, and runs even with purge age 0.
• Known IPs (where users logged in from) are remembered by network for IPv6, forgotten after a year and capped at 100000 rows.
• GeoIP path: no stream wrappers. SECURITY.md rewritten.

Things to know when reviewing

• Behaviour changes: notifyBlockedUser = 1 now means "only for IPs the user logged in from before"; the old behaviour is value 2. IPv6 tracking per /64 is on by default. The block page answers 403 if useHttpError was never saved (the form already defaulted to that); the setting's help text now says when to turn it off, and that it also covers the unblock page's error statuses (component PR). Details are in the CHANGELOG.
• Schema: one new nullable column, unblock_token.username, added to the 2.0.0 install and update scripts (2.0.0 is unreleased, so no extra migration). The PostgreSQL install script was run against a scratch database; the MySQL scripts are exercised by CI.
• Not covered: an attacker with an account of their own can still get blocked and use the unblock link of that account from their own IP (the designed feature). The confirmation step, IP binding and the other-accounts check limit what that gains them.

Testing

283 tests, 1069 assertions, all passing locally against Joomla 5.4.8 with PostgreSQL 16 and the component from the paired branch (1 skipped: a file-permission test that can't fail as root); CI covers MySQL, MariaDB, PostgreSQL, Joomla 5 and 6. Regression tests were checked to fail without the corresponding fix. UnblockPageHttpTest runs the installed Joomla site on PHP's built-in web server to check the real status and headers of the unblock page (CLI processes can't see them); it tests the plugin and component as installed in the site, which tests/README.md now says.

Merge together

Needs codeling/com_bfstop#15 from the branch of the same name (CI picks the component branch by name). Merge both, and release them together.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R3snnF5dGbTM4SazFxGY7q

[codeling]

Addressed the two review comments in c3ecae6 (replying here because the threads belong to a pending review, which doesn't allow replies):

• Bfstop.php, "does http/1.0 apply for all http versions?" No, it hard-coded the protocol version in a raw status header, and HTTP/2 has no status line at all. The block page now sets its status with http_response_code(403) (new Bfstop::blockedResponseCode(), null when "use HTTP error" is off), which leaves the protocol to the web server. The existing tests of the actual status (403 by default, not when switched off) cover it.
• DatabaseHelper.php, "tokens that have outlived their usefulness are not removed?" They weren't, reliably: used tokens were deleted on use and expired ones when somebody visited the unblock page or by the purge by age, which only runs if a purge age is configured (default 0). The daily maintenance now also calls the new DatabaseHelper::purgeExpiredUnblockTokens(), which deletes every token older than the 3 days of validity, whatever the purge age is. Covered by a test of the method and by the maintenance test (checked to fail without the call).

I resolved both threads; reopen them if you'd like to look at them first.

---

Generated by Claude Code