3 * Utility class for bot passwords
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
21 use MediaWiki\Auth\AuthenticationResponse
;
22 use MediaWiki\MediaWikiServices
;
23 use MediaWiki\Session\BotPasswordSessionProvider
;
24 use Wikimedia\Rdbms\IDatabase
;
27 * Utility class for bot passwords
30 class BotPassword
implements IDBAccessObject
{
32 const APPID_MAXLENGTH
= 32;
46 /** @var MWRestrictions */
47 private $restrictions;
53 private $flags = self
::READ_NORMAL
;
56 * @param object $row bot_passwords database row
57 * @param bool $isSaved Whether the bot password was read from the database
58 * @param int $flags IDBAccessObject read flags
60 protected function __construct( $row, $isSaved, $flags = self
::READ_NORMAL
) {
61 $this->isSaved
= $isSaved;
62 $this->flags
= $flags;
64 $this->centralId
= (int)$row->bp_user
;
65 $this->appId
= $row->bp_app_id
;
66 $this->token
= $row->bp_token
;
67 $this->restrictions
= MWRestrictions
::newFromJson( $row->bp_restrictions
);
68 $this->grants
= FormatJson
::decode( $row->bp_grants
);
72 * Get a database connection for the bot passwords database
73 * @param int $db Index of the connection to get, e.g. DB_MASTER or DB_REPLICA.
76 public static function getDB( $db ) {
77 global $wgBotPasswordsCluster, $wgBotPasswordsDatabase;
79 $lbFactory = MediaWikiServices
::getInstance()->getDBLoadBalancerFactory();
80 $lb = $wgBotPasswordsCluster
81 ?
$lbFactory->getExternalLB( $wgBotPasswordsCluster )
82 : $lbFactory->getMainLB( $wgBotPasswordsDatabase );
83 return $lb->getConnectionRef( $db, [], $wgBotPasswordsDatabase );
87 * Load a BotPassword from the database
89 * @param string $appId
90 * @param int $flags IDBAccessObject read flags
91 * @return BotPassword|null
93 public static function newFromUser( User
$user, $appId, $flags = self
::READ_NORMAL
) {
94 $centralId = CentralIdLookup
::factory()->centralIdFromLocalUser(
95 $user, CentralIdLookup
::AUDIENCE_RAW
, $flags
97 return $centralId ? self
::newFromCentralId( $centralId, $appId, $flags ) : null;
101 * Load a BotPassword from the database
102 * @param int $centralId from CentralIdLookup
103 * @param string $appId
104 * @param int $flags IDBAccessObject read flags
105 * @return BotPassword|null
107 public static function newFromCentralId( $centralId, $appId, $flags = self
::READ_NORMAL
) {
108 global $wgEnableBotPasswords;
110 if ( !$wgEnableBotPasswords ) {
114 list( $index, $options ) = DBAccessObjectUtils
::getDBOptions( $flags );
115 $db = self
::getDB( $index );
116 $row = $db->selectRow(
118 [ 'bp_user', 'bp_app_id', 'bp_token', 'bp_restrictions', 'bp_grants' ],
119 [ 'bp_user' => $centralId, 'bp_app_id' => $appId ],
123 return $row ?
new self( $row, true, $flags ) : null;
127 * Create an unsaved BotPassword
128 * @param array $data Data to use to create the bot password. Keys are:
129 * - user: (User) User object to create the password for. Overrides username and centralId.
130 * - username: (string) Username to create the password for. Overrides centralId.
131 * - centralId: (int) User central ID to create the password for.
132 * - appId: (string) App ID for the password.
133 * - restrictions: (MWRestrictions, optional) Restrictions.
134 * - grants: (string[], optional) Grants.
135 * @param int $flags IDBAccessObject read flags
136 * @return BotPassword|null
138 public static function newUnsaved( array $data, $flags = self
::READ_NORMAL
) {
141 'bp_app_id' => isset( $data['appId'] ) ?
trim( $data['appId'] ) : '',
142 'bp_token' => '**unsaved**',
143 'bp_restrictions' => $data['restrictions'] ?? MWRestrictions
::newDefault(),
144 'bp_grants' => $data['grants'] ??
[],
148 $row->bp_app_id
=== '' ||
strlen( $row->bp_app_id
) > self
::APPID_MAXLENGTH ||
149 !$row->bp_restrictions
instanceof MWRestrictions ||
150 !is_array( $row->bp_grants
)
155 $row->bp_restrictions
= $row->bp_restrictions
->toJson();
156 $row->bp_grants
= FormatJson
::encode( $row->bp_grants
);
158 if ( isset( $data['user'] ) ) {
159 if ( !$data['user'] instanceof User
) {
162 $row->bp_user
= CentralIdLookup
::factory()->centralIdFromLocalUser(
163 $data['user'], CentralIdLookup
::AUDIENCE_RAW
, $flags
165 } elseif ( isset( $data['username'] ) ) {
166 $row->bp_user
= CentralIdLookup
::factory()->centralIdFromName(
167 $data['username'], CentralIdLookup
::AUDIENCE_RAW
, $flags
169 } elseif ( isset( $data['centralId'] ) ) {
170 $row->bp_user
= $data['centralId'];
172 if ( !$row->bp_user
) {
176 return new self( $row, false, $flags );
180 * Indicate whether this is known to be saved
183 public function isSaved() {
184 return $this->isSaved
;
188 * Get the central user ID
191 public function getUserCentralId() {
192 return $this->centralId
;
199 public function getAppId() {
207 public function getToken() {
212 * Get the restrictions
213 * @return MWRestrictions
215 public function getRestrictions() {
216 return $this->restrictions
;
223 public function getGrants() {
224 return $this->grants
;
228 * Get the separator for combined user name + app ID
231 public static function getSeparator() {
232 global $wgUserrightsInterwikiDelimiter;
233 return $wgUserrightsInterwikiDelimiter;
240 protected function getPassword() {
241 list( $index, $options ) = DBAccessObjectUtils
::getDBOptions( $this->flags
);
242 $db = self
::getDB( $index );
243 $password = $db->selectField(
246 [ 'bp_user' => $this->centralId
, 'bp_app_id' => $this->appId
],
250 if ( $password === false ) {
251 return PasswordFactory
::newInvalidPassword();
254 $passwordFactory = MediaWikiServices
::getInstance()->getPasswordFactory();
256 return $passwordFactory->newFromCiphertext( $password );
257 } catch ( PasswordError
$ex ) {
258 return PasswordFactory
::newInvalidPassword();
263 * Whether the password is currently invalid
267 public function isInvalid() {
268 return $this->getPassword() instanceof InvalidPassword
;
272 * Save the BotPassword to the database
273 * @param string $operation 'update' or 'insert'
274 * @param Password|null $password Password to set.
275 * @return bool Success
277 public function save( $operation, Password
$password = null ) {
279 'bp_user' => $this->centralId
,
280 'bp_app_id' => $this->appId
,
283 'bp_token' => MWCryptRand
::generateHex( User
::TOKEN_LENGTH
),
284 'bp_restrictions' => $this->restrictions
->toJson(),
285 'bp_grants' => FormatJson
::encode( $this->grants
),
288 if ( $password !== null ) {
289 $fields['bp_password'] = $password->toString();
290 } elseif ( $operation === 'insert' ) {
291 $fields['bp_password'] = PasswordFactory
::newInvalidPassword()->toString();
294 $dbw = self
::getDB( DB_MASTER
);
295 switch ( $operation ) {
297 $dbw->insert( 'bot_passwords', $fields +
$conds, __METHOD__
, [ 'IGNORE' ] );
301 $dbw->update( 'bot_passwords', $fields, $conds, __METHOD__
);
307 $ok = (bool)$dbw->affectedRows();
309 $this->token
= $dbw->selectField( 'bot_passwords', 'bp_token', $conds, __METHOD__
);
310 $this->isSaved
= true;
316 * Delete the BotPassword from the database
317 * @return bool Success
319 public function delete() {
321 'bp_user' => $this->centralId
,
322 'bp_app_id' => $this->appId
,
324 $dbw = self
::getDB( DB_MASTER
);
325 $dbw->delete( 'bot_passwords', $conds, __METHOD__
);
326 $ok = (bool)$dbw->affectedRows();
328 $this->token
= '**unsaved**';
329 $this->isSaved
= false;
335 * Invalidate all passwords for a user, by name
336 * @param string $username User name
337 * @return bool Whether any passwords were invalidated
339 public static function invalidateAllPasswordsForUser( $username ) {
340 $centralId = CentralIdLookup
::factory()->centralIdFromName(
341 $username, CentralIdLookup
::AUDIENCE_RAW
, CentralIdLookup
::READ_LATEST
343 return $centralId && self
::invalidateAllPasswordsForCentralId( $centralId );
347 * Invalidate all passwords for a user, by central ID
348 * @param int $centralId
349 * @return bool Whether any passwords were invalidated
351 public static function invalidateAllPasswordsForCentralId( $centralId ) {
352 global $wgEnableBotPasswords;
354 if ( !$wgEnableBotPasswords ) {
358 $dbw = self
::getDB( DB_MASTER
);
361 [ 'bp_password' => PasswordFactory
::newInvalidPassword()->toString() ],
362 [ 'bp_user' => $centralId ],
365 return (bool)$dbw->affectedRows();
369 * Remove all passwords for a user, by name
370 * @param string $username User name
371 * @return bool Whether any passwords were removed
373 public static function removeAllPasswordsForUser( $username ) {
374 $centralId = CentralIdLookup
::factory()->centralIdFromName(
375 $username, CentralIdLookup
::AUDIENCE_RAW
, CentralIdLookup
::READ_LATEST
377 return $centralId && self
::removeAllPasswordsForCentralId( $centralId );
381 * Remove all passwords for a user, by central ID
382 * @param int $centralId
383 * @return bool Whether any passwords were removed
385 public static function removeAllPasswordsForCentralId( $centralId ) {
386 global $wgEnableBotPasswords;
388 if ( !$wgEnableBotPasswords ) {
392 $dbw = self
::getDB( DB_MASTER
);
395 [ 'bp_user' => $centralId ],
398 return (bool)$dbw->affectedRows();
402 * Returns a (raw, unhashed) random password string.
403 * @param Config $config
406 public static function generatePassword( $config ) {
407 return PasswordFactory
::generateRandomPasswordString(
408 max( 32, $config->get( 'MinimalPasswordLength' ) ) );
412 * There are two ways to login with a bot password: "username@appId", "password" and
413 * "username", "appId@password". Transform it so it is always in the first form.
414 * Returns [bot username, bot password].
415 * If this cannot be a bot password login just return false.
416 * @param string $username
417 * @param string $password
418 * @return array|false
420 public static function canonicalizeLoginData( $username, $password ) {
421 $sep = self
::getSeparator();
422 // the strlen check helps minimize the password information obtainable from timing
423 if ( strlen( $password ) >= 32 && strpos( $username, $sep ) !== false ) {
424 // the separator is not valid in new usernames but might appear in legacy ones
425 if ( preg_match( '/^[0-9a-w]{32,}$/', $password ) ) {
426 return [ $username, $password ];
428 } elseif ( strlen( $password ) > 32 && strpos( $password, $sep ) !== false ) {
429 $segments = explode( $sep, $password );
430 $password = array_pop( $segments );
431 $appId = implode( $sep, $segments );
432 if ( preg_match( '/^[0-9a-w]{32,}$/', $password ) ) {
433 return [ $username . $sep . $appId, $password ];
440 * Try to log the user in
441 * @param string $username Combined user name and app ID
442 * @param string $password Supplied password
443 * @param WebRequest $request
444 * @return Status On success, the good status's value is the new Session object
446 public static function login( $username, $password, WebRequest
$request ) {
447 global $wgEnableBotPasswords, $wgPasswordAttemptThrottle;
449 if ( !$wgEnableBotPasswords ) {
450 return Status
::newFatal( 'botpasswords-disabled' );
453 $manager = MediaWiki\Session\SessionManager
::singleton();
454 $provider = $manager->getProvider( BotPasswordSessionProvider
::class );
456 return Status
::newFatal( 'botpasswords-no-provider' );
459 // Split name into name+appId
460 $sep = self
::getSeparator();
461 if ( strpos( $username, $sep ) === false ) {
462 return self
::loginHook( $username, null, Status
::newFatal( 'botpasswords-invalid-name', $sep ) );
464 list( $name, $appId ) = explode( $sep, $username, 2 );
466 // Find the named user
467 $user = User
::newFromName( $name );
468 if ( !$user ||
$user->isAnon() ) {
469 return self
::loginHook( $user ?
: $name, null, Status
::newFatal( 'nosuchuser', $name ) );
472 if ( $user->isLocked() ) {
473 return Status
::newFatal( 'botpasswords-locked' );
477 if ( !empty( $wgPasswordAttemptThrottle ) ) {
478 $throttle = new MediaWiki\Auth\
Throttler( $wgPasswordAttemptThrottle, [
479 'type' => 'botpassword',
480 'cache' => ObjectCache
::getLocalClusterInstance(),
482 $result = $throttle->increase( $user->getName(), $request->getIP(), __METHOD__
);
484 $msg = wfMessage( 'login-throttled' )->durationParams( $result['wait'] );
485 return self
::loginHook( $user, null, Status
::newFatal( $msg ) );
489 // Get the bot password
490 $bp = self
::newFromUser( $user, $appId );
492 return self
::loginHook( $user, $bp,
493 Status
::newFatal( 'botpasswords-not-exist', $name, $appId ) );
496 // Check restrictions
497 $status = $bp->getRestrictions()->check( $request );
498 if ( !$status->isOK() ) {
499 return self
::loginHook( $user, $bp, Status
::newFatal( 'botpasswords-restriction-failed' ) );
502 // Check the password
503 $passwordObj = $bp->getPassword();
504 if ( $passwordObj instanceof InvalidPassword
) {
505 return self
::loginHook( $user, $bp,
506 Status
::newFatal( 'botpasswords-needs-reset', $name, $appId ) );
508 if ( !$passwordObj->verify( $password ) ) {
509 return self
::loginHook( $user, $bp, Status
::newFatal( 'wrongpassword' ) );
512 // Ok! Create the session.
514 $throttle->clear( $user->getName(), $request->getIP() );
516 return self
::loginHook( $user, $bp,
517 // @phan-suppress-next-line PhanUndeclaredMethod
518 Status
::newGood( $provider->newSessionForRequest( $user, $bp, $request ) ) );
522 * Call AuthManagerLoginAuthenticateAudit
524 * To facilitate logging all authentications, even ones not via
525 * AuthManager, call the AuthManagerLoginAuthenticateAudit hook.
527 * @param User|string $user User being logged in
528 * @param BotPassword|null $bp Bot sub-account, if it can be identified
529 * @param Status $status Login status
530 * @return Status The passed-in status
532 private static function loginHook( $user, $bp, Status
$status ) {
534 if ( $user instanceof User
) {
535 $name = $user->getName();
537 $extraData['appId'] = $name . self
::getSeparator() . $bp->getAppId();
544 if ( $status->isGood() ) {
545 $response = AuthenticationResponse
::newPass( $name );
547 $response = AuthenticationResponse
::newFail( $status->getMessage() );
549 Hooks
::run( 'AuthManagerLoginAuthenticateAudit', [ $response, $user, $name, $extraData ] );