Challenges.php

<?php

namespace Kirby\Auth;

use Kirby\Auth\Exception\ChallengeTimeoutException;
use Kirby\Cms\App;
use Kirby\Cms\User;
use Kirby\Exception\InvalidArgumentException;
use Kirby\Exception\LogicException;
use Kirby\Exception\NotFoundException;
use Kirby\Exception\PermissionException;
use Kirby\Exception\UserNotFoundException;
use Kirby\Session\Session;
use Kirby\Toolkit\A;
use SensitiveParameter;
use Throwable;

/**
 * Handler for all auth challenges
 *
 * @copyright Bastian Allgeier
 * @license   https://getkirby.com/license
 * @since     6.0.0
 */
class Challenges
{
	/**
	 * Available auth challenge classes
	 * from the core and plugins
	 */
	public static array $challenges = [];

	public function __construct(
		protected Auth $auth,
		protected App $kirby
	) {
	}

	public function available(User $user, string $mode): array
	{
		return array_values(A::filter(
			$this->enabled(),
			fn ($type) => $this->class($type)::isAvailable($user, $mode)
		));
	}

	/**
	 * Returns the challenge handler class for the provided type
	 */
	public function class(string $type): string
	{
		if (
			($class = static::$challenges[$type] ?? null) &&
			is_subclass_of($class, Challenge::class) === true
		) {
			/** @var class-string<Challenge> $class */
			return $class;
		}

		throw new NotFoundException(
			message: 'No auth challenge class for: ' . $type
		);
	}

	public function clear(Session $session): void
	{
		$session->remove('kirby.challenge.data');
		$session->remove('kirby.challenge.email');
		$session->remove('kirby.challenge.mode');
		$session->remove('kirby.challenge.timeout');
		$session->remove('kirby.challenge.type');
	}

	/**
	 * Creates the first available challenge for the user
	 * and stores state in the session
	 */
	public function create(
		Session $session,
		string $email,
		string $mode,
	): Challenge {
		// rate-limit the number of challenges for DoS/DDoS protection
		$this->auth->limits()->ensure($email);

		// challenge creation is not a login attempt,
		// do not fire user.login:failed; hook is triggered below
		// when the user lookup fails
		$this->auth->limits()->track($email, triggerHook: false);

		// try to find the provided user
		$user = $this->kirby->user($email);

		if ($user === null) {
			$this->kirby->trigger('user.login:failed', ['email' => $email]);
			throw new UserNotFoundException(name: $email);
		}

		// try to find a challenge that is available for that user
		if ($challenge = $this->firstAvailable($user, $mode)) {
			$this->store($session, $challenge, $email, $mode);
			return $challenge;
		}

		throw new LogicException(
			message: 'Could not find a suitable authentication challenge'
		);
	}

	/**
	 * Returns normalized array of enabled challenges
	 * by the `auth.challenges` config option
	 */
	public function enabled(): array
	{
		$config = $this->kirby->option('auth.challenges', ['webauthn', 'totp', 'email']);

		return array_values(A::filter(
			A::wrap($config),
			fn ($type) => $this->class($type)::isEnabled($this->auth)
		));
	}

	/**
	 * Checks if an active challenge exists or fails otherwise
	 *
	 * @throws InvalidArgumentException
	 */
	protected function ensureActiveChallenge(Session $session): string
	{
		// check if we have an active challenge
		$email = $session->get('kirby.challenge.email');
		$type  = $session->get('kirby.challenge.type');

		if (is_string($email) !== true || is_string($type) !== true) {
			throw new InvalidArgumentException(
				fallback: 'No authentication challenge is active'
			);
		}

		return $email;
	}

	protected function ensureNotTimeout(Session $session): int|null
	{
		// time-limiting; check this early so that we can
		// destroy the session no matter if the user exists
		// (avoids leaking user information to attackers)
		$timeout = $session->get('kirby.challenge.timeout');

		// challenge timed out
		if ($timeout !== null && time() > $timeout) {
			// clear stale challenge data before throwing
			// so that even if the exception is swallowed upstream,
			// the expired challenge cannot be reused
			$this->clear($session);
			throw new ChallengeTimeoutException();
		}

		return $timeout;
	}

