fix(server): boot a fresh install that passes no credential-rotation keys

The Compose files forward `HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY` and its
version with an empty default, so an operator who configured neither still starts the
container with both set to "". Spring binds that as "" for the String and as null for the
Integer beside it, so the both-or-neither rule in SecurityProperties read a fresh install
as a half-finished rotation and the application server crash-looped before Tomcat came up.

Treat blank as absent in SecurityProperties, the way NatsConnectionProperties already does
for the NATS credential pair, and let the rules below read one notion of "configured". The
invariant is not weakened. A prior key without its version, or a version without its key,
still fails at startup, so a rotation cannot half-apply and make credentials unreadable.

Verified against the released v0.75.0 image lock and the blessed self-host install. After
`setup.sh`, `docker compose up` crash-loops on the release image and reports healthy once
the fixed class is in place, with both variables still arriving empty. The new unit tests
bind through a real system environment and fail without the fix.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: FelixTJDietrich

.changeset/self-host-blank-rotation-keys.md

@@ -0,0 +1,11 @@
+---
+"hephaestus": patch
+---
+
+A fresh self-host install now starts instead of crash-looping with
+`hephaestus.security.prior-credential-encryption-key and prior-credential-encryption-key-version must
+be configured together`. The stack passes both credential-rotation variables through empty when you
+have not set them, and Hephaestus was reading one empty value as a half-finished key rotation; an
+empty value now means what you meant by it — not configured. Finishing a rotation by clearing the
+prior key and its version works the same way. Setting only one of the two is still refused at
+startup, so a rotation cannot half-apply and leave stored credentials unreadable.

server/application/src/main/java/de/tum/cit/aet/hephaestus/core/security/SecurityProperties.java

@@ -18,6 +18,14 @@ public record SecurityProperties(
         @DefaultValue("100") int credentialRotationBatchSize) {
 
     public SecurityProperties {
+        // The Compose files forward every key in this block, so an operator who set none of them
+        // still hands the container `HEPHAESTUS_SECURITY_*=""`. Blank is how "unset" arrives here —
+        // a String binds it as "" while the paired Integer version binds it as null, so comparing
+        // the raw values would read a fresh install as a half-finished key rotation and refuse to
+        // boot. Normalize first; every rule below then reads the same notion of "configured".
+        credentialEncryptionKey = blankToNull(credentialEncryptionKey);
+        priorCredentialEncryptionKey = blankToNull(priorCredentialEncryptionKey);
+
         if (credentialEncryptionKeyVersion < 1) {
             throw new IllegalArgumentException(
                     "hephaestus.security.credential-encryption-key-version must be positive");
@@ -34,12 +42,12 @@ public record SecurityProperties(
             throw new IllegalArgumentException(
                     "hephaestus.security.credential-rotation-batch-size must be between 1 and 10000");
         }
-        if (credentialRotationEnabled
-                && (credentialEncryptionKey == null
-                        || credentialEncryptionKey.isBlank()
-                        || priorCredentialEncryptionKey == null
-                        || priorCredentialEncryptionKey.isBlank())) {
+        if (credentialRotationEnabled && (credentialEncryptionKey == null || priorCredentialEncryptionKey == null)) {
             throw new IllegalArgumentException("Credential rotation requires both active and prior encryption keys");
         }
     }
+
+    private static @Nullable String blankToNull(@Nullable String value) {
+        return value == null || value.isBlank() ? null : value;
+    }
 }

server/application/src/test/java/de/tum/cit/aet/hephaestus/core/security/SecurityPropertiesEnvBindingTest.java

@@ -0,0 +1,105 @@
+package de.tum.cit.aet.hephaestus.core.security;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import de.tum.cit.aet.hephaestus.testconfig.BaseUnitTest;
+import java.util.Map;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.context.properties.bind.Binder;
+import org.springframework.core.env.StandardEnvironment;
+import org.springframework.core.env.SystemEnvironmentPropertySource;
+
+/**
+ * The Compose files forward the whole {@code hephaestus.security} block, so a self-hosted install
+ * that configured none of it still starts the container with those variables set to the empty
+ * string. Binding therefore has to agree with the operator that they configured nothing: a fresh
+ * install must boot, and the rotation pair must still fail loudly when only one half is real.
+ *
+ * <p>These bind through a real {@link SystemEnvironmentPropertySource}, because the defect this
+ * covers only exists in the environment: a blank {@code String} binds as {@code ""} while the
+ * {@code Integer} beside it binds as {@code null}, which is what made "both or neither" reject
+ * neither.
+ */
+class SecurityPropertiesEnvBindingTest extends BaseUnitTest {
+
+    @Test
+    void shouldBindNoRotationWhenTheForwardedRotationKeysAreBlank() {
+        SecurityProperties properties = bindWith(Map.of(
+                "HEPHAESTUS_SECURITY_CREDENTIAL_ENCRYPTION_KEY",
+                "0123456789abcdef0123456789abcdef",
+                "HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY",
+                "",
+                "HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY_VERSION",
+                ""));
+
+        assertThat(properties.priorCredentialEncryptionKey())
+                .as("a forwarded-but-empty key is unset, not a half-finished rotation")
+                .isNull();
+        assertThat(properties.priorCredentialEncryptionKeyVersion()).isNull();
+    }
+
+    @Test
+    void shouldBindNoKeysWhenEveryForwardedValueIsBlank() {
+        SecurityProperties properties = bindWith(Map.of(
+                "HEPHAESTUS_SECURITY_CREDENTIAL_ENCRYPTION_KEY",
+                "",
+                "HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY",
+                "",
+                "HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY_VERSION",
+                ""));
+
+        assertThat(properties.credentialEncryptionKey()).isNull();
+        assertThat(properties.priorCredentialEncryptionKey()).isNull();
+    }
+
+    @Test
+    void shouldRejectAPriorKeyWhoseVersionIsBlank() {
+        assertThatThrownBy(() -> bindWith(Map.of(
+                        "HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY",
+                        "fedcba9876543210fedcba9876543210",
+                        "HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY_VERSION",
+                        "")))
+                .rootCause()
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("must be configured together");
+    }
+
+    @Test
+    void shouldRejectAPriorKeyVersionWhoseKeyIsBlank() {
+        assertThatThrownBy(() -> bindWith(Map.of(
+                        "HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY",
+                        "",
+                        "HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY_VERSION",
+                        "2")))
+                .rootCause()
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("must be configured together");
+    }
+
+    @Test
+    void shouldRejectRotationEnabledWhenTheKeysItRotatesAreBlank() {
+        assertThatThrownBy(() -> bindWith(Map.of(
+                        "HEPHAESTUS_SECURITY_CREDENTIAL_ENCRYPTION_KEY",
+                        "",
+                        "HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY",
+                        "",
+                        "HEPHAESTUS_SECURITY_CREDENTIAL_ROTATION_ENABLED",
+                        "true")))
+                .rootCause()
+                .isInstanceOf(IllegalArgumentException.class)
+                .hasMessageContaining("Credential rotation requires both active and prior encryption keys");
+    }
+
+    private static SecurityProperties bindWith(Map<String, Object> environmentVariables) {
+        StandardEnvironment environment = new StandardEnvironment();
+        environment
+                .getPropertySources()
+                .replace(
+                        StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME,
+                        new SystemEnvironmentPropertySource(
+                                StandardEnvironment.SYSTEM_ENVIRONMENT_PROPERTY_SOURCE_NAME, environmentVariables));
+
+        return Binder.get(environment).bindOrCreate("hephaestus.security", SecurityProperties.class);
+    }
+}