Merge pull request #10 from RobDWaller/0.3.0

0.3.0

Author: RobDWaller

.gitignore

@@ -3,3 +3,5 @@ vendor
 coverage
 infection.log
 coverage.xml
+Dockerfile
+docker-compose.yml

README.md

@@ -1,9 +1,9 @@
 # PSR Compliant JSON Web Token Middleware
 [![Build Status](https://travis-ci.org/RobDWaller/psr-jwt.svg?branch=master)](https://travis-ci.org/RobDWaller/psr-jwt) [![codecov](https://codecov.io/gh/RobDWaller/psr-jwt/branch/master/graph/badge.svg)](https://codecov.io/gh/RobDWaller/psr-jwt) [![Infection MSI](https://badge.stryker-mutator.io/github.com/RobDWaller/psr-jwt/master)](https://infection.github.io) [![StyleCI](https://github.styleci.io/repos/167511682/shield?branch=master)](https://github.styleci.io/repos/167511682) [![Latest Stable Version](https://poser.pugx.org/rbdwllr/psr-jwt/v/stable)](https://packagist.org/packages/rbdwllr/psr-jwt) ![PHP Version Support](https://img.shields.io/travis/php-v/RobDWaller/psr-jwt/master)
 
-A [PSR-7](https://www.php-fig.org/psr/psr-7/) and [PSR-15](https://www.php-fig.org/psr/psr-15/) compliant JSON Web Token middleware library built on top of [ReallySimpleJWT](https://github.com/RobDWaller/ReallySimpleJWT).
+PSR-JWT is a middleware library which allows you to authorise JSON Web Tokens contained in a web request. It is [PSR-7](https://www.php-fig.org/psr/psr-7/) and [PSR-15](https://www.php-fig.org/psr/psr-15/) compliant and built on top of [ReallySimpleJWT](https://github.com/RobDWaller/ReallySimpleJWT).
 
-The library allows you to create JSON Web Tokens and then validate them using PSR-15 compliant middleware which can be added to compatible frameworks such as [Slim PHP](http://www.slimframework.com/) and [Zend Expressive](https://docs.zendframework.com/zend-expressive/).
+The library also allows you to generate JSON Web Tokens and the PSR-7 PSR-15 compliant middleware can be added to any compatible framework, such as [Slim PHP](http://www.slimframework.com/).
 
 For more information on JSON Web Tokens please read [RFC 7519](https://tools.ietf.org/html/rfc7519). Also to learn more about how to pass JSON Web Tokens to web applications please read up on bearer token authorisation in [RFC 6750](https://tools.ietf.org/html/rfc6750).
 
@@ -12,9 +12,9 @@ For more information on JSON Web Tokens please read [RFC 7519](https://tools.iet
 - [Setup](#setup)
 - [Basic Usage](#basic-usage)
     - [Slim PHP Example Implementation](#slim-php-example-implementation)
-    - [Zend Expressive Example Implementation](#zend-expressive-example-implementation)
-    - [JSON Response Handler](#json-response-handler)
     - [Generate JSON Web Token](#generate-json-web-token)
+    - [Parse and Validate JSON Web Token](#parse-and-validate-json-web-token)
+    - [Retrieve Token From the Request](retrieve-token-from-the-request)
 - [Advanced Usage](#advanced-usage)
     - [Handlers](#handlers)
     - [Create Custom Handler](#create-custom-handler)
@@ -23,7 +23,7 @@ For more information on JSON Web Tokens please read [RFC 7519](https://tools.iet
 
 To install this package you will need to install [Composer](https://getcomposer.org/) and then run `composer init`. Once this is done you can install the package via the command line or by editing the composer.json file created by the `composer init` command.
 
-Finally you will need to reference the composer autoloader in your PHP code, `require 'vendor/autoload.php';`. The location of the autoload file will differ dependent on where your code is run. Also you will not need to reference the autoload file if you are using a framework like Zend Expressive.
+Finally you will need to reference the Composer autoloader in your PHP code, `require 'vendor/autoload.php';`. The location of the autoload file will differ dependent on where your code is run. Note, some frameworks already have the autoload file referenced for you.
 
 **Install via Composer on the command line:**
 
@@ -35,31 +35,31 @@ composer require rbdwllr/psr-jwt
 
 ```javascript
 "require": {
-    "rbdwllr/psr-jwt": "^0.2"
+    "rbdwllr/psr-jwt": "^0.3"
 }
 ```
 
 ## Basic Usage
 
-PsrJwt can be used with any PSR-7 / PSR-15 compliant framework. Just call one of the middleware factory methods and they will return a middleware instance that exposes two methods, `__invoke()` and `process()`. The latter will work with PSR-15 compliant frameworks like Zend Expressive and the former will work with older PSR-7 compliant frameworks like Slim PHP v3.
+PsrJwt can be used with any PSR-7 / PSR-15 compliant framework. Just call one of the middleware factory methods and they will return a middleware instance that exposes two methods, `__invoke()` and `process()`. The latter will work with PSR-15 compliant frameworks and the former will work with older PSR-7 compliant frameworks.
 
 ```php
-// Will generate a text/html response if JWT authentication fails.
+// Will generate a text/html response if JWT authorisation fails.
 \PsrJwt\Factory\JwtMiddleware::html('secret', 'tokenKey', 'body');
 
-// Will generate an application/json response if JWT authentication fails.
+// Will generate an application/json response if JWT authorisation fails.
 \PsrJwt\Factory\JwtMiddleware::json('secret', 'tokenKey', ['body']);
 ```
 
-The `secret` is the string required to hash the JSON Web Token signature.
+**Secret:** is the string required to hash the JSON Web Token signature.
 
-The `tokenKey` is the key required to retrieve the JSON Web Token from a cookie, query parameter or the request body. By default though the library looks for tokens in the bearer field of the authorization header.
+**Token Key:** is the key required to retrieve the JSON Web Token from a cookie, query parameter or the request body. By default though the library looks for tokens in the bearer field of the authorization header. If you use the bearer field you can pass an empty string for the token key `''`.
 
-The `body` is the body content you would like to return in the response if authentication fails. For example, `<h1>Authentication Failed!</h1>`.
+**Body:** is the body content you would like to return in the response if authorisation fails. For example, `<h1>Authorisation Failed!</h1>`.
 
 ### Slim PHP Example Implementation
 
-To implement the middleware in Slim PHP 3.0 you can use the code below.
+To add the middleware to a route in Slim PHP you can use the code below.
 
 ```php
 // Can be added to any routes file in Slim, often index.php.
@@ -69,35 +69,84 @@ $app->get('/jwt', function (Request $request, Response $response) {
     $response->getBody()->write("JSON Web Token is Valid!");
 
     return $response;
-})->add(\PsrJwt\Factory\JwtMiddleware::html('Secret123!456$', 'jwt', 'Authentication Failed'));
+})->add(\PsrJwt\Factory\JwtMiddleware::html('Secret123!456$', 'jwt', 'Authorisation Failed'));
 ```
 
-### Zend Expressive Example Implementation
+### Generate a JSON Web Token
+
+To generate JSON Web Tokens PsrJwt offers a wrapper for the library [ReallySimpleJWT](https://github.com/RobDWaller/ReallySimpleJWT). You can create an instance of the ReallySimpleJWT builder by calling the built in factory method.
 
 ```php
-// Add to the config/pipeline.php file.
-$app->pipe('/api', \PsrJwt\Factory\JwtMiddleware::html('!Secret#1XYZ$', 'jwt', 'Authentication Failed'));
+require 'vendor/autoload.php';
+
+$factory = new \PsrJwt\Factory\Jwt();
+
+$builder = $factory->builder();
+
+$token = $builder->setSecret('!secReT$123*')
+    ->setPayloadClaim('uid', 12)
+    ->build();
 ```
 
-### Generate JSON Web Token
+### Parse and Validate JSON Web Token
 
-To generate JSON Web Tokens PsrJwt offers a wrapper for the library [ReallySimpleJWT](https://github.com/RobDWaller/ReallySimpleJWT). You can create an instance of the ReallySimpleJWT builder by calling the built in factory method.
+If for some reason you need to parse or validate a token outside of the normal middleware authorisation flow the JWT factory class provides a parser method. 
+
+This will return an instance of the Really Simple JWT Parse class which provides token parsing and validation functionality.
 
 ```php
 require 'vendor/autoload.php';
 
-\PsrJwt\Factory\Jwt::builder();
+$factory = new \PsrJwt\Factory\Jwt();
+
+$parser = $factory->parse('token', 'secret');
+
+$parser->validate();
+
+$parser->parse();
 ```
 
-For more information on creating tokens please read the [ReallySimpleJWT](https://github.com/RobDWaller/ReallySimpleJWT/blob/master/readme.md) documentation.
+For more information on creating, parsing and validating tokens please read the [ReallySimpleJWT](https://github.com/RobDWaller/ReallySimpleJWT/blob/master/readme.md) documentation.
+
+### Retrieve Token From the Request
+
+If you would like to retrieve the JSON Web Token from the request outside of the normal middleware authorisation flow you can use the request helper class. 
+
+It allows you to retrive the token itself or just access the token's payload or header.
+
+```php
+require 'vendor/autoload.php';
+
+use PsrJwt\Helper\Request;
+
+$helper = new Request();
+
+// Will return a ReallySimpleJWT Parsed object.
+$helper->getParsedToken($request, $tokenKey);
+
+// Return the token header as an array.
+$helper->getTokenHeader($request, $tokenKey);
+
+// Return the token payload as an array.
+$helper->getTokenPayload($request, $tokenKey);
+```
 
 ## Advanced Usage
 
-You don't have to use the factory methods explained above to generate the JWT authentication middleware you can call all the required classes directly. This allows you to configure a more customised setup and use your own handlers.
+You don't have to use the factory methods explained above to generate the JWT authorisation middleware you can instantiate all the required classes directly. This allows you to configure a custom setup.
+
+```php
+use PsrJwt\Handler\Html;
+use PsrJwt\JwtAuthMiddleware;
+
+$htmlHandler = new Html($secret, $tokenKey, $body);
+
+$middleware = new JwtAuthMiddleware($htmlHandler);
+```
 
 ### Handlers
 
-PsrJwt is built to work with any PSR 15 compliant handler. As standard it comes with two built in handlers, one which returns text/html responses and another which returns application/json responses.
+PsrJwt is built to work with any PSR-15 compliant handler. As standard it comes with two built in handlers, one which returns text/html responses and another which returns application/json responses.
 
 You can use these handlers simply by instantiating them and passing them to the PsrJwt middleware.
 
@@ -106,27 +155,28 @@ You can use these handlers simply by instantiating them and passing them to the
 use PsrJwt\Handler\Json;
 use PsrJwt\JwtAuthMiddleware;
 
+// The handler.
+$jsonHandler = new Json($secret, $tokenKey, $body);
 
-$auth = new Json($secret, $tokenKey, $body);
-
-$middleware = new JwtAuthMiddleware($auth);
+// The middleware.
+$middleware = new JwtAuthMiddleware($jsonHandler);
 ```
 
 ### Create Custom Handler
 
 To create your own handler you need to do two things. First create a class which implements the `Psr\Http\Server\RequestHandlerInterface` [interface](https://www.php-fig.org/psr/psr-15/). This requires you create a `handle()` method which consumes a `Psr\Http\Message\ServerRequestInterface` object and returns a `Psr\Http\Message\ResponseInterface` object.
 
-Next you will need to extend the `PsrJwt\Auth\Authenticate` class as this will give you access to the JSON Web Token authentication functionality. Once this is done you will be able to pass your handler to the `PsrJwt\JwtAuthMiddleware` class and then integrate it with your desired framework.
+Next you will need to extend the `PsrJwt\Auth\Authorise` class as this will give you access to the JSON Web Token authorisation functionality. Once this is done you will be able to pass your handler to the `PsrJwt\JwtAuthMiddleware` class and then integrate it with your desired framework.
 
 ```php
-// An example JWT Authentication Handler.
-use PsrJwt\Auth\Authenticate;
+// An example JWT Authorisation Handler.
+use PsrJwt\Auth\Authorise;
 use Psr\Http\Server\RequestHandlerInterface;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use Nyholm\Psr7\Response;
 
-class MyHandler extends Authenticate implements RequestHandlerInterface
+class MyHandler extends Authorise implements RequestHandlerInterface
 {
     public function __construct(string $secret, string $tokenKey)
     {
@@ -135,7 +185,7 @@ class MyHandler extends Authenticate implements RequestHandlerInterface
 
     public function handle(ServerRequestInterface $request): ResponseInterface
     {
-        $auth = $this->authenticate($request);
+        $auth = $this->authorise($request);
 
         return new Response(
             $auth->getCode(),

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "rbdwllr/psr-jwt",
     "description": "A PSR 7 compliant JSON Web Token Middleware Library.",
-    "keywords": ["jwt", "json", "tokens", "authentication", "json web tokens", "php", "psr-7"],
+    "keywords": ["jwt", "json", "tokens", "authentication", "authorisation", "json web tokens", "php", "psr-7"],
     "type": "library",
     "license": "MIT",
     "authors": [
@@ -19,8 +19,8 @@
     },
     "require-dev": {
     	"phpunit/phpunit": "^7.0",
-        "phpstan/phpstan": "^0.10",
-        "phpstan/phpstan-mockery": "^0.10",
+        "phpstan/phpstan": "^0.11",
+        "phpstan/phpstan-mockery": "^0.11",
         "phpmd/phpmd": "2.6.*",
         "squizlabs/php_codesniffer": "^3.0",
         "mockery/mockery": "^1.2",

src/Auth/Auth.php

@@ -5,8 +5,8 @@
 namespace PsrJwt\Auth;
 
 /**
- * Tell the middleware what the status code and reason phrase should be based
- * on completing the JWT authentication process.
+ * Tell the middleware what the status code and reason phrase are when the JWT
+ * authorisation process is complete.
  */
 class Auth
 {
@@ -32,7 +32,7 @@ public function __construct(int $code, string $message)
     }
 
     /**
-     * Return the status code based on token authentication
+     * Return the status code based on token authorisation.
      *
      * @return int
      */
@@ -42,7 +42,7 @@ public function getCode(): int
     }
 
     /**
-     * Return the reason phrase based on token authentication
+     * Return the reason phrase based on token authorisation.
      *
      * @return string
      */

src/Auth/Authenticate.php src/Auth/Authorise.phpsrc/Auth/Authenticate.php renamed to src/Auth/Authorise.php

@@ -5,17 +5,18 @@
 namespace PsrJwt\Auth;
 
 use Psr\Http\Message\ServerRequestInterface;
-use ReallySimpleJWT\Exception\ValidateException;
 use PsrJwt\Factory\Jwt;
 use PsrJwt\Auth\Auth;
 use PsrJwt\Parser\Parse;
+use PsrJwt\Parser\Request;
+use PsrJwt\Parser\ParseException;
 use PsrJwt\Validation\Validate;
 
 /**
  * Retrieve the JSON Web Token from the request and attempt to parse and
  * validate it.
  */
-class Authenticate
+class Authorise
 {
     /**
      * The secret required to parse and validate the JWT.
@@ -25,7 +26,7 @@ class Authenticate
     private $secret;
 
     /**
-     * Define under what key the JWT can be found in the request.
+     * Define which key the JWT can be found under in the request.
      *
      * @var string $tokenKey
      */
@@ -48,27 +49,29 @@ public function __construct(string $secret, string $tokenKey)
      * @param ServerRequestInterface $request
      * @return Auth
      */
-    public function authenticate(ServerRequestInterface $request): Auth
+    public function authorise(ServerRequestInterface $request): Auth
     {
         try {
             $token = $this->getToken($request);
-        } catch (ValidateException $e) {
+        } catch (ParseException $e) {
             return new Auth(400, 'Bad Request: ' . $e->getMessage());
         }
 
         return $this->validate($token);
     }
 
     /**
-     * Check the token will parse, the signature is valid, it is ready to use,
-     * and it has not expired.
+     * Check the token will parse, the signature is valid, the token is ready
+     * to use, and it has not expired.
      *
      * @param string $token
      * @return Auth
      */
     private function validate(string $token): Auth
     {
-        $parse = Jwt::parser($token, $this->secret);
+        $jwt = new Jwt();
+
+        $parse = $jwt->parser($token, $this->secret);
 
         $validate = new Validate($parse);
 
@@ -83,7 +86,7 @@ private function validate(string $token): Auth
     }
 
     /**
-     * The authentication can respond as Ok or Unauthorized.
+     * The authorisation process can respond as 200 Ok or 401 Unauthorized.
      *
      * @param int $code
      * @param string $message
@@ -98,40 +101,18 @@ private function validationResponse(int $code, string $message): Auth
         return new Auth(200, 'Ok');
     }
 
-    /**
-     * The token found in the request should not be empty.
-     *
-     * @param string $token
-     * @return bool
-     */
-    private function hasJwt(string $token): bool
-    {
-        return !empty($token);
-    }
-
     /**
      * Find the token in the request. Ideally the token should be passed as
      * a bearer token in the authorization header. Passing the token via
      * query parameters is the least advisable option.
      *
      * @param ServerRequestInterface $request
      * @return string
-     * @throws ValidateException
      */
     private function getToken(ServerRequestInterface $request): string
     {
-        $parse = new Parse(['token_key' => $this->tokenKey]);
-        $parse->addParser(\PsrJwt\Parser\Bearer::class);
-        $parse->addParser(\PsrJwt\Parser\Cookie::class);
-        $parse->addParser(\PsrJwt\Parser\Body::class);
-        $parse->addParser(\PsrJwt\Parser\Query::class);
-
-        $token = $parse->findToken($request);
-
-        if ($this->hasJwt($token)) {
-            return $token;
-        }
+        $parseRequest = new Request(new Parse());
 
-        throw new ValidateException('JSON Web Token not set.', 11);
+        return $parseRequest->parse($request, $this->tokenKey);
     }
 }