Extension:WhiteList/Theory of Operation

'''Note: This theory of operation does reflect the current version of Extension:WhiteList; it is intended to document an upcoming future release. See Future Development for more information. --Msul01 02:45, 13 November 2008 (UTC)'''

User Rights and Groups
Extension:WhiteList adds two new user rights:
 * editwhitelist
 * User has permission to modify the whitelists of existing users using a new special page called Special:WhitelistEdit (see screenshot in User's Guide).


 * restricttowhitelist
 * User is only allowed to view and edit pages as defined by the user-specific whitelist. All other pages are blocked. All restricted users will have a new Personal Tab called My Pages which will list only the pages they have access to. Restricted users may also request access to additional pages using this tab. (Such requests will generate an e-mail to the user's Manager.)

Extension:Whitelist adds two default groups which use these permissions. The Manager group has the editwhitelist user right. The Restricted group has the restricttowhitelist user right. Users with the userrights permission (assigned to the bureaucrat group by default) can assign users to these groups using Special:Userrights on their local MediaWiki installation.

Classes

 * WhiteListEntry - methods that operate on wiki_whitelist table
 * WhiteListCache - methods that operate on wiki_whitelist_cache table
 * WhiteListHooks - methods called by hooks
 * WhiteListMyPages - Restricted user page methods
 * WhiteListAccessEditor - Manager interface (access editor) methods

WhiteListEntry::Add

 * 1) Add entry to wiki_whitelist
 * 2) Call WhiteListCache::ProcessNewWhiteListEntry.

WhiteListEntry::UpdateExpiryDate

 * 1) Update wiki_whitelist entry.

WhiteListEntry::UpdateAction

 * 1) Update wiki_whitelist entry.

WhiteListEntry::Remove

 * 1) Call WhiteListCache::ProcessRemovedWhitelistEntry
 * 2) Remove entry from wiki_whitelist.

WhiteListCache::ProcessNewWhiteListEntry
ProcessNewWhiteListEntry ($wl_id)
 * 1) Search for article titles that match the new whitelist entry.
 * 2) Add matches to whitelist_cache.

WhiteListCache::ProcessRemovedWhiteListEntry
ProcessRemovedWhiteListEntry ($wl_id)
 * 1) Remove all whitelist_cache entries which match $wl_id

WhiteListCache::ProcessNewArticle
ProcessNewArticle($article)
 * 1) Scan all whitelist entries for titles which match the title of the newly created article.
 * 2) Add cache entries for each match.

WhiteListCache::ProcessRemovedArticle
ProcessRemovedArticle($article_id)
 * 1) Remove all whitelist_cache entries which match $article_id.

WhiteListCache::IsAllowed
IsAllowed(&$title, &$wgUser, $action, &$result) Check for matching whitelist entries. NOTE: Set wgUser to NULL for global whitelist/blacklist check.
 * 1) Query whitelist_cache database for user/action/title combination
 * 2) See if there are any matches which have expired
 * 3) If unexpired match is found, return true; otherwirse return false.

WhiteListCache::IsDenied
IsAllowed(&$title, &$wgUser, $action, &$result) Check for matching blacklist entries. NOTE: Set wgUser to NULL for global whitelist/blacklist check.
 * 1) TODO

WhiteListHooks::UserCan
$return = UserCan($title, $user, $action, $result) Check the article $title and $action against the $user's cached whitelist. Also check against global WhiteList and blacklists. May also need a check for edit access to own user page.

Order of Access Precedence:
 * 1) Denied globally
 * 2) Allowed globally
 * 3) Denied for user
 * 4) Allowed for user
 * 5) Neither allowed nor denied

UserCan will return $return and $result based on the following table (Note: * = don't care):

UserCan actions:
 * Blacklisted: Deny access to this page. Do not allow subsequent UserCan hooks to override this decision.
 * Whitelisted: Allow access to this page. Allow subsequent UserCan hooks to override this decision.
 * Unlisted: Deny access to this page. Allow subsequent UserCan hooks to override this decision.

WhiteListHooks::ArticleInsertComplete
ArticleInsertComplete(&$article, &$user, &$text, &$summary, &$minoredit, &$watchthis, &$sectionanchor, &$flags, &$revision)

Call WhiteListCache::ArticleAdd.

WhiteListHooks::ArticleDeleteComplete
ArticleDeleteComplete(&$article, &$user, $reason, $id)</tt>

Call WhiteListCache::ArticleRemove.

WhiteListHooks::TitleMoveComplete
TitleMoveComplete(&$title, &$newtitle, &$user, $oldid, $newid)</tt>

Call WhiteListCache::ArticleRemove, then wfWhitelistCacheArticleAdd.

WhiteListHooks::AddPersonalUrlMyPages
PersonalUrlAddMyPages(&$personal_urls, $wgTitle)</tt> Add 'My Pages' personal URL for restricted users.

wiki_whitelist

 * K=Primary Key; I=Index

wiki_whitelist
TODO: Need to track whether this is a 'allow' or 'deny' entry. May also need to track whether the entry contains a wildcard.
 * K=Primary Key; I=Index

wiki_whitelist_cache

 * K=Primary Key; I=Index