feat(security): add clock skew support and enhanced secret configuration to JWTManager with tests

m0ver · m0ver · commit 8d11d84968cd · 2026-02-26T12:41:34.000+08:00
Introduce configurable clock skew (withClockSkew(long)) to allow expiration leeway during JWT validation
Apply parser.clockSkewSeconds() to improve tolerance for time drift between distributed systems
Add withBase64Secret(String) to support direct Base64-encoded secret keys
Clarify documentation of withSecret(String) to explicitly denote plain text secret usage
Strengthen token validation behavior with new unit tests:
Verify expired tokens correctly throw ExpiredJwtException
Validate that tokens within configured clock skew are accepted
Ensure parsed claims remain correct when skew is applied
diff --git a/src/main/java/org/tinystruct/http/security/JWTManager.java b/src/main/java/org/tinystruct/http/security/JWTManager.java
@@ -14,9 +14,10 @@ public class JWTManager {
     // A default secret key for signing JWTs
     private static final SecretKey SECRET_KEY = Jwts.SIG.HS256.key().build();
     private SecretKey base64Key;
+    private long clockSkew = 0;
 
     /**
-     * Sets the secret key using a base64 encoded string.
+     * Sets the secret key using a plain text string.
      * This method allows for a custom secret key to be used instead of the default one.
      *
      * @param secret The secret key as a plain text string
@@ -25,6 +26,26 @@ public void withSecret(String secret) {
         this.base64Key = Keys.hmacShaKeyFor(Base64.getEncoder().encode(secret.getBytes()));
     }
 
+    /**
+     * Sets the secret key using a base64 encoded string.
+     * This method allows for a custom secret key to be used instead of the default one.
+     *
+     * @param base64Secret The secret key as a base64 string
+     */
+    public void withBase64Secret(String base64Secret) {
+        this.base64Key = Keys.hmacShaKeyFor(base64Secret.getBytes());
+    }
+
+    /**
+     * Sets the clock skew in seconds.
+     * This method allows for a leeway in the token's expiration time to account for clock differences between machines.
+     *
+     * @param clockSkew The clock skew in seconds
+     */
+    public void withClockSkew(long clockSkew) {
+        this.clockSkew = clockSkew;
+    }
+
     /**
      * Builds a JWT with the given subject and claims and returns it as a JWS signed compact String.
      *
@@ -79,6 +100,8 @@ public Jws<Claims> parseToken(final String compactToken)
         else
             parser.verifyWith(SECRET_KEY);
 
+        parser.clockSkewSeconds(this.clockSkew);
+
         // Parse the JWT and return the claims
         return parser.build().parseSignedClaims(compactToken);
     }
diff --git a/src/test/java/org/tinystruct/http/security/JWTManagerTest.java b/src/test/java/org/tinystruct/http/security/JWTManagerTest.java
@@ -52,7 +52,23 @@ public void testExpiredToken() {
         Builder builder = new Builder();
         builder.put("role", "admin");
 
-        // Create a JWT with 1 second validity
+        // Create a JWT with -1 hour validity (already expired)
+        String token = jwtManager.createToken(SUBJECT, builder, -1);
+
+        // Parsing an expired token should throw ExpiredJwtException
+        assertThrows(ExpiredJwtException.class, () -> jwtManager.parseToken(token));
+    }
+
+    @Test
+    public void testTokenWithClockSkew() {
+        assertNotNull(jwtManager); // Ensure jwtManager is not null
+        jwtManager.withSecret(SECRET);
+
+        // Create a builder with some claims
+        Builder builder = new Builder();
+        builder.put("role", "admin");
+
+        // Create a JWT with 0 validity (expires immediately)
         String token = jwtManager.createToken(SUBJECT, builder, 0);
 
         // Sleep for 1 second to ensure token expiration
@@ -62,8 +78,14 @@ public void testExpiredToken() {
             e.printStackTrace();
         }
 
-        // Parsing an expired token should throw ExpiredJwtException
-        assertThrows(ExpiredJwtException.class, () -> jwtManager.parseToken(token));
+        // Set clock skew to 60 seconds
+        jwtManager.withClockSkew(60);
+
+        // Parsing the token should NOT throw ExpiredJwtException because of clock skew
+        assertDoesNotThrow(() -> jwtManager.parseToken(token));
+        
+        Jws<Claims> parsedToken = jwtManager.parseToken(token);
+        assertEquals(SUBJECT, parsedToken.getPayload().getSubject());
     }
 
     @Test
