Merge pull request #2 from RobDWaller/0.1.0-beta

0.1.0 beta

.gitignore

@@ -1,3 +1,4 @@
 composer.lock
 vendor
 coverage
+infection.log

.travis.yml

@@ -1,19 +1,19 @@
 language: php
-
 php:
-    - 7.1
-    - 7.2
-    - 7.3
-
+- 7.1
+- 7.2
+- 7.3
 before_script:
-    - travis_retry composer self-update
-    - travis_retry composer install --no-interaction --prefer-source --dev
-
+- travis_retry composer self-update
+- travis_retry composer install --no-interaction --prefer-source --dev
 script:
-    - vendor/bin/phpcs --standard=psr12 src tests
-    - vendor/bin/phpstan analyse -l 7 src tests
-    - vendor/bin/phpmd src text ruleset.xml
-    - vendor/bin/phpunit --coverage-clover=coverage.xml
-
+- vendor/bin/phpcs --standard=psr12 src tests
+- vendor/bin/phpstan analyse -l 7 src tests
+- vendor/bin/phpmd src text ruleset.xml
+- vendor/bin/phpunit --coverage-clover=coverage.xml
+- vendor/bin/infection -s --min-msi=90
 after_success:
-    - bash <(curl -s https://codecov.io/bash)
+- bash <(curl -s https://codecov.io/bash)
+env:
+  global:
+    secure: oaOExVMXXbPswvGD2IfSM1t9iVybKhui5C4LyoVwvSoyWmkZU2YmS5Yf7Z2oCjbjzTq6b20iswVjlfakrgd2IzlvpvELu7N/jgPylfKLmG4/mvOxK53FujILsOYd8Np90zlvJb4fRcxYp/iHAmJpJEVz6J7keoRFLR8JVyF7TmbNah40Bog2pG6KaNgQ1xabGTRNDf8Vo6SJtMNrgDxv2LBLBY566QTXH8fuTmijkqsVM/r/N49Pa+2EnE26O4t25HJsBDmEbRWWHAxw7SMxrneLG98dg/GqjroqOJ5h2S2ud3I6l2kI8wtKp0bcosMiijcTZ+z7J9STrrzPIVRLVHYrLQ38+N4FaaS94k87Hk0Ywin4gPqLWU9cTtb/R4/3bE25rGTnxn/Gdm6RtniexcMDcqyjqfv65Iq5RX/mTyIDpFRNUn7M22KitTp/7jULZIVtOgHOxd27TseKgOUcPt8OavPsaakb5voL+aCWZMov1kE6H3p5ZsoDyaMusb4sJHFt63aGegtTrm4cjHKU0qO9L7y/ivI9tK/lVenUbzy+Drt5Jdp40jD5AQ8kxvB96QkxZa6DeFkidl0chwC/GgMSWx9lEMHhO5G0RJAWqWgp+wDBl+u0Wki6NlmPdlk72EbjzSWarK5ddhwElO2QTWGumw+AzfmYUNZiwQr/fJo=

README.md

@@ -1,5 +1,5 @@
 # PSR-JWT
-[![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)
+[![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)
 
 A PSR-7 and PSR-15 compliant JSON Web Token Middleware Library. Currently in alpha and built on top of [ReallySimpleJWT](https://github.com/RobDWaller/ReallySimpleJWT).
 

composer.json

@@ -24,7 +24,8 @@
         "phpstan/phpstan-mockery": "^0.10",
         "phpmd/phpmd": "2.6.*",
         "squizlabs/php_codesniffer": "^3.0",
-        "mockery/mockery": "^1.2"
+        "mockery/mockery": "^1.2",
+        "infection/infection": "^0.12.2"
     },
     "autoload": {
         "psr-4": {

infection.json.dist

@@ -0,0 +1,17 @@
+{
+    "timeout": 10,
+    "source": {
+        "directories": [
+            "src"
+        ]
+    },
+    "logs": {
+        "text": "infection.log",
+        "badge": {
+            "branch": "master"
+        }
+    },
+    "mutators": {
+        "@default": true
+    }
+}

phpunit.xml

@@ -9,7 +9,8 @@
          verbose="true"
          colors="true"
          executionOrder="random"
-         resolveDependencies="true">
+         resolveDependencies="true"
+         failOnRisky="true">
     <testsuites>
         <testsuite name="default">
             <directory suffix="Test.php">tests</directory>

src/Auth/Auth.php

@@ -4,24 +4,48 @@
 
 namespace PsrJwt\Auth;
 
+/**
+ * Tell the middleware what the status code and reason phrase should be based
+ * on completing the JWT authentication process.
+ */
 class Auth
 {
+    /**
+     * @var int $code
+     */
     private $code;
 
+    /**
+     * @var string $message
+     */
     private $message;
 
+    /**
+     * @param int $code
+     * @param string $message
+     */
     public function __construct(int $code, string $message)
     {
         $this->code = $code;
 
         $this->message = $message;
     }
 
+    /**
+     * Return the status code based on token authentication
+     *
+     * @return int
+     */
     public function getCode(): int
     {
         return $this->code;
     }
 
+    /**
+     * Return the reason phrase based on token authentication
+     *
+     * @return string
+     */
     public function getMessage(): string
     {
         return $this->message;

src/Auth/Authenticate.php

@@ -11,19 +11,45 @@
 use PsrJwt\Parser\Parse;
 use PsrJwt\Validation\Validate;
 
+/**
+ * Retrieve the JSON Web Token from the request and attempt to parse and
+ * validate it.
+ */
 class Authenticate
 {
+    /**
+     * Define under what key the JWT can be found in the request.
+     *
+     * @var string $tokenKey
+     */
     private $tokenKey;
 
+    /**
+     * The secret required to parse and validate the JWT.
+     *
+     * @var string $secret
+     */
     private $secret;
 
+    /**
+     * @param string $tokenKey
+     * @param string $secret
+     * @todo the tokenKey and secret are the wrong way around, secret is
+     * required token key is not.
+     */
     public function __construct(string $tokenKey, string $secret)
     {
         $this->tokenKey = $tokenKey;
 
         $this->secret = $secret;
     }
 
+    /**
+     * Find, parse and validate the JSON Web Token.
+     *
+     * @param ServerRequestInterface $request
+     * @return Auth
+     */
     public function authenticate(ServerRequestInterface $request): Auth
     {
         try {
@@ -35,14 +61,16 @@ public function authenticate(ServerRequestInterface $request): Auth
         return $this->validate($token);
     }
 
-    public function getSecret(): string
-    {
-        return $this->secret;
-    }
-
+    /**
+     * Check the token will parse, the signature is valid, it 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->getSecret());
+        $parse = Jwt::parser($token, $this->secret);
 
         $validate = new Validate($parse);
 
@@ -56,6 +84,13 @@ private function validate(string $token): Auth
         );
     }
 
+    /**
+     * The authentication can respond as Ok or Unauthorized.
+     *
+     * @param int $code
+     * @param string $message
+     * @return Auth
+     */
     private function validationResponse(int $code, string $message): Auth
     {
         if (in_array($code, [1, 2, 3, 4, 5], true)) {
@@ -65,11 +100,26 @@ 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]);

src/Factory/Jwt.php

@@ -10,8 +10,17 @@
 use ReallySimpleJWT\Parse;
 use ReallySimpleJWT\Jwt as RSJwt;
 
+/**
+ * This middleware wraps around the ReallySimpleJWT library. Easy access to the
+ * token builder and parser are required.
+ */
 class Jwt
 {
+    /**
+     * ALlow for the generation of JSON Web Tokens
+     *
+     * @return Build
+     */
     public static function builder(): Build
     {
         return new Build(
@@ -21,6 +30,11 @@ public static function builder(): Build
         );
     }
 
+    /**
+     * Allow for the parsing and validation of JSON Web Tokens
+     *
+     * @return Parse
+     */
     public static function parser(string $token, string $secret): Parse
     {
         $jwt = new RSJwt($token, $secret);

src/Factory/JwtAuth.php

@@ -8,8 +8,20 @@
 use PsrJwt\Auth\Authenticate;
 use PsrJwt\JwtAuthInvokable;
 
+/**
+ * Easily add the PSR-JWT middleware to PSR compliant frameworks such as
+ * Zend Expressive and Slim PHP.
+ */
 class JwtAuth
 {
+    /**
+     * Add the middleware to the relevant framework.
+     *
+     * @param string $tokenKey
+     * @param string $secret
+     * @return JwtAuthMiddleware
+     * @todo TokenKey and Secret are the wrong way around.
+     */
     public static function middleware(string $tokenKey, string $secret): JwtAuthMiddleware
     {
         $auth = new Authenticate($tokenKey, $secret);

src/JwtAuthMiddleware.php

@@ -12,15 +12,37 @@
 use PsrJwt\Auth\Authenticate;
 use PsrJwt\Auth\Auth;
 
+/**
+ * Psr-Jwt provides a simple means by which to add JSON Web Token
+ * authentication middleware to PSR-7 and PSR-15 compliant frameworks such as
+ * Slim PHP and Zend Expressive. It also allows for the generation of JSON
+ * Web Tokens via its integration with ReallySimpleJWT.
+ *
+ * @author Rob Waller <[email protected]>
+ */
 class JwtAuthMiddleware implements MiddlewareInterface
 {
+    /**
+     * @var Authenticate $authenticate
+     */
     private $authenticate;
 
+    /**
+     * @param Authenticate $authenticate
+     */
     public function __construct(Authenticate $authenticate)
     {
         $this->authenticate = $authenticate;
     }
 
+    /**
+     * PSR-7 compliant middleware compatible with frameworks like Slim PHP v3.
+     *
+     * @param ServerRequestInterface $request
+     * @param ResponseInterface $response
+     * @param callable $next
+     * @return ResponseInterface
+     */
     public function __invoke(
         ServerRequestInterface $request,
         ResponseInterface $response,
@@ -35,6 +57,14 @@ public function __invoke(
         return $this->failResponse($auth);
     }
 
+    /**
+     * PSR-15 compliant middleware compatible with frameworks like
+     * Zend Expressive.
+     *
+     * @param ServerRequestInterface $request
+     * @param RequestHandlerInterface $handler
+     * @return ResponseInterface
+     */
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {
         $auth = $this->authenticate->authenticate($request);
@@ -46,6 +76,12 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
         return $this->failResponse($auth);
     }
 
+    /**
+     * Return a failure response if JSON Web Token authentication fails.
+     *
+     * @param Auth $auth
+     * @return ResponseInterface
+     */
     private function failResponse(Auth $auth): ResponseInterface
     {
         $factory = new Psr17Factory();

src/Parser/ArgumentsInterface.php

@@ -4,7 +4,14 @@
 
 use PsrJwt\Parser\ParserInterface;
 
+/**
+ * Some parsers require arguments passed in via the constructor to execute
+ * properly.
+ */
 interface ArgumentsInterface extends ParserInterface
 {
+    /**
+     * @param array $arguments
+     */
     public function __construct(array $arguments);
 }

src/Parser/Bearer.php

@@ -7,8 +7,16 @@
 use PsrJwt\Parser\ParserInterface;
 use Psr\Http\Message\ServerRequestInterface;
 
+/**
+ * Find the JSON Web Token in the authorization header as a bearer token. This
+ * is the ideal means for passing around JWTs.
+ */
 class Bearer implements ParserInterface
 {
+    /**
+     * @param ServerRequestInterface $request
+     * @return string
+     */
     public function parse(ServerRequestInterface $request): string
     {
         $authorization = $request->getHeader('authorization');