Extension:WhiteList/Theory of Operation

From MediaWiki.org
Jump to navigation Jump to search

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[edit]

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[edit]

  • 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 Methods[edit]

WhiteListEntry::Add[edit]

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

WhiteListEntry::UpdateExpiryDate[edit]

  1. Update wiki_whitelist entry.

WhiteListEntry::UpdateAction[edit]

  1. Update wiki_whitelist entry.

WhiteListEntry::Remove[edit]

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

WhitelistCache Methods[edit]

WhiteListCache::ProcessNewWhiteListEntry[edit]

ProcessNewWhiteListEntry ($wl_id)

  1. Search for article titles that match the new whitelist entry.
  2. Add matches to whitelist_cache.

WhiteListCache::ProcessRemovedWhiteListEntry[edit]

ProcessRemovedWhiteListEntry ($wl_id)

  1. Remove all whitelist_cache entries which match $wl_id

WhiteListCache::ProcessNewArticle[edit]

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[edit]

ProcessRemovedArticle($article_id)

  1. Remove all whitelist_cache entries which match $article_id.

WhiteListCache::IsAllowed[edit]

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[edit]

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

  1. TODO

WhiteListHook Methods[edit]

WhiteListHooks::UserCan[edit]

$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):

Global
IsDenied
Global
IsAllowed
User
IsDenied
User
IsAllowed
UserCan
action
UserCan
$return
UserCan
$result
true * * * blacklisted false false
false true * * whitelisted true true
false false true * blacklisted false false
false false false true whitelisted true true
false false false false unlisted true null

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[edit]

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

Call WhiteListCache::ArticleAdd().

WhiteListHooks::ArticleDeleteComplete[edit]

ArticleDeleteComplete(&$article, &$user, $reason, $id)

Call WhiteListCache::ArticleRemove().

WhiteListHooks::TitleMoveComplete[edit]

TitleMoveComplete(&$title, &$newtitle, &$user, $oldid, $newid)

Call WhiteListCache::ArticleRemove(), then wfWhitelistCacheArticleAdd().

WhiteListHooks::AddPersonalUrlMyPages[edit]

PersonalUrlAddMyPages(&$personal_urls, $wgTitle)
Add 'My Pages' personal URL for restricted users.

Database Structure[edit]

Current Implementation[edit]

wiki_whitelist_entry[edit]

K/I* field type(len) Notes
K wl_id int(8) NOT NULL AUTO_INCREMENT
wl_user_id int(5) NOT NULL
wl_pattern varchar(255) NOT NULL
wl_allow_edit int(1) NOT NULL
wl_expires_on varchar(19) DEFAULT NULL
wl_updated_by_user_id int(5) NOT NULL
wl_updated_on timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
  • K=Primary Key; I=Index

Proposed Implementation[edit]

wiki_whitelist[edit]

TODO: Need to track whether this is a 'allow' or 'deny' entry. May also need to track whether the entry contains a wildcard.

K/I* field type(len) Notes
K,I wl_id int(8) NOT NULL AUTO_INCREMENT
I wl_user_id int(5) NOT NULL
wl_namespace int(8) (null = all namespaces)
wl_pattern varchar(255) NOT NULL
wl_edit int(1) NOT NULL
wl_deny int(1) NOT NULL
I wl_expires_on varchar(19) DEFAULT NULL
wl_updated_by_user_id int(5) NOT NULL
wl_updated_on timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
  • K=Primary Key; I=Index

wiki_whitelist_cache[edit]

K/I* field type(len) Notes
K wlc_id int(8) NOT NULL AUTO_INCREMENT
I wlc_user_id int(5) NOT NULL
I wlc_page_id int(?) NOT NULL
I wlc_wl_id int(8) NOT NULL
  • K=Primary Key; I=Index