Merge branch 'dev' of https://github.com/redmatrix/hubzilla into dev_merge

6 files changed, 281 insertions, 74 deletions

diff --git a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/AuthorizeController.php b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/AuthorizeController.php
index ea7f54a87..4bafb1d24 100644
--- a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/AuthorizeController.php
+++ b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/AuthorizeController.php
@@ -7,37 +7,76 @@ use OAuth2\ScopeInterface;
 use OAuth2\RequestInterface;
 use OAuth2\ResponseInterface;
 use OAuth2\Scope;
+use InvalidArgumentException;
 
 /**
- * @see OAuth2\Controller\AuthorizeControllerInterface
+ * @see AuthorizeControllerInterface
  */
 class AuthorizeController implements AuthorizeControllerInterface
 {
+    /**
+     * @var string
+     */
     private $scope;
+
+    /**
+     * @var int
+     */
     private $state;
+
+    /**
+     * @var mixed
+     */
     private $client_id;
+
+    /**
+     * @var string
+     */
     private $redirect_uri;
+
+    /**
+     * The response type
+     *
+     * @var string
+     */
     private $response_type;
 
+    /**
+     * @var ClientInterface
+     */
     protected $clientStorage;
+
+    /**
+     * @var array
+     */
     protected $responseTypes;
+
+    /**
+     * @var array
+     */
     protected $config;
+
+    /**
+     * @var ScopeInterface
+     */
     protected $scopeUtil;
 
     /**
-     * @param OAuth2\Storage\ClientInterface $clientStorage REQUIRED Instance of OAuth2\Storage\ClientInterface to retrieve client information
-     * @param array                          $responseTypes OPTIONAL Array of OAuth2\ResponseType\ResponseTypeInterface objects.  Valid array
-     *                                                      keys are "code" and "token"
-     * @param array                          $config        OPTIONAL Configuration options for the server
-     *                                                      <code>
-     *                                                      $config = array(
-     *                                                      'allow_implicit' => false,            // if the controller should allow the "implicit" grant type
-     *                                                      'enforce_state'  => true              // if the controller should require the "state" parameter
-     *                                                      'require_exact_redirect_uri' => true, // if the controller should require an exact match on the "redirect_uri" parameter
-     *                                                      'redirect_status_code' => 302,        // HTTP status code to use for redirect responses
-     *                                                      );
-     *                                                      </code>
-     * @param OAuth2\ScopeInterface          $scopeUtil     OPTIONAL Instance of OAuth2\ScopeInterface to validate the requested scope
+     * Constructor
+     *
+     * @param ClientInterface $clientStorage REQUIRED Instance of OAuth2\Storage\ClientInterface to retrieve client information
+     * @param array           $responseTypes OPTIONAL Array of OAuth2\ResponseType\ResponseTypeInterface objects.  Valid array
+     *                                       keys are "code" and "token"
+     * @param array           $config        OPTIONAL Configuration options for the server:
+     * @param ScopeInterface  $scopeUtil     OPTIONAL Instance of OAuth2\ScopeInterface to validate the requested scope
+     * @code
+     *     $config = array(
+     *         'allow_implicit' => false,            // if the controller should allow the "implicit" grant type
+     *         'enforce_state'  => true              // if the controller should require the "state" parameter
+     *         'require_exact_redirect_uri' => true, // if the controller should require an exact match on the "redirect_uri" parameter
+     *         'redirect_status_code' => 302,        // HTTP status code to use for redirect responses
+     *     );
+     * @endcode
      */
     public function __construct(ClientInterface $clientStorage, array $responseTypes = array(), array $config = array(), ScopeInterface $scopeUtil = null)
     {
@@ -56,10 +95,20 @@ class AuthorizeController implements AuthorizeControllerInterface
         $this->scopeUtil = $scopeUtil;
     }
 
+    /**
+     * Handle the authorization request
+     *
+     * @param RequestInterface  $request
+     * @param ResponseInterface $response
+     * @param boolean           $is_authorized
+     * @param mixed             $user_id
+     * @return mixed|void
+     * @throws InvalidArgumentException
+     */
     public function handleAuthorizeRequest(RequestInterface $request, ResponseInterface $response, $is_authorized, $user_id = null)
     {
         if (!is_bool($is_authorized)) {
-            throw new \InvalidArgumentException('Argument "is_authorized" must be a boolean.  This method must know if the user has granted access to the client.');
+            throw new InvalidArgumentException('Argument "is_authorized" must be a boolean.  This method must know if the user has granted access to the client.');
         }
 
         // We repeat this, because we need to re-validate. The request could be POSTed
@@ -101,6 +150,14 @@ class AuthorizeController implements AuthorizeControllerInterface
         $response->setRedirect($this->config['redirect_status_code'], $uri);
     }
 
+    /**
+     * Set not authorized response
+     *
+     * @param RequestInterface  $request
+     * @param ResponseInterface $response
+     * @param string            $redirect_uri
+     * @param mixed             $user_id
+     */
     protected function setNotAuthorizedResponse(RequestInterface $request, ResponseInterface $response, $redirect_uri, $user_id = null)
     {
         $error = 'access_denied';
@@ -108,9 +165,16 @@ class AuthorizeController implements AuthorizeControllerInterface
         $response->setRedirect($this->config['redirect_status_code'], $redirect_uri, $this->state, $error, $error_message);
     }
 
-    /*
+    /**
      * We have made this protected so this class can be extended to add/modify
      * these parameters
+     *
+     * @TODO: add dependency injection for the parameters in this method
+     *
+     * @param RequestInterface $request
+     * @param ResponseInterface $response
+     * @param mixed $user_id
+     * @return array
      */
     protected function buildAuthorizeParameters($request, $response, $user_id)
     {
@@ -127,6 +191,8 @@ class AuthorizeController implements AuthorizeControllerInterface
     }
 
     /**
+     * Validate the OAuth request
+     *
      * @param RequestInterface $request
      * @param ResponseInterface $response
      * @return bool
@@ -186,7 +252,7 @@ class AuthorizeController implements AuthorizeControllerInterface
             $redirect_uri = $registered_redirect_uri;
         }
 
-        // Select the redirect URI
+        // Select the response type
         $response_type = $request->query('response_type', $request->request('response_type'));
 
         // for multiple-valued response types - make them alphabetical
@@ -281,10 +347,10 @@ class AuthorizeController implements AuthorizeControllerInterface
     /**
      * Build the absolute URI based on supplied URI and parameters.
      *
-     * @param $uri    An absolute URI.
-     * @param $params Parameters to be append as GET.
+     * @param string $uri    An absolute URI.
+     * @param array  $params Parameters to be append as GET.
      *
-     * @return
+     * @return string
      * An absolute URI with supplied parameters.
      *
      * @ingroup oauth2_section_4
@@ -302,9 +368,9 @@ class AuthorizeController implements AuthorizeControllerInterface
             }
         }
 
-        // Put humpty dumpty back together
+        // Put the uri back together
         return
-            ((isset($parse_url["scheme"])) ? $parse_url["scheme"] . "://" : "")
+              ((isset($parse_url["scheme"])) ? $parse_url["scheme"] . "://" : "")
             . ((isset($parse_url["user"])) ? $parse_url["user"]
             . ((isset($parse_url["pass"])) ? ":" . $parse_url["pass"] : "") . "@" : "")
             . ((isset($parse_url["host"])) ? $parse_url["host"] : "")
@@ -326,10 +392,10 @@ class AuthorizeController implements AuthorizeControllerInterface
     /**
      * Internal method for validating redirect URI supplied
      *
-     * @param string $inputUri            The submitted URI to be validated
+     * @param string $inputUri The submitted URI to be validated
      * @param string $registeredUriString The allowed URI(s) to validate against.  Can be a space-delimited string of URIs to
      *                                    allow for multiple URIs
-     *
+     * @return bool
      * @see http://tools.ietf.org/html/rfc6749#section-3.1.2
      */
     protected function validateRedirectUri($inputUri, $registeredUriString)
@@ -363,29 +429,50 @@ class AuthorizeController implements AuthorizeControllerInterface
     }
 
     /**
-     * Convenience methods to access the parameters derived from the validated request
+     * Convenience method to access the scope
+     *
+     * @return string
      */
