<?php
/*=====================================================================*\
|| ###################################################################
|| # Bugdar
|| # Copyright (c)2004-2009 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 2 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 - 2007, 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;
	
	/**
	* Array of user data from the AUTHENTICATION database
	* @var array
	*/
	var $authUser;
	
	/**
	* Array of user data from the BUGDAR database
	* @var array
	*/
	var $bugdarUser;
	
	/**
	* Mapping of Bugdar fields to authentication database fields; these will be synced between databases upon login.
	* AT THE VERY MINIMUM, YOU MUST MAP THESE FIELDS:
	* @var array
	*/
	var $fieldMap = array(
		'authid'		=> null,
		'displayname'	=> null,
		'email'			=> null,
	);
	
	// ###################################################################
	/**
	* Constructor
	*/
	function __construct()
	{
		$this->db = BSApp::$db;
		
		BSApp::debug('authentication system: ' . get_class($this));
		
		$this->_setupDatabase();
	}
	
	// ###################################################################
	/**
	* (PHP 4) Constructor
	*/
	function Authentication()
	{
		$this->__construct();
	}
	
	// ###################################################################
	/**
	* 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()
	{
		// connect to the DB
		$this->authDb = new BSDBMySQLI();
		
		require_once 'includes/auth/config.php';
		$this->authDb->connect(
			$config['auth']['dbServer'],
			$config['auth']['dbUser'],
			$config['auth']['dbPassword'],
			$config['auth']['dbName']
		);
	}
	
	// ###################################################################
	/**
	* 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())
		{
			return false;
		}
		
		$this->authUser = $this->_fetchUserUsingCookies();
		if (!$this->authUser)
		{
			$this->authUser = null;
			return false;
		}
		
		if ($this->_verifyCookieData())
		{
			$this->_setCookies(true);
			$this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
			if ($this->_syncBugdarUser())
			{
				$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. Also
	* determines if the cookies are sticky ("rememember me" login)
	*/
	function authenticateLogin($string, $password, $sticky = false)
	{
		$this->authUser = $this->_fetchUserWithIdentifier($string);
		
		if (!$this->authUser)
		{
			$this->authUser = null;
			return false;
		}
		
		if ($this->_verifyLoginUser($password))
		{
			$this->_setCookies($sticky);
			$this->bugdarUser = $this->_fetchBugdarUserFromAuthUser();
			$this->_syncBugdarUser();
			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()
	{
		$user = $this->db->queryFirst("SELECT * FROM " . TABLE_PREFIX . "user WHERE authid = '" . $this->authUser[ $this->fieldMap['authid'] ] . "'");
		if (!$user)
		{
			return $this->_createBugdarUser();
		}
		return $user;
	}
	
	// ###################################################################
	/**
	* 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.
	* This will create a new user in Bugdar with the data from the authentication DB
	* with the fields specified in fieldMap.
	*/
	function _createBugdarUser()
	{
		$user = new UserAPI($this->registry);
		
		// if the email already exists in the DB, it must be the same person so just hook up the authid
		if ($check = $this->db->queryFirst("SELECT * FROM " . TABLE_PREFIX . "user WHERE email = '" . $this->db->escape_string($this->authUser[ $this->fieldMap['email'] ]) . "'"))
		{
			$user->set('userid', $check['userid']);
			$user->set_condition();
			$user->set('authid', $this->authUser[ $this->fieldMap['authid'] ]);
			$user->update();
			$user->fetch();
			
			return $user->record;
		}
		else
		{
			$user = new UserAPI($this->registry);
			foreach ($this->fieldMap AS $bugdar => $authdb)
			{
				$user->set($bugdar, $this->authUser["$authdb"]);
			}
			$user->set('usergroupid', 2);
			$user->insert();
			
			return $user->values;
		}
	}
	
	// ###################################################################
	/**
	* Syncs a Bugdar user's fieldMap'ed values to the authentication DB's
	* values. This allows the users to stay mostly-in-sync for the most
	* basic of information (like email, timezone, etc.). Passwords are
	* NOT synced. Returns TRUE if the user data was changed.
	*/
	function _syncBugdarUser()
	{
		$fields = $this->fieldMap;
		unset($fields['authid']);
		unset($fields['password']);
		
		$change = false;
		
		$user = new UserAPI($this->registry);
		$user->set('userid', $this->bugdarUser['userid']);
		$user->set_condition();
		foreach ($fields AS $bugdar => $auth)
		{
			if ($this->bugdarUser["$bugdar"] != $this->authUser["$auth"])
			{
				$user->set($bugdar, $this->authUser["$auth"]);
				$change = true;
			}
		}
		if ($change)
		{
			$user->update();
		}
		
		return $change;
	}
	
	// ###################################################################
	/**
	* 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. The
	* option it takes determines whether the cookies are sticky or not.
	*/
	function _setCookies($permanent = false) {}
}

?>