ApiAuthManagerHelper.php

Go to the documentation of this file.

<?php
use MediaWiki\Auth\AuthenticationRequest;
use MediaWiki\Auth\AuthenticationResponse;
use MediaWiki\Auth\AuthManager;
use MediaWiki\Auth\CreateFromLoginAuthenticationRequest;
use MediaWiki\Logger\LoggerFactory;
use MediaWiki\MediaWikiServices;
use MediaWiki\Status\Status;
use Wikimedia\ParamValidator\ParamValidator;
 
class ApiAuthManagerHelper {
 
    private $module;
 
    private $messageFormat;
 
    private AuthManager $authManager;
 
    public function __construct( ApiBase $module, AuthManager $authManager = null ) {
        $this->module = $module;
 
        $params = $module->extractRequestParams();
        $this->messageFormat = $params['messageformat'] ?? 'wikitext';
        $this->authManager = $authManager ?: MediaWikiServices::getInstance()->getAuthManager();
    }
 
    public static function newForModule( ApiBase $module, AuthManager $authManager = null ) {
        return new self( $module, $authManager );
    }
 
    private function formatMessage( array &$res, $key, Message $message ) {
        switch ( $this->messageFormat ) {
            case 'none':
                break;
 
            case 'wikitext':
                $res[$key] = $message->setContext( $this->module )->text();
                break;
 
            case 'html':
                $res[$key] = $message->setContext( $this->module )->parseAsBlock();
                $res[$key] = Parser::stripOuterParagraph( $res[$key] );
                break;
 
            case 'raw':
                $params = $message->getParams();
                $res[$key] = [
                    'key' => $message->getKey(),
                    'params' => $params,
                ];
                ApiResult::setIndexedTagName( $params, 'param' );
                break;
        }
    }
 
    public function securitySensitiveOperation( $operation ) {
        $status = $this->authManager->securitySensitiveOperationStatus( $operation );
        switch ( $status ) {
            case AuthManager::SEC_OK:
                return;
 
            case AuthManager::SEC_REAUTH:
                $this->module->dieWithError( 'apierror-reauthenticate' );
                // dieWithError prevents continuation
 
            case AuthManager::SEC_FAIL:
                $this->module->dieWithError( 'apierror-cannotreauthenticate' );
                // dieWithError prevents continuation
 
            default:
                throw new UnexpectedValueException( "Unknown status \"$status\"" );
        }
    }
 
    public static function blacklistAuthenticationRequests( array $reqs, array $remove ) {
        if ( $remove ) {
            $remove = array_fill_keys( $remove, true );
            $reqs = array_filter( $reqs, static function ( $req ) use ( $remove ) {
                return !isset( $remove[get_class( $req )] );
            } );
        }
        return $reqs;
    }
 
    public function loadAuthenticationRequests( $action ) {
        $params = $this->module->extractRequestParams();
 
        $reqs = $this->authManager->getAuthenticationRequests( $action, $this->module->getUser() );
 
        // Filter requests, if requested to do so
        $wantedRequests = null;
        if ( isset( $params['requests'] ) ) {
            $wantedRequests = array_fill_keys( $params['requests'], true );
        } elseif ( isset( $params['request'] ) ) {
            $wantedRequests = [ $params['request'] => true ];
        }
        if ( $wantedRequests !== null ) {
            $reqs = array_filter(
                $reqs,
                static function ( AuthenticationRequest $req ) use ( $wantedRequests ) {
                    return isset( $wantedRequests[$req->getUniqueId()] );
                }
            );
        }
 
        // Collect the fields for all the requests
        $fields = [];
        $sensitive = [];
        foreach ( $reqs as $req ) {
            $info = (array)$req->getFieldInfo();
            $fields += $info;
            $sensitive += array_filter( $info, static function ( $opts ) {
                return !empty( $opts['sensitive'] );
            } );
        }
 
        // Extract the request data for the fields and mark those request
        // parameters as used
        $data = array_intersect_key( $this->module->getRequest()->getValues(), $fields );
        $this->module->getMain()->markParamsUsed( array_keys( $data ) );
 
        if ( $sensitive ) {
            $this->module->getMain()->markParamsSensitive( array_keys( $sensitive ) );
            $this->module->requirePostedParameters( array_keys( $sensitive ), 'noprefix' );
        }
 
        return AuthenticationRequest::loadRequestsFromSubmission( $reqs, $data );
    }
 
    public function formatAuthenticationResponse( AuthenticationResponse $res ) {
        $ret = [
            'status' => $res->status,
        ];
 
        if ( $res->status === AuthenticationResponse::PASS && $res->username !== null ) {
            $ret['username'] = $res->username;
        }
 
        if ( $res->status === AuthenticationResponse::REDIRECT ) {
            $ret['redirecttarget'] = $res->redirectTarget;
            if ( $res->redirectApiData !== null ) {
                $ret['redirectdata'] = $res->redirectApiData;
            }
        }
 
        if ( $res->status === AuthenticationResponse::REDIRECT ||
            $res->status === AuthenticationResponse::UI ||
            $res->status === AuthenticationResponse::RESTART
        ) {
            $ret += $this->formatRequests( $res->neededRequests );
        }
 
        if ( $res->status === AuthenticationResponse::FAIL ||
            $res->status === AuthenticationResponse::UI ||
            $res->status === AuthenticationResponse::RESTART
        ) {
            $this->formatMessage( $ret, 'message', $res->message );
            $ret['messagecode'] = ApiMessage::create( $res->message )->getApiCode();
        }
 
        if ( $res->status === AuthenticationResponse::FAIL ||
            $res->status === AuthenticationResponse::RESTART
        ) {
            $this->module->getRequest()->getSession()->set(
                'ApiAuthManagerHelper::createRequest',
                $res->createRequest
            );
            $ret['canpreservestate'] = $res->createRequest !== null;
        } else {
            $this->module->getRequest()->getSession()->remove( 'ApiAuthManagerHelper::createRequest' );
        }
 
        return $ret;
    }
 
