fix(h005): validate download arguments before any bank contact, use LocalDate

Review round 1 on the BTD download support.

- Reject a partial or reversed date range in the EbicsDownloadParams constructor,
  the one place every caller passes through. A half range used to be dropped when
  the request was built, on the launcher's legacy path without even a warning; a
  reversed range is schema-valid and comes back as EBICS_NO_DOWNLOAD_DATA_AVAILABLE,
  indistinguishable from a genuinely empty period.
- Check every launcher argument before the first environment read, keystore access
  or bank call. It ran after loadUser/createUser and after --ini/--hia/--hpb, so an
  incomplete --btd order could still fire an INI request first, and INI is one-shot
  at most banks.
- Carry the report period as LocalDate instead of Date. A calendar day read out of
  an instant depends on the machine's timezone: a UTC-midnight Date becomes the
  previous day west of UTC. The Date-taking overloads are kept and now document
  that. Adds createDateRange(LocalDate, LocalDate).
- Upper-case the EBICS code list values (--service, --scope, --option, --container)
  so --container zip no longer aborts. Message names such as camt.053 stay as given.

Tests 31 -> 36. New guards were each seen failing first.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 2 people

src/main/java/org/kopi/ebics/client/EbicsClient.java

@@ -58,6 +58,7 @@
 import org.kopi.ebics.session.OrderType;
 import org.kopi.ebics.session.Product;
 import org.kopi.ebics.utils.Constants;
+import org.kopi.ebics.xml.EbicsXmlFactory;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -446,10 +447,22 @@ public void fetchFile(File file, User user, Product product, EbicsOrderType orde
         }
     }
 