-
     public function getScope()
     {
         return $this->scope;
     }
 
+    /**
+     * Convenience method to access the state
+     *
+     * @return int
+     */
     public function getState()
     {
         return $this->state;
     }
 
+    /**
+     * Convenience method to access the client id
+     *
+     * @return mixed
+     */
     public function getClientId()
     {
         return $this->client_id;
     }
 
+    /**
+     * Convenience method to access the redirect url
+     *
+     * @return string
+     */
     public function getRedirectUri()
     {
         return $this->redirect_uri;
     }
 
+    /**
+     * Convenience method to access the response type
+     *
+     * @return string
+     */
     public function getResponseType()
     {
         return $this->response_type;
diff --git a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/AuthorizeControllerInterface.php b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/AuthorizeControllerInterface.php
index fa07ae8d2..f758f976a 100644
--- a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/AuthorizeControllerInterface.php
+++ b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/AuthorizeControllerInterface.php
@@ -11,17 +11,18 @@ use OAuth2\ResponseInterface;
  *  authorization directly, this controller ensures the request is valid, but
  *  requires the application to determine the value of $is_authorized
  *
- *  ex:
- *  > $user_id = $this->somehowDetermineUserId();
- *  > $is_authorized = $this->somehowDetermineUserAuthorization();
- *  > $response = new OAuth2\Response();
- *  > $authorizeController->handleAuthorizeRequest(
- *  >     OAuth2\Request::createFromGlobals(),
- *  >     $response,
- *  >     $is_authorized,
- *  >     $user_id);
- *  > $response->send();
- *
+ *  @code
+ *      $user_id = $this->somehowDetermineUserId();
+ *      $is_authorized = $this->somehowDetermineUserAuthorization();
+ *      $response = new OAuth2\Response();
+ *      $authorizeController->handleAuthorizeRequest(
+ *          OAuth2\Request::createFromGlobals(),
+ *          $response,
+ *          $is_authorized,
+ *          $user_id
+ *      );
+ *      $response->send();
+ * @endcode
  */
 interface AuthorizeControllerInterface
 {
@@ -37,7 +38,21 @@ interface AuthorizeControllerInterface
     const RESPONSE_TYPE_AUTHORIZATION_CODE = 'code';
     const RESPONSE_TYPE_ACCESS_TOKEN = 'token';
 
+    /**
+     * Handle the OAuth request
+     *
+     * @param RequestInterface $request
+     * @param ResponseInterface $response
+     * @param $is_authorized
+     * @param null $user_id
+     * @return mixed
+     */
     public function handleAuthorizeRequest(RequestInterface $request, ResponseInterface $response, $is_authorized, $user_id = null);
 
+    /**
+     * @param RequestInterface $request
+     * @param ResponseInterface $response
+     * @return bool
+     */
     public function validateAuthorizeRequest(RequestInterface $request, ResponseInterface $response);
 }
diff --git a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/ResourceController.php b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/ResourceController.php
index 3cfaaaf12..926f90fda 100644
--- a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/ResourceController.php
+++ b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/ResourceController.php
@@ -10,17 +10,43 @@ use OAuth2\ResponseInterface;
 use OAuth2\Scope;
 
 /**
- * @see OAuth2\Controller\ResourceControllerInterface
+ * @see ResourceControllerInterface
  */
 class ResourceController implements ResourceControllerInterface
 {
+    /**
+     * @var array
+     */
     private $token;
 
+    /**
+     * @var TokenTypeInterface
+     */
     protected $tokenType;
+
+    /**
+     * @var AccessTokenInterface
+     */
     protected $tokenStorage;
+
+    /**
+     * @var array
+     */
     protected $config;
+
+    /**
+     * @var ScopeInterface
+     */
     protected $scopeUtil;
 
+    /**
+     * Constructor
+     *
+     * @param TokenTypeInterface   $tokenType
+     * @param AccessTokenInterface $tokenStorage
+     * @param array                $config
+     * @param ScopeInterface       $scopeUtil
+     */
     public function __construct(TokenTypeInterface $tokenType, AccessTokenInterface $tokenStorage, $config = array(), ScopeInterface $scopeUtil = null)
     {
         $this->tokenType = $tokenType;
@@ -36,6 +62,14 @@ class ResourceController implements ResourceControllerInterface
         $this->scopeUtil = $scopeUtil;
     }
 
+    /**
+     * Verify the resource request
+     *
+     * @param RequestInterface  $request
+     * @param ResponseInterface $response
+     * @param null              $scope
+     * @return bool
+     */
     public function verifyResourceRequest(RequestInterface $request, ResponseInterface $response, $scope = null)
     {
         $token = $this->getAccessTokenData($request, $response);
@@ -71,6 +105,13 @@ class ResourceController implements ResourceControllerInterface
         return (bool) $token;
     }
 
+    /**
+     * Get access token data.
+     *
+     * @param RequestInterface  $request
+     * @param ResponseInterface $response
+     * @return array|null
+     */
     public function getAccessTokenData(RequestInterface $request, ResponseInterface $response)
     {
         // Get the token parameter
@@ -103,7 +144,11 @@ class ResourceController implements ResourceControllerInterface
         return null;
     }
 
-    // convenience method to allow retrieval of the token
+    /**
+     * convenience method to allow retrieval of the token.
+     *
+     * @return array
+     */
     public function getToken()
     {
         return $this->token;
diff --git a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/ResourceControllerInterface.php b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/ResourceControllerInterface.php
index 611421935..0e847ca61 100644
--- a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/ResourceControllerInterface.php
+++ b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/ResourceControllerInterface.php
@@ -10,17 +10,32 @@ use OAuth2\ResponseInterface;
  *  call verifyResourceRequest in order to determine if the request
  *  contains a valid token.
  *
- *  ex:
- *  > if (!$resourceController->verifyResourceRequest(OAuth2\Request::createFromGlobals(), $response = new OAuth2\Response())) {
- *  >     $response->send(); // authorization failed
- *  >     die();
- *  > }
- *  > return json_encode($resource); // valid token!  Send the stuff!
- *
+ * @code
+ *     if (!$resourceController->verifyResourceRequest(OAuth2\Request::createFromGlobals(), $response = new OAuth2\Response())) {
+ *         $response->send(); // authorization failed
+ *         die();
+ *     }
+ *     return json_encode($resource); // valid token!  Send the stuff!
+ * @endcode
  */
 interface ResourceControllerInterface
 {
+    /**
+     * Verify the resource request
+     *
+     * @param RequestInterface  $request  - Request object
+     * @param ResponseInterface $response - Response object
+     * @param string            $scope
+     * @return mixed
+     */
     public function verifyResourceRequest(RequestInterface $request, ResponseInterface $response, $scope = null);
 
+    /**
+     * Get access token data.
+     *
+     * @param RequestInterface  $request  - Request object
+     * @param ResponseInterface $response - Response object
+     * @return mixed
+     */
     public function getAccessTokenData(RequestInterface $request, ResponseInterface $response);
 }
diff --git a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/TokenController.php b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/TokenController.php
index 5d2d731fe..7fdaf85a6 100644
--- a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/TokenController.php
+++ b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/TokenController.php
@@ -10,9 +10,12 @@ use OAuth2\Scope;
 use OAuth2\Storage\ClientInterface;
 use OAuth2\RequestInterface;
 use OAuth2\ResponseInterface;
+use InvalidArgumentException;
+use LogicException;
+use RuntimeException;
 
 /**
- * @see \OAuth2\Controller\TokenControllerInterface
+ * @see TokenControllerInterface
  */
 class TokenController implements TokenControllerInterface
 {
@@ -22,7 +25,7 @@ class TokenController implements TokenControllerInterface
     protected $accessToken;
 
     /**
-     * @var array
+     * @var array<GrantTypeInterface>
      */
     protected $grantTypes;
 
@@ -32,7 +35,7 @@ class TokenController implements TokenControllerInterface
     protected $clientAssertionType;
 
     /**
-     * @var Scope|ScopeInterface
+     * @var ScopeInterface
      */
     protected $scopeUtil;
 
@@ -41,12 +44,22 @@ class TokenController implements TokenControllerInterface
      */
     protected $clientStorage;
 
+    /**
+     * Constructor
+     *
+     * @param AccessTokenInterface         $accessToken
+     * @param ClientInterface              $clientStorage
+     * @param array                        $grantTypes
+     * @param ClientAssertionTypeInterface $clientAssertionType
+     * @param ScopeInterface               $scopeUtil
+     * @throws InvalidArgumentException
+     */
     public function __construct(AccessTokenInterface $accessToken, ClientInterface $clientStorage, array $grantTypes = array(), ClientAssertionTypeInterface $clientAssertionType = null, ScopeInterface $scopeUtil = null)
     {
         if (is_null($clientAssertionType)) {
             foreach ($grantTypes as $grantType) {
                 if (!$grantType instanceof ClientAssertionTypeInterface) {
-                    throw new \InvalidArgumentException('You must supply an instance of OAuth2\ClientAssertionType\ClientAssertionTypeInterface or only use grant types which implement OAuth2\ClientAssertionType\ClientAssertionTypeInterface');
+                    throw new InvalidArgumentException('You must supply an instance of OAuth2\ClientAssertionType\ClientAssertionTypeInterface or only use grant types which implement OAuth2\ClientAssertionType\ClientAssertionTypeInterface');
                 }
             }
         }
@@ -63,6 +76,12 @@ class TokenController implements TokenControllerInterface
         $this->scopeUtil = $scopeUtil;
     }
 
+    /**
+     * Handle the token request.
+     *
+     * @param RequestInterface  $request  - Request object to grant access token
+     * @param ResponseInterface $response - Response object
+     */
     public function handleTokenRequest(RequestInterface $request, ResponseInterface $response)
     {
         if ($token = $this->grantAccessToken($request, $response)) {
@@ -83,8 +102,10 @@ class TokenController implements TokenControllerInterface
      * This would be called from the "/token" endpoint as defined in the spec.
      * You can call your endpoint whatever you want.
      *
-     * @param RequestInterface $request Request object to grant access token
-     * @param ResponseInterface $response
+     * @param RequestInterface  $request  - Request object to grant access token
+     * @param ResponseInterface $response - Response object
+     *
+     * @return bool|null|array
      *
      * @throws \InvalidArgumentException
      * @throws \LogicException
@@ -97,9 +118,15 @@ class TokenController implements TokenControllerInterface
      */
     public function grantAccessToken(RequestInterface $request, ResponseInterface $response)
     {
-        if (strtolower($request->server('REQUEST_METHOD')) != 'post') {
+        if (strtolower($request->server('REQUEST_METHOD')) === 'options') {
+            $response->addHttpHeaders(array('Allow' => 'POST, OPTIONS'));
+
+            return null;
+        }
+
+        if (strtolower($request->server('REQUEST_METHOD')) !== 'post') {
             $response->setError(405, 'invalid_request', 'The request method must be POST when requesting an access token', '#section-3.2');
-            $response->addHttpHeaders(array('Allow' => 'POST'));
+            $response->addHttpHeaders(array('Allow' => 'POST, OPTIONS'));
 
             return null;
         }
@@ -121,6 +148,7 @@ class TokenController implements TokenControllerInterface
             return null;
         }
 
+        /** @var GrantTypeInterface $grantType */
         $grantType = $this->grantTypes[$grantTypeIdentifier];
 
         /**
@@ -128,8 +156,8 @@ class TokenController implements TokenControllerInterface
          * ClientAssertionTypes allow for grant types which also assert the client data
          * in which case ClientAssertion is handled in the validateRequest method
          *
-         * @see OAuth2\GrantType\JWTBearer
-         * @see OAuth2\GrantType\ClientCredentials
+         * @see \OAuth2\GrantType\JWTBearer
+         * @see \OAuth2\GrantType\ClientCredentials
          */
         if (!$grantType instanceof ClientAssertionTypeInterface) {
             if (!$this->clientAssertionType->validateRequest($request, $response)) {
@@ -178,7 +206,6 @@ class TokenController implements TokenControllerInterface
          *
          * @see http://tools.ietf.org/html/rfc6749#section-3.3
          */
-
         $requestedScope = $this->scopeUtil->getScopeFromRequest($request);
         $availableScope = $grantType->getScope();
 
@@ -225,20 +252,24 @@ class TokenController implements TokenControllerInterface
     }
 
     /**
-     * addGrantType
+     * Add grant type
      *
-     * @param GrantTypeInterface $grantType the grant type to add for the specified identifier
-     * @param string $identifier a string passed in as "grant_type" in the response that will call this grantType
+     * @param GrantTypeInterface $grantType  - the grant type to add for the specified identifier
+     * @param string|null        $identifier - a string passed in as "grant_type" in the response that will call this grantType
      */
     public function addGrantType(GrantTypeInterface $grantType, $identifier = null)
     {
         if (is_null($identifier) || is_numeric($identifier)) {
-            $identifier = $grantType->getQuerystringIdentifier();
+            $identifier = $grantType->getQueryStringIdentifier();
         }
 
         $this->grantTypes[$identifier] = $grantType;
     }
 
+    /**
+     * @param RequestInterface  $request
+     * @param ResponseInterface $response
+     */
     public function handleRevokeRequest(RequestInterface $request, ResponseInterface $response)
     {
         if ($this->revokeToken($request, $response)) {
@@ -257,13 +288,20 @@ class TokenController implements TokenControllerInterface
      *
      * @param RequestInterface $request
      * @param ResponseInterface $response
+     * @throws RuntimeException
      * @return bool|null
      */
     public function revokeToken(RequestInterface $request, ResponseInterface $response)
     {
-        if (strtolower($request->server('REQUEST_METHOD')) != 'post') {
+        if (strtolower($request->server('REQUEST_METHOD')) === 'options') {
+            $response->addHttpHeaders(array('Allow' => 'POST, OPTIONS'));
+
+            return null;
+        }
+
+        if (strtolower($request->server('REQUEST_METHOD')) !== 'post') {
             $response->setError(405, 'invalid_request', 'The request method must be POST when revoking an access token', '#section-3.2');
-            $response->addHttpHeaders(array('Allow' => 'POST'));
+            $response->addHttpHeaders(array('Allow' => 'POST, OPTIONS'));
 
             return null;
         }
@@ -285,7 +323,7 @@ class TokenController implements TokenControllerInterface
         // @todo remove this check for v2.0
         if (!method_exists($this->accessToken, 'revokeToken')) {
             $class = get_class($this->accessToken);
-            throw new \RuntimeException("AccessToken {$class} does not implement required revokeToken method");
+            throw new RuntimeException("AccessToken {$class} does not implement required revokeToken method");
         }
 
         $this->accessToken->revokeToken($token, $token_type_hint);
diff --git a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/TokenControllerInterface.php b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/TokenControllerInterface.php
index 72d72570f..2f83ce4bd 100644
--- a/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/TokenControllerInterface.php
+++ b/vendor/bshaffer/oauth2-server-php/src/OAuth2/Controller/TokenControllerInterface.php
@@ -10,23 +10,30 @@ use OAuth2\ResponseInterface;
  *  it is called to handle all grant types the application supports.
  *  It also validates the client's credentials
  *
- *  ex:
- *  > $tokenController->handleTokenRequest(OAuth2\Request::createFromGlobals(), $response = new OAuth2\Response());
- *  > $response->send();
- *
+ * @code
+ *     $tokenController->handleTokenRequest(OAuth2\Request::createFromGlobals(), $response = new OAuth2\Response());
+ *     $response->send();
+ * @endcode
  */
 interface TokenControllerInterface
 {
     /**
-     * handleTokenRequest
-     *
-     * @param $request
-     * OAuth2\RequestInterface - The current http request
-     * @param $response
-     * OAuth2\ResponseInterface - An instance of OAuth2\ResponseInterface to contain the response data
+     * Handle the token request
      *
+     * @param RequestInterface $request   - The current http request
+     * @param ResponseInterface $response - An instance of OAuth2\ResponseInterface to contain the response data
      */
     public function handleTokenRequest(RequestInterface $request, ResponseInterface $response);
 
+    /**
+     * Grant or deny a requested access token.
+     * This would be called from the "/token" endpoint as defined in the spec.
+     * You can call your endpoint whatever you want.
+     *
+     * @param RequestInterface  $request  - Request object to grant access token
+     * @param ResponseInterface $response - Response object
+     *
+     * @return mixed
+     */
     public function grantAccessToken(RequestInterface $request, ResponseInterface $response);
 }