issue #11 -Implement authentication refactor: Add CfAuth interface, ApiTokenAuth and EmailKeyAuth implementations, and CfAuthBuilder for flexible authentication in CfDnsClient. Update tests and adjust related classes for compatibility.

src/main/java/codes/thischwa/cf/CfBasicHttpClient.java

@@ -1,5 +1,6 @@
 package codes.thischwa.cf;
 
+import codes.thischwa.cf.auth.CfAuth;
 import codes.thischwa.cf.model.AbstractResponse;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -19,6 +20,7 @@ import org.apache.hc.core5.http.HttpHeaders;
 import org.apache.hc.core5.http.io.entity.EntityUtils;
 import org.apache.hc.core5.http.io.entity.StringEntity;
 import org.apache.hc.core5.http.message.BasicClassicHttpRequest;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Abstract base class for creating HTTP clients to interact with the Cloudflare API. Provides
@@ -27,23 +29,20 @@ import org.apache.hc.core5.http.message.BasicClassicHttpRequest;
  */
 @Slf4j
 abstract class CfBasicHttpClient {
-  private final String baseUrl;
-  private final String authEmail;
-  private final String authKey;
 
+  private final String baseUrl;
+  private final CfAuth auth;
   private final ObjectMapper objectMapper;
 
-  CfBasicHttpClient(String baseUrl, String authEmail, String authKey)
+  /**
-      throws IllegalArgumentException {
+   * Creates a new Cloudflare HTTP client with the specified base URL and authentication.
-    if (authEmail == null || authEmail.isBlank()) {
+   *
-      throw new IllegalArgumentException("Authentication email must not be null or blank!");
+   * @param baseUrl the base URL for the Cloudflare API
-    }
+   * @param auth    the authentication mechanism to use
-    if (authKey == null || authKey.isBlank()) {
+   */
-      throw new IllegalArgumentException("Authentication key must not be null or blank!");
+  CfBasicHttpClient(@NotNull String baseUrl, @NotNull CfAuth auth) {
-    }
     this.baseUrl = baseUrl;
-    this.authEmail = authEmail;
+    this.auth = auth;
-    this.authKey = authKey;
     this.objectMapper = JsonConf.initObjectMapper();
   }
 
@@ -53,8 +52,9 @@ abstract class CfBasicHttpClient {
       request.addHeader(HttpHeaders.ACCEPT_ENCODING, "gzip");
       request.addHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.getMimeType());
       request.addHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.getMimeType());
-      request.addHeader("X-Auth-Email", authEmail);
+      if (request instanceof ClassicHttpRequest classicRequest) {
-      request.addHeader("X-Auth-Key", authKey);
+        auth.applyAuth(classicRequest);
+      }
     }).build();
   }
 

src/main/java/codes/thischwa/cf/CfDnsClient.java

@@ -1,5 +1,6 @@
 package codes.thischwa.cf;
 
+import codes.thischwa.cf.auth.CfAuth;
 import codes.thischwa.cf.fluent.ZoneOperations;
 import codes.thischwa.cf.fluent.ZoneOperationsImpl;
 import codes.thischwa.cf.model.AbstractResponse;
@@ -26,57 +27,71 @@ import org.jetbrains.annotations.Nullable;
  * records and zones within the Cloudflare system, including creating, updating, retrieving, and
  * deleting DNS records.
  *
- * <p>Example:
+ * <p>Example with API token authentication (recommended):
  * <pre><code>
- * // Create a new CfDnsClient instance
+ * // Create a new CfDnsClient instance with API token
- * CfDnsClient cfDnsClient = new CfDnsClient(
+ * CfDnsClient cfDnsClient = new CfDnsClient(CfAuthBuilder.build("your-api-token"));
- *     "email@example.com",
+ *
- *     "yourApiKey"
- * );
  * // Retrieve a zone
  * ZoneEntity zone = cfDnsClient.zoneGet("example.com");
  * System.out.println("Zone ID: " + zone.getId());
+ *
  * // Retrieve records of a subdomain
