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]>

templates/module/ekklesia.module.json

@@ -1,5 +1,5 @@
 {
-  "manifestVersion": 4,
+  "manifestVersion": 5,
   "id": "example",
   "name": "Example Module",
   "description": "A minimal Ekklesia module template with backend behavior and optional UI.",
@@ -21,6 +21,15 @@
       "description": "Read example records."
     }
   ],
+  "configuration": [
+    {
+      "key": "greeting",
+      "type": "string",
+      "default": "Hello",
+      "maxLength": 120,
+      "description": "Prefix this module puts in front of a record value."
+    }
+  ],
   "storage": {
     "buckets": [
       {

templates/module/src/server/index.ts

@@ -31,7 +31,17 @@ export default defineModuleRuntime({
         const rows = await context.services.database
           .select({ id: records.id, value: records.value })
           .from(records);
-        return Response.json(rows);
+        // The accepted module configuration boundary: `context.config` is a frozen, already
+        // validated snapshot of exactly this module's own declared keys (ADR 0029). It reaches
+        // `register`, `start`, `stop`, and every handler as the same object. This module never
+        // reads `process.env`, never queries a platform table for a setting, and has no way to see
+        // another module's configuration — which is what keeps it runnable under a future
+        // standalone host that stores configuration somewhere else entirely.
+        //
+        // `greeting` is declared with a default in `ekklesia.module.json`, so it is always present;
+        // the `??` is only here because accessors are typed `T | undefined` for undeclared keys.
+        const greeting = context.config.getString("greeting") ?? "Hello";
+        return Response.json(rows.map((row) => ({ ...row, value: `${greeting}, ${row.value}` })));
       },
     });
   },

templates/module/tests/manifest.test.ts

@@ -3,6 +3,8 @@ import { readFile } from "node:fs/promises";
 import {
   ANONYMOUS_PRINCIPAL,
   type CapabilityId,
+  EMPTY_MODULE_CONFIGURATION,
+  type ModuleConfiguration,
   type ModuleDatabase,
   type ModuleRouteDefinitionInput,
   type ModuleRouteHandlerContext,
@@ -31,6 +33,9 @@ async function registerAndCaptureRoutes(): Promise<{
   const provided = new Map<CapabilityId, unknown>();
   const routes: ModuleRouteDefinitionInput[] = [];
   await moduleRuntime.register?.({
+    // The template declares no configuration, so it receives an empty snapshot — proof that a
+    // backend module needing no settings stays exactly as simple as it was (ADR 0029).
+    config: EMPTY_MODULE_CONFIGURATION,
     capabilities: {
       provide(capabilityId, implementation) {
         provided.set(capabilityId, implementation);
@@ -124,6 +129,7 @@ describe("module template", () => {
       database: fakeModuleDatabase(fakeRows),
     });
     const context: ModuleRouteHandlerContext = Object.freeze({
+      config: EMPTY_MODULE_CONFIGURATION,
       moduleId: "example",
       params: Object.freeze({}),
       principal: ANONYMOUS_PRINCIPAL,
@@ -133,7 +139,69 @@ describe("module template", () => {
     const response = await route.handler(new Request("http://localhost/records"), context);
 
     expect(response).toBeInstanceOf(Response);
-    expect(await response.json()).toEqual(fakeRows);
+    // With no configuration supplied, the handler falls back to the same default the manifest
+    // declares. In a real Ekklesia deployment that fallback is unreachable — the platform resolves
+    // the declared default before any module code runs — but the accessor is typed `T | undefined`
+    // for undeclared keys, so module code still writes it.
+    expect(await response.json()).toEqual([{ ...fakeRows[0], value: "Hello, hello" }]);
+  });
+
+  it("reads its own declared configuration through context.config, never the environment", async () => {
+    const { routes } = await registerAndCaptureRoutes();
+    const route = routes[0];
+    if (!route) {
+      throw new Error("Expected the example route to be registered.");
+    }
+
+    const fakeRows = [{ id: "9d3f9f7e-3b1a-4c9a-8b8e-2b6b1e6f9a11", value: "hello" }];
+    // A hand-rolled `ModuleConfiguration`: it is a `@ekklesia/contracts` interface, and a module may
+    // never import Core, so this is what a module-layer test can legitimately construct. It also
+    // demonstrates the portability claim directly — the host that produces this object could be
+    // Ekklesia, or a future standalone host reading YAML, and this module cannot tell.
+    const config: ModuleConfiguration = Object.freeze({
+      get: (key: string) => (key === "greeting" ? "Welcome" : undefined),
+      getBoolean: () => undefined,
+      getEnum: () => undefined,
+      getInteger: () => undefined,
+      getSecret: () => undefined,
+      getString: (key: string) => (key === "greeting" ? "Welcome" : undefined),
+      getUrl: () => undefined,
+      has: (key: string) => key === "greeting",
+      keys: () => Object.freeze(["greeting"]),
+    });
+    const context: ModuleRouteHandlerContext = Object.freeze({
+      config,
+      moduleId: "example",
+      params: Object.freeze({}),
+      principal: ANONYMOUS_PRINCIPAL,
+      services: Object.freeze({ database: fakeModuleDatabase(fakeRows) }),
+    });
+
+    const response = await route.handler(new Request("http://localhost/records"), context);
+
+    expect(await response.json()).toEqual([{ ...fakeRows[0], value: "Welcome, hello" }]);
+  });
+
+  it("declares exactly one configuration key, with a default, and no secret", async () => {
+    const manifestUrl = new URL("../ekklesia.module.json", import.meta.url);
+    const manifest = parseModuleManifest(
+      JSON.parse(await readFile(manifestUrl, "utf8")) as unknown,
+    );
+
+    // The template stays the smallest thing that demonstrates the contract: one ordinary key with a
+    // safe default. A backend module needing no settings omits `configuration` entirely and remains
+    // valid, which the manifest schema's own default proves.
+    expect(manifest.configuration).toEqual([
+      {
+        default: "Hello",
+        description: "Prefix this module puts in front of a record value.",
+        key: "greeting",
+        maxLength: 120,
+        required: false,
+        type: "string",
+      },
+    ]);
+    expect(manifest.configuration.some((entry) => entry.type === "secret")).toBe(false);
   });
 
   it("exports a namespaced module-owned Drizzle schema", () => {