	/**
	 * Returns the first available auth challenge
	 * for the user and purpose/mode
	 */
	public function firstAvailable(User $user, string $mode): Challenge|null
	{
		$available = $this->available($user, $mode);
		$type      = array_shift($available);
		return $type !== null ? $this->get($type, $user, $mode) : null;
	}

	/**
	 * Returns an instance of the requested auth challenge.
	 * (This is based on the config. You might need to check
	 * yourself if the method should be available in your context)
	 */
	public function get(
		string $type,
		User $user,
		string $mode,
		int|null $timeout = null
	): Challenge {
		$challenge = $this->class($type);
		$timeout ??= $this->timeout();

		return new $challenge(
			user:    $user,
			mode:    $mode,
			timeout: $timeout
		);
	}

	/**
	 * Checks whether at least one challenge is available
	 * for the user and purpose/mode
	 */
	public function hasAvailable(User $user, string $mode): bool
	{
		return $this->available($user, $mode) !== [];
	}

	/**
	 * Writes challenge state into the session
	 */
	protected function store(
		Session $session,
		Challenge $challenge,
		string $email,
		string $mode
	): void {
		$data    = $challenge->create();
		$timeout = $this->timeout();

		$session->set('kirby.challenge.email', $email);
		$session->set('kirby.challenge.type', $challenge->type());
		$session->set('kirby.challenge.mode', $mode);
		$session->set('kirby.challenge.timeout', time() + $timeout);

		if ($data !== null) {
			$session->set('kirby.challenge.data', $data->toArray());
		}
	}

	/**
	 * Switches the active challenge within an existing pending session
	 */
	public function switch(Session $session, string $type): Challenge
	{
		$this->ensureNotTimeout($session);

		$email = $session->get('kirby.challenge.email');
		$mode  = $session->get('kirby.challenge.mode');

		if (is_string($email) !== true || is_string($mode) !== true) {
			throw new InvalidArgumentException(
				fallback: 'No authentication challenge is active'
			);
		}

		$user = $this->kirby->user($email);

		if ($user === null) {
			throw new UserNotFoundException(name: $email);
		}

		// keep existing challenge if the requested type is same
		if ($session->get('kirby.challenge.type') === $type) {
			return $this->get($type, $user, $mode);
		}

		// rate-limiting:
		// each switch can trigger side effects (e.g. email sends),
		// so it must consume budget just like ::create()
		$this->auth->limits()->ensure($email);
		$this->auth->limits()->track($email, triggerHook: false);

		// check if new challenge is available for the user and mode
		$available = $this->available($user, $mode);

		if (in_array($type, $available) === false) {
			throw new InvalidArgumentException(
				fallback: 'The requested challenge is not available'
			);
		}

		// clear existing challenge
		$this->clear($session);

		// create new challenge and store in session
		$challenge = $this->get($type, $user, $mode);
		$this->store($session, $challenge, $email, $mode);

		return $challenge;
	}

	public function timeout(): int|null
	{
		return $this->kirby->option('auth.challenge.timeout', 10 * 60);
	}

	/**
	 * Verifies and return the current challenge
	 */
	public function verify(
		Session $session,
		#[SensitiveParameter]
		mixed $input
	): Challenge {
		// ensure we have an active challenge for a valid user
		$timeout = $this->ensureNotTimeout($session);
		$email   = $this->ensureActiveChallenge($session);
		$user    = $this->kirby->user($email);

		if ($user === null) {
			throw new UserNotFoundException(name: $email);
		}

		$this->auth->limits()->ensure($email);

		$type      = $session->get('kirby.challenge.type');
		$mode      = $session->get('kirby.challenge.mode');
		$data      = $session->get('kirby.challenge.data');
		$data      = Pending::from($data ?? []);
		$challenge = $this->get($type, $user, $mode, $timeout);

		try {
			if ($challenge->verify($input, $data) !== true) {
				throw new PermissionException(key: 'access.code');
			}
		} catch (Throwable $e) {
			// a single-use challenge signs a one-time
			// nonce that must not survive a failed attempt
			if ($challenge->isSingleUse() === true) {
				$this->clear($session);
			}

			throw $e;
		}

		return $challenge;
	}
}