feat: add host-provided module object storage

`manifest.storage.buckets` has existed since manifest version 1 and meant
nothing — discovery validated it and no code read it. This turns it into a
real capability, which is what stands between Announcements and the module
system: that product currently fetches a hardcoded LAN S3 endpoint, parses
ListObjectsV2 XML by hand, and hands the browser direct object URLs.

- A module declares a logical bucket and receives a scoped facade at
  `context.storage` — list, head, get, put, delete. The contract names no
  provider: no endpoint, region, credential, or physical bucket is reachable
  from it, which is what lets the same module run under a future standalone
  host over its own or a shared S3-compatible service.
- Core's first provider speaks S3 through the AWS SDK. SeaweedFS is the
  deployment target (ADR 0004), never an API name. Probing the pinned image
  found `CreateBucket` reporting `BucketAlreadyExists` rather than AWS's
  `BucketAlreadyOwnedByYou`; treating only the AWS spelling as success would
  have failed every second boot. A live test pins it.
- Logical → physical mapping is deterministic and collision-safe: an
  installation prefix, the module and bucket ids joined by `--` (which cannot
  occur inside either identifier, so `a-b`+`c` and `a`+`b-c` cannot collide),
  and a digest over the full untruncated identity. Two modules declaring
  `assets` always get separate namespaces; neither can see the physical name.
- Declaring a bucket is now a requirement: with no provider configured the
  module is `blocked · storage_unavailable` through ADR 0028's existing
  resolver, propagating to required dependents. An installation with no object
  storage stays a complete deployment.
- Binding availability is not provider health. Eligibility asks whether
  storage is configured, never whether it answered; bucket creation is lazy on
  first use so a storage outage cannot stop the platform booting; a running
  module whose store blinks stays running and retries. Nothing deletes a
  bucket.
- Credentials are deployment-supplied, never persisted, never routed through
  module configuration, and never visible to modules, module UI, diagnostics,
  or API responses. Provider errors translate to a closed code set carrying no
  endpoint, bucket, request id, or XML.
- Retires ADR 0029's transitional `bucket` configuration key. No manifest
  version change. The template declares no bucket, so it still runs without S3.

See ADR 0030.

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

apps/api/src/app.ts

@@ -18,6 +18,7 @@ import type {
   ModuleLifecycleSnapshot,
   ModuleConfigurationLookup,
   ModuleLifecycleStore,
+  ModuleStorageLookup,
   ModuleUiPublicationRegistry,
 } from "@ekklesia/core/modules";
 import { Hono } from "hono";
@@ -93,6 +94,19 @@ export interface CreateApiAppOptions {
      * read the same object rather than two independently resolved values. */
     readonly snapshots: ModuleConfigurationLookup;
   };