+    /**
+     * Downloads a file for a report period.
+     *
+     * <p><b>A {@link Date} is an instant, the EBICS report period is a pair of calendar days.</b>
+     * The calendar day is therefore read in the timezone of the machine running this code, so a
+     * {@code Date} at UTC midnight becomes the previous day in any zone west of UTC. Prefer
+     * {@link #fetchFile(File, User, Product, EbicsOrderType, EbicsDownloadParams, boolean)} with
+     * {@link java.time.LocalDate} values, which has no timezone in it.
+     */
     public void fetchFile(File file, EbicsOrderType orderType, Date start, Date end) throws IOException,
         EbicsException {
         fetchFile(file, defaultUser, defaultProduct, orderType,
-            EbicsDownloadParams.dateRangeOnly(start, end), false);
+            EbicsDownloadParams.dateRangeOnly(
+                start == null ? null : EbicsXmlFactory.toLocalDate(start),
+                end == null ? null : EbicsXmlFactory.toLocalDate(end)),
+            false);
     }
 
     /**

src/main/java/org/kopi/ebics/client/EbicsDownloadParams.java

@@ -1,6 +1,6 @@
 package org.kopi.ebics.client;
 
-import java.util.Date;
+import java.time.LocalDate;
 
 /**
  * Service parameters for an EBICS 3.0 (H005) BTD download order.
@@ -9,6 +9,15 @@
  * {@code BTDOrderParams/Service} block. With {@code serviceName} left {@code null}, only the
  * optional date range is applied and the legacy EBICS 2.x order type is kept, so existing
  * callers keep their behaviour.
+ *
+ * <p>The report period is a pair of calendar days ({@link LocalDate}), not instants: EBICS sends
+ * it as {@code xs:date}, and a timezone in that position only creates off-by-one-day bugs.
+ *
+ * <p>The constructor rejects a partial or reversed range. Both would otherwise travel silently:
+ * a half range is dropped when the request is built, and a reversed one is schema-valid and comes
+ * back as "no data available", which is indistinguishable from a period that really was empty.
+ * This is the single place every caller passes through, so the check lives here rather than in
+ * each caller.
  */
 public record EbicsDownloadParams(
     String serviceName,
@@ -17,11 +26,23 @@ public record EbicsDownloadParams(
     String messageName,
     String messageVersion,
     String containerType,
-    Date startDate,
-    Date endDate) {
+    LocalDate startDate,
+    LocalDate endDate) {
+
+    public EbicsDownloadParams {
+        if ((startDate == null) != (endDate == null)) {
+            throw new IllegalArgumentException(
+                "startDate and endDate must be given together (--start/--end); a single one"
+                    + " would be dropped from the bank request");
+        }
+        if (startDate != null && endDate.isBefore(startDate)) {
+            throw new IllegalArgumentException(
+                "endDate must not be before startDate, got " + startDate + " to " + endDate);
+        }
+    }
 
     /** Date-range-only parameters for the legacy (non-BTD) download path. */
-    public static EbicsDownloadParams dateRangeOnly(Date startDate, Date endDate) {
+    public static EbicsDownloadParams dateRangeOnly(LocalDate startDate, LocalDate endDate) {
         if (startDate == null && endDate == null) {
             return null;
         }

src/main/java/org/kopi/ebics/client/ParameterizedEbicsClientLauncher.java

@@ -68,6 +68,11 @@ public static void main(String[] args) throws Exception {
             return;
         }
 
+        // Every argument is checked before the first environment read, keystore access or bank
+        // call. INI is one-shot at most banks: aborting on a missing --container after the INI
+        // request has gone out would leave a half-initialised access behind.
+        validateArguments(parsedArguments);
+
         String passphrase = requiredEnv("EBICS_PASSWORD");
         String userId = requiredEnv("EBICS_USER_ID");
         String partnerId = requiredEnv("EBICS_PARTNER_ID");
@@ -162,10 +167,7 @@ public static void main(String[] args) throws Exception {
                     user,
                     product,
                     orderType,
-                    EbicsDownloadParams.dateRangeOnly(
-                        parseDate(parsedArguments.startDate(), "--start"),
-                        parseDate(parsedArguments.endDate(), "--end")
-                    ),
+                    legacyDownloadParams(parsedArguments),
                     Boolean.parseBoolean(env("EBICS_TEST_MODE", "false"))
                 );
             }
@@ -187,25 +189,50 @@ private static void printUsage() {
         System.out.println(usage);
     }
 
+    /**
+     * Rejects every unusable argument combination before the program talks to anyone. Nothing here
+     * touches the network, the filesystem or the environment.
+     */
+    static void validateArguments(ParsedArguments parsedArguments) {
+        if (parsedArguments.hasFlag("--btd")) {
+            btdDownloadParams(parsedArguments);
+            requireOutputPath(parsedArguments);
+        } else {
+            legacyDownloadParams(parsedArguments);
+        }
+    }
+
     /**
      * Builds the EBICS 3.0 service parameters for {@code --btd}. Fails fast on a missing mandatory
-     * value, so a half-filled order is never sent to the bank.
+     * value, so a half-filled order is never sent to the bank. The date range pair itself is
+     * checked by {@link EbicsDownloadParams}, which covers every other caller too.
      */
     static EbicsDownloadParams btdDownloadParams(ParsedArguments parsedArguments) {
-        // A half date range would be dropped silently further down, which is exactly how a
-        // catch-up run loses the days it was supposed to fetch.
-        if ((parsedArguments.startDate() == null) != (parsedArguments.endDate() == null)) {
-            throw new IllegalArgumentException(
-                "Options --start and --end must be given together, a single one is ignored"
-                    + " by the bank request");
-        }
         return new EbicsDownloadParams(
-            requireOption(parsedArguments.serviceName(), "--service"),
-            requireOption(parsedArguments.scope(), "--scope"),
-            parsedArguments.option(),
+            upperCase(requireOption(parsedArguments.serviceName(), "--service")),
+            upperCase(requireOption(parsedArguments.scope(), "--scope")),
+            upperCase(parsedArguments.option()),
             requireOption(parsedArguments.messageName(), "--msg-name"),
             requireOption(parsedArguments.messageVersion(), "--msg-version"),
-            requireOption(parsedArguments.containerType(), "--container"),
+            upperCase(requireOption(parsedArguments.containerType(), "--container")),
+            parseDate(parsedArguments.startDate(), "--start"),
+            parseDate(parsedArguments.endDate(), "--end")
+        );
+    }
+
+    /**
+     * Service code, scope, service option and container type are EBICS code list values and are
+     * always upper case. Message names like {@code camt.053} are not, and stay untouched.
+     */
+    private static String upperCase(String value) {
+        return value == null ? null : value.toUpperCase(Locale.ROOT);
+    }
+
+    /**
+     * Builds the date-range-only parameters of the legacy (EBICS 2.x) download path.
+     */
+    static EbicsDownloadParams legacyDownloadParams(ParsedArguments parsedArguments) {
+        return EbicsDownloadParams.dateRangeOnly(
             parseDate(parsedArguments.startDate(), "--start"),
             parseDate(parsedArguments.endDate(), "--end")
         );
@@ -223,14 +250,17 @@ private static String requireOption(String value, String option) {
         return normalized;
     }
 
-    private static Date parseDate(String value, String option) {
+    /**
+     * Parses a {@code YYYY-MM-DD} argument into a calendar day. No timezone is involved, so the
+     * day the user typed is the day that reaches the bank, wherever the job runs.
+     */
+    private static LocalDate parseDate(String value, String option) {
         String normalized = normalize(value);
         if (normalized == null) {
             return null;
         }
         try {
-            return Date.from(LocalDate.parse(normalized)
-                .atStartOfDay(ZoneId.systemDefault()).toInstant());
+            return LocalDate.parse(normalized);
         } catch (DateTimeParseException e) {
             throw new IllegalArgumentException(
                 "Option " + option + " expects a date as YYYY-MM-DD but was: " + normalized);

src/main/java/org/kopi/ebics/xml/DownloadInitializationRequestElement.java

@@ -115,8 +115,8 @@ public void buildInitialization() throws EbicsException {
           type.setStringValue(this.getType());
           StandardOrderParamsType standardOrderParamsType =
               EbicsXmlFactory.createStandardOrderParamsType();
-          if (downloadParams != null
-              && downloadParams.startDate() != null && downloadParams.endDate() != null) {
+          // EbicsDownloadParams guarantees the range is either absent or complete.
+          if (downloadParams != null && downloadParams.startDate() != null) {
               standardOrderParamsType.setDateRange(EbicsXmlFactory.createDateRange(
                   downloadParams.startDate(), downloadParams.endDate()));
           }

src/main/java/org/kopi/ebics/xml/EbicsXmlFactory.java

@@ -18,6 +18,7 @@
 
 package org.kopi.ebics.xml;
 
+import java.time.LocalDate;
 import java.time.ZoneId;
 import java.util.Calendar;
 import java.util.Date;
@@ -934,12 +935,15 @@ public static BTUParamsType createBTUParams(String serviceName, String scope, St
      * @param messageVersion the message version, e.g. {@code 08}
      * @param containerType  the container type ({@code XML}, {@code ZIP} or {@code SVC});
      *                       may be {@code null}
-     * @param start          the start of the requested report period; may be {@code null}
-     * @param end            the end of the requested report period; may be {@code null}
+     * @param start          the first calendar day of the requested report period; may be
+     *                       {@code null}
+     * @param end            the last calendar day of the requested report period; may be
+     *                       {@code null}
      * @return the <code>BTDParamsType</code> XML object
      */
     public static BTDParamsType createBTDParams(String serviceName, String scope, String option,
-        String messageName, String messageVersion, String containerType, Date start, Date end) {
+        String messageName, String messageVersion, String containerType,
+        LocalDate start, LocalDate end) {
         var type = BTDParamsType.Factory.newInstance();
         var service = type.addNewService();
         service.setServiceName(serviceName);
@@ -972,14 +976,15 @@ public static BTDParamsType createBTDParams(String serviceName, String scope, St
     }
 
     /**
-     * Converts a date into an <code>xs:date</code> value without a timezone offset. Passing a
-     * {@link Calendar} instead would make XMLBeans append the local offset (e.g.
-     * {@code 2026-08-10+02:00}), which shifts the reported day for a bank in another timezone.
+     * Converts a calendar day into an <code>xs:date</code> value. No timezone is involved in
+     * either direction: setting a {@link Calendar} would make XMLBeans append the local offset
+     * (e.g. {@code 2026-08-10+02:00}), which shifts the reported day for a bank in another
+     * timezone, and converting through an instant would make the day itself depend on the
+     * machine's zone.
      */
-    private static DateType toXmlDate(Date date) {
+    private static DateType toXmlDate(LocalDate date) {
         var value = DateType.Factory.newInstance();
-        value.setStringValue(
-            date.toInstant().atZone(ZoneId.systemDefault()).toLocalDate().toString());
+        value.setStringValue(date.toString());
         return value;
     }
 
@@ -1034,13 +1039,29 @@ public static StandardOrderParamsType createStandardOrderParamsType() {
     }
 
     /**
-     * Creates a new <code>DateRange</code> XML object
+     * Creates a new <code>DateRange</code> XML object.
+     *
+     * <p><b>A {@link Date} is an instant, the EBICS date range is a pair of calendar days.</b>
+     * The calendar day is therefore taken in the timezone of the machine running this code: a
+     * {@code Date} at UTC midnight becomes the previous day in any zone west of UTC. Prefer
+     * {@link #createDateRange(LocalDate, LocalDate)} — that overload has no timezone in it.
      *
      * @param start the start range
      * @param end   the end range
      * @return the <code>DateRange</code> XML object
      */
     public static StandardOrderParamsType.DateRange createDateRange(Date start, Date end) {
+        return createDateRange(toLocalDate(start), toLocalDate(end));
+    }
+
+    /**
+     * Creates a new <code>DateRange</code> XML object from two calendar days.
+     *
+     * @param start the first day of the range
+     * @param end   the last day of the range
+     * @return the <code>DateRange</code> XML object
+     */
+    public static StandardOrderParamsType.DateRange createDateRange(LocalDate start, LocalDate end) {
         StandardOrderParamsType.DateRange newDateRange = StandardOrderParamsType.DateRange.Factory.newInstance();
 
         newDateRange.xsetStart(toXmlDate(start));
@@ -1049,6 +1070,14 @@ public static StandardOrderParamsType.DateRange createDateRange(Date start, Date
         return newDateRange;
     }
 
+    /**
+     * Reads the calendar day out of an instant, in the timezone of this machine. Only for the
+     * {@link Date}-based compatibility overloads; anything new should carry a {@link LocalDate}.
+     */
+    public static LocalDate toLocalDate(Date date) {
+        return date.toInstant().atZone(ZoneId.systemDefault()).toLocalDate();
+    }
+
 //    /**
 //     * Creates a new <code>FileFormatType</code> XML object
 //     *