Login Throttling

# Login Throttling
# See docs/features/MVP-login_throttling.md for the full spec.

CREATE TABLE `login_attempts` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `ip` varchar(45) NOT NULL COMMENT 'IPv4 or IPv6',
  `username_hash` char(64) NOT NULL COMMENT 'SHA-256 of trimmed, lowercased username; raw username is never stored',
  `created` datetime NOT NULL,
  PRIMARY KEY (`id`),
  KEY `ip_username_created` (`ip`, `username_hash`, `created`),
  KEY `created` (`created`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

<?php
declare(strict_types=1);

namespace App\Model\Table;

use Cake\I18n\FrozenTime;
use Cake\ORM\Table;

/**
 * Login Throttling - failed password logins per IP + username.
 * See docs/features/MVP-login_throttling.md
 *
 * Rolling window: a key is blocked while it has $maxFailures or more failures
 * inside the last $windowMinutes. The block lifts as old failures age out.
 * An IP is also blocked for every username once it has $maxFailuresPerIp
 * failures in the window, so rotating usernames does not give unlimited
 * password checks.
 *
 * NO GROUP SCOPE (deliberate AGENTS.md exception): attempts are recorded
 * before anyone is logged in, so there is no group_id / user_id to scope by.
 * Deletes are limited instead: rows older than the window (purge), or the
 * exact ip + username_hash of a successful login (clear). Nothing deletes all rows.
 */
class LoginAttemptsTable extends Table
{
    protected int $maxFailures = 5;
    protected int $maxFailuresPerIp = 50;
    protected int $windowMinutes = 5;

    // Set by setKey(), used by the public methods
    private array $key = [];

    public function initialize(array $config): void
    {
        parent::initialize($config);
        $this->setTable('login_attempts');
    }

    public function settings(): array
    {
        return [
            'STATUS' => 200,
            'MSG' => 'Login throttling settings',
            'maxFailures' => $this->maxFailures,
            'maxFailuresPerIp' => $this->maxFailuresPerIp,
            'windowMinutes' => $this->windowMinutes,
        ];
    }

    public function isBlocked(string $ip, string $username): array
    {
        if (!$this->setKey($ip, $username)) {
            return ['STATUS' => 400, 'MSG' => 'IP is required'];
        }

        $since = ['created >=' => $this->windowStart()];
        $blocked = $this->find()->where($this->key + $since)->count() >= $this->maxFailures
            || $this->find()->where(['ip' => $this->key['ip']] + $since)->count() >= $this->maxFailuresPerIp;

        return [
            'STATUS' => 200,
            'MSG' => $blocked ? 'Too many failed attempts' : 'Not blocked',
            'blocked' => $blocked,
        ];
    }

    public function recordFailure(string $ip, string $username): array
    {
        if (!$this->setKey($ip, $username)) {
            return ['STATUS' => 400, 'MSG' => 'IP is required'];
        }

        $entity = $this->newEntity($this->key + ['created' => FrozenTime::now()]);
        if (!$this->save($entity)) {
            return ['STATUS' => 500, 'MSG' => 'Failed attempt not saved'];
        }

        // Precondition: only rows already outside the window are purged
        $this->deleteAll(['created <' => $this->windowStart()]);

        return ['STATUS' => 200, 'MSG' => 'Failed attempt recorded'];
    }

    public function clearFailures(string $ip, string $username): array
    {
        if (!$this->setKey($ip, $username)) {
            return ['STATUS' => 400, 'MSG' => 'IP is required'];
        }

        // Filter on the full key in the same query: a different user is never touched
        $deleted = $this->deleteAll($this->key);

        return ['STATUS' => 200, 'MSG' => 'Failed attempts cleared', 'deleted' => $deleted];
    }

    // The raw username is never stored: people sometimes type their password into it
    private function setKey(string $ip, string $username): bool
    {
        $ip = trim($ip);
        if ($ip === '') {
            return false;
        }

        $this->key = [
            'ip' => $ip,
            'username_hash' => hash('sha256', mb_strtolower(trim($username))),
        ];

        return true;
    }

    private function windowStart(): FrozenTime
    {
        return FrozenTime::now()->subMinutes($this->windowMinutes);
    }
}

<?php
declare(strict_types=1);

namespace App\Authenticator;

use Authentication\Authenticator\FormAuthenticator;
use Authentication\Authenticator\Result;
use Authentication\Authenticator\ResultInterface;
use Authentication\Identifier\IdentifierInterface;
use Cake\ORM\Locator\LocatorAwareTrait;
use Psr\Http\Message\ServerRequestInterface;

/**
 * Login Throttling - FormAuthenticator that refuses a login POST while its
 * IP + username has too many recent failures. See docs/features/MVP-login_throttling.md
 *
 * The check runs here, before the password is verified. By the time a
 * controller runs, a correct password has already logged the user in.
 *
 * Proxies are only trusted when TRUSTED_PROXIES (comma-separated IPs) is set.
 */
class ThrottledFormAuthenticator extends FormAuthenticator
{
    use LocatorAwareTrait;

    public const FAILURE_THROTTLED = 'FAILURE_THROTTLED';

    public function authenticate(ServerRequestInterface $request): ResultInterface
    {
        // Not the login URL or no credentials posted: no password is checked, nothing to count
        if (!$this->_checkUrl($request) || $this->_getData($request) === null) {
            return parent::authenticate($request);
        }

        $ip = $this->clientIp($request);
        $username = (string)$this->_getData($request)[IdentifierInterface::CREDENTIAL_USERNAME];
        $attempts = $this->fetchTable('LoginAttempts');

        if ($attempts->isBlocked($ip, $username)['blocked'] ?? false) {
            return new Result(null, self::FAILURE_THROTTLED, ['Too many failed login attempts']);
        }

        $result = parent::authenticate($request);
        if ($result->isValid()) {
            $attempts->clearFailures($ip, $username);
        } else {
            $attempts->recordFailure($ip, $username);
        }

        return $result;
    }

    // Not ServerRequest::setTrustedProxies(): CakePHP then trusts X-Forwarded-For
    // without checking that the request really came from a listed proxy
    private function clientIp(ServerRequestInterface $request): string
    {
        $remote = trim((string)($request->getServerParams()['REMOTE_ADDR'] ?? ''));
        $proxies = (string)(get_cfg_var('TRUSTED_PROXIES') ?: env('TRUSTED_PROXIES') ?: '');
        $proxies = array_values(array_filter(array_map('trim', explode(',', $proxies))));
        if (!in_array($remote, $proxies, true)) {
            return $remote;
        }

        // Right to left: the first address that is not one of our proxies is the client
        $forwarded = array_map('trim', explode(',', $request->getHeaderLine('X-Forwarded-For')));
        foreach (array_reverse($forwarded) as $ip) {
            if ($ip !== '' && !in_array($ip, $proxies, true)) {
                return $ip;
            }
        }

        return $remote;
    }
}