Merge pull request #10 from Staffbase/add-module-exceptions

Add module exceptions

README.md

@@ -96,7 +96,7 @@ class RemoteCallHandler extends AbstractRemoteCallHandler implements DeleteInsta
 
 // pass it to the PluginSession on construction as the last parameter
 $remoteCallHandler = new RemoteCallHandler($db);
-$session = new PluginSessiona(PLUGIN_ID, $secret, $sessionHandler, null, $remoteCallHandler);
+$session = new PluginSession(PLUGIN_ID, $secret, $sessionHandler, null, $remoteCallHandler);
 
 /* Unreachable code in a delete call follows */
 ...
@@ -121,6 +121,6 @@ To run the tests a simple `# composer test` command in the root directory will s
 
 ## License
 
-Copyright 2017-2018 Staffbase GmbH.
+Copyright 2017-2019 Staffbase GmbH.
 
 Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

doc/api.md

@@ -31,6 +31,8 @@
     * [getSessionData](#getsessiondata)
     * [setSessionVar](#setsessionvar)
     * [isUserView](#isuserview)
+* [SSOAuthenticationException](#ssoauthenticationexception)
+* [SSOException](#ssoexception)
 * [SSOToken](#ssotoken)
     * [getAudience](#getaudience-1)
     * [getExpireAtTime](#getexpireattime-1)
@@ -552,6 +554,32 @@ PluginSession::isUserView(  ): boolean
 
 ---
 
+## SSOAuthenticationException
+
+Class SSOAuthenticationException
+
+An SSO Exception type which indicates
+a failure during the authentication process
+caused by invalid input.
+
+Can be used to identify cases which can
+be handled with a soft http error eg.: 401.
+
+* Full name: \Staffbase\plugins\sdk\Exceptions\SSOAuthenticationException
+* Parent class: \Staffbase\plugins\sdk\Exceptions\SSOException
+
+
+## SSOException
+
+Class SSOException
+
+A general SSO Exception type to group
+exceptions from this library.
+
+* Full name: \Staffbase\plugins\sdk\Exceptions\SSOException
+* Parent class: 
+
+
 ## SSOToken
 
 A container which is able to decrypt and store the data transmitted
@@ -957,4 +985,4 @@ PEM encoded key
 
 
 --------
-> This document was automatically generated from source code comments on 2019-02-07 using [phpDocumentor](http://www.phpdoc.org/) and [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public)
+> This document was automatically generated from source code comments on 2019-08-29 using [phpDocumentor](http://www.phpdoc.org/) and [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public)

src/Exceptions/SSOAuthenticationException.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * SSO Session implementation, based on this doc:
+ * https://developers.staffbase.com/api/plugin-sso/
+ *
+ * PHP version 5.5.9
+ *
+ * @category  Authentication
+ * @copyright 2017-2019 Staffbase, GmbH.
+ * @author    Vitaliy Ivanov
+ * @license   http://www.apache.org/licenses/LICENSE-2.0
+ * @link      https://github.com/staffbase/plugins-sdk-php
+ */
+
+namespace Staffbase\plugins\sdk\Exceptions;
+
+/**
+ * Class SSOAuthenticationException
+ * 
+ * An SSO Exception type which indicates
+ * a failure during the authentication process
+ * caused by invalid input.
+ *
+ * Can be used to identify cases which can
+ * be handled with a soft http error eg.: 401.
+ */
+class SSOAuthenticationException extends SSOException {}

src/Exceptions/SSOException.php

@@ -0,0 +1,25 @@
+<?php
+/**
+ * SSO Session implementation, based on this doc:
+ * https://developers.staffbase.com/api/plugin-sso/
+ *
+ * PHP version 5.5.9
+ *
+ * @category  Authentication
+ * @copyright 2017-2019 Staffbase, GmbH.
+ * @author    Vitaliy Ivanov
+ * @license   http://www.apache.org/licenses/LICENSE-2.0
+ * @link      https://github.com/staffbase/plugins-sdk-php
+ */
+
+namespace Staffbase\plugins\sdk\Exceptions;
+
+use Exception;
+
+/**
+ * Class SSOException
+ * 
+ * A general SSO Exception type to group
+ * exceptions from this library.
+ */
+class SSOException extends Exception {}

src/PluginSession.php

@@ -6,18 +6,19 @@
  * PHP version 5.5.9
  *
  * @category  Authentication
- * @copyright 2017 Staffbase, GmbH.
+ * @copyright 2017-2019 Staffbase, GmbH.
  * @author    Vitaliy Ivanov
  * @license   http://www.apache.org/licenses/LICENSE-2.0
  * @link      https://github.com/staffbase/plugins-sdk-php
  */
 
 namespace Staffbase\plugins\sdk;
 
-use Exception;
 use SessionHandlerInterface;
 use Staffbase\plugins\sdk\SSOData;
 use Staffbase\plugins\sdk\SSOToken;
+use Staffbase\plugins\sdk\Exceptions\SSOException;
+use Staffbase\plugins\sdk\Exceptions\SSOAuthenticationException;
 use Staffbase\plugins\sdk\RemoteCall\RemoteCallInterface;
 use Staffbase\plugins\sdk\RemoteCall\DeleteInstanceCallHandlerInterface;
 
@@ -52,15 +53,15 @@ class PluginSession extends SSOData
 	 * @param $leeway in seconds to compensate clock skew
 	 * @param $remoteCallHandler a class handling remote calls
 	 *
-	 * @throws Exception
+	 * @throws SSOAuthenticationException | SSOException
 	 */
 	public function __construct($pluginId, $appSecret, SessionHandlerInterface $sessionHandler = null, $leeway = 0, RemoteCallInterface $remoteCallHandler = null) {
 
 		if (!$pluginId)
-			throw new Exception('Empty plugin ID.');
+			throw new SSOException('Empty plugin ID.');
 
 		if (!$appSecret)
-			throw new Exception('Empty app secret.');
+			throw new SSOException('Empty app secret.');
 
 		if ($sessionHandler)
 			session_set_save_handler($sessionHandler, true);
@@ -73,11 +74,11 @@ public function __construct($pluginId, $appSecret, SessionHandlerInterface $sess
 		// lets hint to bad class usage, as these cases should never happen.
 
 		if($pid && $jwt) {
-			throw new Exception('Tried to initialize the session with both PID and JWT provided.');
+			throw new SSOAuthenticationException('Tried to initialize the session with both PID and JWT provided.');
 		}
 
 		if (!$pid && !$jwt) {
-			throw new Exception('Missing PID or JWT query parameter in Request.');
+			throw new SSOAuthenticationException('Missing PID or JWT query parameter in Request.');
 		}
 
 		$this->pluginInstanceId = $pid;
@@ -120,7 +121,7 @@ public function __construct($pluginId, $appSecret, SessionHandlerInterface $sess
 		// requests with spoofed PID are not allowed
 		if (!isset($_SESSION[$this->pluginInstanceId][self::KEY_SSO])
 		  || empty($_SESSION[$this->pluginInstanceId][self::KEY_SSO]))
-			throw new Exception('Tried to access an instance without previous authentication.');
+			throw new SSOAuthenticationException('Tried to access an instance without previous authentication.');
 
 		// decide if we are in user view or not
 		if($this->isEditor() && (!isset($_GET[self::QUERY_PARAM_USERVIEW]) || $_GET[self::QUERY_PARAM_USERVIEW] !== 'true'))

src/RemoteCall/AbstractRemoteCallHandler.php

@@ -6,7 +6,7 @@
  * PHP version 5.5.9
  *
  * @category  Authentication
- * @copyright 2018 Staffbase, GmbH.
+ * @copyright 2017-2019 Staffbase, GmbH.
  * @author    Vitaliy Ivanov
  * @license   http://www.apache.org/licenses/LICENSE-2.0
  * @link      https://github.com/staffbase/plugins-sdk-php

src/RemoteCall/DeleteInstanceCallHandlerInterface.php

@@ -6,7 +6,7 @@
  * PHP version 5.5.9
  *
  * @category  Authentication
- * @copyright 2018 Staffbase, GmbH.
+ * @copyright 2017-2019 Staffbase, GmbH.
  * @author    Vitaliy Ivanov
  * @license   http://www.apache.org/licenses/LICENSE-2.0
  * @link      https://github.com/staffbase/plugins-sdk-php

src/RemoteCall/RemoteCallInterface.php

@@ -6,7 +6,7 @@
  * PHP version 5.5.9
  *
  * @category  Authentication
- * @copyright 2018 Staffbase, GmbH.
+ * @copyright 2017-2019 Staffbase, GmbH.
  * @author    Vitaliy Ivanov
  * @license   http://www.apache.org/licenses/LICENSE-2.0
  * @link      https://github.com/staffbase/plugins-sdk-php
@@ -17,7 +17,7 @@
  * Interface RemoteCallInterface
  *
  * A generic interface describing the protocol with the
- * Staffbase Backend after a Remote SSO cal was issued.
+ * Staffbase Backend after a Remote SSO call was issued.
  *
  * @package Staffbase\plugins\sdk\RemoteCall
  */
@@ -31,7 +31,7 @@ interface RemoteCallInterface
 	public function exitSuccess();
 
 	/**
-	 * Stop the execution by providing a 5XX HTTP response
+	 * Stop the execution by providing a non 2XX HTTP response
 	 * 
 	 * This will tell Staffbase that it should try again later.
 	 */

src/SSOData.php

@@ -6,7 +6,7 @@
  * PHP version 5.5.9
  *
  * @category  Authentication
- * @copyright 2017 Staffbase, GmbH.
+ * @copyright 2017-2019 Staffbase, GmbH.
  * @author    Vitaliy Ivanov
  * @license   http://www.apache.org/licenses/LICENSE-2.0
  * @link      https://github.com/staffbase/plugins-sdk-php

src/SSOToken.php

@@ -6,21 +6,22 @@
  * PHP version 5.5.9
  *
  * @category  Authentication
- * @copyright 2017 Staffbase, GmbH. 
+ * @copyright 2017-2019 Staffbase, GmbH. 
  * @author    Vitaliy Ivanov
  * @license   http://www.apache.org/licenses/LICENSE-2.0
  * @link      https://github.com/staffbase/plugins-sdk-php
  */
 
 namespace Staffbase\plugins\sdk;
 
-use Exception;
 use Lcobucci\JWT\Parser;
 use Lcobucci\JWT\Builder;
 use Lcobucci\JWT\ValidationData;
 use Lcobucci\JWT\Claim\Validatable;
 use Lcobucci\JWT\Signer\Keychain;
 use Lcobucci\JWT\Signer\Rsa\Sha256;
+use Staffbase\plugins\sdk\Exceptions\SSOException;
+use Staffbase\plugins\sdk\Exceptions\SSOAuthenticationException;
 
 /**
  * A container which is able to decrypt and store the data transmitted
@@ -40,18 +41,18 @@ class SSOToken extends SSOData
 	 * @param string $tokenData The token text.
 	 * @param int $leeway count of seconds added to current timestamp 
 	 *
-	 * @throws Exception on invalid parameters.
+	 * @throws SSOException on invalid parameters.
 	 */
 	public function __construct($appSecret, $tokenData, $leeway = 0) {
 
 		if (!trim($appSecret))
-			throw new Exception('Parameter appSecret for SSOToken is empty.');
+			throw new SSOException('Parameter appSecret for SSOToken is empty.');
 
 		if (!trim($tokenData))
-			throw new Exception('Parameter tokenData for SSOToken is empty.');
+			throw new SSOException('Parameter tokenData for SSOToken is empty.');
 
 		if (!is_numeric($leeway))
-			throw new Exception('Parameter leeway has to be numeric.');
+			throw new SSOException('Parameter leeway has to be numeric.');
 
 		// convert secret to PEM if its a plain base64 string and does not yield an url
 		if(strpos(trim($appSecret),'-----') !== 0 && strpos(trim($appSecret), 'file://') !==0 )
@@ -69,7 +70,7 @@ public function __construct($appSecret, $tokenData, $leeway = 0) {
 	 * 
 	 * @return Lcobucci\JWT\Token;
 	 *
-	 * @throws Exception if the parsing/verification/validation of the token fails.
+	 * @throws SSOAuthenticationException if the parsing/verification/validation of the token fails.
 	 */
 	protected function parseToken($appSecret, $tokenData, $leeway) {
 
@@ -81,7 +82,7 @@ protected function parseToken($appSecret, $tokenData, $leeway) {
 		$keychain = new Keychain();
 
 		if (!$this->token->verify($signer, $keychain->getPublicKey($appSecret)))
-			throw new Exception('Token verification failed.');
+			throw new SSOAuthenticationException('Token verification failed.');
 
 		// validate claims
 		$data = new ValidationData(time() +$leeway); // iat, nbf and exp are validated by default
@@ -92,7 +93,7 @@ protected function parseToken($appSecret, $tokenData, $leeway) {
 
 		// its a security risk to work with tokens lacking instance id
 		if (!trim($this->getInstanceId()))
-			throw new Exception('Token lacks instance id.');
+			throw new SSOAuthenticationException('Token lacks instance id.');
 	}
 
 	/**
@@ -128,7 +129,7 @@ public static function base64ToPEMPublicKey($data) {
 	 * 
 	 * @param Lcobucci\JWT\ValidationData $data to validate against
 	 * 
-	 * @throws Exception always.
+	 * @throws SSOAuthenticationException always.
 	 */
 	protected function throwVerboseException(ValidationData $data) {
 
@@ -144,13 +145,13 @@ protected function throwVerboseException(ValidationData $data) {
 					$operator = array_pop($segments);
 					$operand  = $data->get($claimName);
 
-					throw new Exception("Token Validation failed on claim '$claimName' $claimValue $operator $operand.");
+					throw new SSOAuthenticationException("Token Validation failed on claim '$claimName' $claimValue $operator $operand.");
 				}
 			}
 		}
 
 		// unknown reason, probably an addition to used library
-		throw new Exception('Token Validation failed.');
+		throw new SSOAuthenticationException('Token Validation failed.');
 	}
 
 	/**

test/PluginSessionTest.php

@@ -6,7 +6,7 @@
  * PHP version 5.5.9
  *
  * @category  Authentication
- * @copyright 2017 Staffbase, GmbH. 
+ * @copyright 2017-2019 Staffbase, GmbH. 
  * @author    Vitaliy Ivanov
  * @license   http://www.apache.org/licenses/LICENSE-2.0
  * @link      https://github.com/staffbase/plugins-sdk-php

test/SSODataTest.php

@@ -6,7 +6,7 @@
  * PHP version 5.5.9
  *
  * @category  Authentication
- * @copyright 2017 Staffbase, GmbH. 
+ * @copyright 2017-2019 Staffbase, GmbH. 
  * @author    Vitaliy Ivanov
  * @license   http://www.apache.org/licenses/LICENSE-2.0
  * @link      https://github.com/staffbase/plugins-sdk-php

test/SSOTokenTest.php

@@ -6,7 +6,7 @@
  * PHP version 5.5.9
  *
  * @category  Authentication
- * @copyright 2017 Staffbase, GmbH. 
+ * @copyright 2017-2019 Staffbase, GmbH. 
  * @author    Vitaliy Ivanov
  * @license   http://www.apache.org/licenses/LICENSE-2.0
  * @link      https://github.com/staffbase/plugins-sdk-php