Add a custom exception with error codes (#41)

Add a custom exception (InvalidJsonTokenException) that supports error codes. Update the existing thrown exceptions to include this custom exception with the appropriate error code as a cause. Update test cases to test these error codes.

Author: Will-Lin4

src/main/java/net/oauth/jsontoken/AbstractJsonTokenParser.java

@@ -25,6 +25,8 @@
 import java.util.List;
 import net.oauth.jsontoken.crypto.AsciiStringVerifier;
 import net.oauth.jsontoken.crypto.Verifier;
+import net.oauth.jsontoken.exceptions.ErrorCode;
+import net.oauth.jsontoken.exceptions.InvalidJsonTokenException;
 import org.apache.commons.codec.binary.Base64;
 import org.joda.time.Instant;
 
@@ -83,9 +85,10 @@ public JsonToken deserialize(String tokenString) {
    *   or if tokenString is not a properly formatted JWT
    */
   public void verify(JsonToken jsonToken, List<Verifier> verifiers) throws SignatureException {
-    if (! signatureIsValid(jsonToken.getTokenString(), verifiers)) {
-      throw new SignatureException("Invalid signature for token: " +
-          jsonToken.getTokenString());
+    if (!signatureIsValid(jsonToken.getTokenString(), verifiers)) {
+      throw new SignatureException(
+          "Invalid signature for token: " + jsonToken.getTokenString(),
+          new InvalidJsonTokenException(ErrorCode.BAD_SIGNATURE));
     }
 
     Instant issuedAt = jsonToken.getIssuedAt();
@@ -100,10 +103,22 @@ public void verify(JsonToken jsonToken, List<Verifier> verifiers) throws Signatu
     }
 
     if (issuedAt != null && expiration != null) {
-      if (issuedAt.isAfter(expiration)
-          || ! clock.isCurrentTimeInInterval(issuedAt, expiration)) {
-        throw new IllegalStateException(String.format("Invalid iat and/or exp. iat: %s exp: %s "
-            + "now: %s", jsonToken.getIssuedAt(), jsonToken.getExpiration(), clock.now()));
+      String errorMessage = String.format("Invalid iat and/or exp. iat: %s exp: %s now: %s",
+          jsonToken.getIssuedAt(), jsonToken.getExpiration(), clock.now());
+
+      if (issuedAt.isAfter(expiration)) {
+        throw new IllegalStateException(
+            errorMessage, new InvalidJsonTokenException(ErrorCode.BAD_TIME_RANGE));
+      }
+
+      if (!clock.isCurrentTimeInInterval(issuedAt, expiration)) {
+        if (clock.now().isAfter(expiration)) {
+          throw new IllegalStateException(
+              errorMessage, new InvalidJsonTokenException(ErrorCode.EXPIRED_TOKEN));
+        } else {
+          throw new IllegalStateException(
+              errorMessage, new InvalidJsonTokenException(ErrorCode.BAD_TIME_RANGE));
+        }
       }
     }
 
@@ -173,8 +188,10 @@ public boolean issuedAtIsValid(JsonToken jsonToken, Instant now) {
   private List<String> splitTokenString(String tokenString) {
     List<String> pieces = Splitter.on(JsonTokenUtil.DELIMITER).splitToList(tokenString);
     if (pieces.size() != 3) {
-      throw new IllegalStateException("Expected JWT to have 3 segments separated by '" +
-          JsonTokenUtil.DELIMITER + "', but it has " + pieces.size() + " segments");
+      throw new IllegalStateException(
+          "Expected JWT to have 3 segments separated by '" +
+              JsonTokenUtil.DELIMITER + "', but it has " + pieces.size() + " segments",
+          new InvalidJsonTokenException(ErrorCode.MALFORMED_TOKEN_STRING));
     }
     return pieces;
   }

src/main/java/net/oauth/jsontoken/AsyncJsonTokenParser.java

@@ -16,7 +16,6 @@
  */
 package net.oauth.jsontoken;
 
-import com.google.common.base.Function;
 import com.google.common.base.Preconditions;
 import com.google.common.util.concurrent.AsyncFunction;
 import com.google.common.util.concurrent.Futures;
@@ -29,6 +28,8 @@
 import net.oauth.jsontoken.crypto.Verifier;
 import net.oauth.jsontoken.discovery.AsyncVerifierProvider;
 import net.oauth.jsontoken.discovery.AsyncVerifierProviders;
+import net.oauth.jsontoken.exceptions.ErrorCode;
+import net.oauth.jsontoken.exceptions.InvalidJsonTokenException;
 
 /**
  * The asynchronous counterpart of {@link JsonTokenParser}.
@@ -117,24 +118,29 @@ private ListenableFuture<List<Verifier>> provideVerifiers(JsonToken jsonToken) {
       AsyncVerifierProvider provider =
           asyncVerifierProviders.getVerifierProvider(signatureAlgorithm);
       if (provider == null) {
-        throw new IllegalArgumentException("Signature algorithm not supported: "
-            + signatureAlgorithm);
+        return Futures.immediateFailedFuture(
+            new InvalidJsonTokenException(
+                ErrorCode.UNSUPPORTED_ALGORITHM,
+                "Signature algorithm not supported: " + signatureAlgorithm));
       }
       futureVerifiers = provider.findVerifier(jsonToken.getIssuer(), jsonToken.getKeyId());
     } catch (Exception e) {
       return Futures.immediateFailedFuture(e);
     }
 
-    Function<List<Verifier>, List<Verifier>> checkNullFunction =
+    // Use AsyncFunction instead of Function to allow for checked exceptions to propagate forward
+    AsyncFunction<List<Verifier>, List<Verifier>> checkNullFunction =
         verifiers -> {
-          if (verifiers == null) {
-            throw new IllegalStateException("No valid verifier for issuer: "
-                + jsonToken.getIssuer());
+          if (verifiers == null || verifiers.isEmpty()) {
+            return Futures.immediateFailedFuture(
+                new InvalidJsonTokenException(
+                    ErrorCode.NO_VERIFIER,
+                    "No valid verifier for issuer: " + jsonToken.getIssuer()));
           }
-          return verifiers;
+          return Futures.immediateFuture(verifiers);
         };
 
-    return Futures.transform(futureVerifiers, checkNullFunction, executor);
+    return Futures.transformAsync(futureVerifiers, checkNullFunction, executor);
   }
 
 }

src/main/java/net/oauth/jsontoken/JsonToken.java

@@ -25,6 +25,8 @@
 import net.oauth.jsontoken.crypto.AsciiStringSigner;
 import net.oauth.jsontoken.crypto.SignatureAlgorithm;
 import net.oauth.jsontoken.crypto.Signer;
+import net.oauth.jsontoken.exceptions.ErrorCode;
+import net.oauth.jsontoken.exceptions.InvalidJsonTokenException;
 import org.apache.commons.codec.binary.Base64;
 import org.joda.time.Instant;
 
@@ -254,10 +256,18 @@ public SignatureAlgorithm getSignatureAlgorithm() {
 
     JsonElement algorithmName = header.get(ALGORITHM_HEADER);
     if (algorithmName == null) {
-      throw new IllegalStateException("JWT header is missing the required '" +
-          ALGORITHM_HEADER + "' parameter");
+      throw new IllegalStateException(
+          "JWT header is missing the required '" + ALGORITHM_HEADER + "' parameter",
+          new InvalidJsonTokenException(ErrorCode.BAD_HEADER));
+    }
+
+    try {
+      return SignatureAlgorithm.getFromJsonName(algorithmName.getAsString());
+    } catch (IllegalArgumentException e) {
+      throw new IllegalArgumentException(
+          e.getMessage(),
+          new InvalidJsonTokenException(ErrorCode.UNSUPPORTED_ALGORITHM));
     }
-    return SignatureAlgorithm.getFromJsonName(algorithmName.getAsString());
   }
 
   public String getTokenString() {
@@ -329,8 +339,11 @@ private String getSignature() throws SignatureException {
     }
 
     if (signer == null) {
-      throw new SignatureException("can't sign JsonToken with signer.");
+      throw new SignatureException(
+          "can't sign JsonToken with signer",
+          new InvalidJsonTokenException(ErrorCode.ILLEGAL_STATE));
     }
+
     String signature;
     // now, generate the signature
     AsciiStringSigner asciiSigner = new AsciiStringSigner(signer);

src/main/java/net/oauth/jsontoken/JsonTokenParser.java

@@ -25,6 +25,8 @@
 import net.oauth.jsontoken.crypto.Verifier;
 import net.oauth.jsontoken.discovery.VerifierProvider;
 import net.oauth.jsontoken.discovery.VerifierProviders;
+import net.oauth.jsontoken.exceptions.ErrorCode;
+import net.oauth.jsontoken.exceptions.InvalidJsonTokenException;
 
 /**
  * Class that parses and verifies JSON Tokens.
@@ -114,7 +116,9 @@ private List<Verifier> provideVerifiers(JsonToken jsonToken) {
 
     List<Verifier> verifiers = provider.findVerifier(jsonToken.getIssuer(), jsonToken.getKeyId());
     if (verifiers == null) {
-      throw new IllegalStateException("No valid verifier for issuer: " + jsonToken.getIssuer());
+      throw new IllegalStateException(
+          "No valid verifier for issuer: " + jsonToken.getIssuer(),
+          new InvalidJsonTokenException(ErrorCode.NO_VERIFIER));
     }
 
     return verifiers;

src/main/java/net/oauth/jsontoken/exceptions/ErrorCode.java

@@ -0,0 +1,52 @@
+package net.oauth.jsontoken.exceptions;
+
+public enum ErrorCode {
+
+ /**
+  * The header is missing required parameters.
+  */
+ BAD_HEADER,
+
+ /**
+  * Signature failed verification.
+  */
+ BAD_SIGNATURE,
+
+ /**
+  * IAT is after EXP or IAT is in the future
+  */
+ BAD_TIME_RANGE,
+
+ /**
+  * IAT and EXP are both in the past.
+  */
+ EXPIRED_TOKEN,
+
+ /**
+  * The token is in an illegal state because of incorrect use of the library.
+  * If this error code appears, immediately rethrow as an {@link IllegalStateException}.
+  */
+ ILLEGAL_STATE,
+
+ /**
+  * Token string is corrupted and/or does not contain three components.
+  */
+ MALFORMED_TOKEN_STRING,
+
+ /**
+  * There are no verifiers available for a given issuer and keyId.
+  */
+ NO_VERIFIER,
+
+ /**
+  * Generic catch-all for exceptions with scenarios that are not pre-defined.
+  */
+ UNKNOWN,
+
+ /**
+  * The signature algorithm is not supported or is unknown.
+  */
+ UNSUPPORTED_ALGORITHM
+
+}
+

src/main/java/net/oauth/jsontoken/exceptions/InvalidJsonTokenException.java

@@ -0,0 +1,24 @@
+package net.oauth.jsontoken.exceptions;
+
+public final class InvalidJsonTokenException extends Exception {
+  private final ErrorCode errorCode;
+
+  public InvalidJsonTokenException(ErrorCode errorCode) {
+    this.errorCode = errorCode;
+  }
+
+  public InvalidJsonTokenException(ErrorCode errorCode, String message) {
+    super(message);
+    this.errorCode = errorCode;
+  }
+
+  public InvalidJsonTokenException(ErrorCode errorCode, Throwable cause) {
+    super(cause);
+    this.errorCode = errorCode;
+  }
+
+  public ErrorCode getErrorCode() {
+    return errorCode;
+  }
+
+}