+  /**
+   * The platform's module object storage (ADR 0030): the per-module scoped facades the runtime
+   * started with, and whether a host provider is configured at all.
+   *
+   * Required rather than defaulted, like every other module option here — a caller exercising no
+   * storage says so with an empty map and `providerConfigured: false`, never falls through to an
+   * implicit one. Nothing here carries an endpoint, a region, or a credential: those never leave
+   * Core's provider.
+   */
+  readonly moduleStorage: {
+    readonly snapshots: ModuleStorageLookup;
+    readonly providerConfigured: boolean;
+  };
   /** Core's persistence for how this Dashboard presents installed modules (ADR 0027). Required
    * rather than defaulted, like every other module option here: a caller that exercises no
    * Dashboard says so with an explicit store, never falls through to an implicit one. Grouping is
@@ -273,6 +287,7 @@ export function createApiApp(options: CreateApiAppOptions): Hono {
         secrets: options.moduleConfiguration.secrets,
         store: options.moduleConfiguration.store,
       },
+      storage: { providerConfigured: options.moduleStorage.providerConfigured },
       snapshot: options.moduleLifecycle.snapshot,
       store: options.moduleLifecycle.store,
       trustedOrigins: allowedOrigins,
@@ -297,6 +312,7 @@ export function createApiApp(options: CreateApiAppOptions): Hono {
 
   mountModuleHttpRoutes(app, options.moduleRoutes, {
     configurations: options.moduleConfiguration.snapshots,
+    storages: options.moduleStorage.snapshots,
     evaluator: options.authorization.evaluator,
     registry: options.authorization.registry,
     runtime,

apps/api/src/config.ts

@@ -10,6 +10,11 @@ import {
   type IdentityConfig,
   type IdentityConfigInput,
 } from "@ekklesia/core/identity";
+import {
+  createStorageProviderConfig,
+  type StorageProviderConfig,
+  type StorageProviderConfigInput,
+} from "@ekklesia/core/storage";
 import {
   type ClientAddressConfig,
   type ClientAddressConfigInput,
@@ -55,6 +60,16 @@ export interface ApiRuntimeConfig {
   readonly host: string;
   readonly identity: IdentityConfig;
   readonly port: number;
+  /**
+   * The validated host object-storage provider, or `undefined` when this installation has none
+   * (ADR 0030).
+   *
+   * `undefined` is a complete, valid deployment: modules that declare no logical buckets are
+   * unaffected, and a module that does declare one is reported blocked rather than crashing
+   * anything. These values reach Core's provider and nowhere else — no module, module UI, browser
+   * bundle, diagnostic, or API response ever sees the endpoint or the credentials.
+   */
+  readonly storage: StorageProviderConfig | undefined;
 }
 
 export interface ApiRuntimeConfigInput {
@@ -68,6 +83,8 @@ export interface ApiRuntimeConfigInput {
   readonly host?: unknown;
   readonly identity: IdentityConfigInput;
   readonly port?: unknown;
+  /** Optional. Omitted, or with no endpoint, means this installation has no object storage. */
+  readonly storage?: StorageProviderConfigInput;
 }
 
 export interface CreateApiRuntimeConfigOptions {
@@ -142,6 +159,11 @@ export function createApiRuntimeConfig(
   // the URL carries TLS parameters that could override the policy.
   assertProductionDatabaseTransport(databaseUrl, databaseTransport, environment);
 
+  // Validated in the same pass as every other runtime value, before `startApi` constructs a pool,
+  // a provider client, or a listener — so a malformed endpoint or a half-supplied credential pair
+  // fails startup with a sanitized code rather than surfacing later as a confusing storage error.
+  const storage = createStorageProviderConfig(input.storage, { environment });
+
   return Object.freeze({
     clientAddress,
     databaseTransport,
@@ -149,5 +171,6 @@ export function createApiRuntimeConfig(
     host,
     identity,
     port,
+    storage,
   });
 }

apps/api/src/module-http-routes.ts

@@ -1,11 +1,12 @@
 import {
   EMPTY_MODULE_CONFIGURATION,
+  EMPTY_MODULE_STORAGE,
   type ModuleId,
   type ModuleRouteHandlerContext,
   type ModuleRuntimeServices,
   type RegisteredModuleHttpRoute,
 } from "@ekklesia/contracts";
-import type { ModuleConfigurationLookup } from "@ekklesia/core/modules";
+import type { ModuleConfigurationLookup, ModuleStorageLookup } from "@ekklesia/core/modules";
 import type { Context, Hono } from "hono";
 import {
   type AuthorizationMiddlewareOptions,
@@ -43,6 +44,15 @@ export interface ModuleHttpRoutesOptions extends AuthorizationMiddlewareOptions
    * ever reach its own module's configuration, because that is the only entry looked up for it.
    */
   readonly configurations: ModuleConfigurationLookup;
+  /**
+   * Per-module scoped object storage — the exact map the module runtime started from (ADR 0030), so
+   * a handler and that module's lifecycle hooks share one facade rather than two independently
+   * resolved ones.
+   *
+   * Keyed by module id, like `configurations` and unlike `services`: a handler can only ever reach
+   * its own module's storage, because that is the only entry looked up for it.
+   */
+  readonly storages: ModuleStorageLookup;
 }
 
 /** Never carries the offending permission id, route path, module id, or any other configuration
@@ -226,6 +236,7 @@ export function mountModuleHttpRoutes(
       const context: ModuleRouteHandlerContext = Object.freeze({
         config: options.configurations.get(route.moduleId) ?? EMPTY_MODULE_CONFIGURATION,
         moduleId: route.moduleId,
+        storage: options.storages.get(route.moduleId) ?? EMPTY_MODULE_STORAGE,
         params: Object.freeze({ ...c.req.param() }),
         principal: getAuthorizedPrincipal(c),
         services: options.services,

apps/api/src/module-lifecycle-routes.ts

@@ -8,6 +8,7 @@ import { CORE_MODULES_LIFECYCLE_MANAGE } from "@ekklesia/core/authorization";
 import {
   type ModuleConfigurationStore,
   type ModuleLifecycleSnapshot,
+  type ModuleStorageAvailability,
   type ModuleLifecycleStore,
   ModuleLifecycleStoreError,
   type ModuleLifecycleView,
@@ -65,6 +66,9 @@ export interface ModuleLifecycleModuleView {
     /** Present for a configuration reason (ADR 0029): the offending key, never its value. A key is
      * declared in a public manifest; a value may be a credential or arbitrary operator text. */
     readonly configurationKey?: string;
+    /** Present for a storage reason (ADR 0030): the logical bucket the module declared, never an
+     * endpoint, a credential, or the physical bucket the host maps it to. */
+    readonly storageBucketId?: string;
   };
   readonly restartRequired: boolean;
 }
@@ -90,6 +94,9 @@ export interface CreateModuleLifecycleRoutesOptions extends AuthorizationMiddlew
     readonly store: ModuleConfigurationStore;
     readonly secrets: ModuleSecretSource;
   };
