fix: give Doctor the host configuration the runtime receives

`pnpm doctor` and `startApi` each read their own subset of the same
environment variables, and the subsets had drifted. Doctor never read
`S3_*` or module secrets at all, so a correctly configured installation
was told its object storage was "not configured" and every module
requiring a bucket or a secret was reported blocked -- while the runtime,
from the identical environment, bound those buckets and ran the modules.

Both executables now map the environment through one
`loadHostConfiguration(env)` in Core, which takes the environment as an
argument and never reads `process.env` itself. Validation stays with the
existing per-domain validators, so each caller keeps its own failure
behaviour: startup refuses a rejected value, Doctor reports it as a
sanitized code.

Doctor's storage option becomes raw input like its mail option, so a
half-configured provider is reported as a blocking configuration failure
instead of throwing before a report exists. The outbound-email check --
computed, counted toward the result, but absent from every rendered
section -- is now printed, and the rendered set is asserted against a
real report so a future check cannot go missing the same way.

Co-Authored-By: Claude Opus 5 <[email protected]>

apps/api/src/config.ts

@@ -90,7 +90,7 @@ export interface ApiRuntimeConfig {
 export interface ApiRuntimeConfigInput {
   /** Optional. Defaults to direct mode (trusts only the actual immediate socket peer) — no proxy
    * trust unless explicitly configured. See `./client-address.js`. */
-  readonly clientAddress?: ClientAddressConfigInput;
+  readonly clientAddress?: ClientAddressConfigInput | undefined;
   readonly databaseUrl?: unknown;
   /** Optional. Defaults to certificate-verified TLS in production and plaintext in development;
    * production can never select plaintext. See `@ekklesia/core/database`'s transport policy. */

apps/api/src/server.ts

@@ -12,10 +12,10 @@ import {
 } from "@ekklesia/core/authorization";
 import { createDashboardStore } from "@ekklesia/core/dashboard";
 import { createDeviceStore } from "@ekklesia/core/devices";
+import { type HostEnvironment, loadHostConfiguration } from "@ekklesia/core/host";
 import { createIdentityRuntime, type IdentityRateLimitOverride } from "@ekklesia/core/identity";
 import { createSmtpMailProvider, type MailProvider } from "@ekklesia/core/mail";
 import {
-  createEnvironmentModuleSecretSource,
   createModuleConfigurationStore,
   createModuleLifecycleStore,
   createModuleUiPublicationRegistry,
@@ -35,7 +35,6 @@ import { type ServerType, serve } from "@hono/node-server";
 import type { Hono } from "hono";
 import { createApiApp } from "./app.js";
 import {
-  type ClientAddressConfigInput,
   type ClientAddressResolver,
   createClientAddressResolver,
   wrapFetchWithClientAddress,
@@ -719,98 +718,40 @@ export function installShutdownSignalHandlers(
   process.on("SIGTERM", handleSignal);
 }
 
-function readClientAddressInputFromEnvironment(): ClientAddressConfigInput | undefined {
-  const mode = process.env.EKKLESIA_CLIENT_ADDRESS_MODE;
-  if (mode === undefined) {
-    // Omitted entirely: `createClientAddressConfig` defaults to direct mode. Reading `header`/
-    // `trustedProxies` only when `mode` is actually set keeps an operator from accidentally
-    // half-configuring proxy mode by setting only one of the three variables.
-    return undefined;
-  }
-  const trustedProxiesValue = process.env.EKKLESIA_CLIENT_ADDRESS_TRUSTED_PROXIES;
-  return {
-    header: process.env.EKKLESIA_CLIENT_ADDRESS_HEADER,
-    mode,
-    trustedProxies: trustedProxiesValue
-      ?.split(",")
-      .map((entry) => entry.trim())
-      .filter((entry) => entry.length > 0),
-  };
-}
-
-function readConfigFromEnvironment(): {
+/**
+ * Turns one deployment environment into this process's startup inputs.
+ *
+ * Every host infrastructure value comes from `loadHostConfiguration` — the same function
+ * `pnpm doctor` calls with the same environment — so the runtime and the diagnostic that reports on
+ * it can never disagree about what this deployment is configured to use. Only the two values that
+ * describe *this listener* rather than the host's infrastructure are read here.
+ */
+export function readConfigFromEnvironment(processEnvironment: HostEnvironment): {
   readonly input: Parameters<typeof createApiRuntimeConfig>[0];
   readonly environment: "development" | "production";
+  readonly moduleSecrets: ModuleSecretSource;
 } {
-  const trustedOriginsValue = process.env.EKKLESIA_IDENTITY_TRUSTED_ORIGINS;
-  const trustedOrigins = trustedOriginsValue
-    ?.split(",")
-    .map((origin) => origin.trim())
-    .filter((origin) => origin.length > 0);
-  const clientAddress = readClientAddressInputFromEnvironment();
-
+  const host = loadHostConfiguration(processEnvironment);
   return {
-    environment: process.env.NODE_ENV === "development" ? "development" : "production",
+    environment: host.environment,
     input: {
-      ...(clientAddress === undefined ? {} : { clientAddress }),
-      databaseTransport: {
-        ...(process.env.EKKLESIA_DATABASE_CA === undefined
-          ? {}
-          : { certificateAuthority: process.env.EKKLESIA_DATABASE_CA }),
-        ...(process.env.EKKLESIA_DATABASE_TLS_MODE === undefined
-          ? {}
-          : { mode: process.env.EKKLESIA_DATABASE_TLS_MODE }),
-      },
-      databaseUrl: process.env.DATABASE_URL,
-      host: process.env.EKKLESIA_API_HOST,
-      identity: {
-        baseUrl: process.env.EKKLESIA_IDENTITY_BASE_URL,
-        publicSignupEnabled: process.env.EKKLESIA_PUBLIC_SIGNUP_ENABLED,
-        secret: process.env.EKKLESIA_IDENTITY_SECRET,
-        trustedOrigins,
-      },
-      port: process.env.EKKLESIA_API_PORT,
-      // The one place this process turns its environment into storage configuration. The names are
-      // the `S3_*` ones ADR 0004 already established for this repository's Compose stack, and Core's
-      // validator never reads `process.env` itself.
-      // The one place this process turns its environment into mail configuration. Names follow the
-      // platform's own `EKKLESIA_<DOMAIN>_<FIELD>` convention rather than a provider's, and Core's
-      // validator never reads `process.env` itself. Absent host means this installation sends no
-      // outbound email, which is a complete deployment (ADR 0037).
-      mail: {
-        fromAddress: process.env.EKKLESIA_SMTP_FROM_ADDRESS,
-        fromName: process.env.EKKLESIA_SMTP_FROM_NAME,
-        host: process.env.EKKLESIA_SMTP_HOST,
-        // Optional as a pair: a relay authorized by source IP has neither.
-        password: process.env.EKKLESIA_SMTP_PASSWORD,
-        port: process.env.EKKLESIA_SMTP_PORT,
-        security: process.env.EKKLESIA_SMTP_SECURITY,
-        username: process.env.EKKLESIA_SMTP_USERNAME,
-      },
-      storage: {
-        accessKey: process.env.S3_ACCESS_KEY,
-        bucketPrefix: process.env.S3_BUCKET_PREFIX,
-        // Optional, and unset is the ordinary case: it matters only where the name Core reaches
-        // storage by is not a name a browser could resolve.
-        deliveryEndpoint: process.env.S3_DELIVERY_ENDPOINT,
-        endpoint: process.env.S3_ENDPOINT,
-        forcePathStyle: process.env.S3_FORCE_PATH_STYLE,
-        region: process.env.S3_REGION,
-        secretKey: process.env.S3_SECRET_KEY,
-      },
+      clientAddress: host.clientAddress,
+      databaseTransport: host.databaseTransport,
+      databaseUrl: host.databaseUrl,
+      host: processEnvironment.EKKLESIA_API_HOST,
+      identity: host.identity,
+      mail: host.mail,
+      port: processEnvironment.EKKLESIA_API_PORT,
+      storage: host.storage,
     },
+    moduleSecrets: host.moduleSecrets,
   };
 }
 
 export async function main(): Promise<void> {
-  const { environment, input } = readConfigFromEnvironment();
+  const { environment, input, moduleSecrets } = readConfigFromEnvironment(process.env);
   const config = createApiRuntimeConfig(input, { environment });
-  // The one place this process turns its environment into module secrets. Core's factory takes the
-  // environment as an argument and never touches `process.env` itself, preserving the rule that
-  // only executables read the environment.
-  const running = await startApi(config, {
-    moduleSecrets: createEnvironmentModuleSecretSource(process.env),
-  });
+  const running = await startApi(config, { moduleSecrets });
 
   const address = running.server.address();
   const boundPort = address && typeof address === "object" ? address.port : config.port;

apps/api/tests/host-configuration-parity.test.ts

@@ -0,0 +1,169 @@
+import { loadHostConfiguration } from "@ekklesia/core/host";
+import { createMailProviderConfig } from "@ekklesia/core/mail";
+import { createStorageProviderConfig } from "@ekklesia/core/storage";
+import { describe, expect, it } from "vitest";
+import { createApiRuntimeConfig } from "../src/config.js";
+import { readConfigFromEnvironment } from "../src/server.js";
+
+/**
+ * `pnpm doctor` and `startApi` must reach the same conclusions from the same environment. They
+ * previously could not: each executable read its own subset of the variables, and Doctor's subset
+ * omitted `S3_*` and the module secrets entirely.
+ *
+ * These tests assert the property directly — the API's startup inputs and the inputs Doctor
+ * validates come from one `loadHostConfiguration` call and produce identical validated
+ * configuration, including every default.
+ */
+
+const secretKey = "sk-example-secret-material";
+const smtpPassword = "sup3r-secret-relay-password";
+
+function environment(
+  overrides: Readonly<Record<string, string | undefined>> = {},
+): Readonly<Record<string, string | undefined>> {
+  return {
+    DATABASE_URL: "postgres://[email protected]:5432/ekklesia",
+    EKKLESIA_IDENTITY_BASE_URL: "https://ekklesia.example.org",
+    EKKLESIA_IDENTITY_SECRET: "b7QwZ2rTn4Xs9LmVpKdF6yHc3JgEuNaW",
+    EKKLESIA_IDENTITY_TRUSTED_ORIGINS: "https://ekklesia.example.org",
+    NODE_ENV: "production",
+    ...overrides,
+  };
+}
+
+const configuredInfrastructure = Object.freeze({
+  EKKLESIA_SMTP_FROM_ADDRESS: "[email protected]",
+  EKKLESIA_SMTP_HOST: "smtp.example.org",
+  EKKLESIA_SMTP_PASSWORD: smtpPassword,
+  EKKLESIA_SMTP_USERNAME: "[email protected]",
+  S3_ACCESS_KEY: "AKIAEXAMPLEACCESSID",
+  S3_ENDPOINT: "https://storage.example.org",
+  S3_SECRET_KEY: secretKey,
+});
+
+/** Exactly what Doctor validates, from exactly the same load the API performs. */
+function doctorView(env: Readonly<Record<string, string | undefined>>) {
+  const host = loadHostConfiguration(env);
+  return {
+    mail: createMailProviderConfig(host.mail, { environment: host.environment }),
+    storage: createStorageProviderConfig(host.storage, { environment: host.environment }),
+  };
+}
+
+function apiView(env: Readonly<Record<string, string | undefined>>) {
+  const { environment: resolved, input } = readConfigFromEnvironment(env);
+  return createApiRuntimeConfig(input, { environment: resolved });
+}
+
+describe("host configuration parity between startApi and Doctor", () => {
+  it("derives identical object-storage configuration, defaults included", () => {
+    const env = environment(configuredInfrastructure);
+
+    expect(apiView(env).storage).toEqual(doctorView(env).storage);
+    // Named explicitly rather than only compared, so a change to either default fails here loudly.
+    expect(apiView(env).storage).toEqual({
+      accessKey: "AKIAEXAMPLEACCESSID",
+      bucketPrefix: "ekklesia",
+      deliveryEndpoint: "https://storage.example.org",
+      endpoint: "https://storage.example.org",
+      forcePathStyle: true,
+      region: "us-east-1",
+      secretKey,
+    });
+  });
+
+  it("derives identical outbound-email configuration, defaults included", () => {
+    const env = environment(configuredInfrastructure);
+
+    expect(apiView(env).mail).toEqual(doctorView(env).mail);
+    expect(apiView(env).mail).toMatchObject({
+      host: "smtp.example.org",
+      port: 587,
+      security: "starttls",
+    });
+  });
+
+  it("agrees that an installation with neither service is complete", () => {
+    const env = environment();
+
+    expect(apiView(env).storage).toBeUndefined();
+    expect(doctorView(env).storage).toBeUndefined();
+    expect(apiView(env).mail).toBeUndefined();
+    expect(doctorView(env).mail).toBeUndefined();
+  });
+
+  it("carries every storage field the direct-delivery pass established", () => {
+    const env = environment({
+      ...configuredInfrastructure,
+      S3_BUCKET_PREFIX: "rogc",
+      S3_DELIVERY_ENDPOINT: "https://files.example.org",
+      S3_FORCE_PATH_STYLE: "false",
+      S3_REGION: "eu-west-1",
+    });
+
+    expect(apiView(env).storage).toEqual(doctorView(env).storage);
+    expect(apiView(env).storage).toMatchObject({
+      bucketPrefix: "rogc",
+      deliveryEndpoint: "https://files.example.org",
+      forcePathStyle: false,
+      region: "eu-west-1",
+    });
+  });
+
+  it("rejects the same malformed environment with the same sanitized code", () => {
+    for (const [overrides, code] of [
+      [{ S3_ENDPOINT: "https://storage.example.org" }, "STORAGE_ACCESS_KEY_MISSING"],
+      [{ ...configuredInfrastructure, S3_ENDPOINT: "not-a-url" }, "STORAGE_ENDPOINT_INVALID"],
+      [
+        { ...configuredInfrastructure, S3_ENDPOINT: "http://storage.example.org" },
+        "STORAGE_ENDPOINT_INSECURE_IN_PRODUCTION",
+      ],
+      [
+        { ...configuredInfrastructure, EKKLESIA_SMTP_PASSWORD: undefined },
+        "MAIL_USERNAME_WITHOUT_PASSWORD",
+      ],
+      [{ ...configuredInfrastructure, EKKLESIA_SMTP_PORT: "70000" }, "MAIL_PORT_INVALID"],
+    ] as const) {
+      const env = environment(overrides);
+      expect(() => apiView(env)).toThrowError(expect.objectContaining({ code }));
+      expect(() => doctorView(env)).toThrowError(expect.objectContaining({ code }));
+    }
+  });
+
+  it("resolves module secrets from the same source the runtime is given", () => {
+    const env = environment({
+      EKKLESIA_MODULE_SECRET__ANNOUNCEMENTS__STORAGE_CREDENTIAL: "module-secret-material",
+    });
+
+    expect(
+      readConfigFromEnvironment(env).moduleSecrets.get("announcements", "storageCredential"),
+    ).toBe("module-secret-material");
+    expect(loadHostConfiguration(env).moduleSecrets.get("announcements", "storageCredential")).toBe(
+      "module-secret-material",
+    );
+  });
+
+  it("reads only this listener's own address and port outside the shared loader", () => {
+    const config = apiView(
+      environment({ EKKLESIA_API_HOST: "0.0.0.0", EKKLESIA_API_PORT: "8080" }),
+    );
+
+    expect(config.host).toBe("0.0.0.0");
+    expect(config.port).toBe(8080);
+    // Defaults, when unset, stay where they always were.
+    const defaults = apiView(environment());
+    expect(defaults.host).toBe("127.0.0.1");
+    expect(defaults.port).toBe(3000);
+  });
+
+  it("interprets a set-but-empty flag identically instead of one side ignoring it", () => {
+    // Doctor used to drop any falsy identity value before validating, so `startApi` refused to
+    // start on `EKKLESIA_PUBLIC_SIGNUP_ENABLED=` while Doctor reported the deployment ready.
+    const env = environment({ EKKLESIA_PUBLIC_SIGNUP_ENABLED: "" });
+
+    expect(loadHostConfiguration(env).identity.publicSignupEnabled).toBe("");
+    expect(() => apiView(env)).toThrowError(
+      expect.objectContaining({ code: "PUBLIC_SIGNUP_ENABLED_INVALID" }),
+    );
+  });
+});