feat: implement authenticateRequest and verifyToken helper methods

.genignore

@@ -1,2 +1 @@
-src/main/java/com/clerk/backend_api/helpers/JwtHelper.java
-src/test/java/com/clerk/backend_api/helpers/JwtHelperTest.java
+src/main/java/com/clerk/backend_api/helpers/

build.gradle

@@ -158,3 +158,12 @@ dependencies {
 
 
 apply from: 'build-extras.gradle'
+
+test {
+    testLogging {
+        showStandardStreams true
+        showStackTraces true
+        showExceptions true
+        exceptionFormat "full"
+    }
+}

src/main/java/com/clerk/backend_api/helpers/jwks/AuthErrorReason.java

@@ -0,0 +1,30 @@
+package com.clerk.backend_api.helpers.jwks;
+
+/**
+ * AuthErrorReason - The reason for request authentication failure.
+ */
+public enum AuthErrorReason implements ErrorReason {
+
+    SESSION_TOKEN_MISSING(
+            "session-token-missing",
+            "Could not retrieve session token. Please make sure that the __session cookie or the HTTP authorization header contain a Clerk-generated session JWT"),
+    SECRET_KEY_MISSING(
+            "secret-key-missing",
+            "Missing Clerk Secret Key. Go to https://dashboard.clerk.com and get your key for your instance.");
+
+    private final String id;
+    private final String message;
+
+    private AuthErrorReason(String id, String message) {
+        this.id = id;
+        this.message = message;
+    }
+
+    public String id() {
+        return id;
+    }
+
+    public String message() {
+        return message;
+    }
+}

src/main/java/com/clerk/backend_api/helpers/jwks/AuthStatus.java

@@ -0,0 +1,19 @@
+package com.clerk.backend_api.helpers.jwks;
+
+/**
+ * AuthStatus - The request authentication status.
+ */
+public enum AuthStatus {
+    SIGNED_IN("signed-in"),
+    SIGNED_OUT("signed-out");
+
+    private final String value;
+
+    private AuthStatus(String value) {
+        this.value = value;
+    }
+
+    public String value() {
+        return value;
+    }
+}

src/main/java/com/clerk/backend_api/helpers/jwks/AuthenticateRequest.java

@@ -0,0 +1,96 @@
+package com.clerk.backend_api.helpers.jwks;
+
+import java.net.HttpCookie;
+import java.net.http.HttpHeaders;
+import java.net.http.HttpRequest;
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * AuthenticateRequest - Helper methods to authenticate requests.
+ */
+public final class AuthenticateRequest {
+
+    private AuthenticateRequest() {
+        // prevent instantiation (this is a utility class)
+    }
+
+    /**
+     * Checks if the HTTP request is authenticated.
+     *
+     * First the session token is retrieved from either the __session cookie
+     * or the HTTP Authorization header.
+     * Then the session token is verified: networklessly if the options.jwtKey
+     * is provided, otherwise by fetching the JWKS from Clerk's Backend API.
+     *
+     * @param options The request authentication options
+     * @return The request state.
+     *
+     *         WARNING: authenticateRequest is applicable in the context of Backend
+     *         APIs only.
+     */
+    public static final RequestState authenticateRequest(HttpRequest request, AuthenticateRequestOptions options) {
+
+        String sessionToken = getSessionToken(request);
+        if (sessionToken == null) {
+            return RequestState.signedOut(AuthErrorReason.SESSION_TOKEN_MISSING);
+        }
+
+        VerifyTokenOptions verifyTokenOptions;
+
+        if (options.jwtKey().isPresent()) {
+            verifyTokenOptions = VerifyTokenOptions //
+                    .jwtKey(options.jwtKey().get()) //
+                    .audience(options.audience()) //
+                    .authorizedParties(options.authorizedParties()) //
+                    .clockSkew(options.clockSkewInMs(), TimeUnit.MILLISECONDS) //
+                    .build();
+        } else if (options.secretKey().isPresent()) {
+            verifyTokenOptions = VerifyTokenOptions //
+                    .secretKey(options.secretKey().get()) //
+                    .audience(options.audience()) //
+                    .authorizedParties(options.authorizedParties()) //
+                    .clockSkew(options.clockSkewInMs(), TimeUnit.MILLISECONDS) //
+                    .build();
+        } else {
+            return RequestState.signedOut(AuthErrorReason.SECRET_KEY_MISSING);
+        }
+
+        try {
+            VerifyToken.verifyToken(sessionToken, verifyTokenOptions);
+        } catch (TokenVerificationException e) {
+            return RequestState.signedOut(e.reason());
+        }
+
+        return RequestState.signedIn(sessionToken);
+    }
+
+    /**
+     * Retrieve token from __session cookie or Authorization header.
+     *
+     * @param request The HTTP request
+     * @return The session token, if present
+     */
+    private static String getSessionToken(HttpRequest request) {
+        HttpHeaders headers = request.headers();
+
+        Optional<String> bearerToken = headers.firstValue("Authorization");
+        if (bearerToken.isPresent()) {
+            return bearerToken.get().replace("Bearer ", "");
+        }
+
+        Optional<String> cookieHeader = headers.firstValue("cookie");
+        if (cookieHeader.isPresent()) {
+            String cookieHeaderValue = cookieHeader.get();
+            List<HttpCookie> cookies = HttpCookie.parse(cookieHeaderValue);
+            for (HttpCookie cookie : cookies) {
+                if ("__session".equals(cookie.getName())) {
+                    return cookie.getValue();
+                }
+            }
+        }
+
+        return null;
+    }
+}