@podosoft/podokit 1.1.6 → 1.3.0

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/s3-object.store.spec.ts

@@ -0,0 +1,80 @@
+import { afterAll, describe, expect, it } from "bun:test";
+import { randomBytes, randomUUID } from "node:crypto";
+import { ReadinessService } from "../health/readiness.service";
+import { S3ObjectStore } from "./s3-object.store";
+import { StorageService } from "./storage.service";
+
+// Runs against the bucket in the S3_* settings, like the storage API spec.
+const integration = process.env.S3_ENDPOINT ? describe : describe.skip;
+
+integration("S3ObjectStore against a live bucket", () => {
+  const storage = new StorageService(new ReadinessService());
+  const store = new S3ObjectStore(storage);
+  const prefix = `podokit-test/${randomUUID()}/`;
+  const created: string[] = [];
+
+  async function put(name: string, content: Uint8Array | string, contentType?: string): Promise<string> {
+    const key = `${prefix}${name}`;
+    created.push(key);
+    await store.put(key, content, contentType ? { contentType } : {});
+    return key;
+  }
+
+  afterAll(async () => {
+    await Promise.all(created.map((key) => storage.delete(key)));
+    storage.close();
+  });
+
+  it("describes an object and streams exactly its content", async () => {
+    const content = randomBytes(3 * 1024 * 1024);
+    const key = await put("object.bin", content, "application/octet-stream");
+
+    const info = await store.stat(key);
+    expect(info).toMatchObject({ key, size: content.byteLength, contentType: "application/octet-stream" });
+    expect(info?.etag).toMatch(/^"[^"]+"$/);
+    expect(info?.lastModified).toBeInstanceOf(Date);
+
+    const object = await store.get(key);
+    if (!object) throw new Error("expected the stored object");
+    expect(object.etag).toBe(info?.etag ?? "");
+    const streamed = Buffer.from(await new Response(object.body).arrayBuffer());
+    expect(streamed.equals(content)).toBe(true);
+  });
+
+  it("lists keys a page at a time", async () => {
+    const names = ["list/a.txt", "list/b.txt", "list/c/d.txt", "list/e.txt", "listed.txt"];
+    for (const name of names) await put(name, name);
+
+    const pages: string[][] = [];
+    let cursor: string | undefined;
+    do {
+      const page = await store.list(`${prefix}list/`, { limit: 2, ...(cursor ? { cursor } : {}) });
+      pages.push(page.keys.map((key) => key.slice(prefix.length)));
+      cursor = page.nextCursor;
+    } while (cursor !== undefined);
+
+    expect(pages).toEqual([["list/a.txt", "list/b.txt"], ["list/c/d.txt", "list/e.txt"]]);
+    expect((await store.list(`${prefix}list`)).keys).toHaveLength(names.length);
+    await expect(store.list(prefix, { limit: 0 })).rejects.toThrow("from 1 to 1000");
+  });
+
+  it("reports a missing key as null and lets an unread body be dropped", async () => {
+    expect(await store.get(`${prefix}missing`)).toBeNull();
+    expect(await store.stat(`${prefix}missing`)).toBeNull();
+
+    const key = await put("unread.txt", "unread", "text/plain");
+    const object = await store.get(key);
+    if (!object) throw new Error("expected the stored object");
+    await object.body.cancel();
+    expect(object.size).toBe(6);
+  });
+
+  it("fails the stream rather than mix in content written after the metadata was read", async () => {
+    const key = await put("replaced.txt", "before", "text/plain");
+    const object = await store.get(key);
+    if (!object) throw new Error("expected the stored object");
+    await store.put(key, "after!", { contentType: "text/plain" });
+
+    await expect(new Response(object.body).text()).rejects.toThrow("changed while it was being read");
+  });
+});

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/s3-object.store.ts

