refactor: remove private/public key from commons and use typed keys expected by the algorithms (#243)

Break inheritance with Key superclass as the byte[] is all we need.

The secret key is 32 of length and by using a type for SecretKey we don't need to check as the code does not allow to pass a SecretKey instance to a PrivateKey instance. Typing to the rescue.

Public/private key define own types in each version.

Author: nbaars

CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to the paseto4j project will be documented in this file.
+
+## 2024.3 (Unreleased)
+
+### ✨ New Features
+
+- 🔐 Added support for lazysodium, replacing the deprecated Tuweni library for XChaCha20Poly1305 encryption
+- 🧩 Introduced `Hex` class for better handling of binary data with proper equals, hashCode, and toString behavior
+- 🛡️ Improved key handling with typed key representations
+- 📦 Enhanced support for Bouncy Castle cryptographic operations
+
+### 🐛 Bug Fixes
+
+- 🔧 Fixed issue with SHAKE digest handling in crypto operations
+- 🔍 Corrected RSA key handling for proper signing operations
+- 🧪 Resolved issues with key length validation for secure operations
+- 🚫 Fixed license header issues with multi-module project structure
+
+### 🔧 Technical Updates
+
+- 📈 Upgraded to Bouncy Castle 1.80
+- 🏗️ Moved to Java 17 as minimum supported version
+- 🧹 Added Google Error Prone for enhanced static code analysis
+- 🧪 Improved test coverage with parameterized tests
+- 📝 Added Spotless formatting integration in the compile phase
+- 🔄 Updated Jackson dependencies to version 2.18.3
+- 🛠️ Enhanced build process with better Maven plugin configuration
+- 📊 Added JaCoCo for code coverage reporting
+
+### 🔀 Breaking Changes
+
+- ⚠️ Changed key representations to use byte arrays instead of various key types
+- ⚠️ Removed support for deprecated cryptographic functions
+- ⚠️ Refactored API to provide clearer type safety for different key types
+
+## Previous Releases
+
+For information about previous releases, please see the [GitHub release page](https://github.com/nbaars/paseto4j/releases).

commons/src/main/java/org/paseto4j/commons/Hex.java

@@ -0,0 +1,71 @@
+/*
+ * SPDX-FileCopyrightText: Copyright © 2025 Nanne Baars
+ * SPDX-License-Identifier: MIT
+ */
+package org.paseto4j.commons;
+
+import java.util.Locale;
+import java.util.Objects;
+
+/**
+ * An immutable representation of binary data using a hexadecimal string for storage. This class
+ * provides a better alternative to using byte arrays in records and ensures proper equals,
+ * hashCode, and toString behavior.
+ */
+public record Hex(String hexValue) {
+
+  /** Creates a new Hex instance with validation. */
+  public Hex {
+    Objects.requireNonNull(hexValue, "Hex string cannot be null");
+    HexToBytes.hexToBytes(hexValue);
+    hexValue = hexValue.toLowerCase(Locale.ROOT);
+  }
+
+  /**
+   * Creates a new Hex instance from a byte array.
+   *
+   * @param bytes the byte array to convert to hexadecimal
+   */
+  public Hex(byte[] bytes) {
+    this(HexToBytes.hexEncode(Objects.requireNonNull(bytes, "Bytes cannot be null")));
+  }
+
+  /**
+   * Returns the bytes represented by this Hex object.
+   *
+   * @return a new byte array containing the bytes
+   */
+  public byte[] toBytes() {
+    return HexToBytes.hexToBytes(hexValue);
+  }
+
+  /**
+   * Factory method to create a Hex instance from a byte array.
+   *
+   * @param bytes the byte array to convert
+   * @return a new Hex instance
+   */
+  public static Hex of(byte[] bytes) {
+    return new Hex(bytes);
+  }
+
+  /**
+   * Factory method to create a Hex instance from a hexadecimal string.
+   *
+   * @param hexString the hexadecimal string
+   * @return a new Hex instance
+   * @throws IllegalArgumentException if the string is not valid hexadecimal
+   */
+  public static Hex fromString(String hexString) {
+    return new Hex(hexString);
+  }
+
+  /**
+   * Returns the length of the byte array representation.
+   *
+   * @return the length in bytes
+   */
+  public int length() {
+    return hexValue.length() / 2;
+  }
+}

…ava/org/paseto4j/commons/HexToBytes.java …ava/org/paseto4j/commons/HexToBytes.javacommons/src/test/java/org/paseto4j/commons/HexToBytes.java renamed to commons/src/main/java/org/paseto4j/commons/HexToBytes.java commons/src/test/java/org/paseto4j/commons/HexToBytes.java renamed to commons/src/main/java/org/paseto4j/commons/HexToBytes.java

@@ -5,11 +5,13 @@
 package org.paseto4j.commons;
 
 /**
- * Copied from
- * <a href="http://www.docjar.com/html/api/com/sun/xml/internal/bind/DatatypeConverterImpl.java.html">...</a>
+ * Copied from <a
+ * href="http://www.docjar.com/html/api/com/sun/xml/internal/bind/DatatypeConverterImpl.java.html">...</a>
  */
 public class HexToBytes {
 
+  private HexToBytes() {}
+
   public static byte[] hexToBytes(String s) {
     final int len = s.length();
 

commons/src/main/java/org/paseto4j/commons/Key.java

@@ -4,12 +4,50 @@
  */
 package org.paseto4j.commons;
 
-public class SecretKey extends Key<javax.crypto.SecretKey> {
-  public SecretKey(byte[] keyMaterial, Version version) {
-    super(keyMaterial, version, 32);
+/**
+ * An immutable representation of a secret key used in PASETO operations. Uses Hex for internal
+ * storage to ensure proper equals, hashCode, and toString behavior.
+ */
+public record SecretKey(Hex key) {
+  /**
+   * Creates a new SecretKey with the given Hex key.
+   *
+   * @param key the key material as a Hex object
+   * @throws PasetoException if the key is null or not 32 bytes in length
+   */
+  public SecretKey {
+    Conditions.verify(key != null, "Key must not be null");
+    Conditions.verify(key.length() == 32, "Key must be 32 bytes in length");
+  }
+
+  /**
+   * Creates a new SecretKey with the given byte array.
+   *
+   * @param keyBytes the key material as a byte array
+   * @return a new SecretKey instance
+   * @throws PasetoException if the key is null or not 32 bytes in length
+   */
+  public static SecretKey fromBytes(byte[] keyBytes) {
+    Conditions.verify(keyBytes != null, "Key must not be null");
+    Conditions.verify(keyBytes.length == 32, "Key must be a byte array of length 32");
+    return new SecretKey(new Hex(keyBytes));
+  }
+
+  public static SecretKey fromHexString(String key) {
+    return new SecretKey(Hex.fromString(key));
+  }
+
+  /**
+   * Returns the key material as a byte array.
+   *
+   * @return a new byte array containing the key material
+   */
+  public byte[] toBytes() {
+    return key.toBytes();
   }
 
-  public boolean isValidFor(Version v, Purpose p) {
-    return v == this.getVersion() && p == Purpose.PURPOSE_LOCAL;
+  @Override
+  public String toString() {
+    return "****";
   }
 }

commons/src/main/java/org/paseto4j/commons/PrivateKey.java

@@ -7,17 +7,9 @@
 import java.util.Locale;
 
 /** Wrapper class for the chosen Paseto version */
-public class TokenAlgorithm {
+public record TokenAlgorithm(Version version, Purpose purpose) {
 
-  private final Version version;
-  private final Purpose purpose;
-
-  public TokenAlgorithm(Version version, Purpose purpose) {
-    this.version = version;
-    this.purpose = purpose;
-  }
-
-  /**
+    /**
    * Return the header which is a concatenation of the version and the purpose
    *
    * @return the header in the format: {version}.{purpose}.