+  /** The other axis that decides eligibility (ADR 0030). A boolean, never a probe: whether storage
+   * is *configured* decides eligibility, while whether it is *reachable right now* never does. */
+  readonly storage: ModuleStorageAvailability;
   readonly trustedOrigins: ReadonlySet<string>;
 }
 
@@ -156,6 +163,9 @@ function present(view: ModuleLifecycleView): ModuleLifecycleModuleView {
       ...(view.runtime.configurationKey === undefined
         ? {}
         : { configurationKey: view.runtime.configurationKey }),
+      ...(view.runtime.storageBucketId === undefined
+        ? {}
+        : { storageBucketId: view.runtime.storageBucketId }),
     },
     version: view.version,
   };
@@ -220,10 +230,12 @@ export function createModuleLifecycleRoutes(options: CreateModuleLifecycleRoutes
         options.store.readConfiguration(),
         options.configuration.store.readSettings(),
       ]);
-      const modules = resolveModuleLifecycleView(options.snapshot, configuration, {
-        secrets: options.configuration.secrets,
-        settings,
-      }).map(present);
+      const modules = resolveModuleLifecycleView(
+        options.snapshot,
+        configuration,
+        { secrets: options.configuration.secrets, settings },
+        options.storage,
+      ).map(present);
       return c.json({ modules } satisfies ModuleLifecycleResponse, 200);
     } catch (error) {
       return storeFailure(c, error, "read");
@@ -254,10 +266,12 @@ export function createModuleLifecycleRoutes(options: CreateModuleLifecycleRoutes
           options.store.readConfiguration(),
           options.configuration.store.readSettings(),
         ]);
-        const view = resolveModuleLifecycleView(options.snapshot, configuration, {
-          secrets: options.configuration.secrets,
-          settings,
-        }).find((entry) => entry.moduleId === moduleId);
+        const view = resolveModuleLifecycleView(
+          options.snapshot,
+          configuration,
+          { secrets: options.configuration.secrets, settings },
+          options.storage,
+        ).find((entry) => entry.moduleId === moduleId);
         if (!view) {
           return sanitizedFailure(c, 503, "MODULE_LIFECYCLE_READ_FAILED");
         }

apps/api/src/server.ts

@@ -12,6 +12,11 @@ import {
 } from "@ekklesia/core/authorization";
 import { createDashboardStore } from "@ekklesia/core/dashboard";
 import { createIdentityRuntime, type IdentityRateLimitOverride } from "@ekklesia/core/identity";
+import {
+  createModuleStorageLookup,
+  createS3StorageProvider,
+  type StorageProvider,
+} from "@ekklesia/core/storage";
 import {
   createEnvironmentModuleSecretSource,
   createModuleConfigurationStore,
@@ -171,6 +176,19 @@ async function safeCloseDatabase(handle: ApiDatabaseHandle): Promise<void> {
   }
 }
 
+/** Same swallow-on-cleanup-path rule as `safeCloseDatabase`, for the storage provider's own
+ * connection pool. */
+async function safeCloseStorage(provider: StorageProvider | undefined): Promise<void> {
+  if (!provider) {
+    return;
+  }
+  try {
+    await provider.close();
+  } catch {
+    // See safeCloseDatabase: never mask a failure that is already propagating.
+  }
+}
+
 /** Same swallow-on-cleanup-path rule as `safeCloseDatabase`, used only while unwinding a startup
  * failure that already occurred after the module runtime started — never during normal shutdown,
  * where a module stop failure remains an observable result instead (see `startApi`'s `shutdown`). */
