Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
55.10% covered (warning)
55.10%
27 / 49
63.64% covered (warning)
63.64%
7 / 11
 CRAP
0.00% covered (danger)
0.00%
0 / 1
CentralIdLookup
56.25% covered (warning)
56.25%
27 / 48
63.64% covered (warning)
63.64%
7 / 11
 62.53
0.00% covered (danger)
0.00%
0 / 1
 factory
0.00% covered (danger)
0.00%
0 / 6
0.00% covered (danger)
0.00%
0 / 1
 6
 init
100.00% covered (success)
100.00%
5 / 5
100.00% covered (success)
100.00%
1 / 1
 2
 getProviderId
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 checkAudience
100.00% covered (success)
100.00%
7 / 7
100.00% covered (success)
100.00%
1 / 1
 4
 isAttached
n/a
0 / 0
n/a
0 / 0
 0
 isOwned
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 lookupCentralIds
n/a
0 / 0
n/a
0 / 0
 0
 lookupUserNames
n/a
0 / 0
n/a
0 / 0
 0
 nameFromCentralId
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 namesFromCentralIds
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
 6
 centralIdFromName
100.00% covered (success)
100.00%
2 / 2
100.00% covered (success)
100.00%
1 / 1
 1
 centralIdsFromNames
0.00% covered (danger)
0.00%
0 / 7
0.00% covered (danger)
0.00%
0 / 1
 2
 localUserFromCentralId
100.00% covered (success)
100.00%
7 / 7
100.00% covered (success)
100.00%
1 / 1
 5
 centralIdFromLocalUser
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
 2