@@ -1,7 +1,10 @@
 import type {
   DownloadUrlOptions,
+  ListObjectsOptions,
   ObjectBody,
   ObjectData,
+  ObjectInfo,
+  ObjectPage,
   ObjectStore,
   PutObjectOptions,
   StoredObject,
@@ -16,10 +19,6 @@ async function bodyBytes(body: ObjectBody): Promise<Uint8Array> {
   return Buffer.concat(chunks);
 }
 
-async function* oneChunk(body: Uint8Array): AsyncGenerator<Uint8Array> {
-  yield body;
-}
-
 export class S3ObjectStore implements ObjectStore {
   constructor(private readonly storage: StorageService) {}
 
@@ -29,9 +28,16 @@ export class S3ObjectStore implements ObjectStore {
     return { key, size: bytes.byteLength, ...options };
   }
 
-  async get(key: string): Promise<ObjectData> {
-    const bytes = await this.storage.get(key);
-    return { key, size: bytes.byteLength, body: oneChunk(bytes) };
+  get(key: string): Promise<ObjectData | null> {
+    return this.storage.open(key);
+  }
+
+  stat(key: string): Promise<ObjectInfo | null> {
+    return this.storage.stat(key);
+  }
+
+  list(prefix: string, options?: ListObjectsOptions): Promise<ObjectPage> {
+    return this.storage.list(prefix, options);
   }
 
   exists(key: string): Promise<boolean> {

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage-demo.spec.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "bun:test";
+import { AppException } from "@podosoft/podokit-contracts";
+import { Elysia } from "elysia";
+import type { RequestIdentity } from "../core/services";
+import { storageDemoRoutes, type DemoStorage } from "./storage.module";
+
+interface MemoryStorage extends DemoStorage {
+  objects: Map<string, string>;
+  presigned: string[];
+}
+
+function memoryStorage(): MemoryStorage {
+  const objects = new Map<string, string>();
+  const presigned: string[] = [];
+  return {
+    objects,
+    presigned,
+    put: async (key, body) => {
+      if (typeof body === "string") objects.set(key, body);
+      else if (body instanceof Blob) objects.set(key, await body.text());
+      else objects.set(key, Buffer.from(body).toString("utf8"));
+    },
+    open: async (key) => {
+      const content = objects.get(key);
+      if (content === undefined) return null;
+      const bytes = Buffer.from(content);
+      return {
+        key,
+        size: bytes.byteLength,
+        contentType: "text/plain",
+        etag: `"${bytes.toString("hex")}"`,
+        lastModified: new Date("2026-01-02T03:04:05Z"),
+        body: new Blob([bytes]).stream(),
+      };
+    },
+    presignedGetUrl: async (key) => {
+      presigned.push(key);
+      return `https://storage.example.com/${key}?signature=test`;
+    },
+  };
+}
+
+function caller(userId: string | undefined, admin = false): RequestIdentity {
+  return {
+    userId: async () => userId,
+    isAdmin: async () => admin,
+    roles: async () => (admin ? ["admin"] : []),
+    activeOrganizationId: async () => undefined,
+  };
+}
+
+async function call(
+  storage: DemoStorage,
+  identity: RequestIdentity,
+  method: "GET" | "PUT",
+  path: string,
+  options: { content?: string; headers?: Record<string, string> } = {},
+): Promise<Response> {
+  const app = new Elysia()
+    .onError(({ code, error, set }) => {
+      if (error instanceof AppException) {
+        set.status = error.statusCode;
+        return { code: error.code };
+      }
+      if (code === "VALIDATION") {
+        set.status = 400;
+        return { code: "VALIDATION_ERROR" };
+      }
+      if (code === "NOT_FOUND") {
+        set.status = 404;
+        return { code: "NOT_FOUND" };
+      }
+      return undefined;
+    })
+    .use(storageDemoRoutes(storage, identity));
+  return app.handle(new Request(`http://localhost${path}`, {
+    method,
+    headers: {
+      ...(options.content === undefined ? {} : { "content-type": "application/json" }),
+      ...options.headers,
+    },
+    ...(options.content === undefined ? {} : { body: JSON.stringify({ content: options.content }) }),
+  }));
+}
+
+async function reply(response: Promise<Response>): Promise<{ status: number; body: unknown }> {
+  const resolved = await response;
+  return { status: resolved.status, body: await resolved.json() };
+}
+
+describe("object storage demo routes", () => {
+  it("require a signed-in administrator", async () => {
+    const storage = memoryStorage();
+
+    expect(await reply(call(storage, caller(undefined), "PUT", "/storage/hello", { content: "x" }))).toEqual({
+      status: 401,
+      body: { code: "AUTH_REQUIRED" },
+    });
+    for (const [method, path] of [
+      ["PUT", "/storage/hello"],
+      ["GET", "/storage/hello"],
+      ["GET", "/storage/hello/presigned"],
+    ] as const) {
+      const response = call(storage, caller("user-1"), method, path, method === "PUT" ? { content: "x" } : {});
+      expect(await reply(response)).toEqual({ status: 403, body: { code: "ADMIN_REQUIRED" } });
+    }
+    expect(storage.objects.size).toBe(0);
+    expect(storage.presigned).toEqual([]);
+  });
+
+  it("stores, streams, and presigns objects under the demo prefix for administrators", async () => {
+    const storage = memoryStorage();
+    const admin = caller("admin-1", true);
+
+    expect(await reply(call(storage, admin, "PUT", "/storage/hello", { content: "hi" }))).toEqual({
+      status: 200,
+      body: { key: "hello" },
+    });
+    expect([...storage.objects.keys()]).toEqual(["demo/hello"]);
+
+    const read = await call(storage, admin, "GET", "/storage/hello");
+    expect(read.status).toBe(200);
+    expect(read.headers.get("content-type")).toBe("text/plain");
+    expect(read.headers.get("content-length")).toBe("2");
+    expect(read.headers.get("x-content-type-options")).toBe("nosniff");
+    const etag = read.headers.get("etag");
+    expect(etag).toBe("\"6869\"");
+    expect(await read.text()).toBe("hi");
+
+    const revalidated = await call(storage, admin, "GET", "/storage/hello", {
+      headers: { "if-none-match": etag ?? "" },
+    });
+    expect(revalidated.status).toBe(304);
+    expect(await revalidated.text()).toBe("");
+
+    const presigned = await call(storage, admin, "GET", "/storage/hello/presigned");
+    expect(presigned.status).toBe(200);
+    expect(storage.presigned).toEqual(["demo/hello"]);
+  });
+
+  it("reports a missing demo object as not found", async () => {
+    const response = call(memoryStorage(), caller("admin-1", true), "GET", "/storage/missing");
+    expect(await reply(response)).toEqual({ status: 404, body: { code: "STORAGE_OBJECT_NOT_FOUND" } });
+  });
+
+  it("rejects keys that would leave the demo prefix", async () => {
+    const storage = memoryStorage();
+    const admin = caller("admin-1", true);
+
+    for (const key of ["site%2Ffavicon", "profile-images%2Fa.png", "..%2Fsite%2Ffavicon", ".podokit", "%2E%2E"]) {
+      const response = await call(storage, admin, "PUT", `/storage/${key}`, { content: "x" });
+      expect([400, 404]).toContain(response.status);
+    }
+    expect(storage.objects.size).toBe(0);
+  });
+});

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage-demo.ts

@@ -0,0 +1,38 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { t } from "elysia";
+import type { RequestIdentity } from "../core/services";
+
+/**
+ * The demo routes only reach objects under this prefix, so even an
+ * administrator cannot overwrite keys owned by other features such as
+ * uploads, profile images, or the site favicon.
+ */
+export const DEMO_KEY_PREFIX = "demo/";
+
+/**
+ * One path segment. Elysia decodes `%2F` inside `:key`, so the pattern rejects
+ * slashes and leading dots instead of trusting the router.
+ */
+export const demoKeyParams = t.Object({
+  key: t.String({ pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }),
+});
+
+export function demoObjectKey(name: string): string {
+  return `${DEMO_KEY_PREFIX}${name}`;
+}
+
+export function storageObjectNotFound(): AppException {
+  return new AppException("STORAGE_OBJECT_NOT_FOUND", "Object not found", 404);
+}
+
+export async function requireStorageAdmin(
+  identity: RequestIdentity,
+  request: Request,
+): Promise<void> {
+  if (!(await identity.userId(request))) {
+    throw new AppException("AUTH_REQUIRED", "Authentication is required", 401);
+  }
+  if (!(await identity.isAdmin(request))) {
+    throw new AppException("ADMIN_REQUIRED", "Administrator access is required", 403);
+  }
+}

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.module.ts

@@ -1,44 +1,62 @@
 import { Elysia, t } from "elysia";
-import { OBJECT_STORAGE } from "@podosoft/podokit-runtime";
+import { OBJECT_STORAGE, objectResponse } from "@podosoft/podokit-runtime";
 import { PROVIDERS } from "../config/providers";
 import {
   type AppPlugin,
+  type ElysiaPlugin,
   type PodokitModule,
   READINESS,
+  REQUEST_IDENTITY,
+  type RequestIdentity,
   type ServiceKey,
 } from "../core/services";
 import { StorageService } from "./storage.service";
 import { S3ObjectStore } from "./s3-object.store";
+import {
+  demoKeyParams,
+  demoObjectKey,
+  storageObjectNotFound,
+  requireStorageAdmin,
+} from "./storage-demo";
 
 export const STORAGE = Symbol("storage") as ServiceKey<StorageService>;
 
-const storagePlugin: AppPlugin = ({ services }) => {
-  if (PROVIDERS["object-storage"] !== "s3") {
-    return new Elysia({ name: "podokit.storage-s3.inactive" });
-  }
-  const storage = services.resolve(STORAGE);
+export type DemoStorage = Pick<StorageService, "put" | "open" | "presignedGetUrl">;
+
+export function storageDemoRoutes(storage: DemoStorage, identity: RequestIdentity): ElysiaPlugin {
   return new Elysia({ name: "podokit.storage" })
-    .put("/storage/:key", async ({ params, body }) => {
-      await storage.put(params.key, body.content, "text/plain");
+    .put("/storage/:key", async ({ request, params, body }) => {
+      await requireStorageAdmin(identity, request);
+      await storage.put(demoObjectKey(params.key), body.content, "text/plain");
       return { key: params.key };
     }, {
-      params: t.Object({ key: t.String({ minLength: 1 }) }),
+      params: demoKeyParams,
       body: t.Object({ content: t.String() }),
-      detail: { tags: ["storage"], summary: "Store an object" },
+      detail: { tags: ["storage"], summary: "Store a demo object (administrators only)" },
     })
-    .get("/storage/:key/presigned", async ({ params }) => ({
-      url: await storage.presignedGetUrl(params.key),
-    }), {
-      params: t.Object({ key: t.String({ minLength: 1 }) }),
-      detail: { tags: ["storage"], summary: "Presign an object download" },
+    .get("/storage/:key/presigned", async ({ request, params }) => {
+      await requireStorageAdmin(identity, request);
+      return { url: await storage.presignedGetUrl(demoObjectKey(params.key)) };
+    }, {
+      params: demoKeyParams,
+      detail: { tags: ["storage"], summary: "Presign a demo object download (administrators only)" },
     })
-    .get("/storage/:key", async ({ params }) => ({
-      key: params.key,
-      content: (await storage.get(params.key)).toString("utf8"),
-    }), {
-      params: t.Object({ key: t.String({ minLength: 1 }) }),
-      detail: { tags: ["storage"], summary: "Read an object" },
+    .get("/storage/:key", async ({ request, params }) => {
+      await requireStorageAdmin(identity, request);
+      const object = await storage.open(demoObjectKey(params.key));
+      if (!object) throw storageObjectNotFound();
+      return objectResponse(request, object, { headers: { "x-content-type-options": "nosniff" } });
+    }, {
+      params: demoKeyParams,
+      detail: { tags: ["storage"], summary: "Read a demo object (administrators only)" },
     });
+}
+
+const storagePlugin: AppPlugin = ({ services }) => {
+  if (PROVIDERS["object-storage"] !== "s3") {
+    return new Elysia({ name: "podokit.storage-s3.inactive" });
+  }
+  return storageDemoRoutes(services.resolve(STORAGE), services.resolve(REQUEST_IDENTITY));
 };
 
 export const storageModule: PodokitModule = {

package/dist/templates/modules/object-storage-s3/files/apps/api/src/storage/storage.service.ts

@@ -1,7 +1,70 @@
-import { S3Client } from "bun";
+import { S3Client, type S3Stats } from "bun";
+import {
+  objectListLimit,
+  type ListObjectsOptions,
+  type ObjectData,
+  type ObjectInfo,
+  type ObjectPage,
+} from "@podosoft/podokit-runtime";
 import { ReadinessService } from "../health/readiness.service";
 import { storageSettings } from "./storage.config";
 
+function isMissingObject(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "NoSuchKey";
+}
+
+function entityTag(etag: string): string {
+  return etag.startsWith("\"") || etag.startsWith("W/\"") ? etag : `"${etag}"`;
+}
+
+function objectInfo(key: string, stats: S3Stats): ObjectInfo {
+  return {
+    key,
+    size: stats.size,
+    ...(stats.type ? { contentType: stats.type } : {}),
+    etag: entityTag(stats.etag),
+    lastModified: stats.lastModified,
+  };
+}
+
+/**
+ * Downloads on the first read, so an unread body costs no request. Bun's
+ * `S3File.stream()` reads ahead without backpressure and would hold the rest of
+ * the object for a slow client; a presigned GET through fetch is paced by the
+ * socket instead, and If-Match keeps it on the version that was described.
+ */
+function download(client: S3Client, key: string, etag: string): ReadableStream<Uint8Array> {
+  const abort = new AbortController();
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller): Promise<void> {
+      if (!reader) {
+        const response = await fetch(client.presign(key, { expiresIn: 60 }), {
+          headers: { "if-match": etag },
+          decompress: false,
+          signal: abort.signal,
+        });
+        if (!response.ok || !response.body) {
+          await response.body?.cancel();
+          throw new Error(
+            response.status === 404 || response.status === 412
+              ? `Object ${key} changed while it was being read`
+              : `Object ${key} download failed with status ${response.status}`,
+          );
+        }
+        reader = response.body.getReader();
+      }
+      const next = await reader.read();
+      if (next.done) controller.close();
+      else controller.enqueue(next.value);
+    },
+    async cancel(reason): Promise<void> {
+      abort.abort(reason);
+      await reader?.cancel(reason).catch(() => undefined);
+    },
+  }, { highWaterMark: 0 });
+}
+
 export class StorageService {
   private readonly client: S3Client;
   private unregisterReadiness?: () => void;
@@ -25,8 +88,44 @@ export class StorageService {
     await this.client.file(key).write(body, contentType ? { type: contentType } : undefined);
   }
 
+  /** Reads a whole object into memory. Use `open()` for anything that can be large. */
   async get(key: string): Promise<Buffer> {
-    return Buffer.from(await this.client.file(key).bytes());
+    const bytes = await this.client.file(key).bytes();
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  }
+
+  /** Object metadata, or null when the key does not exist. */
+  async stat(key: string): Promise<ObjectInfo | null> {
+    try {
+      return objectInfo(key, await this.client.file(key).stat());
+    } catch (error) {
+      if (isMissingObject(error)) return null;
+      throw error;
+    }
+  }
+
+  /**
+   * Metadata plus a streamed body, or null when the key does not exist. The
+   * metadata request comes first because a missing key would otherwise only
+   * fail the stream, after a response has already started.
+   */
+  async open(key: string): Promise<ObjectData | null> {
+    const info = await this.stat(key);
+    if (!info) return null;
+    return { ...info, body: download(this.client, key, info.etag) };
+  }
+
+  /** One page of the keys under `prefix`; the bucket is never listed in full. */
+  async list(prefix: string, options: ListObjectsOptions = {}): Promise<ObjectPage> {
+    const page = await this.client.list({
+      prefix,
+      maxKeys: objectListLimit(options),
+      ...(options.cursor ? { continuationToken: options.cursor } : {}),
+    });
+    const keys = (page.contents ?? []).map((object) => object.key);
+    return page.isTruncated && page.nextContinuationToken
+      ? { keys, nextCursor: page.nextContinuationToken }
+      : { keys };
   }
 
   async exists(key: string): Promise<boolean> {

package/dist/templates/modules/object-storage-s3/files/tests/api/storage.api.spec.ts

@@ -1,19 +1,50 @@
-import { expect, test } from "@playwright/test";
+import { expect, test, type APIRequestContext, type PlaywrightWorkerArgs } from "@playwright/test";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
+// The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
+// spec also compiles in apps that do not install that module.
+const admin = {
+  email: "admin@example.com",
+  password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
+};
 
-async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]): Promise<import("@playwright/test").APIRequestContext> {
-  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+type Playwright = PlaywrightWorkerArgs["playwright"];
+
+function uniqueKey(): string {
+  return `obj-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function newContext(playwright: Playwright): Promise<APIRequestContext> {
+  return playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
+}
+
+async function sessionRoles(ctx: APIRequestContext): Promise<string[] | undefined> {
+  const response = await ctx.get("/api/auth/get-session");
+  if (!response.ok()) return undefined;
+  const session = await response.json() as { user?: { role?: string | null } } | null;
+  if (!session?.user) return undefined;
+  return (session.user.role ?? "").split(",").map((role) => role.trim()).filter(Boolean);
+}
+
+/** Resolves false when the auth module is missing or sign-up does not start a session. */
+async function signUp(ctx: APIRequestContext): Promise<boolean> {
   const email = `storage-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
-  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "S" } }).catch(() => undefined);
-  return ctx;
+  await ctx.post("/api/auth/sign-up/email", { data: { email, password: "Podokit3e-Str0ng!pw", name: "S" } });
+  return (await sessionRoles(ctx)) !== undefined;
+}
+
+/** Resolves false when no administrator session is available. */
+async function signInAdmin(ctx: APIRequestContext): Promise<boolean> {
+  const response = await ctx.post("/api/auth/sign-in/email", { data: admin });
+  return response.ok() && ((await sessionRoles(ctx)) ?? []).includes("admin");
 }
 
 test("object storage: put, get, and presign @smoke", async ({ playwright }) => {
-  const ctx = await session(playwright);
-  const key = `obj-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const ctx = await newContext(playwright);
+  const key = uniqueKey();
   try {
+    test.skip(!(await signInAdmin(ctx)), "requires the auth module and the seeded administrator");
     const put = await ctx.put(`/api/storage/${key}`, { data: { content: "hello world" } });
     test.skip(!process.env.S3_ENDPOINT && put.status() >= 500, "optional S3-compatible service not configured");
     expect(put.ok()).toBeTruthy();
@@ -21,12 +52,20 @@ test("object storage: put, get, and presign @smoke", async ({ playwright }) => {
 
     const read = await ctx.get(`/api/storage/${key}`);
     expect(read.ok()).toBeTruthy();
-    expect(await read.json()).toMatchObject({ key, content: "hello world" });
+    expect(read.headers()["content-type"]).toContain("text/plain");
+    expect(read.headers()["content-length"]).toBe("11");
+    expect(read.headers()["last-modified"]).toBeTruthy();
+    const etag = read.headers()["etag"];
+    expect(etag).toMatch(/^"[^"]+"$/);
+    expect(await read.text()).toBe("hello world");
+
+    const revalidated = await ctx.get(`/api/storage/${key}`, { headers: { "if-none-match": etag ?? "" } });
+    expect(revalidated.status()).toBe(304);
 
     const presigned = await ctx.get(`/api/storage/${key}/presigned`);
     expect(presigned.ok()).toBeTruthy();
     const pre = await presigned.json() as { url: string };
-    expect(new URL(pre.url).pathname).toContain(key);
+    expect(new URL(pre.url, base).pathname).toContain(`demo/${key}`);
     // The URL is signed for the API's S3 endpoint. A containerized dev stack signs an
     // in-network host, so download it only when the runner was given that endpoint too.
     if (process.env.S3_ENDPOINT) {
@@ -38,3 +77,39 @@ test("object storage: put, get, and presign @smoke", async ({ playwright }) => {
     await ctx.dispose();
   }
 });
+
+test("object storage demo routes are limited to administrators", async ({ playwright }) => {
+  const anonymous = await newContext(playwright);
+  const user = await newContext(playwright);
+  const key = uniqueKey();
+  try {
+    test.skip(!(await signUp(user)), "requires the auth module");
+    const unauthenticated = await anonymous.put(`/api/storage/${key}`, { data: { content: "x" } });
+    expect(unauthenticated.status()).toBe(401);
+
+    for (const response of [
+      await user.put(`/api/storage/${key}`, { data: { content: "x" } }),
+      await user.get(`/api/storage/${key}`),
+      await user.get(`/api/storage/${key}/presigned`),
+    ]) {
+      expect(response.status()).toBe(403);
+      expect(await response.json()).toMatchObject({ error: { code: "ADMIN_REQUIRED" } });
+    }
+  } finally {
+    await anonymous.dispose();
+    await user.dispose();
+  }
+});
+
+test("object storage demo keys cannot reach other features' objects", async ({ playwright }) => {
+  const ctx = await newContext(playwright);
+  try {
+    test.skip(!(await signInAdmin(ctx)), "requires the auth module and the seeded administrator");
+    for (const key of ["site%2Ffavicon", "profile-images%2Fx.png", "..%2Fsite%2Ffavicon", ".podokit"]) {
+      const response = await ctx.put(`/api/storage/${key}`, { data: { content: "x" } });
+      expect([400, 404], `PUT /api/storage/${key}`).toContain(response.status());
+    }
+  } finally {
+    await ctx.dispose();
+  }
+});

package/dist/templates/modules/object-storage-s3/module.manifest.json

@@ -7,6 +7,9 @@
   "requiredProjectFiles": [
     "apps/api/src/health/readiness.service.ts"
   ],
+  "requiredProjectContents": {
+    "apps/api/src/core/services.ts": ["isAdmin(request: Request): Promise<boolean>;"]
+  },
   "targetApp": "api",
   "env": [
     "# object storage — STORAGE_PROVIDER: minio | aws",
@@ -24,9 +27,11 @@
   ],
   "instructions": [
     "Start Silo for local dev:  docker compose -f infra/docker/docker-compose.yml -f infra/docker/minio.compose.yml up -d",
-    "Store an object:  curl -XPUT localhost:5002/storage/hello -H 'content-type: application/json' -d '{\"content\":\"hi\"}'",
-    "Read it back:     curl localhost:5002/storage/hello",
-    "Presigned URL:    curl localhost:5002/storage/hello/presigned",
+    "The /storage demo routes need the auth module and an administrator session, and only reach keys under demo/.",
+    "Sign in as an administrator:  curl -c cookies.txt -XPOST localhost:5002/api/auth/sign-in/email -H 'content-type: application/json' -d '{\"email\":\"admin@example.com\",\"password\":\"<password>\"}'",
+    "Store an object:  curl -b cookies.txt -XPUT localhost:5002/storage/hello -H 'content-type: application/json' -d '{\"content\":\"hi\"}'",
+    "Read it back:     curl -b cookies.txt localhost:5002/storage/hello",
+    "Presigned URL:    curl -b cookies.txt localhost:5002/storage/hello/presigned",
     "For AWS S3: set STORAGE_PROVIDER=aws, remove S3_ENDPOINT, set S3_FORCE_PATH_STYLE=false and real credentials/bucket."
   ]
 }