@@ -422,6 +440,13 @@ export async function startApi(
   // start, before a single module entrypoint is imported. A failure here fails startup rather than
   // 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.
+  // The host's object-storage provider, constructed from validated configuration before any module
+  // runs — and **without touching the network**. Building the client opens no connection, so a
+  // storage outage can never stop the platform from booting; a bucket is ensured lazily on first
+  // use instead (ADR 0030). An installation with no storage configured gets `undefined` here, which
+  // is a complete, valid deployment.
+  const storageProvider = config.storage ? createS3StorageProvider(config.storage) : undefined;
+
   const moduleLifecycleStore = createModuleLifecycleStore(databaseHandle.moduleLifecycle);
   const moduleConfigurationStore = createModuleConfigurationStore(
     databaseHandle.moduleConfiguration,
@@ -441,15 +466,29 @@ export async function startApi(
     const lifecycleConfiguration = await moduleLifecycleStore.readConfiguration();
     const settings = await moduleConfigurationStore.readSettings();
     moduleConfigurationSettings = settings;
-    eligibility = resolveModuleEligibility(inventory.modules, lifecycleConfiguration, {
-      secrets: moduleSecrets,
-      settings,
-    });
+    eligibility = resolveModuleEligibility(
+      inventory.modules,
+      lifecycleConfiguration,
+      { secrets: moduleSecrets, settings },
+      { providerConfigured: storageProvider !== undefined },
+    );
   } catch (error) {
+    await safeCloseStorage(storageProvider);
     await safeCloseDatabase(databaseHandle);
     throw error;
   }
 
+  // One scoped facade per eligible module, over the exact buckets that module's own manifest
+  // declares. Built from the eligible set so a blocked module never receives storage at all.
+  const moduleStorages = createModuleStorageLookup(
+    storageProvider,
+    config.storage?.bucketPrefix ?? "",
+    eligibility.eligibleModules.map((module) => ({
+      logicalBucketIds: module.manifest.storage.buckets.map((bucket) => bucket.id),
+      moduleId: module.manifest.id,
+    })),
+  );
+
   // Module load/register/start failures use Core's own existing rollback (already-started
   // modules are stopped, in reverse order, before this rejects) — there is no separate runtime
   // handle to stop here, only the pool this failure leaves open.
@@ -462,11 +501,13 @@ export async function startApi(
   try {
     moduleRuntime = await startDiscoveredModuleRuntime(eligibility.eligibleModules, services, {
       configurations: eligibility.configurations,
+      storages: moduleStorages,
       ...(options.moduleHookTimeoutMsOverride === undefined
         ? {}
         : { hookTimeoutMs: options.moduleHookTimeoutMsOverride }),
     });
   } catch (error) {
+    await safeCloseStorage(storageProvider);
     await safeCloseDatabase(databaseHandle);
     throw error;
   }
@@ -507,6 +548,10 @@ export async function startApi(
         snapshots: eligibility.configurations,
         store: moduleConfigurationStore,
       },
+      moduleStorage: {
+        providerConfigured: storageProvider !== undefined,
+        snapshots: moduleStorages,
+      },
       // A typed view over the same single pool as identity, authorization, and the module facade.
       dashboard: createDashboardStore(databaseHandle.dashboard),
       runtime,
@@ -514,6 +559,7 @@ export async function startApi(
     });
   } catch (error) {
     await safeStopModuleRuntime(moduleRuntime);
+    await safeCloseStorage(storageProvider);
     await safeCloseDatabase(databaseHandle);
     throw error;
   }
@@ -529,6 +575,7 @@ export async function startApi(
     server = await bindServer(app, config.host, config.port, clientAddressResolver, timeouts);
   } catch (error) {
     await safeStopModuleRuntime(moduleRuntime);
+    await safeCloseStorage(storageProvider);
     await safeCloseDatabase(databaseHandle);
     throw error;
   }
@@ -558,6 +605,9 @@ export async function startApi(
         } catch (error) {
           moduleStopError = error;
         }
+        // After the module runtime has stopped, so a `stop` hook may still use its storage
+        // facade, and before the pool closes, matching the existing ordering discipline exactly.
+        await safeCloseStorage(storageProvider);
         await safeCloseDatabase(databaseHandle);
         // Every stage above ran regardless of what the earlier ones did, so a drain timeout or a
         // module-stop failure can never leave the pool open. Both failures are reported together,
@@ -652,6 +702,17 @@ function readConfigFromEnvironment(): {
         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.
+      storage: {
+        accessKey: process.env.S3_ACCESS_KEY,
+        bucketPrefix: process.env.S3_BUCKET_PREFIX,
+        endpoint: process.env.S3_ENDPOINT,
+        forcePathStyle: process.env.S3_FORCE_PATH_STYLE,
+        region: process.env.S3_REGION,
+        secretKey: process.env.S3_SECRET_KEY,
+      },
     },
   };
 }