[Summary view]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * MFA factor interface.
  19   *
  20   * @package     tool_mfa
  21   * @author      Mikhail Golenkov <golenkovm@gmail.com>
  22   * @copyright   Catalyst IT
  23   * @license     http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  namespace tool_mfa\local\factor;
  27  
  28  use stdClass;
  29  
  30  interface object_factor {
  31  
  32      /**
  33       * Returns true if factor is enabled, otherwise false.
  34       *
  35       * @return bool
  36       * @throws \dml_exception
  37       */
  38      public function is_enabled(): bool;
  39  
  40      /**
  41       * Returns configured factor weight.
  42       *
  43       * @return int
  44       * @throws \dml_exception
  45       */
  46      public function get_weight(): int;
  47  
  48      /**
  49       * Returns factor name from language string.
  50       *
  51       * @return string
  52       * @throws \coding_exception
  53       */
  54      public function get_display_name(): string;
  55  
  56      /**
  57       * Returns factor info from language string.
  58       *
  59       * @return string
  60       * @throws \coding_exception
  61       */
  62      public function get_info(): string;
  63  
  64      /**
  65       * Defines setup_factor form definition page for particular factor.
  66       *
  67       * @param \MoodleQuickForm $mform
  68       * @return object $mform
  69       * @throws \coding_exception
  70       */
  71      public function setup_factor_form_definition(\MoodleQuickForm $mform): \MoodleQuickForm;
  72  
  73      /**
  74       * Defines setup_factor form definition page after form data has been set.
  75       *
  76       * @param \MoodleQuickForm $mform
  77       * @return object $mform
  78       * @throws \coding_exception
  79       */
  80      public function setup_factor_form_definition_after_data(\MoodleQuickForm $mform): \MoodleQuickForm;
  81  
  82      /**
  83       * Implements setup_factor form validation for particular factor.
  84       * Returns an array of errors, where array key = field id and array value = error text.
  85       *
  86       * @param array $data
  87       * @return array
  88       */
  89      public function setup_factor_form_validation(array $data): array;
  90  
  91      /**
  92       * Defines login form definition page for particular factor.
  93       *
  94       * @param \MoodleQuickForm $mform
  95       * @return object $mform
  96       * @throws \coding_exception
  97       */
  98      public function login_form_definition(\MoodleQuickForm $mform): \MoodleQuickForm;
  99  
 100      /**
 101       * Defines login form definition page after form data has been set.
 102       *
 103       * @param \MoodleQuickForm $mform
 104       * @return object $mform
 105       * @throws \coding_exception
 106       */
 107      public function login_form_definition_after_data(\MoodleQuickForm $mform): \MoodleQuickForm;
 108  
 109      /**
 110       * Implements login form validation for particular factor.
 111       * Returns an array of errors, where array key = field id and array value = error text.
 112       *
 113       * @param array $data
 114       * @return array
 115       */
 116      public function login_form_validation(array $data): array;
 117  
 118      /**
 119       * Setups given factor and adds it to user's active factors list.
 120       * Returns true if factor has been successfully added, otherwise false.
 121       *
 122       * @param stdClass $data
 123       * @return stdClass|null the factor record, or null.
 124       */
 125      public function setup_user_factor(stdClass $data): stdClass|null;
 126  
 127      /**
 128       * Returns an array of all user factors of given type (both active and revoked).
 129       *
 130       * @param stdClass $user the user to check against.
 131       * @return array
 132       */
 133      public function get_all_user_factors(stdClass $user): array;
 134  
 135      /**
 136       * Returns an array of active user factor records.
 137       * Filters get_all_user_factors() output.
 138       *
 139       * @param stdClass $user the user to check against.
 140       * @return array
 141       */
 142      public function get_active_user_factors(stdClass $user): array;
 143  
 144      /**
 145       * Returns true if factor class has factor records that might be revoked.
 146       * It means that user can revoke factor record from their profile.
 147       *
 148       * @return bool
 149       */
 150      public function has_revoke(): bool;
 151  
 152      /**
 153       * Marks factor record as revoked.
 154       * If factorid is not provided, revoke all instances of factor.
 155       *
 156       * @param int|null $factorid
 157       * @return bool
 158       */
 159      public function revoke_user_factor(?int $factorid = null): bool;
 160  
 161      /**
 162       * When validation code is correct - update lastverified field for given factor.
 163       * If factor id is not provided, update all factor entries for user.
 164       *
 165       * @param int|null $factorid
 166       * @return bool|\dml_exception
 167       */
 168      public function update_lastverified(?int $factorid = null): bool|\dml_exception;
 169  
 170      /**
 171       * Gets lastverified timestamp.
 172       *
 173       * @param int $factorid
 174       * @return int|bool
 175       */
 176      public function get_lastverified(int $factorid): int|bool;
 177  
 178      /**
 179       * Returns true if factor needs to be setup by user and has setup_form.
 180       *
 181       * @return bool
 182       */
 183      public function has_setup(): bool;
 184  
 185      /**
 186       * If has_setup returns true, decides if the setup buttons should be shown on the preferences page.
 187       *
 188       * @return bool
 189       */
 190      public function show_setup_buttons(): bool;
 191  
 192      /**
 193       * Returns true if factor requires user input for success or failure during login.
 194       *
 195       * @return bool
 196       */
 197      public function has_input(): bool;
 198  
 199      /**
 200       * Returns the state of the factor check
 201       *
 202       * @return string
 203       */
 204      public function get_state(): string;
 205  
 206      /**
 207       * Sets the state of the factor check into the session.
 208       * Returns whether storing the var was successful.
 209       *
 210       * @param string $state
 211       * @return bool
 212       */
 213      public function set_state(string $state): bool;
 214  
 215      /**
 216       * Fires any additional actions required by the factor once the user reaches the pass state.
 217       *
 218       * @return void
 219       */
 220      public function post_pass_state(): void;
 221  
 222      /**
 223       * Retrieves label for a factorid.
 224       *
 225       * @param int $factorid
 226       * @return string|\dml_exception
 227       */
 228      public function get_label(int $factorid): string|\dml_exception;
 229  
 230      /**
 231       * Returns a list of urls to not redirect from.
 232       *
 233       * @return array
 234       */
 235      public function get_no_redirect_urls(): array;
 236  
 237      /**
 238       * Returns all possible states for a user.
 239       *
 240       * @param stdClass $user
 241       * @return array
 242       */
 243      public function possible_states(stdClass $user): array;
 244  
 245      /**
 246       * Return summary condition for passing factor.
 247       *
 248       * @return string
 249       */
 250      public function get_summary_condition(): string;
 251  
 252      /**
 253       * Checks whether the factor combination is valid based on factor behaviour.
 254       * E.g. a combination with nosetup and another factor is not valid,
 255       * as you cannot pass nosetup with another factor.
 256       *
 257       * @param array $combination array of factors that make up the combination
 258       * @return bool
 259       */
 260      public function check_combination(array $combination): bool;
 261  
 262      /**
 263       * Gets the string for setup button on preferences page.
 264       *
 265       * @return string the string to display on the button.
 266       */
 267      public function get_setup_string(): string;
 268  
 269      /**
 270       * Deletes all instances of a factor for user.
 271       *
 272       * @param stdClass $user the user to delete for.
 273       * @return void
 274       */
 275      public function delete_factor_for_user(stdClass $user): void;
 276  
 277      /**
 278       * Process a cancel action from a user.
 279       *
 280       * @return void
 281       */
 282      public function process_cancel_action(): void;
 283  
 284      /**
 285       * Hook point for global auth form action hooks.
 286       *
 287       * @param \MoodleQuickForm $mform Form to inject global elements into.
 288       * @return void
 289       */
 290      public function global_definition(\MoodleQuickForm $mform): void;
 291  
 292      /**
 293       * Hook point for global auth form action hooks.
 294       *
 295       * @param \MoodleQuickForm $mform Form to inject global elements into.
 296       * @return void
 297       */
 298      public function global_definition_after_data(\MoodleQuickForm $mform): void;
 299  
 300      /**
 301       * Hook point for global auth form action hooks.
 302       *
 303       * @param array $data Data from the form.
 304       * @param array $files Files form the form.
 305       * @return array of errors from validation.
 306       */
 307      public function global_validation(array $data, array $files): array;
 308  
 309      /**
 310       * Hook point for global auth form action hooks.
 311       *
 312       * @param object $data Data from the form.
 313       * @return void
 314       */
 315      public function global_submit(object $data): void;
 316  }