Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace tool_mfa\local\factor;

use stdClass;

/**

 * MFA factor abstract class.

 *

 * @package     tool_mfa

 * @author      Mikhail Golenkov <golenkovm@gmail.com>

 * @copyright   Catalyst IT

 * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

abstract class object_factor_base implements object_factor {

    /** @var string Factor name */

    public $name;

    /** @var int Lock counter */

    private $lockcounter;

    /**

     * Secret manager

     *

     * @var \tool_mfa\local\secret_manager

     */

    protected $secretmanager;

    /** @var string Factor icon */

    protected $icon = 'fa-lock';

    /**

     * Class constructor

     *

     * @param string $name factor name

     */

    public function __construct($name) {

        global $DB, $USER;

        $this->name = $name;

        // Setup secret manager.

        $this->secretmanager = new \tool_mfa\local\secret_manager($this->name);

    }

    /**

     * This loads the locked state from the DB

     * Base class implementation.

     *

     * @return void

     */

    public function load_locked_state(): void {

        global $DB, $USER;

        // Check if lockcounter column exists (incase upgrade hasnt run yet).

        // Only 'input factors' are lockable.

        if ($this->is_enabled() && $this->is_lockable()) {

            try {

                // Setup the lock counter.

                $sql = "SELECT MAX(lockcounter) FROM {tool_mfa} WHERE userid = ? AND factor = ? AND revoked = ?";

                @$this->lockcounter = $DB->get_field_sql($sql, [$USER->id, $this->name, 0]);

                if (empty($this->lockcounter)) {

                    $this->lockcounter = 0;

                }

                // Now lock this factor if over the counter.

                $lockthreshold = get_config('tool_mfa', 'lockout');

                if ($this->lockcounter >= $lockthreshold) {

                    $this->set_state(\tool_mfa\plugininfo\factor::STATE_LOCKED);

                }

            } catch (\dml_exception $e) {

                // Set counter to -1.

                $this->lockcounter = -1;

            }

        }

    }

    /**

     * Returns true if factor is enabled, otherwise false.

     *

     * Base class implementation.

     *

     * @return bool

     * @throws \dml_exception

     */

    public function is_enabled(): bool {

        $status = get_config('factor_'.$this->name, 'enabled');

        if ($status == 1) {

            return true;

        }

        return false;

    }

    /**

     * Returns configured factor weight.

     *

     * Base class implementation.

     *

     * @return int

     * @throws \dml_exception

     */

    public function get_weight(): int {

        $weight = get_config('factor_'.$this->name, 'weight');

        if ($weight) {

            return (int) $weight;

        }

        return 0;

    }

    /**

     * Returns factor name from language string.

     *

     * Base class implementation.

     *

     * @return string

     * @throws \coding_exception

     */

    public function get_display_name(): string {

        return get_string('pluginname', 'factor_'.$this->name);

    }

    /**

     * Returns factor short description from language string.

     *

     * Base class implementation.

     *

     * @return string

     * @throws \coding_exception

     */

    public function get_short_description(): string {

        return get_string('settings:shortdescription', 'factor_'.$this->name);

    }

    /**

     * Returns factor help from language string.

     *

     * Base class implementation.

     *

     * @return string

     * @throws \coding_exception

     */

    public function get_info(): string {

        return get_string('info', 'factor_'.$this->name);

    }

    /**

     * Returns factor help from language string when there is factor management available.

     *

     * Base class implementation.

     *

     * @param int $factorid The factor we want manage info for.

     * @return string

     * @throws \coding_exception

     */

    public function get_manage_info(int $factorid): string {

        return get_string('manageinfo', 'factor_'.$this->name, $this->get_label($factorid));

    }

    /**

     * Defines setup_factor form definition page for particular factor.

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param \MoodleQuickForm $mform

     * @return \MoodleQuickForm $mform

     */

    public function setup_factor_form_definition(\MoodleQuickForm $mform): \MoodleQuickForm {

        return $mform;

    }

    /**

     * Defines setup_factor form definition page after form data has been set.

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param \MoodleQuickForm $mform

     * @return \MoodleQuickForm $mform

     */

    public function setup_factor_form_definition_after_data(\MoodleQuickForm $mform): \MoodleQuickForm {

        return $mform;

    }

    /**

     * Implements setup_factor form validation for particular factor.

     * Returns an array of errors, where array key = field id and array value = error text.

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param array $data

     * @return array

     */

    public function setup_factor_form_validation(array $data): array {

        return [];

    }

    /**

     * Setups in given factor when the form is cancelled

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param int $factorid

     * @return void

     */

    public function setup_factor_form_is_cancelled(int $factorid): void {

    }

    /**

     * Setup submit button string in given factor

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @return string|null

     */

    public function setup_factor_form_submit_button_string(): ?string {

        return null;

    }

    /**

     * Setups given factor and adds it to user's active factors list.

     * Returns true if factor has been successfully added, otherwise false.

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param stdClass $data

     * @return stdClass|null the record if created, or null.

     */

    public function setup_user_factor(stdClass $data): stdClass|null {

        return null;

    }

    /**

     * Replaces a given factor and adds it to user's active factors list.

     * Returns the new factor if it has been successfully replaced.

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param stdClass $data The new factor data.

     * @param int $id The id of the factor to replace.

     * @return stdClass|null the record if created, or null.

     */

    public function replace_user_factor(stdClass $data, int $id): stdClass|null {

        return null;

    }

    /**

     * Returns an array of all user factors of given type (both active and revoked).

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param stdClass $user the user to check against.

     * @return array

     */

    public function get_all_user_factors(stdClass $user): array {

        return [];

    }

    /**

     * Returns an array of active user factor records.

     * Filters get_all_user_factors() output.

     *

     * @param stdClass $user object to check against.

     * @return array

     */

    public function get_active_user_factors(stdClass $user): array {

        $return = [];

        $factors = $this->get_all_user_factors($user);

        foreach ($factors as $factor) {

            if ($factor->revoked == 0) {

                $return[] = $factor;

            }

        }

        return $return;

    }

    /**

     * Defines login form definition page for particular factor.

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param \MoodleQuickForm $mform

     * @return \MoodleQuickForm $mform

     */

    public function login_form_definition(\MoodleQuickForm $mform): \MoodleQuickForm {

        return $mform;

    }

    /**

     * Defines login form definition page after form data has been set.

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param \MoodleQuickForm $mform

     * @return \MoodleQuickForm $mform

     */

    public function login_form_definition_after_data(\MoodleQuickForm $mform): \MoodleQuickForm {

        return $mform;

    }

    /**

     * Implements login form validation for particular factor.

     * Returns an array of errors, where array key = field id and array value = error text.

     *

     * Dummy implementation. Should be overridden in child class.

     *

     * @param array $data

     * @return array

     */

    public function login_form_validation(array $data): array {

        return [];

    }

    /**

     * Returns true if factor class has factor records that might be revoked.

     * It means that user can revoke factor record from their profile.

     *

     * Override in child class if necessary.

     *

     * @return bool

     */

    public function has_revoke(): bool {

        return false;

    }

    /**

     * Marks factor record as revoked.

     * If factorid is not provided, revoke all instances of factor.

     *

     * @param int|null $factorid

     * @return bool

     * @throws \coding_exception

     * @throws \dml_exception

     */

    public function revoke_user_factor(?int $factorid = null): bool {

        global $DB, $USER;

        if (!empty($factorid)) {

            // If we have an explicit factor id, this means we need to be careful about the user.

            $params = ['id' => $factorid];

            $existing = $DB->get_record('tool_mfa', $params);

            if (empty($existing)) {

                return false;

            }

            $matchinguser = $existing->userid == $USER->id;

            if (!is_siteadmin() && !$matchinguser) {

                // We aren't admin, and this isn't our factor.

                return false;

            }

        } else {

            $params = ['userid' => $USER->id, 'factor' => $this->name];

        }

        $DB->set_field('tool_mfa', 'revoked', 1, $params);

        $event = \tool_mfa\event\user_revoked_factor::user_revoked_factor_event($USER, $this->get_display_name());

        $event->trigger();

        return true;

    }

    /**

     * Returns true if factor class has factor records that can be replaced.

     *

     * Override in child class if necessary.

     *

     * @return bool

     */

    public function has_replace(): bool {

        return false;

    }

    /**

     * When validation code is correct - update lastverified field for given factor.

     * If factor id is not provided, update all factor entries for user.

     *

     * @param int|null $factorid

     * @return bool|\dml_exception

     * @throws \dml_exception

     */

    public function update_lastverified(?int $factorid = null): bool|\dml_exception {

        global $DB, $USER;

        if (!empty($factorid)) {

            $params = ['id' => $factorid];

        } else {

            $params = ['factor' => $this->name, 'userid' => $USER->id];

        }

        return $DB->set_field('tool_mfa', 'lastverified', time(), $params);

    }

    /**

     * Gets lastverified timestamp.

     *

     * @param int $factorid

     * @return int|bool the lastverified timestamp, or false if not found.

     */

    public function get_lastverified(int $factorid): int|bool {

        global $DB;

        $record = $DB->get_record('tool_mfa', ['id' => $factorid]);

        return $record->lastverified;

    }

    /**

     * Returns true if factor needs to be setup by user and has setup_form.

     * Override in child class if necessary.

     *

     * @return bool

     */

    public function has_setup(): bool {

        return false;

    }

    /**

     * If has_setup returns true, decides if the setup buttons should be shown on the preferences page.

     *

     * @return bool

     */

    public function show_setup_buttons(): bool {

        return $this->has_setup();

    }

    /**

     * Returns true if a button should be shown to add factors of the same kind on the preferences page.

     * For example, give user's the ability to set up multiple security keys.

     *

     * Override in child class if necessary.

     *

     * @return bool

     */

    public function show_additional_setup_button(): bool {

        return false;

    }

    /**

     * Returns true if a factor requires input from the user to verify.

     *

     * Override in child class if necessary

     *

     * @return bool

     */

    public function has_input(): bool {

        return true;

    }

    /**

     * Returns true if a factor is able to be locked if it fails.

     *

     * Generally only input factors are lockable.

     * Override in child class if necessary

     *

     * @return bool

     */

    public function is_lockable(): bool {

        return $this->has_input();

    }

    /**

     * Returns the state of the factor from session information.

     *

     * Implementation for factors that require input.

     * Should be overridden in child classes with no input.

     *

     * @return mixed

     */

    public function get_state(): string {

        global $SESSION;

        $property = 'factor_'.$this->name;

        if (property_exists($SESSION, $property)) {

            return $SESSION->$property;

        } else {

            return \tool_mfa\plugininfo\factor::STATE_UNKNOWN;

        }

    }

    /**

     * Sets the state of the factor into the session.

     *

     * Implementation for factors that require input.

     * Should be overridden in child classes with no input.

     *

     * @param string $state the state constant to set.

     * @return bool

     */

    public function set_state(string $state): bool {

        global $SESSION;

        // Do not allow overwriting fail states.

        if ($this->get_state() == \tool_mfa\plugininfo\factor::STATE_FAIL) {

            return false;

        }

        $property = 'factor_'.$this->name;

        $SESSION->$property = $state;

        return true;

    }

    /**

     * Creates an event when user successfully setup a factor

     *

     * @param object $user

     * @return void

     */

    public function create_event_after_factor_setup(object $user): void {

        $event = \tool_mfa\event\user_setup_factor::user_setup_factor_event($user, $this->get_display_name());

        $event->trigger();

    }

    /**

     * Function for factor actions in the pass state.

     * Override in child class if necessary.

     *

     * @return void

     */

    public function post_pass_state(): void {

        // Update lastverified for factor.

        if ($this->get_state() == \tool_mfa\plugininfo\factor::STATE_PASS) {

            $this->update_lastverified();

        }

        // Now clean temp secrets for factor.

        $this->secretmanager->cleanup_temp_secrets();

    }

    /**

     * Function to retrieve the label for a factorid.

     *

     * @param int $factorid

     * @return string|\dml_exception

     */

    public function get_label(int $factorid): string|\dml_exception {

        global $DB;

        return $DB->get_field('tool_mfa', 'label', ['id' => $factorid]);

    }

    /**

     * Function to get urls that should not be redirected from.

     *

     * @return array

     */

    public function get_no_redirect_urls(): array {

        return [];

    }

    /**

     * Function to get possible states for a user from factor.

     * Implementation where state is based on deterministic user data.

     * This should be overridden in factors where state is non-deterministic.

     * E.g. IP changes based on whether a user is using a VPN.

     *

     * @param stdClass $user

     * @return array

     */

    public function possible_states(stdClass $user): array {

        return [$this->get_state()];

    }

    /**

     * Returns condition for passing factor.

     * Implementation for basic conditions.

     * Override for complex conditions such as auth type.

     *

     * @return string

     */

    public function get_summary_condition(): string {

        return get_string('summarycondition', 'factor_'.$this->name);

    }

    /**

     * Checks whether the factor combination is valid based on factor behaviour.

     * E.g. a combination with nosetup and another factor is not valid,

     * as you cannot pass nosetup with another factor.

     *

     * @param array $combination array of factors that make up the combination

     * @return bool

     */

    public function check_combination(array $combination): bool {

        return true;

    }

    /**

     * Gets the string for setup button on preferences page.

     *

     * @return string

     */

    public function get_setup_string(): string {

        return get_string('setupfactor', 'tool_mfa');

    }

    /**

     * Gets the string for additional setup button on preferences page.

     * If the user has the ability to set up multiple security keys.

     *

     * Override in child class if necessary.

     *

     * @return string

     */

    public function get_additional_setup_string(): string {

        return get_string('setupfactorbuttonadditional', 'tool_mfa');

    }

    /**

     * Gets the string for manage button on preferences page.

     *

     * @return string

     */

    public function get_manage_string(): string {

        return get_string('managefactor', 'tool_mfa');

    }

    /**

     * Deletes all instances of factor for a user.

     *

     * @param stdClass $user the user to delete for.

     * @return void

     */

    public function delete_factor_for_user(stdClass $user): void {

        global $DB, $USER;

        $DB->delete_records('tool_mfa', ['userid' => $user->id, 'factor' => $this->name]);

        // Emit event for deletion.

        $event = \tool_mfa\event\user_deleted_factor::user_deleted_factor_event($user, $USER, $this->name);

        $event->trigger();

    }

    /**

     * Increments the lock counter for a factor.

     *

     * @return void

     */

    public function increment_lock_counter(): void {

        global $DB, $USER;

        // First make sure the state is loaded.

        $this->load_locked_state();

        // If lockcounter is negative, the field does not exist yet.

        if ($this->lockcounter === -1) {

            return;

        }

        $this->lockcounter++;

        // Update record in DB.

        $DB->set_field('tool_mfa', 'lockcounter', $this->lockcounter, ['userid' => $USER->id, 'factor' => $this->name]);

        // Now lock this factor if over the counter.

        $lockthreshold = get_config('tool_mfa', 'lockout');

        if ($this->lockcounter >= $lockthreshold) {

            $this->set_state(\tool_mfa\plugininfo\factor::STATE_LOCKED);

        }

    }

    /**

     * Return the number of remaining attempts at this factor.

     *

     * @return int the number of attempts at this factor remaining.

     */

    public function get_remaining_attempts(): int {

        $lockthreshold = get_config('tool_mfa', 'lockout');

        if ($this->lockcounter === -1) {

            // If upgrade.php hasnt been run yet, just return 10.

            return $lockthreshold;

        } else {

            return $lockthreshold - $this->lockcounter;

        }

    }

    /**

     * Process a cancel input from a user.

     *

     * @return void

     */

    public function process_cancel_action(): void {

        $this->set_state(\tool_mfa\plugininfo\factor::STATE_NEUTRAL);

    }

    /**

     * Hook point for global auth form action hooks.

     *

     * @param \MoodleQuickForm $mform Form to inject global elements into.

     * @return void

     */

    public function global_definition(\MoodleQuickForm $mform): void {

        return;

    }

    /**

     * Hook point for global auth form action hooks.

     *

     * @param \MoodleQuickForm $mform Form to inject global elements into.

     * @return void

     */

    public function global_definition_after_data(\MoodleQuickForm $mform): void {

        return;

    }

    /**

     * Hook point for global auth form action hooks.

     *

     * @param array $data Data from the form.

     * @param array $files Files form the form.

     * @return array of errors from validation.

     */

    public function global_validation(array $data, array $files): array {

        return [];

    }

    /**

     * Hook point for global auth form action hooks.

     *

     * @param object $data Data from the form.

     * @return void

     */

    public function global_submit(object $data): void {

        return;

    }

    /**

     * Get the icon associated with this factor.

     *

     * @return string the icon name.

     */

    public function get_icon(): string {

        return $this->icon;

    }

    /**

     * Get the login description associated with this factor.

     * Override for factors that have a user input.

     *

     * @return string The login option.

     */

    public function get_login_desc(): string {

        return get_string('logindesc', 'factor_'.$this->name);

    }

}