- * List&lt;{@link RecordEntity}&gt; records = cfDnsClient.recordGet(zone, "sld");
+ * List&lt;RecordEntity&gt; records = cfDnsClient.recordList(zone, "sld");
  * records.forEach(record ->
  *     System.out.println("Record Type: " + record.getType() + ", Value: " + record.getContent())
  * );
+ *
  * // Create a record for the subdomain "api"
  * RecordEntity created = cfDnsClient.recordCreateSld(zone, "api", 60, RecordType.A, "192.168.1.10");
  * System.out.println("Created Record ID: " + created.getId());
  * </code></pre>
+ *
+ * <p>Example with email/key authentication (legacy):
+ * <pre><code>
+ * CfDnsClient cfDnsClient = new CfDnsClient(
+ *     CfAuthBuilder.build("email@example.com", "your-api-key")
+ * );
+ * </code></pre>
+ *
+ * <p>Example with exception throwing enabled:
+ * <pre><code>
+ * // Throws exception when results are empty
+ * CfDnsClient cfDnsClient = new CfDnsClient(true, CfAuthBuilder.build("your-api-token"));
+ * </code></pre>
+ *
+ * <p>Example with custom base URL:
+ * <pre><code>
+ * CfAuth auth = CfAuthBuilder.build("your-api-token");
+ * auth.setBaseUrl("https://custom-api.example.com");
+ * CfDnsClient cfDnsClient = new CfDnsClient(auth);
+ * </code></pre>
  */
 @Slf4j
 public class CfDnsClient extends CfBasicHttpClient {
-  private static final String DEFAULT_BASEURL = "https://api.cloudflare.com/client/v4";
 
+  public static final String DEFAULT_BASEURL = "https://api.cloudflare.com/client/v4";
   private final ResponseValidator responseValidator;
 
   private final boolean emptyResultThrowsException;
 
   /**
-   * Constructs a new instance of {@code CfDnsClient}.
+   * Constructs a new instance of {@code CfDnsClient} with default configuration.
    *
-   * @param authEmail The email address associated with the Cloudflare account, used for
+   * @param auth The authentication mechanism to use (ApiTokenAuth or EmailKeyAuth)
-   *                  authentication.
-   * @param authKey   The API key of the Cloudflare account, used as part of the authentication
-   *                  process.
    */
-  public CfDnsClient(String authEmail, String authKey) {
+  public CfDnsClient(CfAuth auth) {
-    this(DEFAULT_BASEURL, authEmail, authKey);
+    this(false, DEFAULT_BASEURL, auth);
   }
 
   /**
    * Constructs a new instance of {@code CfDnsClient}.
    *
    * @param baseUrl The base URL of the Cloudflare API to be used for requests.
-   * @param authEmail The email address associated with the Cloudflare account, used for
+   * @param auth    The authentication mechanism to use (ApiTokenAuth or EmailKeyAuth)
-   *                  authentication.
-   * @param authKey   The API key of the Cloudflare account, used as part of the authentication
-   *                  process.
    */
-  public CfDnsClient(String baseUrl, String authEmail, String authKey) {
+  public CfDnsClient(String baseUrl, CfAuth auth) {
-    this(false, baseUrl, authEmail, authKey);
+    this(false, baseUrl, auth);
   }
 
   /**
@@ -85,13 +100,10 @@ public class CfDnsClient extends CfBasicHttpClient {
    * @param emptyResultThrowsException A boolean value indicating whether an exception should be
    *                                   thrown when the result is empty. Applies to both single and
    *                                   multiple result requests. Default is false.
-   * @param authEmail                  The email address associated with the Cloudflare account,
+   * @param auth                       The authentication mechanism to use (ApiTokenAuth or EmailKeyAuth)
-   *                                   used for authentication.
-   * @param authKey                    The API key of the Cloudflare account, used as part of the
-   *                                   authentication process.
    */
-  public CfDnsClient(boolean emptyResultThrowsException, String authEmail, String authKey) {
+  public CfDnsClient(boolean emptyResultThrowsException, CfAuth auth) {
-    this(emptyResultThrowsException, DEFAULT_BASEURL, authEmail, authKey);
+    this(emptyResultThrowsException, DEFAULT_BASEURL, auth);
   }
 
   /**
@@ -101,14 +113,10 @@ public class CfDnsClient extends CfBasicHttpClient {
    *                                   thrown when the result is empty. Applies to both single and
    *                                   multiple result requests. Default is false.
    * @param baseUrl                    The base URL for the Cloudflare API endpoint.
-   * @param authEmail                  The email associated with the Cloudflare account for
+   * @param auth                       The authentication mechanism to use (ApiTokenAuth or EmailKeyAuth)
-   *                                   authentication.
-   * @param authKey                    The API key for authenticating the client with Cloudflare
-   *                                   services.
    */
-  public CfDnsClient(boolean emptyResultThrowsException, String baseUrl, String authEmail,
+  public CfDnsClient(boolean emptyResultThrowsException, String baseUrl, CfAuth auth) {
-                     String authKey) {
+    super(baseUrl, auth);
-    super(baseUrl, authEmail, authKey);
     this.responseValidator = new ResponseValidator(emptyResultThrowsException);
     this.emptyResultThrowsException = emptyResultThrowsException;
   }

src/main/java/codes/thischwa/cf/auth/ApiTokenAuth.java

@@ -0,0 +1,31 @@
+package codes.thischwa.cf.auth;
+
+import org.apache.hc.core5.http.ClassicHttpRequest;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Authentication mechanism using Cloudflare API token.
+ * This is the recommended authentication method for the Cloudflare API.
+ */
+public class ApiTokenAuth implements CfAuth {
+
+  private final String apiToken;
+
+  /**
+   * Creates a new API token authentication object.
+   *
+   * @param apiToken the Cloudflare API token
+   * @throws IllegalArgumentException if the API token is null or blank
+   */
+  public ApiTokenAuth(@NotNull String apiToken) {
+    if (apiToken.isBlank()) {
+      throw new IllegalArgumentException("API token must not be null or blank!");
+    }
+    this.apiToken = apiToken;
+  }
+
+  @Override
+  public void applyAuth(ClassicHttpRequest request) {
+    request.addHeader("Authorization", "Bearer " + apiToken);
+  }
+}

src/main/java/codes/thischwa/cf/auth/CfAuth.java

@@ -0,0 +1,19 @@
+package codes.thischwa.cf.auth;
+
+import org.apache.hc.core5.http.ClassicHttpRequest;
+
+/**
+ * Interface for Cloudflare authentication mechanisms.
+ * Implementations of this interface provide different methods of authentication
+ * with the Cloudflare API (e.g., API token, email/key combination).
+ */
+public interface CfAuth {
+
+  /**
+   * Applies authentication headers to the given HTTP request.
+   *
+   * @param request the HTTP request to authenticate
+   */
+  void applyAuth(ClassicHttpRequest request);
+
+}

src/main/java/codes/thischwa/cf/auth/CfAuthBuilder.java

@@ -0,0 +1,12 @@
+package codes.thischwa.cf.auth;
+
+public class CfAuthBuilder {
+
+  public static ApiTokenAuth build(String apiToken) {
+    return new ApiTokenAuth(apiToken);
+  }
+
+  public static EmailKeyAuth build(String authEmail, String authKey) {
+    return new EmailKeyAuth(authEmail, authKey);
+  }
+}

src/main/java/codes/thischwa/cf/auth/EmailKeyAuth.java

@@ -0,0 +1,38 @@
+package codes.thischwa.cf.auth;
+
+import org.apache.hc.core5.http.ClassicHttpRequest;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Authentication mechanism using Cloudflare account email and API key.
+ * This is the legacy authentication method for the Cloudflare API.
+ */
+public class EmailKeyAuth implements CfAuth {
+
+  private final String authEmail;
+  private final String authKey;
+
+  /**
+   * Creates a new email/key authentication object.
+   *
+   * @param authEmail the email address associated with the Cloudflare account
+   * @param authKey   the API key of the Cloudflare account
+   * @throws IllegalArgumentException if email or key is null or blank
+   */
+  public EmailKeyAuth(@NotNull String authEmail, @NotNull String authKey) {
+    if (authEmail.isBlank()) {
+      throw new IllegalArgumentException("Authentication email must not be null or blank!");
+    }
+    if (authKey.isBlank()) {
+      throw new IllegalArgumentException("Authentication key must not be null or blank!");
+    }
+    this.authEmail = authEmail;
+    this.authKey = authKey;
+  }
+
+  @Override
+  public void applyAuth(ClassicHttpRequest request) {
+    request.addHeader("X-Auth-Email", authEmail);
+    request.addHeader("X-Auth-Key", authKey);
+  }
+}

src/main/java/codes/thischwa/cf/auth/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * The authentication package of CloudflareDNS-java.
+ */
+
+package codes.thischwa.cf.auth;

src/main/java/codes/thischwa/cf/model/RecordEntity.java

@@ -64,10 +64,10 @@ public class RecordEntity extends AbstractEntity {
    */
   public static RecordEntity build(String name, RecordType type, Integer ttl, String content) {
     RecordEntity rec = new RecordEntity();
-    rec.setName(name);
+    rec.name = name;
-    rec.setType(type.getType());
+    rec.type = type.getType();
-    rec.setTtl(ttl);
+    rec.ttl = ttl;
-    rec.setContent(content);
+    rec.content = content;
     return rec;
   }
 
@@ -81,7 +81,7 @@ public class RecordEntity extends AbstractEntity {
   public static RecordEntity build(String id, String content) {
     RecordEntity rec = new RecordEntity();
     rec.setId(id);
-    rec.setContent(content);
+    rec.content = content;
     return rec;
   }
 
@@ -104,8 +104,12 @@ public class RecordEntity extends AbstractEntity {
       throw new IllegalArgumentException("Invalid record type: " + type + ". Must be one of: "
           + java.util.Arrays.toString(RecordType.values()), e);
     }
-    RecordEntity rec = build(name, recordType, ttl, content);
+    RecordEntity rec = new RecordEntity();
     rec.setId(id);
+    rec.name = name;
+    rec.type = recordType.getType();
+    rec.ttl = ttl;
+    rec.content = content;
     return rec;
   }
 

src/main/java/codes/thischwa/cf/model/RecordType.java

@@ -199,6 +199,6 @@ public enum RecordType {
 
   @Override
   public String toString() {
-    return getType();
+    return type;
   }
 }

src/test/java/codes/thischwa/cf/CfClientPenTest.java

@@ -4,6 +4,7 @@ import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assumptions.assumeTrue;
 
+import codes.thischwa.cf.auth.CfAuthBuilder;
 import codes.thischwa.cf.model.RecordType;
 import codes.thischwa.cf.model.ZoneEntity;
 import java.util.List;
@@ -22,24 +23,22 @@ public class CfClientPenTest {
 
   private static final String ZONE_STR = "mein-d-ns.de"; // existing baseline zone
 
-  private static final String API_EMAIL = System.getenv("API_EMAIL");
+  private static final String API_TOKEN = System.getenv("API_TOKEN");
-  private static final String API_KEY = System.getenv("API_KEY");
 
   @BeforeAll
   static void checkEnv() {
-    assumeTrue(API_EMAIL != null && !API_EMAIL.isBlank(), "API_EMAIL not set; skipping pen tests");
+    assumeTrue(API_TOKEN != null && !API_TOKEN.isBlank(), "API_TOKEN not set; skipping pen tests");
-    assumeTrue(API_KEY != null && !API_KEY.isBlank(), "API_KEY not set; skipping pen tests");
   }
 
   private CfDnsClient newClient() {
-    return new CfDnsClient(true, API_EMAIL, API_KEY);
+    return new CfDnsClient(true, CfAuthBuilder.build(API_TOKEN));
   }
 
   @Test
   @DisplayName("Invalid credentials should not authenticate and must throw CloudflareApiException")
   void testInvalidCredentialsShouldFail() {
     // Use syntactically valid but wrong credentials
-    CfDnsClient badClient = new CfDnsClient("invalid@example.com", UUID.randomUUID().toString());
+    CfDnsClient badClient = new CfDnsClient(CfAuthBuilder.build("invalid@example.com", UUID.randomUUID().toString()));
     assertThrows(CloudflareApiException.class, badClient::zoneList);
   }
 

src/test/java/codes/thischwa/cf/CfClientTest.java

@@ -8,6 +8,9 @@ import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.Assertions.fail;
 import static org.junit.jupiter.api.Assumptions.assumeTrue;
 
+import codes.thischwa.cf.auth.ApiTokenAuth;
+import codes.thischwa.cf.auth.CfAuthBuilder;
+import codes.thischwa.cf.auth.EmailKeyAuth;
 import codes.thischwa.cf.model.BatchEntry;
 import codes.thischwa.cf.model.RecordEntity;
 import codes.thischwa.cf.model.RecordType;
@@ -28,15 +31,13 @@ public class CfClientTest {
   private static final String SLD_STR = "devsld";
   private static final int TTL = 60;
 
-  private static final String API_EMAIL = System.getenv("API_EMAIL");
+  private static final String API_TOKEN = System.getenv("API_TOKEN");
-  private static final String API_KEY = System.getenv("API_KEY");
 
-  private final CfDnsClient client = new CfDnsClient(true, API_EMAIL, API_KEY);
+  private final CfDnsClient client = new CfDnsClient(true, CfAuthBuilder.build(API_TOKEN));
 
   @BeforeAll
   static void checkEnv() {
-    assumeTrue(API_EMAIL != null && !API_EMAIL.isBlank(), "API_EMAIL not set; skipping pen tests");
+    assumeTrue(API_TOKEN != null && !API_TOKEN.isBlank(), "API_TOKEN not set; skipping client tests");
-    assumeTrue(API_KEY != null && !API_KEY.isBlank(), "API_KEY not set; skipping pen tests");
   }
 
   @Test
@@ -106,13 +107,13 @@ public class CfClientTest {
   void testDns() throws Exception {
     // starting point: already existing zone 'mein-d-ns.de'
     ZoneEntity z = client.zoneGet(ZONE_STR);
-    assertEquals("0a83dd6e7f8c46039f2517bbded8115e", z.getId());
+    assertEquals("cf9d8b12f61423f280e0a3ea2a96d921", z.getId());
     assertEquals("mein-d-ns.de", z.getName());
     assertEquals("active", z.getStatus());
     assertEquals(2, z.getNameServers().size());
-    assertTrue(z.getNameServers().contains("sergi.ns.cloudflare.com"));
+    assertTrue(z.getNameServers().contains("rafe.ns.cloudflare.com"));
-    assertEquals(4, z.getOriginalNameServers().size());
+    assertTrue(z.getOriginalNameServers().size() >= 2);
-    assertTrue(z.getOriginalNameServers().contains("a.ns14.net"));
+    assertTrue(z.getOriginalNameServers().contains("blair.ns.cloudflare.com"));
     assertNotNull(z.getActivatedOn());
     assertNotNull(z.getModifiedOn());
     assertNotNull(z.getCreatedOn());
@@ -226,10 +227,12 @@ public class CfClientTest {
 
   @Test
   void testException() {
-    assertThrows(IllegalArgumentException.class, () -> new CfDnsClient(null, "key"));
+    // Test EmailKeyAuth validation
-    assertThrows(IllegalArgumentException.class, () -> new CfDnsClient("email", null));
+    assertThrows(IllegalArgumentException.class, () -> new EmailKeyAuth("email", ""));
-    assertThrows(IllegalArgumentException.class, () -> new CfDnsClient("email", ""));
+    assertThrows(IllegalArgumentException.class, () -> new EmailKeyAuth("", "key"));
-    assertThrows(IllegalArgumentException.class, () -> new CfDnsClient("", "key"));
+
+    // Test ApiTokenAuth validation;
+    assertThrows(IllegalArgumentException.class, () -> new ApiTokenAuth(""));
   }
 
   @Test