    public function logAuthenticationResult( $event, $result ) {
        if ( is_string( $result ) ) {
            $status = Status::newFatal( $result );
        } elseif ( $result->status === AuthenticationResponse::PASS ) {
            $status = Status::newGood();
        } elseif ( $result->status === AuthenticationResponse::FAIL ) {
            $status = Status::newFatal( $result->message );
        } else {
            return;
        }
 
        $module = $this->module->getModuleName();
        LoggerFactory::getInstance( 'authevents' )->info( "$module API attempt", [
            'event' => $event,
            'status' => strval( $status ),
            'module' => $module,
        ] );
    }
 
    public function getPreservedRequest() {
        $ret = $this->module->getRequest()->getSession()->get( 'ApiAuthManagerHelper::createRequest' );
        return $ret instanceof CreateFromLoginAuthenticationRequest ? $ret : null;
    }
 
    public function formatRequests( array $reqs ) {
        $params = $this->module->extractRequestParams();
        $mergeFields = !empty( $params['mergerequestfields'] );
 
        $ret = [ 'requests' => [] ];
        foreach ( $reqs as $req ) {
            $describe = $req->describeCredentials();
            $reqInfo = [
                'id' => $req->getUniqueId(),
                'metadata' => $req->getMetadata() + [ ApiResult::META_TYPE => 'assoc' ],
            ];
            switch ( $req->required ) {
                case AuthenticationRequest::OPTIONAL:
                    $reqInfo['required'] = 'optional';
                    break;
                case AuthenticationRequest::REQUIRED:
                    $reqInfo['required'] = 'required';
                    break;
                case AuthenticationRequest::PRIMARY_REQUIRED:
                    $reqInfo['required'] = 'primary-required';
                    break;
            }
            $this->formatMessage( $reqInfo, 'provider', $describe['provider'] );
            $this->formatMessage( $reqInfo, 'account', $describe['account'] );
            if ( !$mergeFields ) {
                $reqInfo['fields'] = $this->formatFields( (array)$req->getFieldInfo() );
            }
            $ret['requests'][] = $reqInfo;
        }
 
        if ( $mergeFields ) {
            $fields = AuthenticationRequest::mergeFieldInfo( $reqs );
            $ret['fields'] = $this->formatFields( $fields );
        }
 
        return $ret;
    }
 
    private function formatFields( array $fields ) {
        static $copy = [
            'type' => true,
            'value' => true,
        ];
 
        $module = $this->module;
        $retFields = [];
 
        foreach ( $fields as $name => $field ) {
            $ret = array_intersect_key( $field, $copy );
 
            if ( isset( $field['options'] ) ) {
                $ret['options'] = array_map( static function ( $msg ) use ( $module ) {
                    return $msg->setContext( $module )->plain();
                }, $field['options'] );
                ApiResult::setArrayType( $ret['options'], 'assoc' );
            }
            $this->formatMessage( $ret, 'label', $field['label'] );
            $this->formatMessage( $ret, 'help', $field['help'] );
            $ret['optional'] = !empty( $field['optional'] );
            $ret['sensitive'] = !empty( $field['sensitive'] );
 
            $retFields[$name] = $ret;
        }
 
        ApiResult::setArrayType( $retFields, 'assoc' );
 
        return $retFields;
    }
 
    public static function getStandardParams( $action, ...$wantedParams ) {
        $params = [
            'requests' => [
                ParamValidator::PARAM_TYPE => 'string',
                ParamValidator::PARAM_ISMULTI => true,
                ApiBase::PARAM_HELP_MSG => [ 'api-help-authmanagerhelper-requests', $action ],
            ],
            'request' => [
                ParamValidator::PARAM_TYPE => 'string',
                ParamValidator::PARAM_REQUIRED => true,
                ApiBase::PARAM_HELP_MSG => [ 'api-help-authmanagerhelper-request', $action ],
            ],
            'messageformat' => [
                ParamValidator::PARAM_DEFAULT => 'wikitext',
                ParamValidator::PARAM_TYPE => [ 'html', 'wikitext', 'raw', 'none' ],
                ApiBase::PARAM_HELP_MSG => 'api-help-authmanagerhelper-messageformat',
            ],
            'mergerequestfields' => [
                ParamValidator::PARAM_DEFAULT => false,
                ApiBase::PARAM_HELP_MSG => 'api-help-authmanagerhelper-mergerequestfields',
            ],
            'preservestate' => [
                ParamValidator::PARAM_DEFAULT => false,
                ApiBase::PARAM_HELP_MSG => 'api-help-authmanagerhelper-preservestate',
            ],
            'returnurl' => [
                ParamValidator::PARAM_TYPE => 'string',
                ApiBase::PARAM_HELP_MSG => 'api-help-authmanagerhelper-returnurl',
            ],
            'continue' => [
                ParamValidator::PARAM_DEFAULT => false,
                ApiBase::PARAM_HELP_MSG => 'api-help-authmanagerhelper-continue',
            ],
        ];
 
        $ret = [];
        foreach ( $wantedParams as $name ) {
            if ( isset( $params[$name] ) ) {
                $ret[$name] = $params[$name];
            }
        }
        return $ret;
    }
}