PermissionManager: Add PermissionErrorAudit hook

Add a new hook, PermissionErrorAudit, to
PermissionsManager::getPermissionErrorsInternal for keeping track of
permission errors.

Bug: T306018
Change-Id: I7e31c909d1f617c106cb6d40dbb4e0646ccc9cb4

RELEASE-NOTES-1.39

@@ -93,6 +93,9 @@ For notes on 1.38.x and older releases, see HISTORY.
 === New developer features in 1.39 ===
 * JsonValidateSaveHook has been added to allow extensions to set additional
   pre-save validations for specific JSON pages (T313254)
+* Added 'PermissionErrorAudit' hook, enabling extensions to audit permission
+  errors on specfic actions. For instance account registration failed attempts
+  due to a block (T306018).
 * …
 
 === External library changes in 1.39 ===

includes/HookContainer/HookRunner.php

@@ -471,6 +471,7 @@ class HookRunner implements
 	\MediaWiki\Page\Hook\ShowMissingArticleHook,
 	\MediaWiki\Page\Hook\WikiPageDeletionUpdatesHook,
 	\MediaWiki\Page\Hook\WikiPageFactoryHook,
+	\MediaWiki\Permissions\Hook\PermissionErrorAuditHook,
 	\MediaWiki\Permissions\Hook\GetUserPermissionsErrorsExpensiveHook,
 	\MediaWiki\Permissions\Hook\GetUserPermissionsErrorsHook,
 	\MediaWiki\Permissions\Hook\TitleQuickPermissionsHook,
@@ -1944,6 +1945,20 @@ class HookRunner implements
 		);
 	}
 
+	public function onPermissionErrorAudit(
+		LinkTarget $title,
+		UserIdentity $user,
+		string $action,
+		string $rigor,
+		array $errors
+	): void {
+		$this->container->run(
+			'PermissionErrorAudit',
+			[ $title, $user, $action, $rigor, $errors ],
+			[ 'abortable' => false ]
+		);
+	}
+
 	public function onGetUserPermissionsErrors( $title, $user, $action, &$result ) {
 		return $this->container->run(
 			'getUserPermissionsErrors',

includes/Permissions/Hook/PermissionErrorAuditHook.php

@@ -0,0 +1,35 @@
+<?php
+namespace MediaWiki\Permissions\Hook;
+
+use MediaWiki\Linker\LinkTarget;
+use MediaWiki\User\UserIdentity;
+
+/**
+ * This is a hook handler interface, see docs/Hooks.md
+ * Use the hook name "PermissionErrorAudit" to register handlers implementing this interface.
+ *
+ * @stable to implement
+ * @ingroup Hooks
+ */
+interface PermissionErrorAuditHook {
+	/**
+	 * This hook is called from PermissionManager::getPermissionErrorsInternal()
+	 * to collect internal permission errors and make them available to consumers.
+	 *
+	 * @param LinkTarget $title Page in question
+	 * @param UserIdentity $user User to check
+	 * @param string $action Action being checked
+	 * @param string $rigor One of PermissionManager::RIGOR_ constants
+	 * @param array[] $errors Array of arrays of the arguments to wfMessage to explain permissions problems.
+	 * @return void This hook must not abort, it must return no value
+	 *
+	 * @since 1.39
+	 */
+	public function onPermissionErrorAudit(
+		LinkTarget $title,
+		UserIdentity $user,
+		string $action,
+		string $rigor,
+		array $errors
+	): void;
+}

includes/Permissions/PermissionManager.php

@@ -543,6 +543,9 @@ class PermissionManager {
 		}
 		// remove duplicate errors
 		$errors = array_unique( $errors, SORT_REGULAR );
+		if ( $errors ) {
+			$this->hookRunner->onPermissionErrorAudit( $page, $user, $action, $rigor, $errors );
+		}
 
 		return $errors;
 	}