Automatically generated hook interfaces

Add hook interfaces which were generated by a script which parses
hooks.txt and identifies caller namespaces and directories.

Hook interfaces are mostly placed in a Hook/ subdirectory
relative to the caller location. When there are callers in multiple
directories, a "primary" caller was manually selected. The exceptions to
this are:

* The source root, maintenance and tests, which use includes/Hook. Test
  hooks need to be autoloadable in a non-test request so that
  implementing test interfaces in a generic handler will not fail.
* resources uses includes/resourceloader/Hook
* The following third-level subdirectories had their hooks placed in
  the parent ../Hook:
    * includes/filerepo/file
    * includes/search/searchwidgets
    * includes/specials/forms
    * includes/specials/helpers
    * includes/specials/pagers

Parameters marked as legacy references in hooks.txt are passed
by value in the interfaces.

Bug: T240307
Change-Id: I6efe2e7dd1f0c6a3d0f4d100a4c34e41f8428720

6 files changed, 140 insertions, 0 deletions

diff --git a/includes/auth/Hook/AuthManagerLoginAuthenticateAuditHook.php b/includes/auth/Hook/AuthManagerLoginAuthenticateAuditHook.php
new file mode 100644
index 000000000000..adfa407d7db7
--- /dev/null
+++ b/includes/auth/Hook/AuthManagerLoginAuthenticateAuditHook.php
@@ -0,0 +1,32 @@
+<?php
+
+namespace MediaWiki\Auth\Hook;
+
+/**
+ * @stable for implementation
+ * @ingroup Hooks
+ */
+interface AuthManagerLoginAuthenticateAuditHook {
+	/**
+	 * A login attempt either succeeded or failed
+	 * for a reason other than misconfiguration or session loss. No return data is
+	 * accepted; this hook is for auditing only.
+	 *
+	 * @since 1.35
+	 *
+	 * @param ?mixed $response The MediaWiki\Auth\AuthenticationResponse in either a PASS or FAIL
+	 *   state.
+	 * @param ?mixed $user The User object being authenticated against, or null if authentication
+	 *   failed before getting that far.
+	 * @param ?mixed $username A guess at the user name being authenticated, or null if we can't
+	 *   even determine that. When $user is not null, it can be in the form of
+	 *   <username>@<more info> (e.g. for bot passwords).
+	 * @param ?mixed $extraData An array (string => string) with extra information, intended to be
+	 *   added to log contexts. Fields it might include:
+	 *   - appId: the application ID, only if the login was with a bot password
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onAuthManagerLoginAuthenticateAudit( $response, $user,
+		$username, $extraData
+	);
+}
diff --git a/includes/auth/Hook/ExemptFromAccountCreationThrottleHook.php b/includes/auth/Hook/ExemptFromAccountCreationThrottleHook.php
new file mode 100644
index 000000000000..82bf44fc0f4d
--- /dev/null
+++ b/includes/auth/Hook/ExemptFromAccountCreationThrottleHook.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace MediaWiki\Auth\Hook;
+
+/**
+ * @stable for implementation
+ * @ingroup Hooks
+ */
+interface ExemptFromAccountCreationThrottleHook {
+	/**
+	 * Exemption from the account creation
+	 * throttle.
+	 *
+	 * @since 1.35
+	 *
+	 * @param ?mixed $ip The ip address of the user
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onExemptFromAccountCreationThrottle( $ip );
+}
diff --git a/includes/auth/Hook/LocalUserCreatedHook.php b/includes/auth/Hook/LocalUserCreatedHook.php
new file mode 100644
index 000000000000..e81a3cb281c5
--- /dev/null
+++ b/includes/auth/Hook/LocalUserCreatedHook.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace MediaWiki\Auth\Hook;
+
+/**
+ * @stable for implementation
+ * @ingroup Hooks
+ */
+interface LocalUserCreatedHook {
+	/**
+	 * Called when a local user has been created
+	 *
+	 * @since 1.35
+	 *
+	 * @param ?mixed $user User object for the created user
+	 * @param ?mixed $autocreated Boolean, whether this was an auto-creation
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onLocalUserCreated( $user, $autocreated );
+}
diff --git a/includes/auth/Hook/ResetPasswordExpirationHook.php b/includes/auth/Hook/ResetPasswordExpirationHook.php
new file mode 100644
index 000000000000..2ace42596a36
--- /dev/null
+++ b/includes/auth/Hook/ResetPasswordExpirationHook.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace MediaWiki\Auth\Hook;
+
+/**
+ * @stable for implementation
+ * @ingroup Hooks
+ */
+interface ResetPasswordExpirationHook {
+	/**
+	 * Allow extensions to set a default password expiration
+	 *
+	 * @since 1.35
+	 *
+	 * @param ?mixed $user The user having their password expiration reset
+	 * @param ?mixed &$newExpire The new expiration date
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onResetPasswordExpiration( $user, &$newExpire );
+}
diff --git a/includes/auth/Hook/SecuritySensitiveOperationStatusHook.php b/includes/auth/Hook/SecuritySensitiveOperationStatusHook.php
new file mode 100644
index 000000000000..f2dc494ad925
--- /dev/null
+++ b/includes/auth/Hook/SecuritySensitiveOperationStatusHook.php
@@ -0,0 +1,29 @@
+<?php
+
+namespace MediaWiki\Auth\Hook;
+
+/**
+ * @stable for implementation
+ * @ingroup Hooks
+ */
+interface SecuritySensitiveOperationStatusHook {
+	/**
+	 * Affect the return value from
+	 * MediaWiki\Auth\AuthManager::securitySensitiveOperationStatus().
+	 *
+	 * @since 1.35
+	 *
+	 * @param ?mixed &$status (string) The status to be returned. One of the AuthManager::SEC_*
+	 *   constants. SEC_REAUTH will be automatically changed to SEC_FAIL if
+	 *   authentication isn't possible for the current session type.
+	 * @param ?mixed $operation (string) The operation being checked.
+	 * @param ?mixed $session (MediaWiki\Session\Session) The current session. The
+	 *   currently-authenticated user may be retrieved as $session->getUser().
+	 * @param ?mixed $timeSinceAuth (int) The time since last authentication. PHP_INT_MAX if
+	 *   the time of last auth is unknown, or -1 if authentication is not possible.
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onSecuritySensitiveOperationStatus( &$status, $operation,
+		$session, $timeSinceAuth
+	);
+}
diff --git a/includes/auth/Hook/UserLoggedInHook.php b/includes/auth/Hook/UserLoggedInHook.php
new file mode 100644
index 000000000000..8d87bd954a5a
--- /dev/null
+++ b/includes/auth/Hook/UserLoggedInHook.php
@@ -0,0 +1,19 @@
+<?php
+
+namespace MediaWiki\Auth\Hook;
+
+/**
+ * @stable for implementation
+ * @ingroup Hooks
+ */
+interface UserLoggedInHook {
+	/**
+	 * Called after a user is logged in
+	 *
+	 * @since 1.35
+	 *
+	 * @param ?mixed $user User object for the logged-in user
+	 * @return bool|void True or no return value to continue or false to abort
+	 */
+	public function onUserLoggedIn( $user );
+}