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

core/tests/doctor.test.ts

@@ -1,4 +1,4 @@
-import { parsePermissionId, type ModuleManifest } from "@ekklesia/contracts";
+import { type ModuleManifest, parsePermissionId } from "@ekklesia/contracts";
 import { describe, expect, it, vi } from "vitest";
 import { createPermissionRegistry, PermissionRegistryError } from "../src/authorization/index.js";
 import {
@@ -1219,6 +1219,7 @@ describe("Ekklesia Doctor — object storage", () => {
   const storageConfig = {
     accessKey: "AKIAEXAMPLEACCESSID",
     bucketPrefix: "ekklesia",
+    deliveryEndpoint: "https://storage.example.test",
     endpoint: "https://storage.example.test",
     forcePathStyle: true,
     region: "us-east-1",

core/tests/module-delivery.integration.ts

@@ -0,0 +1,458 @@
+import { randomBytes } from "node:crypto";
+import { request } from "node:http";
+import type { ModuleStorage } from "@ekklesia/contracts";
+import { afterAll, describe, expect, it } from "vitest";
+import { createStorageProviderConfig } from "../src/storage/config.js";
+import { createModuleStorage } from "../src/storage/module-storage.js";
+import type { StorageProvider } from "../src/storage/provider.js";
+import { createS3StorageProvider } from "../src/storage/s3-provider.js";
+
+/**
+ * Direct browser delivery against a **real S3-compatible server** (ADR 0031).
+ *
+ * Everything here is a claim that cannot be checked without a live provider. That a signature
+ * survives being served through a reverse proxy, that a byte range works without Core in the path,
+ * that a tampered URL is refused, that expiry is actually enforced — none of these are properties of
+ * the code in this repository, they are properties of the agreement between the signer and the
+ * server, and only the server can settle them.
+ *
+ * The bucket frugality of `module-storage.integration.ts` applies here for the same reason: a bucket
+ * is a collection on the pinned SeaweedFS image and collections come out of a finite, disk-derived
+ * budget. Tests share one bucket and separate by key.
+ */
+const endpointEnvironment = "EKKLESIA_TEST_STORAGE_ENDPOINT";
+const accessKeyEnvironment = "EKKLESIA_TEST_STORAGE_ACCESS_KEY";
+const secretKeyEnvironment = "EKKLESIA_TEST_STORAGE_SECRET_KEY";
+
+class IntegrationHarnessError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IntegrationHarnessError";
+    this.stack = `${this.name}: ${this.message}`;
+  }
+}
+
+function providerConfig(deliveryEndpoint?: string) {
+  const endpoint = process.env[endpointEnvironment];
+  if (typeof endpoint !== "string" || endpoint.trim() === "") {
+    throw new IntegrationHarnessError("The storage integration endpoint is not configured.");
+  }
+  const config = createStorageProviderConfig(
+    {
+      accessKey: process.env[accessKeyEnvironment],
+      ...(deliveryEndpoint === undefined ? {} : { deliveryEndpoint }),
+      endpoint,
+      secretKey: process.env[secretKeyEnvironment],
+    },
+    { environment: "development" },
+  );
+  if (!config) {
+    throw new IntegrationHarnessError("The storage integration configuration is invalid.");
+  }
+  return config;
+}
+
+function endpointOrigin(): URL {
+  return new URL(providerConfig().endpoint);
+}
+
+const openProviders: StorageProvider[] = [];
+
+function provider(deliveryEndpoint?: string): StorageProvider {
+  const created = createS3StorageProvider(providerConfig(deliveryEndpoint));
+  openProviders.push(created);
+  return created;
+}
+
+let cachedProvider: StorageProvider | undefined;
+function sharedProvider(): StorageProvider {
+  cachedProvider ??= provider();
+  return cachedProvider;
+}
+
+const runPrefix = `ekkdel${randomBytes(3).toString("hex")}`;
+
+/** The scoped facade a module would receive — every test drives delivery through this, never through
+ * the provider, so nothing here can accidentally prove something a module could not do. */
+function moduleBucket(moduleId = "announcements", logicalBucketId = "announcement-assets") {
+  return createModuleStorage({
+    bucketPrefix: runPrefix,
+    logicalBucketIds: [logicalBucketId],
+    moduleId,
+    provider: sharedProvider(),
+  }).bucket(logicalBucketId);
+}
+
+let namespaceCounter = 0;
+function keyNamespace(): string {
+  namespaceCounter += 1;
+  return `case-${namespaceCounter}`;
+}
+
+/** Issues a request to the real backend while presenting an arbitrary `Host`, which is exactly what
+ * a reverse proxy in front of storage does. `fetch` cannot express this: `Host` is a forbidden
+ * header name there, so it would silently send the wrong one and prove nothing. */
+function getWithHost(
+  pathAndQuery: string,
+  hostHeader: string,
+): Promise<{ status: number; headers: Record<string, string | string[] | undefined> }> {
+  const target = endpointOrigin();
+  return new Promise((resolve, reject) => {
+    const outbound = request(
+      {
+        headers: { Host: hostHeader },
+        host: target.hostname,
+        method: "GET",
+        path: pathAndQuery,
+        port: target.port,
+      },
+      (response) => {
+        response.resume();
+        response.on("end", () =>
+          resolve({ headers: response.headers, status: response.statusCode ?? 0 }),
+        );
+      },
+    );
+    outbound.on("error", reject);
+    outbound.end();
+  });
+}
+
+afterAll(async () => {
+  for (const open of openProviders.splice(0)) {
+    await open.close().catch(() => undefined);
+  }
+});
+
+describe.sequential("live direct object delivery", () => {
+  it("hands a browser a URL that returns the object, with its content type intact", async () => {
+    const bucket = moduleBucket();
+    const key = `${keyNamespace()}/welcome.png`;
+    const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    await bucket.put(key, png, { contentType: "image/png" });
+
+    const delivery = await bucket.createReadUrl(key);
+    // An ordinary fetch with no credentials, no SDK, and no Ekklesia in the path.
+    const response = await fetch(delivery.url);
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("content-type")).toBe("image/png");
+    expect(new Uint8Array(await response.arrayBuffer())).toEqual(png);
+    expect(delivery.expiresAt.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  it("refuses the same object without the URL's authorization", async () => {
+    const bucket = moduleBucket();
+    const key = `${keyNamespace()}/private.png`;
+    await bucket.put(key, "x");
+    const delivery = await bucket.createReadUrl(key);
+    const unsigned = new URL(delivery.url);
+    for (const parameter of [...unsigned.searchParams.keys()]) {
+      unsigned.searchParams.delete(parameter);
+    }
+
+    // The bucket is not public: delivery works because the URL carries authorization, not because
+    // anyone may read the object. This is the assertion that would fail if a future change "fixed"
+    // delivery by making buckets anonymous.
+    expect((await fetch(unsigned.toString())).status).toBe(403);
+  });
+
+  it("refuses a tampered signature, a swapped key, and a swapped bucket", async () => {
+    const bucket = moduleBucket();
+    const namespace = keyNamespace();
+    await bucket.put(`${namespace}/a.txt`, "a");
+    await bucket.put(`${namespace}/b.txt`, "b");
+    const delivery = await bucket.createReadUrl(`${namespace}/a.txt`);
+
+    const forged = new URL(delivery.url);
+    forged.searchParams.set("X-Amz-Signature", "0".repeat(64));
+    expect((await fetch(forged.toString())).status).toBe(403);
+
+    // The signature covers the path, so a URL is a capability for one object rather than for the
+    // bucket it happens to live in.
+    expect((await fetch(delivery.url.replace("/a.txt", "/b.txt"))).status).toBe(403);
+
+    // And swapping the physical bucket is refused too, which is what stops a URL for one module's
+    // object from being edited into a URL for another module's.
+    const physical = new URL(delivery.url).pathname.split("/")[1] ?? "";
+    expect(physical).not.toBe("");
+    expect((await fetch(delivery.url.replace(physical, physical.replace(/.$/u, "z")))).status).toBe(
+      403,
+    );
+  });
+
+  it("stops working once it expires", async () => {
+    // Driven at the provider seam so the deadline can be one second: the module-facing contract
+    // deliberately refuses lifetimes that short, and waiting out its minute-long floor would buy no
+    // extra confidence about whether the server enforces expiry.
+    const bucket = `${runPrefix}-expiry`.toLowerCase();
+    await sharedProvider().ensureBucket(bucket);
+    await sharedProvider().put(bucket, "fleeting.txt", "x", {});
+    const delivery = await sharedProvider().createReadUrl(bucket, "fleeting.txt", {
+      expiresInSeconds: 1,
+    });
+
+    expect((await fetch(delivery.url)).status).toBe(200);
+    await new Promise((resolve) => setTimeout(resolve, 2_500));
+    expect((await fetch(delivery.url)).status).toBe(403);
+  });
+
+  it("serves byte ranges directly, with no Core process in the data path", async () => {
+    const bucket = moduleBucket();
+    const key = `${keyNamespace()}/sermon.bin`;
+    const payload = "0123456789".repeat(500);
+    await bucket.put(key, payload, { contentType: "video/mp4" });
+
+    const delivery = await bucket.createReadUrl(key);
+    const ranged = await fetch(delivery.url, { headers: { Range: "bytes=10-19" } });
+
+    // This is what makes direct delivery worth having for media: seeking in a video is the provider's
+    // job, and Ekklesia never sees the bytes. A proxying route would have had to implement all of it.
+    expect(ranged.status).toBe(206);
+    expect(ranged.headers.get("content-range")).toBe(`bytes 10-19/${payload.length}`);
+    expect(await ranged.text()).toBe("0123456789");
+    expect((await fetch(delivery.url)).headers.get("accept-ranges")).toBe("bytes");
+  });
+
+  it("returns the same URL for the same object within a window, so caches and DOM keys hold", async () => {
+    const bucket = moduleBucket();
+    const key = `${keyNamespace()}/stable.png`;
+    await bucket.put(key, "x", { contentType: "image/png" });
+
+    // Signing timestamps have one-second granularity of their own, so the pair has to straddle a
+    // second for this to mean anything — otherwise it would pass with no windowing at all. That
+    // introduces the one race worth handling: the pair can land either side of a window boundary,
+    // which is not a defect but would look like one. A crossing cannot recur immediately, so one
+    // retry settles it deterministically rather than leaving a rare failure in the suite.
+    let first = await bucket.createReadUrl(key);
+    await new Promise((resolve) => setTimeout(resolve, 1_100));
+    let second = await bucket.createReadUrl(key);
+    if (second.url !== first.url) {
+      first = await bucket.createReadUrl(key);
+      await new Promise((resolve) => setTimeout(resolve, 1_100));
+      second = await bucket.createReadUrl(key);
+    }
+
+    // A second apart and byte-identical. Without this a client that rebuilds its state on a timer
+    // re-downloads every asset each time, because the URL is the browser's cache key — and a UI that
+    // keys elements by URL remounts them.
+    expect(second.url).toBe(first.url);
+    expect(second.expiresAt.getTime()).toBe(first.expiresAt.getTime());
+    expect((await fetch(second.url)).status).toBe(200);
+  });
+
+  it("asks the browser to cache the object for no longer than the URL lives", async () => {
+    const bucket = moduleBucket();
+    const key = `${keyNamespace()}/cacheable.png`;
+    await bucket.put(key, "x", { contentType: "image/png" });
+
+    const delivery = await bucket.createReadUrl(key);
+    const response = await fetch(delivery.url);
+    const cacheControl = response.headers.get("cache-control") ?? "";
+
+    expect(cacheControl).toMatch(/^private, max-age=\d+$/u);
+    const maxAge = Number(/max-age=(\d+)/u.exec(cacheControl)?.[1]);
+    expect(maxAge).toBeGreaterThan(0);
+    expect(delivery.expiresAt.getTime() - Date.now()).toBeGreaterThanOrEqual(maxAge * 1000);
+    // Revalidation still works, which is what keeps a long-running display cheap.
+    expect(response.headers.get("etag")).toMatch(/"[0-9a-f]{32}"/u);
+  });
+
+  it("offers a download name when asked, and displays inline otherwise", async () => {
+    const bucket = moduleBucket();
+    const key = `${keyNamespace()}/bulletin.pdf`;
+    await bucket.put(key, "%PDF-", { contentType: "application/pdf" });
+
+    const inline = await fetch((await bucket.createReadUrl(key)).url);
+    expect(inline.headers.get("content-disposition")).toBeNull();
+
+    const download = await bucket.createReadUrl(key, { downloadFilename: "Sunday Bulletin.pdf" });
+    const saved = await fetch(download.url);
+    expect(saved.status).toBe(200);
+    expect(saved.headers.get("content-disposition")).toBe(
+      'attachment; filename="Sunday Bulletin.pdf"',
+    );
+  });
+
+  describe("the browser delivery origin is a signing input, not a rewrite", () => {
+    const deliveryHost = "storage.example.org";
+
+    it("signs for the delivery origin and verifies behind a Host-preserving proxy", async () => {
+      const bucket = createModuleStorage({
+        bucketPrefix: runPrefix,
+        logicalBucketIds: ["announcement-assets"],
+        moduleId: "announcements",
+        // Core still reaches storage at the endpoint it always did; only signing differs.
+        provider: provider(`https://${deliveryHost}`),
+      }).bucket("announcement-assets");
+      const key = `${keyNamespace()}/proxied.png`;
+      await bucket.put(key, "x", { contentType: "image/png" });
+
+      const delivery = await bucket.createReadUrl(key);
+      const signed = new URL(delivery.url);
+      expect(signed.host).toBe(deliveryHost);
+
+      // Delivered through a proxy that passes the original Host through: the backend verifies it,
+      // even though the signed scheme was https and this hop is plaintext. SigV4 covers the Host
+      // header, the path, and the query — not the scheme — so terminating TLS at a proxy is fine.
+      const throughProxy = await getWithHost(signed.pathname + signed.search, deliveryHost);
+      expect(throughProxy.status).toBe(200);
+
+      // A proxy that replaces Host with its backend's breaks the signature. This is the single
+      // configuration requirement direct delivery imposes on a deployment.
+      const hostRewritten = await getWithHost(
+        signed.pathname + signed.search,
+        `${endpointOrigin().hostname}:${endpointOrigin().port}`,
+      );
+      expect(hostRewritten.status).toBe(403);
+    });
+
+    it("cannot be faked by rewriting a URL signed for the internal endpoint", async () => {
+      const bucket = moduleBucket();
+      const key = `${keyNamespace()}/internal.png`;
+      await bucket.put(key, "x");
+      const delivery = await bucket.createReadUrl(key);
+
+      const rewritten = new URL(delivery.url);
+      rewritten.host = deliveryHost;
+      const attempted = await getWithHost(rewritten.pathname + rewritten.search, deliveryHost);
+
+      // The reason `deliveryEndpoint` exists at all: post-hoc rewriting is not an option, so the
+      // browser-facing origin has to be known at signing time.
+      expect(attempted.status).toBe(403);
+    });
+  });
+
+  it("keeps a module's delivery URLs inside its own bucket", async () => {
+    const announcements = moduleBucket("announcements", "assets");
+    const video = moduleBucket("video", "assets");
+    const key = `${keyNamespace()}/same-name.txt`;
+    await announcements.put(key, "from-announcements");
+    await video.put(key, "from-video");
+
+    const fromAnnouncements = await fetch((await announcements.createReadUrl(key)).url);
+    const fromVideo = await fetch((await video.createReadUrl(key)).url);
+
+    // Same logical bucket name, same key, two modules — and a URL from one never reaches the other's
+    // object, because the physical bucket it names came from the binding rather than from anything
+    // the module said.
+    expect(await fromAnnouncements.text()).toBe("from-announcements");
+    expect(await fromVideo.text()).toBe("from-video");
+  });
+});
+
+/**
+ * An Announcements-shaped module, modelled on the real slideshow this platform exists to replace.
+ *
+ * The real one, today, hardcodes an object-storage origin, lists a public bucket over anonymous
+ * HTTP, and hands the browser absolute URLs it built by string concatenation. This is the same
+ * behaviour expressed against the module contract — and the point of writing it out is what it is
+ * **unable** to say. Its entire world is the parameter list: a `ModuleStorage` and two names it
+ * declared in its own manifest. There is no endpoint to hardcode, no credential to hold, no bucket
+ * to name, and no branch on which host is running it, so the identical function would run unchanged
+ * under a single-module standalone host (ADR 0031).
+ */
+interface Slide {
+  readonly key: string;
+  readonly url: string;
+  readonly expiresAt: Date;
+}
+
+async function announcementsSlideshowState(storage: ModuleStorage): Promise<readonly Slide[]> {
+  const assets = storage.bucket("announcement-assets");
+  const listing = await assets.list({ prefix: "slides/" });
+  const images = listing.objects.filter((object) => /\.(png|jpe?g|webp)$/iu.test(object.key));
+  return Promise.all(
+    images.map(async (object) => {
+      const delivery = await assets.createReadUrl(object.key);
+      return { expiresAt: delivery.expiresAt, key: object.key, url: delivery.url };
+    }),
+  );
+}
+
+describe.sequential("an Announcements-shaped module delivers slides directly", () => {
+  it("lists its own slides and hands a browser URLs that work", async () => {
+    const storage = createModuleStorage({
+      bucketPrefix: runPrefix,
+      logicalBucketIds: ["announcement-assets"],
+      moduleId: "announcements",
+      provider: sharedProvider(),
+    });
+    const assets = storage.bucket("announcement-assets");
+    const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    await assets.put("slides/welcome.png", png, { contentType: "image/png" });
+    await assets.put("slides/offering.jpg", png, { contentType: "image/jpeg" });
+    // Not an image, and the slideshow must not try to display it.
+    await assets.put("slides/notes.txt", "not a slide");
+
+    const state = await announcementsSlideshowState(storage);
+
+    expect(state.map((slide) => slide.key)).toEqual(["slides/offering.jpg", "slides/welcome.png"]);
+
+    // The display fetches every slide itself. Nothing in this repository carries the image bytes.
+    for (const slide of state) {
+      const response = await fetch(slide.url);
+      expect(response.status).toBe(200);
+      expect(new Uint8Array(await response.arrayBuffer())).toEqual(png);
+    }
+    expect(await fetch(state[0]?.url ?? "").then((r) => r.headers.get("content-type"))).toBe(
+      "image/jpeg",
+    );
+  });
+
+  it("persists logical keys, never URLs", async () => {
+    const storage = createModuleStorage({
+      bucketPrefix: runPrefix,
+      logicalBucketIds: ["announcement-assets"],
+      moduleId: "announcements",
+      provider: sharedProvider(),
+    });
+    await storage.bucket("announcement-assets").put("slides/keep.png", "x", {
+      contentType: "image/png",
+    });
+
+    const state = await announcementsSlideshowState(storage);
+    const slide = state.find((candidate) => candidate.key === "slides/keep.png");
+    if (!slide) {
+      throw new IntegrationHarnessError("The Announcements-shaped fixture lost its own slide.");
+    }
+
+    // What a module writes to its own tables is the key: it is stable, it is meaningful, and it
+    // still resolves tomorrow. The URL is a temporary capability that happens to be how today's
+    // browser reaches it, and storing one would be storing a credential with an expiry date in it.
+    expect(slide.key).toBe("slides/keep.png");
+    expect(slide.url).not.toBe(slide.key);
+    expect(slide.expiresAt.getTime()).toBeGreaterThan(Date.now());
+
+    // The module's own durable state names nothing about the host. The URL it hands the browser
+    // inevitably does — that asymmetry is the whole design, and it is asserted rather than assumed.
+    const persisted = JSON.stringify({ key: slide.key });
+    expect(persisted).not.toMatch(/http|amz|signature|ekkdel|127\.0\.0\.1/iu);
+    expect(new URL(slide.url).searchParams.has("X-Amz-Signature")).toBe(true);
+  });
+
+  it("builds a whole slideshow's URLs without a round trip each", async () => {
+    const storage = createModuleStorage({
+      bucketPrefix: runPrefix,
+      logicalBucketIds: ["announcement-assets"],
+      moduleId: "announcements",
+      provider: sharedProvider(),
+    });
+    const assets = storage.bucket("announcement-assets");
+
+    // Warm the binding first, so what is measured is signing rather than the one lazy CreateBucket
+    // round trip every binding pays once.
+    await assets.createReadUrl("slides/warm.png");
+
+    const startedAt = Date.now();
+    const urls = await Promise.all(
+      Array.from({ length: 40 }, (_, index) => assets.createReadUrl(`slides/deck-${index}.png`)),
+    );
+    const elapsed = Date.now() - startedAt;
+
+    expect(new Set(urls.map((delivery) => delivery.url)).size).toBe(40);
+    // Signing is local arithmetic, so a forty-slide deck costs no provider traffic and needs no
+    // batch API to stay cheap. A per-URL round trip could not come close to this.
+    expect(elapsed).toBeLessThan(1_000);
+  });
+});

core/tests/module-storage.test.ts

@@ -2,10 +2,13 @@ import {
   EMPTY_MODULE_STORAGE,
   isValidModuleStorageKey,
   MODULE_STORAGE_KEY_MAX_BYTES,
+  MODULE_STORAGE_READ_URL_DEFAULT_SECONDS,
+  MODULE_STORAGE_READ_URL_MAX_SECONDS,
+  MODULE_STORAGE_READ_URL_MIN_SECONDS,
   type ModuleStorageBody,
   ModuleStorageError,
-  type ModuleStorageListOptions,
   type ModuleStorageListing,
+  type ModuleStorageListOptions,
   type ModuleStorageObject,
   type ModuleStorageObjectMetadata,
   type ModuleStoragePutOptions,
@@ -81,6 +84,15 @@ function fakeProvider(options: { failEnsure?: () => Error } = {}): StorageProvid
 
   const provider: StorageProvider = {
     async close() {},
+    async createReadUrl(physicalBucket, key, urlOptions) {
+      calls.push({ key, operation: "createReadUrl", physicalBucket });
+      // Shaped like a real delivery URL — opaque, single-object, carrying an expiry — without any
+      // signing, so facade-level tests prove scoping and validation rather than cryptography.
+      return Object.freeze({
+        expiresAt: new Date(Date.now() + urlOptions.expiresInSeconds * 1000),
+        url: `https://delivery.test/${physicalBucket}/${encodeURIComponent(key)}?token=fake`,
+      });
+    },
     async delete(physicalBucket, key) {
       calls.push({ key, operation: "delete", physicalBucket });
       objectsIn(physicalBucket).delete(key);
@@ -354,7 +366,17 @@ describe("module storage scoping", () => {
 
     // The handle names the *logical* bucket, and has no accessor for anything else.
     expect(bucket.id).toBe("announcement-assets");
-    expect(Object.keys(bucket).sort()).toEqual(["delete", "get", "head", "id", "list", "put"]);
+    // Still the complete surface, now including delivery: a module can ask for a browser URL but has
+    // gained no way to ask where the object actually lives.
+    expect(Object.keys(bucket).sort()).toEqual([
+      "createReadUrl",
+      "delete",
+      "get",
+      "head",
+      "id",
+      "list",
+      "put",
+    ]);
     expect(Object.keys(storage).sort()).toEqual(["bucket", "buckets"]);
     const serialized = JSON.stringify({ bucket, storage });
     expect(serialized).not.toContain(
@@ -569,6 +591,9 @@ describe("storage provider configuration", () => {
     expect(config).toEqual({
       accessKey: "AKIAEXAMPLEACCESSID",
       bucketPrefix: "ekklesia",
+      // Unset, so the one endpoint serves both roles — the zero-configuration case, and the reason
+      // an ordinary deployment never has to think about browser delivery at all.
+      deliveryEndpoint: "https://storage.example.test",
       endpoint: "https://storage.example.test",
       // Path-style by default: every self-hosted S3-compatible service needs it, and virtual-host
       // addressing would require wildcard DNS a typical deployment does not have.
@@ -578,6 +603,85 @@ describe("storage provider configuration", () => {
     });
   });
 
+  it("lets one endpoint serve both roles when no delivery origin is configured", () => {
+    // The zero-configuration case, and the one an ordinary church deployment stays in: the
+    // repository's own development stack publishes storage on loopback, so the endpoint Core uses is
+    // already an origin a browser can reach and direct delivery needs nothing configured.
+    expect(createStorageProviderConfig(base)?.deliveryEndpoint).toBe(
+      "https://storage.example.test",
+    );
+    expect(createStorageProviderConfig({ ...base, deliveryEndpoint: "  " })?.deliveryEndpoint).toBe(
+      "https://storage.example.test",
+    );
+  });
+
+  it("keeps the browser delivery origin separate from the endpoint Core talks to", () => {
+    const config = createStorageProviderConfig(
+      {
+        ...base,
+        deliveryEndpoint: "https://storage.example.org/",
+        endpoint: "http://object-storage:8333",
+      },
+      { environment: "development" },
+    );
+
+    // The deployment this exists for: Core reaches storage by a private service name, browsers reach
+    // it by a public one, and the signature has to be made for the public one because it cannot be
+    // rewritten afterwards.
+    expect(config?.endpoint).toBe("http://object-storage:8333");
+    expect(config?.deliveryEndpoint).toBe("https://storage.example.org");
+  });
+
+  it("validates the delivery origin exactly as strictly as the endpoint", () => {
+    expect(() => createStorageProviderConfig({ ...base, deliveryEndpoint: "not-a-url" })).toThrow(
+      expect.objectContaining({ code: "STORAGE_DELIVERY_ENDPOINT_INVALID" }),
+    );
+    expect(() =>
+      createStorageProviderConfig({ ...base, deliveryEndpoint: "ftp://storage.example.org" }),
+    ).toThrow(expect.objectContaining({ code: "STORAGE_DELIVERY_ENDPOINT_INVALID" }));
+    expect(() =>
+      createStorageProviderConfig({ ...base, deliveryEndpoint: "https://k:[email protected]" }),
+    ).toThrow(expect.objectContaining({ code: "STORAGE_DELIVERY_ENDPOINT_WITH_CREDENTIALS" }));
+  });
+
+  it("refuses a plaintext delivery origin in production", () => {
+    // A browser on an https page will not load an http asset anyway, so allowing this would produce
+    // URLs that are silently unusable rather than a configuration error anyone can see.
+    expect(() =>
+      createStorageProviderConfig(
+        { ...base, deliveryEndpoint: "http://storage.example.org" },
+        { environment: "production" },
+      ),
+    ).toThrow(
+      expect.objectContaining({ code: "STORAGE_DELIVERY_ENDPOINT_INSECURE_IN_PRODUCTION" }),
+    );
+  });
+
+  it("describes a separate delivery origin without naming a credential", () => {
+    const split = createStorageProviderConfig(
+      {
+        ...base,
+        deliveryEndpoint: "https://storage.example.org",
+        endpoint: "http://object-storage:8333",
+      },
+      { environment: "development" },
+    );
+    const single = createStorageProviderConfig(base);
+    if (!split || !single) {
+      throw new Error("The storage configuration fixture produced no configuration.");
+    }
+    const described = describeStorageProvider(split);
+
+    expect(described).toContain("http://object-storage:8333");
+    expect(described).toContain("https://storage.example.org");
+    expect(described).not.toContain("AKIAEXAMPLEACCESSID");
+    expect(described).not.toContain("sk-example-secret-material");
+
+    // And an ordinary single-origin deployment reads exactly as it did before the distinction
+    // existed, so nobody is asked to understand a split that does not apply to them.
+    expect(describeStorageProvider(single)).not.toContain("browser delivery");
+  });
+
   it("requires both credentials once an endpoint is set", () => {
     expect(() => createStorageProviderConfig({ ...base, accessKey: undefined })).toThrow(
       expect.objectContaining({ code: "STORAGE_ACCESS_KEY_MISSING" }),
@@ -773,3 +877,133 @@ describe("an Announcements-shaped module reads its slides without knowing any in
     expect(JSON.stringify(caught)).not.toContain("http");
   });
 });
+
+describe("read URLs are bounded, scoped, and provider-neutral", () => {
+  function bucketFor(moduleId = "announcements", logicalBucketIds = ["assets"]) {
+    const provider = fakeProvider();
+    const storage = createModuleStorage({
+      bucketPrefix: "ekklesia",
+      logicalBucketIds,
+      moduleId,
+      provider,
+    });
+    return { bucket: storage.bucket(logicalBucketIds[0] ?? "assets"), provider, storage };
+  }
+
+  it("takes the host's default lifetime when the module asks for none", async () => {
+    const { bucket, provider } = bucketFor();
+    const delivery = await bucket.createReadUrl("welcome.png");
+
+    // A module that expresses no opinion gets the host's, which is the case that must stay easy:
+    // needing to know a duration to fetch an image would be provider knowledge leaking upward.
+    const expectedMs = MODULE_STORAGE_READ_URL_DEFAULT_SECONDS * 1000;
+    expect(delivery.expiresAt.getTime() - Date.now()).toBeGreaterThan(expectedMs - 5_000);
+    expect(delivery.expiresAt.getTime() - Date.now()).toBeLessThanOrEqual(expectedMs);
+    expect(provider.calls.at(-1)).toMatchObject({
+      key: "welcome.png",
+      operation: "createReadUrl",
+      physicalBucket: expect.stringContaining("ekklesia-announcements--assets-"),
+    });
+  });
+
+  it("accepts a lifetime inside the allowed range", async () => {
+    const { bucket } = bucketFor();
+    await expect(
+      bucket.createReadUrl("welcome.png", { expiresIn: MODULE_STORAGE_READ_URL_MIN_SECONDS }),
+    ).resolves.toMatchObject({ url: expect.any(String) });
+    await expect(
+      bucket.createReadUrl("welcome.png", { expiresIn: MODULE_STORAGE_READ_URL_MAX_SECONDS }),
+    ).resolves.toMatchObject({ url: expect.any(String) });
+  });
+
+  it.each([
+    ["below the floor", MODULE_STORAGE_READ_URL_MIN_SECONDS - 1],
+    ["above the ceiling", MODULE_STORAGE_READ_URL_MAX_SECONDS + 1],
+    ["a year", 365 * 24 * 60 * 60],
+    ["zero", 0],
+    ["negative", -60],
+    ["fractional", 90.5],
+    ["not a number", Number.NaN],
+    ["infinite", Number.POSITIVE_INFINITY],
+  ])("refuses a lifetime %s rather than clamping it", async (_label, expiresIn) => {
+    const { bucket, provider } = bucketFor();
+    const before = provider.calls.length;
+
+    await expect(bucket.createReadUrl("welcome.png", { expiresIn })).rejects.toMatchObject({
+      code: "STORAGE_READ_URL_EXPIRY_INVALID",
+    });
+    // Refused in the facade, so no provider ever sees a value it might interpret differently — and
+    // "expires forever" is unreachable rather than merely discouraged.
+    expect(provider.calls.filter((call) => call.operation === "createReadUrl")).toHaveLength(0);
+    expect(provider.calls.length).toBe(before);
+  });
+
+  it.each([
+    ["a quote", 'in"jected.pdf'],
+    ["a carriage return", "a\r\nX-Injected: 1.pdf"],
+    ["a newline", "a\nb.pdf"],
+    ["a path separator", "slides/welcome.png"],
+    ["a backslash", "slides\\welcome.png"],
+    ["a semicolon", "a;filename=b.pdf"],
+    ["nothing at all", ""],
+  ])("refuses a download filename containing %s", async (_label, downloadFilename) => {
+    const { bucket } = bucketFor();
+
+    // The value lands in a Content-Disposition response header, so anything that could close the
+    // quoted string or start a new header is refused at the contract rather than escaped and hoped
+    // over.
+    await expect(bucket.createReadUrl("bulletin.pdf", { downloadFilename })).rejects.toMatchObject({
+      code: "STORAGE_READ_URL_FILENAME_INVALID",
+    });
+  });
+
+  it("accepts an ordinary download filename", async () => {
+    const { bucket } = bucketFor();
+    await expect(
+      bucket.createReadUrl("bulletin.pdf", { downloadFilename: "Sunday Bulletin (2026).pdf" }),
+    ).resolves.toMatchObject({ url: expect.any(String) });
+  });
+
+  it("refuses an invalid key before it reaches the provider", async () => {
+    const { bucket, provider } = bucketFor();
+
+    await expect(bucket.createReadUrl("/absolute.png")).rejects.toMatchObject({
+      code: "STORAGE_KEY_INVALID",
+    });
+    expect(provider.calls.filter((call) => call.operation === "createReadUrl")).toHaveLength(0);
+  });
+
+  it("cannot produce a URL for a bucket this module did not declare", () => {
+    const { storage } = bucketFor("announcements", ["assets"]);
+
+    // There is no path to another module's object at all: the name does not resolve, so delivery
+    // inherits scoping from the facade rather than re-implementing it.
+    expect(() => storage.bucket("video-assets")).toThrow(ModuleStorageError);
+  });
+
+  it("sends two modules' identical logical names to two different physical buckets", async () => {
+    const provider = fakeProvider();
+    const urlFor = async (moduleId: string) => {
+      const bucket = createModuleStorage({
+        bucketPrefix: "ekklesia",
+        logicalBucketIds: ["assets"],
+        moduleId,
+        provider,
+      }).bucket("assets");
+      await bucket.createReadUrl("same-key.txt");
+      return provider.calls.at(-1)?.physicalBucket;
+    };
+
+    expect(await urlFor("announcements")).not.toBe(await urlFor("video"));
+  });
+
+  it("returns nothing but an opaque URL and an expiry", async () => {
+    const { bucket } = bucketFor();
+    const delivery = await bucket.createReadUrl("welcome.png");
+
+    // No provider identity, no physical bucket as a separate field, no credentials, no endpoint —
+    // a module can act on this without being able to learn anything about the host from it.
+    expect(Object.keys(delivery).sort()).toEqual(["expiresAt", "url"]);
+    expect(delivery.expiresAt).toBeInstanceOf(Date);
+  });
+});