Add check for iat claim with some minor documentation updates

Author: Brendan Abbott

Authentication/JWT.php

@@ -30,8 +30,11 @@ class JWT
      * @param bool        $verify    Don't skip verification process
      *
      * @return object      The JWT's payload as a PHP object
-     * @throws UnexpectedValueException Provided JWT was invalid
      * @throws DomainException          Algorithm was not provided
+     * @throws UnexpectedValueException Provided JWT was invalid
+     * @throws BeforeValidException     Provided JWT is trying to be used before it's eligible as defined by 'nbf'
+     * @throws BeforeValidException     Provided JWT is trying to be used before it's been created as defined by 'iat'
+     * @throws ExpiredException         Provided JWT has since expired, as defined by the 'exp' claim
      *
      * @uses jsonDecode
      * @uses urlsafeB64Decode
@@ -67,17 +70,27 @@ public static function decode($jwt, $key = null, $verify = true)
                 throw new SignatureInvalidException('Signature verification failed');
             }
 
-            // Check token expiry time if defined.
-            if (isset($payload->exp) && time() >= $payload->exp) {
-                throw new ExpiredException('Expired token');
-            }
-
-            // Check if the nbf if it is defined.
+            // Check if the nbf if it is defined. This is the time that the
+            // token can actually be used. If it's not yet that time, abort.
             if (isset($payload->nbf) && $payload->nbf > time()) {
                 throw new BeforeValidException(
                     'Cannot handle token prior to ' . date(DateTime::ISO8601, $payload->nbf)
                 );
             }
+
+            // Check that this token has been created before 'now'. This prevents
+            // using tokens that have been created for later use (and haven't
+            // correctly used the nbf claim).
+            if (isset($payload->iat) && $payload->iat > time()) {
+                throw new BeforeValidException(
+                    'Cannot handle token prior to ' . date(DateTime::ISO8601, $payload->iat)
+                );
+            }
+
+            // Check if this token has expired.
+            if (isset($payload->exp) && time() >= $payload->exp) {
+                throw new ExpiredException('Expired token');
+            }
         }
 
         return $payload;

tests/JWTTest.php

@@ -45,7 +45,7 @@ public function testExpiredToken()
         JWT::decode($encoded, 'my_key');
     }
 
-    public function testBeforeValidToken()
+    public function testBeforeValidTokenWithNbf()
     {
         $this->setExpectedException('BeforeValidException');
         $payload = array(
@@ -55,6 +55,16 @@ public function testBeforeValidToken()
         JWT::decode($encoded, 'my_key');
     }
 
+    public function testBeforeValidTokenWithIat()
+    {
+        $this->setExpectedException('BeforeValidException');
+        $payload = array(
+            "message" => "abc",
+            "iat" => time() + 20); // time in the future
+        $encoded = JWT::encode($payload, 'my_key');
+        JWT::decode($encoded, 'my_key');
+    }
+
     public function testValidToken()
     {
         $payload = array(
@@ -69,6 +79,7 @@ public function testValidTokenWithNbf()
     {
         $payload = array(
             "message" => "abc",
+            "iat" => time(),
             "exp" => time() + 20, // time in the future
             "nbf" => time() - 20);
         $encoded = JWT::encode($payload, 'my_key');