Merge pull request #2 from avaje/feature/exceptions-and-javadoc

Add JwtKeyException, all exceptions throws extend JwtVerifyException,…

Author: rbygrave

avaje-oauth2-core/src/main/java/io/avaje/oauth2/core/jwt/DJwtVerifier.java

@@ -26,12 +26,13 @@ final class DJwtVerifier implements JwtVerifier {
     private final Duration clockSkew;
     private final Clock clock;
 
-    private DJwtVerifier(Map<String, AlgorithmVerifier> map,
-                         JwtKeySource keySource,
-                         JsonDataMapper mapper,
-                         String expectedIssuer,
-                         Duration clockSkew,
-                         Clock clock) {
+    private DJwtVerifier(
+            Map<String, AlgorithmVerifier> map,
+            JwtKeySource keySource,
+            JsonDataMapper mapper,
+            String expectedIssuer,
+            Duration clockSkew,
+            Clock clock) {
         this.map = map;
         this.keySource = keySource;
         this.mapper = mapper;
@@ -45,7 +46,7 @@ static JwtVerifier.Builder builder() {
     }
 
     @Override
-    public AccessToken verifyAccessToken(String accessToken) {
+    public AccessToken verifyAccessToken(String accessToken) throws JwtVerifyException {
         SignedJwt accessTokenJwt = SignedJwt.parse(accessToken);
         verify(accessTokenJwt);
 
@@ -172,7 +173,6 @@ public JwtVerifier.Builder clockSkew(Duration clockSkew) {
             return this;
         }
 
-
         @Override
         public JwtVerifier build() {
             if (mapper == null) {
@@ -208,7 +208,7 @@ public Signature get() {
             try {
                 return Signature.getInstance(algorithm);
             } catch (NoSuchAlgorithmException e) {
-                throw new RuntimeException(e);
+                throw new JwtVerifyException("Unsupported algorithm", e);
             }
         }
     }
@@ -228,7 +228,7 @@ boolean verify(PublicKey publicKey, final byte[] content, final byte[] signature
                 verifier.update(content);
                 return verifier.verify(signature);
             } catch (InvalidKeyException e) {
-                throw new IllegalArgumentException("Invalid public key", e);
+                throw new JwtVerifyException("Invalid public key", e);
             } catch (SignatureException e) {
                 return false;
             }

avaje-oauth2-core/src/main/java/io/avaje/oauth2/core/jwt/JwtKeyException.java

@@ -0,0 +1,15 @@
+package io.avaje.oauth2.core.jwt;
+
+/**
+ * Exception when obtaining or building key used to verify a JWT.
+ */
+public class JwtKeyException extends JwtVerifyException {
+
+    public JwtKeyException(String message) {
+        super(message);
+    }
+
+    public JwtKeyException(String message, Exception e) {
+        super(message, e);
+    }
+}

avaje-oauth2-core/src/main/java/io/avaje/oauth2/core/jwt/JwtKeySource.java

@@ -12,7 +12,7 @@ public interface JwtKeySource {
     /**
      * Return the public key for the given key id.
      */
-    PublicKey key(String kid);
+    PublicKey key(String kid) throws JwtKeyException;
 
     /**
      * Build an immutable KeySource from the KeySet.

avaje-oauth2-core/src/main/java/io/avaje/oauth2/core/jwt/JwtVerifier.java

@@ -7,36 +7,103 @@
 import java.time.Clock;
 import java.time.Duration;
 
+/**
+ * Verify that a JWT is valid.
+ *
+ * <pre>{@code
+ *
+ *   String issuer = "https://cognito-idp.<region>.amazonaws.com/<endpoint>"
+ *
+ *   JwtVerifier verifier =
+ *     JwtVerifier.builder()
+ *       .issuer(issuer)
+ *       .build()
+ *
+ * }</pre>
+ */
 public interface JwtVerifier {
 
+    /**
+     * Create and return a builder for JwtVerifier.
+     */
     static Builder builder() {
         return DJwtVerifier.builder();
     }
 
+    /**
+     * Verify that the SignedJwt is valid.
+     */
     void verify(SignedJwt jwt) throws JwtVerifyException;
 
+    /**
+     * Parse and verify the accessToken.
+     *
+     * @param accessToken The raw JWT access token.
+     * @return The verified AccessToken.
+     * @throws JwtVerifyException When the access token is not valid.
+     */
     AccessToken verifyAccessToken(String accessToken) throws JwtVerifyException;
 
+    /**
+     * Builder for JwtVerifier.
+     */
     interface Builder {
 
+        /**
+         * Add RSA 256 algorithm signing.
+         */
         Builder addRS256();
 
+        /**
+         * Add an algorithm that this verifier will support.
+         *
+         * @param key       The key for the algorithm
+         * @param algorithm The algorithm
+         */
         Builder add(String key, String algorithm);
 
+        /**
+         * Add a key source.
+         */
         Builder keySource(JwtKeySource keySource);
 
+        /**
+         * Add a URI for remote JSON Web Key Set.
+         */
         Builder jwksUri(String jwksUri);
 
+        /**
+         * Add a JsonDataMapper to parse the various json payloads.
+         * <p>
+         * A default is provided when a mapper is not explicitly specified.
+         */
         Builder jsonMapper(JsonDataMapper mapper);
 
+        /**
+         * Add the HttpClient to use. Defaults to creating a new HttpClient.
+         */
         Builder httpClient(HttpClient httpClient);
 
+        /**
+         * Specify the Issuer.
+         * <p>
+         * Cognito example: <code>https://cognito-idp.{region}.amazonaws.com/{endpoint}</code>
+         */
         Builder issuer(String expectedIssuer);
 
+        /**
+         * Specify the Clock to use. Defaults to <code>Clock.systemDefaultZone()</code>
+         */
         Builder clock(Clock clock);
 
+        /**
+         * Specify the Clock skew to use. Defaults to 60 seconds.
+         */
         Builder clockSkew(Duration clockSkew);
 
+        /**
+         * Build and return the JwtVerifier.
+         */
         JwtVerifier build();
     }
 

avaje-oauth2-core/src/main/java/io/avaje/oauth2/core/jwt/JwtVerifyException.java

@@ -1,7 +1,15 @@
 package io.avaje.oauth2.core.jwt;
 
+/**
+ * Verification of JWT failed.
+ */
 public class JwtVerifyException extends RuntimeException {
+
     public JwtVerifyException(String message) {
         super(message);
     }
+
+    public JwtVerifyException(String message, Exception cause) {
+        super(message, cause);
+    }
 }

avaje-oauth2-core/src/main/java/io/avaje/oauth2/core/jwt/RemoteKeySetSource.java

@@ -37,7 +37,7 @@ private void reloadKeys() {
     }
 
     @Override
-    public PublicKey key(String kid) {
+    public PublicKey key(String kid) throws JwtKeyException {
         final PublicKey publicKey = publicKeys.get(kid);
         if (publicKey != null) {
             return publicKey;
@@ -46,7 +46,7 @@ public PublicKey key(String kid) {
         reloadKeys();
         final PublicKey refreshedKey = publicKeys.get(kid);
         if (refreshedKey == null) {
-            throw new IllegalArgumentException("Unable to provide key for " + kid);
+            throw new JwtKeyException("Unable to provide key for " + kid);
         }
         return refreshedKey;
     }
@@ -64,13 +64,13 @@ private String readBody() {
             if (statusCode < 400) {
                 return res.body();
             }
-            throw new RuntimeException("Unexpected status code " + res.statusCode() + " obtaining jwks json from " + jwksUri);
+            throw new JwtKeyException("Unexpected status code " + res.statusCode() + " obtaining jwks json from " + jwksUri);
 
         } catch (InterruptedException e) {
             Thread.currentThread().interrupt();
-            throw new RuntimeException(e);
+            throw new JwtKeyException("Error obtaining remote Key", e);
         } catch (IOException e) {
-            throw new RuntimeException(e);
+            throw new JwtKeyException("Error obtaining remote Key", e);
         }
     }
 

avaje-oauth2-core/src/main/java/io/avaje/oauth2/core/jwt/SignedJwt.java

@@ -1,13 +1,25 @@
-
 package io.avaje.oauth2.core.jwt;
 
+/**
+ * Signed JWT.
+ *
+ * @param header         The raw header content.
+ * @param payload        The raw payload content.
+ * @param contentBytes   The content bytes used for verifying.
+ * @param signatureBytes The signature bytes for verifying.
+ */
 public record SignedJwt(
         String header,
         String payload,
         byte[] contentBytes,
         byte[] signatureBytes) {
 
-    public static SignedJwt parse(String rawToken) {
+    /**
+     * Parse the raw JWT content and return as SignedJwt.
+     *
+     * @throws JwtVerifyException When the token is not SignedJwt
+     */
+    public static SignedJwt parse(String rawToken) throws JwtVerifyException {
         return SignedJwtParser.parse(rawToken);
     }
 

avaje-oauth2-core/src/main/java/io/avaje/oauth2/core/jwt/SignedJwtParser.java

@@ -7,17 +7,16 @@
 
 final class SignedJwtParser {
 
-    static SignedJwt parse(String rawToken) {
+    static SignedJwt parse(String rawToken) throws JwtVerifyException {
         int first = rawToken.indexOf('.');
         int second = rawToken.indexOf('.', first + 1);
         int third = rawToken.indexOf('.', second + 1);
         if (third != -1) {
-            throw new IllegalArgumentException("Only support signed jwt token");
+            throw new JwtVerifyException("Only signed jwt token supported");
         }
 
         String headerDecoded = decodeString(rawToken.substring(0, first));
         String payloadDecoded = decodeString(rawToken.substring(first + 1, second));
-
         byte[] contentBytes = rawToken.substring(0, second).getBytes(StandardCharsets.UTF_8);
         byte[] signatureBytes = decode(rawToken.substring(second + 1));
 

avaje-oauth2-core/src/main/java/io/avaje/oauth2/core/jwt/UtilRSA.java

@@ -12,7 +12,7 @@ final class UtilRSA {
 
     static PublicKey createRsaKey(KeySet.KeyInfo key) {
         if (!"RS256".equals(key.algorithm())) {
-            throw new IllegalArgumentException("Unsupported key algorithm: " + key.algorithm());
+            throw new JwtKeyException("Unsupported key algorithm: " + key.algorithm());
         }
         return createRsaKey(key.exponent(), key.modulus());
     }
@@ -25,7 +25,7 @@ static PublicKey createRsaKey(String exponentBase64, String modulusBase64) {
             KeyFactory factory = KeyFactory.getInstance("RSA");
             return factory.generatePublic(new RSAPublicKeySpec(modulus, exponent));
         } catch (Exception e) {
-            throw new RuntimeException(e);
+            throw new JwtKeyException("Unable to create PublicKey", e);
         }
     }