feat(server): validate production configuration on startup

Author: FelixTJDietrich

.changeset/redacted-configuration-readiness.md

@@ -0,0 +1,5 @@
+---
+"hephaestus": minor
+---
+
+Production startup now reports all boot-critical configuration problems together without exposing configured values, and instance administrators can inspect redacted deployment and runtime readiness facts through the API. **Operators:** validate production settings against the configuration readiness guide before upgrading; the process now refuses to start when a required setting is missing or invalid.

MIGRATION.md

@@ -82,6 +82,22 @@ review runs and no feedback is prepared about them.
 **Operator action after upgrading**: open **Practices → Review → When and where** and confirm the
 **People** and **Repositories** counts. Existing members need no action. If expected contributors are
 missing, follow [Who counts as a person](https://ls1intum.github.io/Hephaestus/admin/practice-review#who-counts-as-a-person).
+#### 🔴 Production configuration is validated before startup
+
+**Affected**: deployments that activate the `prod` Spring profile and have a missing, malformed, or
+role-inconsistent required setting.
+
+Production processes now validate all applicable boot-critical settings together and refuse to
+start until every reported error is resolved. The failure report identifies properties and
+documentation but never includes configured values. Development and test-only profiles retain their
+existing defaults.
+
+**Action**: before upgrading, compare every production role's settings with the
+[configuration readiness guide](https://ls1intum.github.io/Hephaestus/admin/configuration-readiness).
+Correct every required setting reported during a staging startup, then deploy the same configuration
+to production. After the server role starts, an instance administrator can inspect the redacted
+facts through `GET /admin/configuration-readiness`.
+
 #### 🔴 Practice area API names are replaced by practice group names
 
 **Affected**: anything calling the application API directly. The generated Hephaestus web client is

docs/admin/configuration-readiness.mdx

@@ -0,0 +1,83 @@
+---
+title: Configuration readiness
+---
+
+# Configuration readiness
+
+The production profile validates deployment settings before application beans are created. The
+server-role endpoint `GET /api/admin/configuration-readiness` returns those facts plus checks that need
+runtime state. It requires the `app_admin` authority and is available only when boot-fatal checks pass.
+Diagnostics never contain configured values.
+
+| Setting | Deployment environment variable | Accepted value |
+| --- | --- | --- |
+| `hephaestus.host-url` | `APPLICATION_HOST_URL` | Root HTTPS origin |
+| `hephaestus.security.encryption-key` | `HEPHAESTUS_SECURITY_ENCRYPTION_KEY` | Exactly 32 ASCII bytes |
+| `hephaestus.webhook.secret` | `WEBHOOK_SECRET` | At least 32 ASCII characters |
+| `hephaestus.sync.nats.enabled` | `NATS_ENABLED` | `true` on server/webhook; `false` on worker-only |
+| `hephaestus.sync.nats.server` | `NATS_SERVER` | `nats://` or `tls://` URI |
+| `hephaestus.auth.state-cookie-key` | `HEPHAESTUS_AUTH_STATE_COOKIE_KEY` | Base64-encoded 32-byte key |
+| `hephaestus.agent.image.require-digest` | `HEPHAESTUS_AGENT_IMAGE_REQUIRE_DIGEST` | `true` on workers |
+| `hephaestus.agent.image.reference` | `HEPHAESTUS_AGENT_IMAGE_REFERENCE` | SHA-256 digest reference |
+| `hephaestus.sandbox.container-runtime` | `SANDBOX_CONTAINER_RUNTIME` | `runsc` recommended |
+
+## Runtime roles {#runtime-roles}
+
+Enable at least one of `hephaestus.runtime.server.enabled`, `worker.enabled`, or `webhook.enabled`.
+The supported split topology enables only webhook on the webhook process, only worker on a remote
+worker, and server (optionally with a colocated worker) on the application process.
+
+## Database {#database}
+
+Every role uses PostgreSQL. Set `spring.datasource.url` to a PostgreSQL JDBC URL and supply a non-empty
+username and password. A successful static check does not replace the connection and migration health
+checks performed by Spring Boot and Liquibase.
+
+## Credential encryption {#credential-encryption}
+
+Set `hephaestus.security.encryption-key` to exactly 32 ASCII bytes and keep it with the database backup.
+Generate it with `openssl rand -base64 24 | cut -c1-32`. Do not change it on an existing installation.
+
+## External URL {#external-url}
+
+Set `hephaestus.host-url` to the public HTTPS origin, without credentials, a path other than `/`, a
+query, or a fragment.
+
+## Webhooks {#webhooks}
+
+Server and webhook roles require `hephaestus.webhook.secret` with at least 32 ASCII characters. Generate
+an independent value with `openssl rand -hex 32`; never reuse another application key.
+
+## NATS {#nats}
+
+Server and webhook roles require NATS and an explicit `nats://` or `tls://` server URI. A worker-only
+process must disable NATS because its job queue is PostgreSQL-backed.
+This check validates syntax and role consistency, not authentication, connectivity, or JetStream health.
+
+## Login {#login}
+
+The server role requires a Base64-encoded 32-byte `hephaestus.auth.state-cookie-key` and an enabled
+GitHub or GitLab sign-in provider in the database-backed provider catalogue. Environment provider
+entries are seeds, not the readiness authority. Slack and Outline are link-only providers and do not
+satisfy sign-in readiness. Worker and webhook roles do not load login providers.
+
+## LLM proxy {#llm-proxy}
+
+Worker roles must leave `hephaestus.llm.egress.allow-loopback=false`. Provider credentials and model
+configuration are database-backed runtime configuration and are not deployment settings.
+
+## Agent image {#agent-image}
+
+Worker roles require digest enforcement and a SHA-256-pinned `hephaestus.agent.image.reference`. See
+[Agent image digests](./agent-image-digests.md).
+
+## Sandbox isolation {#sandbox-isolation}
+
+Set `SANDBOX_CONTAINER_RUNTIME=runsc` on workers after
+[installing and configuring gVisor](https://gvisor.dev/docs/user_guide/install/) on the host. This
+recommendation is non-fatal.
+
+## Optional observability {#optional-observability}
+
+Sentry is optional. When configured, `hephaestus.sentry.dsn` must use HTTPS. The fact is classified
+`OPTIONAL` and never prevents startup.

docs/sidebars.admin.ts

@@ -20,6 +20,7 @@ const sidebars: SidebarsConfig = {
 		{ type: "doc", id: "production-setup", label: "Integrations & Reference Deployment" },
 		{ type: "doc", id: "compatibility-policy", label: "Compatibility Policy" },
 		{ type: "doc", id: "runtime-roles", label: "Runtime Roles" },
+		{ type: "doc", id: "configuration-readiness", label: "Configuration Readiness" },
 		{ type: "doc", id: "agent-image-digests", label: "Agent image digests" },
 		{ type: "doc", id: "buildpacks-cds-decision", label: "Server image build (Buildpacks + CDS)" },
 		{ type: "doc", id: "legal-pages", label: "Legal Pages" },

server/application/src/main/java/de/tum/cit/aet/hephaestus/core/auth/provider/LoginProviderClientRegistrationRepository.java

@@ -7,6 +7,7 @@
 import java.time.Duration;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Set;
 import org.jspecify.annotations.Nullable;
 import org.springframework.security.oauth2.client.registration.ClientRegistration;
 import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
@@ -86,6 +87,12 @@ public List<ClientRegistration> listRegistrations() {
                 .toList();
     }
 
+    @Override
+    public boolean hasEnabledPrimarySignInProvider() {
+        return loginProviderRepository.existsByEnabledTrueAndTypeIn(
+                Set.of(LoginProvider.ProviderType.GITHUB, LoginProvider.ProviderType.GITLAB));
+    }
+
     private boolean isApproved(LoginProvider provider) {
         return (provider.getType() != LoginProvider.ProviderType.OUTLINE
                 || outlineOriginPolicy.allows(provider.getBaseUrl()));

server/application/src/main/java/de/tum/cit/aet/hephaestus/core/auth/provider/LoginProviderRepository.java

@@ -1,6 +1,7 @@
 package de.tum.cit.aet.hephaestus.core.auth.provider;
 
 import de.tum.cit.aet.hephaestus.core.WorkspaceAgnostic;
+import java.util.Collection;
 import java.util.List;
 import java.util.Optional;
 import org.springframework.data.jpa.repository.JpaRepository;
@@ -22,4 +23,6 @@ public interface LoginProviderRepository extends JpaRepository<LoginProvider, Lo
 
     /** Enabled providers, ordered for a stable login-page display. */
     List<LoginProvider> findByEnabledTrueOrderByDisplayNameAsc();
+
+    boolean existsByEnabledTrueAndTypeIn(Collection<LoginProvider.ProviderType> types);
 }

server/application/src/main/java/de/tum/cit/aet/hephaestus/core/auth/spi/IdentityProviderCatalog.java

@@ -3,18 +3,12 @@
 import java.util.List;
 import org.springframework.security.oauth2.client.registration.ClientRegistration;
 
-/**
- * Enumerates every enabled sign-in option a user may pick, drawn from the instance-scoped
- * {@code login_provider} store. Backs the public identity-provider discovery endpoint.
- *
- * <p>Implemented by {@code core.auth.provider.LoginProviderClientRegistrationRepository} (the
- * DB-backed {@code ClientRegistrationRepository} that displaces Boot's in-memory bean); consumed by
- * {@code core.auth}'s discovery controller through this port. Returns Spring Security
- * {@link ClientRegistration}s — a framework-neutral type both sides already speak.
- */
+/** Provides enabled OAuth registrations and primary sign-in capability. */
 public interface IdentityProviderCatalog {
     /**
      * @return the client registrations for all enabled login providers. Never {@code null}.
      */
     List<ClientRegistration> listRegistrations();
+
+    boolean hasEnabledPrimarySignInProvider();
 }

server/application/src/main/java/de/tum/cit/aet/hephaestus/core/configuration/ConfigurationFactDTO.java

@@ -0,0 +1,13 @@
+package de.tum.cit.aet.hephaestus.core.configuration;
+
+import java.util.Set;
+import org.jspecify.annotations.NonNull;
+
+public record ConfigurationFactDTO(
+        @NonNull String id,
+        @NonNull String subject,
+        @NonNull Set<ConfigurationRole> roles,
+        @NonNull ConfigurationRequirement requirement,
+        @NonNull ConfigurationStatus status,
+        @NonNull String explanation,
+        @NonNull String documentationUrl) {}

server/application/src/main/java/de/tum/cit/aet/hephaestus/core/configuration/ConfigurationReadinessController.java

@@ -0,0 +1,36 @@
+package de.tum.cit.aet.hephaestus.core.configuration;
+
+import de.tum.cit.aet.hephaestus.core.WorkspaceAgnostic;
+import de.tum.cit.aet.hephaestus.core.auth.spi.IdentityProviderCatalog;
+import de.tum.cit.aet.hephaestus.core.runtime.ConditionalOnServerRole;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import java.util.List;
+import org.springframework.core.env.Environment;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@ConditionalOnServerRole
+@RestController
+@WorkspaceAgnostic("Redacted instance configuration facts, app_admin only")
+@RequestMapping("/admin/configuration-readiness")
+@Tag(name = "Configuration Readiness", description = "Redacted production configuration facts")
+@PreAuthorize("hasAuthority('app_admin')")
+public class ConfigurationReadinessController {
+
+    private final ConfigurationReadinessEvaluator evaluator;
+    private final IdentityProviderCatalog identityProviderCatalog;
+
+    ConfigurationReadinessController(Environment environment, IdentityProviderCatalog identityProviderCatalog) {
+        this.evaluator = new ConfigurationReadinessEvaluator(environment);
+        this.identityProviderCatalog = identityProviderCatalog;
+    }
+
+    @GetMapping
+    @Operation(summary = "Get redacted configuration readiness", operationId = "adminGetConfigurationReadiness")
+    public List<ConfigurationFactDTO> get() {
+        return evaluator.evaluateReadiness(identityProviderCatalog.hasEnabledPrimarySignInProvider());
+    }
+}