<?php
/*=====================================================================*\
|| ###################################################################
|| # Bugdar [#]version[#]
|| # Copyright ©2002-[#]year[#] Blue Static
|| #
|| # This program is free software; you can redistribute it and/or modify
|| # it under the terms of the GNU General Public License as published by
|| # the Free Software Foundation; version [#]gpl[#] of the License.
|| #
|| # This program is distributed in the hope that it will be useful, but
|| # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
|| # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
|| # more details.
|| #
|| # You should have received a copy of the GNU General Public License along
|| # with this program; if not, write to the Free Software Foundation, Inc.,
|| # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
|| ###################################################################
\*=====================================================================*/

require_once('./includes/api_user.php');

/**
* Abstract Authentication
*
* This is an abstract class that is used to provide authentication for
* Bugdar.
*
* @author		Blue Static
* @copyright	Copyright (c)2002 - [#]year[#], Blue Static
* @version		$Revision$
* @package		Bugdar
*
*/
class Authentication
{
	/**
	* The database connection to AUTHENTICATE against; can be to a separate database
	* @var object
	*/
	var $authDb;
	
	/**
	* The database connection to the BUGDAR database
	* @var object
	*/
	var $db;
	
	/**
	* The Bugdar registry
	* @var object
	*/
	var $registry;
	
	/**
	* Array of user data from the AUTHENTICATION database
	* @var array
	*/
	var $authUser;
	
	/**
	* Array of user data from the BUGDAR database
	* @var array
	*/
	var $bugdarUser;
	
	// ###################################################################
	/**
	* Constructor
	*/
	function __construct()
	{
		global $bugsys;
		
		$this->registry =& $bugsys;
		$this->db =& $bugsys->db;
		
		$this->_setupDatabase();
	}
	
	// ###################################################################
	/**
	* Returns the information array for the Bugdar user. This must be
	* called after an authentication method.
	*/
	function fetchBugdarUser()
	{
		return $this->bugdarUser;
	}
	
	// ###################################################################
	/**
	* Sets up the database to authenticate against. You can create a new
	* database object here. Whatever you choose, you need to reference
	* Authentication->authDb to the object
	*/
	function _setupDatabase() {}
	
	// ###################################################################
	/**
	* Returns the sanitized value of the user ID or unique identifier
	* found in the cookie of an already-authenticated user.
	*/
	function _fetchCookieUniqueId() {}
	
	// ###################################################################
	/**
	* Returns the sanitized value of the authentication key or cookie-safe
	* password found in the cookies of an already-authenticated user.
	*/
	function _fetchCookiePassword() {}
	
	// ###################################################################
	/**
	* Returns an array of user data fetched using the user information
	* values found in cookies. It should NOT be responsible for verifying
	* the authentication information, but only fetching it.
	*/
	function _fetchUserUsingCookies() {}
	
	// ###################################################################
	/**
	* Returns TRUE if the cookie data values are valid in the data array
	* returned from _fetchUserUsingCookies(), and FALSE if they are not.
	*/
	function _verifyCookieData() {}
	
	// ###################################################################
	/**
	* Authenticates the user using cookie data. You shouldn't need to
	* customize this method if you implement all the helpers correctly.
	* Returns TRUE if the cookies are valid and the user is logged in.
	*/
	function authenticateCookies()
	{
		if (!$this->_fetchCookieUniqueId() OR !$this->_fetchCookiePassword())
		{
			$this->_clearCookies();
			return false;
		}
		
		$this->authUser = $this->_fetchUserUsingCookies();
		
		if (!$this->authUser)
		{
			$this->authUser = null;
			$this->_clearCookies();
			return false;
		}
		
		if ($this->_verifyCookieData())
		{
			$this->_setCookies();
			$this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
			return true;
		}
		else
		{
			$this->authUser = null;
			$this->_clearCookies();
			return false;
		}
	}
	
	// ###################################################################
	/**
	* Returns an array with the authentication user information, found
	* by the unique login identifier passed to the function.
	*/
	function _fetchUserWithIdentifier($string) {}
	
	// ###################################################################
	/**
	* Verifies that the authUser's password matches the plain-text password
	* passed to this function. This is basically the transformation of
	* the plaintext to the hashed password and the result of the comparison.
	*/
	function _verifyLoginUser($password) {}
	
	// ###################################################################
	/**
	* Authenticates a user at login from two keys: an identifier and
	* a password. In Bugdar, the identifier is an email, but it can be
	* any unique string found in the authentication database. Returns
	* TRUE if the authentication is successful, and FALSE if not.
	*/
	function authenticateLogin($string, $password)
	{
		$this->authUser = $this->_fetchUserWithIdentifier($string);
		
		if (!$this->authUser)
		{
			$this->authUser = null;
			return false;
		}
		
		if ($this->_verifyLoginUser($password))
		{
			$this->_setCookies();
			$this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
			return true;
		}
		else
		{
			$this->authUser = null;
			return false;
		}
	}
	
	// ###################################################################
	/**
	* Returns the BUGDAR user array from the data in the AUTHENTICATION user
	* array. If the Bugdar user does not exist, call _createBugdarUser()
	* to add the user into the Bugdar database. This is necessary so Bugdar options
	* can be saved in the Bugdar database (and not in the auth one), however
	* authentication details will NOT be stored in the Bugdar database.
	*/
	function _fetchBugdarUserFromAuthUser() {}
	
	// ###################################################################
	/**
	* Creates a Bugdar user with the authentication details specified in
	* the auth array and returns it. You need to call this in
	* _fetchBugdarUserFromAuthUser() and use the UserAPI to create the user.
	* Example for this function is this (all of these fields are required):
	*
	* $user = new UserAPI($this->registry); // do not change this
	* $user->set('email', $this->authUser['email']);
	* $user->set('displayname', $this->authUser['name']);
	* $user->set('password', $this->authUser['password']); // some random value that won't be used for authentication
	* $user->set('usergroupid', 2); // default "Registered Users" group
	* $user->set('authid', $this->authUser['userid']); // This must be a COMPLETELY STATIC key that is found in the auth db that will permanently link Bugdar to the auth user
	* $user->insert(); // saves the user
	*
	* return $user->values; // returns the newly created user array
	*/
	function _createBugdarUser() {}
		
	// ###################################################################
	/**
	* Responsible for unsetting all authentication cookies because they
	* are invalid
	*/
	function _clearCookies() {}
	
	// ###################################################################
	/**
	* Sets the authentication cookies; this is done both at login and
	* for renewing the cookies upon successful cookie validation
	*/
	function _setCookies() {}
}

/*=====================================================================*\
|| ###################################################################
|| # $HeadURL$
|| # $Id$
|| ###################################################################
\*=====================================================================*/
?>