feat: deliver module objects directly to browsers through opaque read URLs

ADR 0030 left exactly one way to get an image to a browser: read the
object into the module's process and write it back out of a module HTTP
route. Every byte of every asset travelled storage -> Ekklesia -> browser.
For the slideshow this platform exists to replace that means Ekklesia in
the path of every image on every display, permanently, for bytes that
never change — and it would make Ekklesia responsible for re-implementing
byte ranges, without which video seeking cannot work at all.

A module can now ask a logical bucket for a temporary browser URL:

    const { url, expiresAt } = await assets.createReadUrl("slides/welcome.png");

The contract names intent, not mechanism. There is no signing, expiry
format, endpoint, or bucket in it — a host with no S3 anywhere could
satisfy the same method, which is what keeps a future single-module
standalone host able to implement it. The URL is opaque to module code and
a bearer capability to whoever holds it, so a module authorizes the
request in its own route before asking: storage bounds reach, never
identity. Lifetimes run one minute to six hours, fifteen by default, and
out-of-range values are refused rather than clamped, so "expires forever"
is unreachable. Logical keys stay canonical state; URLs are generated on
demand and never persisted or logged.

The provider endpoint and the browser delivery origin are separated
because measurement showed they cannot be collapsed: an S3-compatible
signature covers the request Host, so a URL signed for one origin and
rewritten to another is rejected. The browser-facing origin is therefore a
signing input (S3_DELIVERY_ENDPOINT), defaulting to S3_ENDPOINT — so the
standard deployment configures nothing and delivery just works. The scheme
is not signed, so a reverse proxy may terminate TLS provided it passes the
original Host through; that is pinned by a test rather than described and
hoped for.

Read URLs are stable within a window of one third of their lifetime.
Signing is a pure function of the clock, so naive re-signing yields a new
URL per second — a guaranteed browser cache miss, and the reference client
keys its <img> by URL, so an unchanged image would be torn down and
re-downloaded continuously. Quantizing the signing timestamp makes
repeated calls byte-identical while leaving at least two-thirds of the
lifetime; Cache-Control is set at signing time to the guaranteed
remainder, because the pinned SeaweedFS image sends none of its own.

Verified against live SeaweedFS: byte ranges answered directly with 206
and a correct Content-Range, so no range proxy is needed in Core; signing
is local (200 URLs in 66ms), so no batch API is needed; unsigned requests
for the same object are refused, so delivery never depends on a public
bucket; tampered signatures, swapped keys, and swapped buckets all
rejected. Signed write and delete URLs are deliberately not built.

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

apps/api/src/server.ts

@@ -12,11 +12,6 @@ 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,
@@ -29,7 +24,12 @@ import {
   type StartedModuleRuntime,
   startDiscoveredModuleRuntime,
 } from "@ekklesia/core/modules";
-import { serve, type ServerType } from "@hono/node-server";
+import {
+  createModuleStorageLookup,
+  createS3StorageProvider,
+  type StorageProvider,
+} from "@ekklesia/core/storage";
+import { type ServerType, serve } from "@hono/node-server";
 import type { Hono } from "hono";
 import { createApiApp } from "./app.js";
 import {
@@ -708,6 +708,9 @@ function readConfigFromEnvironment(): {
       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,

apps/api/tests/support/in-memory-module-storage.ts

@@ -2,11 +2,12 @@ import {
   type ModuleStorage,
   type ModuleStorageBody,
   ModuleStorageError,
-  type ModuleStorageListOptions,
   type ModuleStorageListing,
+  type ModuleStorageListOptions,
   type ModuleStorageObject,
   type ModuleStorageObjectMetadata,
   type ModuleStoragePutOptions,
+  type ModuleStorageReadUrl,
 } from "@ekklesia/contracts";
 import type { DiscoveredModule, ModuleStorageLookup } from "@ekklesia/core/modules";
 import { createModuleStorageLookup, type StorageProvider } from "@ekklesia/core/storage";
@@ -91,6 +92,18 @@ export function createInMemoryStorageProvider(): StorageProvider & {
     async close(): Promise<void> {
       // Nothing to release.
     },
+    async createReadUrl(
+      physicalBucket: string,
+      key: string,
+      urlOptions: { readonly expiresInSeconds: number; readonly downloadFilename?: string },
+    ): Promise<ModuleStorageReadUrl> {
+      // Keyed by physical bucket like everything else here, so a route test can prove the URL a
+      // handler received belongs to that module's namespace and not another's.
+      return Object.freeze({
+        expiresAt: new Date(Date.now() + urlOptions.expiresInSeconds * 1000),
+        url: `https://delivery.test/${physicalBucket}/${encodeURIComponent(key)}?token=fake`,
+      });
+    },
     async delete(physicalBucket: string, key: string): Promise<void> {
       objectsIn(physicalBucket).delete(key);
     },