feat: add the module configuration and secrets contract

Modules had no way to be told anything. Announcements — the first real
product Ekklesia will absorb — has zero environment variables and compiles
a LAN IP address into its source, so this is the contract standing between
it and the module system.

- A module declares what it needs in its manifest, using six bounded types
  (string, integer, boolean, enum, url, secret) with no nesting and no
  regular expressions. Static declaration is what lets the platform validate
  configuration *before* deciding whether a module may start: an enabled
  module missing a required value is reported `blocked ·
  configuration_missing · <key>` rather than taking startup down from inside
  its own `start` hook, and Doctor reports the same while still importing no
  module code. That forces `manifestVersion: 5`, a hard cutover.
- Ordinary values persist in one Core table (migration 0005), one row per
  (module_id, key), stored as text until validated against the declaring
  module's current manifest. Nothing is coerced; an invalid stored value
  blocks the module rather than falling back to the default. A key the
  manifest no longer declares is retained and ignored.
- Secrets are never persisted. There is no encryption at rest in this
  repository, so a `secret` key is deployment-supplied and mapped in by the
  host under a name the module never sees. A secret declaration has no
  `default` field, the write API refuses secret material, and the HTTP view
  has no `value` field for one — absent by construction, not filtered.
- Modules receive a frozen `context.config` on the registration, runtime,
  and HTTP handler contexts: the same object identity, per module, beside
  `services` rather than inside it (services is deliberately one shared
  instance). No environment access, no database reference, no way to reach
  another module's values.
- Configuration decides eligibility through ADR 0028's existing resolver:
  three new blocked reasons, each with a distinct operator fix, propagating
  to required dependents through the same mechanism as a disabled module.
- Changes take effect at the next restart; both resources report
  restartRequired. New restricted permission
  `core.modules.configuration.manage`, separate from lifecycle, at the
  sibling prefix `/api/v1/module-configuration`.
- Migration participation stays independent of configuration validity.
  Endpoints and credentials for shared infrastructure stay platform
  concerns; a module declares which bucket it needs, not an S3 endpoint.

See ADR 0029.

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

apps/api/src/server.ts

@@ -1,7 +1,11 @@
 import type { Socket } from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import type { ModuleRuntimeServices } from "@ekklesia/contracts";
+import {
+  EMPTY_MODULE_SECRET_SOURCE,
+  type ModuleRuntimeServices,
+  type ModuleSecretSource,
+} from "@ekklesia/contracts";
 import {
   createAuthorizationEvaluator,
   createAuthorizationStore,
@@ -9,9 +13,12 @@ import {
 import { createDashboardStore } from "@ekklesia/core/dashboard";
 import { createIdentityRuntime, type IdentityRateLimitOverride } from "@ekklesia/core/identity";
 import {
+  createEnvironmentModuleSecretSource,
+  createModuleConfigurationStore,
   createModuleLifecycleStore,
   createModuleUiPublicationRegistry,
   type DiscoveredModule,
+  type ModuleConfigurationSettings,
   type ModuleEligibilityResolution,
   resolveModuleEligibility,
   type StartedModuleRuntime,
@@ -142,6 +149,17 @@ export interface StartApiOptions {
   /** Test-only escape hatch: narrows the per-module stop/rollback hook deadline
    * (`MODULE_STOP_HOOK_TIMEOUT_MS`). Never set by the executable entry point. */
   readonly moduleHookTimeoutMsOverride?: number;
+  /**
+   * Where deployment-supplied module secrets come from (ADR 0029) — the one *production* dependency
+   * in this options object rather than a test-only escape hatch.
+   *
+   * It is a dependency rather than a field on `ApiRuntimeConfig` because it is a lookup, not a
+   * validated value, and because the set of secrets depends on which modules are discovered — which
+   * is not known when configuration is validated. The executable entry point supplies an
+   * environment-backed source; omitting it supplies nothing, so a module declaring a required secret
+   * is reported `secret_missing` rather than silently starting without it.
+   */
+  readonly moduleSecrets?: ModuleSecretSource;
 }
 
 async function safeCloseDatabase(handle: ApiDatabaseHandle): Promise<void> {
@@ -405,12 +423,28 @@ export async function startApi(
   // falling back to "start everything": the platform cannot know what it was told, and starting a
   // module an administrator disabled is worse than not starting at all.
   const moduleLifecycleStore = createModuleLifecycleStore(databaseHandle.moduleLifecycle);
+  const moduleConfigurationStore = createModuleConfigurationStore(
+    databaseHandle.moduleConfiguration,
+  );
+  const moduleSecrets = options.moduleSecrets ?? EMPTY_MODULE_SECRET_SOURCE;
   let eligibility: ModuleEligibilityResolution;
+  let moduleConfigurationSettings: ModuleConfigurationSettings;
   try {
-    eligibility = resolveModuleEligibility(
-      inventory.modules,
-      await moduleLifecycleStore.readConfiguration(),
-    );
+    // Both axes are read before a single module entrypoint is imported, and resolved together in
+    // one pass (ADR 0029): a module is eligible only if an administrator enabled it, its own
+    // required configuration is satisfiable, and every module it requires is eligible too. The pass
+    // also produces each eligible module's frozen configuration snapshot, so the configuration that
+    // made a module eligible is the identical object it later receives.
+    // Read sequentially rather than concurrently, deliberately: these are two tiny queries, and
+    // racing them would make the reported failure depend on which rejected first. An operator
+    // debugging a broken deployment must get the same error code every time.
+    const lifecycleConfiguration = await moduleLifecycleStore.readConfiguration();
+    const settings = await moduleConfigurationStore.readSettings();
+    moduleConfigurationSettings = settings;
+    eligibility = resolveModuleEligibility(inventory.modules, lifecycleConfiguration, {
+      secrets: moduleSecrets,
+      settings,
+    });
   } catch (error) {
     await safeCloseDatabase(databaseHandle);
     throw error;
@@ -427,6 +461,7 @@ export async function startApi(
   let moduleRuntime: StartedModuleRuntime;
   try {
     moduleRuntime = await startDiscoveredModuleRuntime(eligibility.eligibleModules, services, {
+      configurations: eligibility.configurations,
       ...(options.moduleHookTimeoutMsOverride === undefined
         ? {}
         : { hookTimeoutMs: options.moduleHookTimeoutMsOverride }),
@@ -463,6 +498,15 @@ export async function startApi(
         }),
         store: moduleLifecycleStore,
       },
+      moduleConfiguration: {
+        // The settings this process actually resolved from, so `restartRequired` is a comparison
+        // against what is running rather than a guess.
+        bootSettings: moduleConfigurationSettings,
+        discoveredModules: inventory.modules,
+        secrets: moduleSecrets,
+        snapshots: eligibility.configurations,
+        store: moduleConfigurationStore,
+      },
       // A typed view over the same single pool as identity, authorization, and the module facade.
       dashboard: createDashboardStore(databaseHandle.dashboard),
       runtime,
@@ -615,7 +659,12 @@ function readConfigFromEnvironment(): {
 export async function main(): Promise<void> {
   const { environment, input } = readConfigFromEnvironment();
   const config = createApiRuntimeConfig(input, { environment });
-  const running = await startApi(config);
+  // 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 address = running.server.address();
   const boundPort = address && typeof address === "object" ? address.port : config.port;