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 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 Methods

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

WhiteListHook Methods

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

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

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

Call WhiteListCache::ArticleAdd().

WhiteListHooks::ArticleDeleteComplete

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

Call WhiteListCache::ArticleRemove().

WhiteListHooks::TitleMoveComplete

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

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

WhiteListHooks::AddPersonalUrlMyPages

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

Database Structure

Current Implementation

wiki_whitelist_entry

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

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/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

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