1<?php
2/**
3 * A central user id lookup service
4 *
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.
9 *
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.
14 *
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
19 *
20 * @file
21 */
22
23namespace MediaWiki\User\CentralId;
24
25use InvalidArgumentException;
26use LogicException;
27use MediaWiki\MediaWikiServices;
28use MediaWiki\Permissions\Authority;
29use MediaWiki\User\UserFactory;
30use MediaWiki\User\UserIdentity;
31use MediaWiki\User\UserIdentityLookup;
32use Throwable;
33use Wikimedia\Rdbms\IDBAccessObject;
34
35/**
36 * The CentralIdLookup service allows for connecting local users with
37 * cluster-wide IDs.
38 *
39 * @since 1.27
40 * @stable to extend
41 */
42abstract class CentralIdLookup {
43    // Audience options for accessors
44    public const AUDIENCE_PUBLIC = 1;
45    public const AUDIENCE_RAW = 2;
46
47    /** @var string */
48    private $providerId;
49
50    private UserIdentityLookup $userIdentityLookup;
51    private UserFactory $userFactory;
52
53    /**
54     * Fetch a CentralIdLookup
55     * @deprecated since 1.37 Use MediaWikiServices to obtain an instance.
56     * @param string|null $providerId Provider ID from $wgCentralIdLookupProviders
57     * @return CentralIdLookup|null
58     */
59    public static function factory( $providerId = null ) {
60        wfDeprecated( __METHOD__, '1.37' );
61        try {
62            return MediaWikiServices::getInstance()
63                ->getCentralIdLookupFactory()
64                ->getLookup( $providerId );
65        } catch ( Throwable $unused ) {
66            return null;
67        }
68    }
69
70    /**
71     * Initialize the provider.
72     *
73     * @internal
74     */
75    public function init(
76        string $providerId,
77        UserIdentityLookup $userIdentityLookup,
78        UserFactory $userFactory
79    ) {
80        if ( $this->providerId !== null ) {
81            throw new LogicException( "CentralIdProvider $providerId already initialized" );
82        }
83        $this->providerId = $providerId;
84        $this->userIdentityLookup = $userIdentityLookup;
85        $this->userFactory = $userFactory;
86    }
87
88    /**
89     * Get the provider id.
90     *
91     * @return string
92     */
93    public function getProviderId(): string {
94        return $this->providerId;
95    }
96
97    /**
98     * Check that the "audience" parameter is valid
99     * @param int|Authority $audience One of the audience constants, or a specific authority
100     * @return Authority|null authority to check against, or null if no checks are needed
101     * @throws InvalidArgumentException
102     */
103    protected function checkAudience( $audience ): ?Authority {
104        if ( $audience instanceof Authority ) {
105            return $audience;
106        }
107        if ( $audience === self::AUDIENCE_PUBLIC ) {
108            // TODO: when available, inject AuthorityFactory
109            // via init and use it to create anon authority
110            return $this->userFactory->newAnonymous();
111        }
112        if ( $audience === self::AUDIENCE_RAW ) {
113            return null;
114        }
115        throw new InvalidArgumentException( 'Invalid audience' );
116    }
117
118    /**
119     * Check that a user is attached on the specified wiki.
120     *
121     * If unattached local accounts don't exist in your extension, this comes
122     * down to a check whether the central account exists at all and that
123     * $wikiId is using the same central database.
124     *
125     * @param UserIdentity $user
126     * @param string|false $wikiId Wiki to check attachment status. If false, check the current wiki.
127     * @return bool
128     */
129    abstract public function isAttached( UserIdentity $user, $wikiId = UserIdentity::LOCAL ): bool;
130
131    /**
132     * Check that a username is owned by the central user on the specified wiki.
133     *
134     * This should return true if the local account exists and is attached (see isAttached()),
135     * or if it does not exist but is reserved for the central user (it's guaranteed that
136     * if it's ever created, then it will be attached to the central user).
137     *
138     * @since 1.43
139     * @stable to override
140     * @param UserIdentity $user
141     * @param string|false $wikiId Wiki to check attachment status. If false, check the current wiki.
142     * @return bool
143     */
144    public function isOwned( UserIdentity $user, $wikiId = UserIdentity::LOCAL ): bool {
145        return $this->isAttached( $user, $wikiId );
146    }
147
148    /**
149     * Given central user IDs, return the (local) user names
150     * @note There's no requirement that the user names actually exist locally,
151     *  or if they do that they're actually attached to the central account.
152     * @param array $idToName Array with keys being central user IDs
153     * @param int|Authority $audience One of the audience constants, or a specific authority
154     * @param int $flags IDBAccessObject read flags
155     * @return string[] Copy of $idToName with values set to user names (or
156     *  empty-string if the user exists but $audience lacks the rights needed
157     *  to see it). IDs not corresponding to a user are unchanged.
158     */
159    abstract public function lookupCentralIds(
160        array $idToName, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
161    ): array;
162
163    /**
164     * Given (local) user names, return the central IDs
165     * @note There's no requirement that the user names actually exist locally,
166     *  or if they do that they're actually attached to the central account.
167     * @param array $nameToId Array with keys being canonicalized user names
168     * @param int|Authority $audience One of the audience constants, or a specific authority
169     * @param int $flags IDBAccessObject read flags
170     * @return int[] Copy of $nameToId with values set to central IDs.
171     *  Names not corresponding to a user (or $audience lacks the rights needed
172     *  to see it) are unchanged.
173     */
174    abstract public function lookupUserNames(
175        array $nameToId, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
176    ): array;
177
178    /**
179     * Given a central user ID, return the (local) user name
180     * @note There's no requirement that the user name actually exists locally,
181     *  or if it does that it's actually attached to the central account.
182     * @param int $id Central user ID
183     * @param int|Authority $audience One of the audience constants, or a specific authority
184     * @param int $flags IDBAccessObject read flags
185     * @return string|null user name, or empty string if $audience lacks the
186     *  rights needed to see it, or null if $id doesn't correspond to a user
187     */
188    public function nameFromCentralId(
189        $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
190    ): ?string {
191        $idToName = $this->lookupCentralIds( [ $id => null ], $audience, $flags );
192        return $idToName[$id];
193    }
194
195    /**
196     * Given a an array of central user IDs, return the (local) user names.
197     * @param int[] $ids Central user IDs
198     * @param int|Authority $audience One of the audience constants, or a specific authority
199     * @param int $flags IDBAccessObject read flags
200     * @return string[] user names
201     * @since 1.30
202     */
203    public function namesFromCentralIds(
204        array $ids, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
205    ): array {
206        $idToName = array_fill_keys( $ids, false );
207        $names = $this->lookupCentralIds( $idToName, $audience, $flags );
208        $names = array_unique( $names );
209        $names = array_filter( $names, static function ( $name ) {
210            return $name !== false && $name !== '';
211        } );
212
213        return array_values( $names );
214    }
215
216    /**
217     * Given a (local) user name, return the central ID
218     * @note There's no requirement that the user name actually exists locally,
219     *  or if it does that it's actually attached to the central account.
220     * @param string $name Canonicalized user name
221     * @param int|Authority $audience One of the audience constants, or a specific authority
222     * @param int $flags IDBAccessObject read flags
223     * @return int user ID; 0 if the name does not correspond to a user or
224     *  $audience lacks the rights needed to see it.
225     */
226    public function centralIdFromName(
227        $name, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
228    ): int {
229        $nameToId = $this->lookupUserNames( [ $name => 0 ], $audience, $flags );
230        return $nameToId[$name];
231    }
232
233    /**
234     * Given an array of (local) user names, return the central IDs.
235     * @param string[] $names Canonicalized user names
236     * @param int|Authority $audience One of the audience constants, or a specific authority
237     * @param int $flags IDBAccessObject read flags
238     * @return int[] user IDs
239     * @since 1.30
240     */
241    public function centralIdsFromNames(
242        array $names, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
243    ): array {
244        $nameToId = array_fill_keys( $names, false );
245        $ids = $this->lookupUserNames( $nameToId, $audience, $flags );
246        $ids = array_unique( $ids );
247        $ids = array_filter( $ids, static function ( $id ) {
248            return $id !== false;
249        } );
250
251        return array_values( $ids );
252    }
253
254    /**
255     * Given a central user ID, return a local user object
256     * @note Unlike nameFromCentralId(), this does guarantee that the local
257     *  user exists and is attached to the central account.
258     * @stable to override
259     * @param int $id Central user ID
260     * @param int|Authority $audience One of the audience constants, or a specific authority
261     * @param int $flags IDBAccessObject read flags
262     * @return UserIdentity|null Local user, or null if: $id doesn't correspond to a
263     *  user, $audience lacks the rights needed to see the user, the user
264     *  doesn't exist locally, or the user isn't locally attached.
265     */
266    public function localUserFromCentralId(
267        $id, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
268    ): ?UserIdentity {
269        $name = $this->nameFromCentralId( $id, $audience, $flags );
270        if ( !$name ) {
271            return null;
272        }
273        $user = $this->userIdentityLookup->getUserIdentityByName( $name );
274        if ( $user && $user->isRegistered() && $this->isAttached( $user ) ) {
275            return $user;
276        }
277        return null;
278    }
279
280    /**
281     * Given a local UserIdentity object, return the central ID
282     * @stable to override
283     * @note Unlike centralIdFromName(), this does guarantee that the local
284     *  user is attached to the central account.
285     * @param UserIdentity $user Local user
286     * @param int|Authority $audience One of the audience constants, or a specific authority
287     * @param int $flags IDBAccessObject read flags
288     * @return int user ID; 0 if the local user does not correspond to a
289     *  central user, $audience lacks the rights needed to see it, or the
290     *  central user isn't locally attached.
291     */
292    public function centralIdFromLocalUser(
293        UserIdentity $user, $audience = self::AUDIENCE_PUBLIC, $flags = IDBAccessObject::READ_NORMAL
294    ): int {
295        return $this->isAttached( $user )
296            ? $this->centralIdFromName( $user->getName(), $audience, $flags )
297            : 0;
298    }
299
300}
301
302/** @deprecated class alias since 1.41 */
303class_alias( CentralIdLookup::class, 'CentralIdLookup' );