@podosoft/podokit 1.1.6 → 1.3.0

package/dist/templates/modules/object-storage-local/files/apps/api/src/storage-local/download-url.ts

@@ -0,0 +1,159 @@
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { link, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type {
+  DownloadUrlOptions,
+  ListObjectsOptions,
+  ObjectBody,
+  ObjectData,
+  ObjectInfo,
+  ObjectPage,
+  ObjectStore,
+  PutObjectOptions,
+  StoredObject,
+} from "@podosoft/podokit-runtime";
+
+const KEY_BYTES = 32;
+const DEFAULT_EXPIRES_IN_SECONDS = 3600;
+const MAX_EXPIRES_IN_SECONDS = 7 * 24 * 60 * 60;
+const EXPIRES = /^\d{1,12}$/;
+
+export interface DownloadUrlSignature {
+  expires: string;
+  signature: string;
+}
+
+function errorCode(error: unknown): string | undefined {
+  return error instanceof Error && "code" in error && typeof error.code === "string"
+    ? error.code
+    : undefined;
+}
+
+async function readKey(path: string): Promise<Buffer> {
+  const key = await readFile(path);
+  if (key.byteLength !== KEY_BYTES) throw new Error(`Download URL key is corrupt: ${path}`);
+  return key;
+}
+
+/**
+ * Creates the key once and shares it with every later process. `link` fails
+ * when another process won the race, so a reader never sees a partial file.
+ */
+async function loadOrCreateKey(path: string): Promise<Buffer> {
+  try {
+    return await readKey(path);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, randomBytes(KEY_BYTES), { mode: 0o600, flag: "wx" });
+  try {
+    await link(temporary, path);
+  } catch (error) {
+    if (errorCode(error) !== "EEXIST") throw error;
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  return readKey(path);
+}
+
+/**
+ * Signs local download URLs so a URL works like an S3 presigned URL: it names
+ * one object, expires, and cannot be altered to reach another key.
+ */
+export class DownloadUrlSigner {
+  private key?: Promise<Buffer>;
+
+  constructor(
+    private readonly keyFile: string,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  async sign(
+    objectKey: string,
+    expiresInSeconds = DEFAULT_EXPIRES_IN_SECONDS,
+  ): Promise<DownloadUrlSignature> {
+    const lifetime = Math.min(
+      Math.max(Math.floor(expiresInSeconds), 1),
+      MAX_EXPIRES_IN_SECONDS,
+    );
+    const expires = String(Math.floor(this.now() / 1000) + lifetime);
+    const signature = (await this.digest(objectKey, expires)).toString("base64url");
+    return { expires, signature };
+  }
+
+  async verify(
+    objectKey: string,
+    expires: string | undefined,
+    signature: string | undefined,
+  ): Promise<boolean> {
+    if (!expires || !signature || !EXPIRES.test(expires)) return false;
+    if (Number(expires) * 1000 <= this.now()) return false;
+    const expected = await this.digest(objectKey, expires);
+    const provided = Buffer.from(signature, "base64url");
+    return provided.byteLength === expected.byteLength && timingSafeEqual(provided, expected);
+  }
+
+  private async digest(objectKey: string, expires: string): Promise<Buffer> {
+    this.key ??= loadOrCreateKey(this.keyFile);
+    return createHmac("sha256", await this.key)
+      .update(`podokit-local-download-v1\n${expires}\n${objectKey}`, "utf8")
+      .digest();
+  }
+}
+
+/** Reverses the per-segment encoding used in download URL paths. */
+export function objectKeyFromPath(encoded: string): string | undefined {
+  try {
+    return encoded.split("/").map((segment) => decodeURIComponent(segment)).join("/");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Delegates storage to the local store and adds a signature to download URLs. */
+export class SignedDownloadStore implements ObjectStore {
+  constructor(
+    private readonly store: ObjectStore,
+    private readonly signer: DownloadUrlSigner,
+    private readonly baseUrl: string,
+  ) {}
+
+  put(key: string, body: ObjectBody, options?: PutObjectOptions): Promise<StoredObject> {
+    return this.store.put(key, body, options);
+  }
+
+  get(key: string): Promise<ObjectData | null> {
+    return this.store.get(key);
+  }
+
+  stat(key: string): Promise<ObjectInfo | null> {
+    return this.store.stat(key);
+  }
+
+  list(prefix: string, options?: ListObjectsOptions): Promise<ObjectPage> {
+    return this.store.list(prefix, options);
+  }
+
+  exists(key: string): Promise<boolean> {
+    return this.store.exists(key);
+  }
+
+  delete(key: string): Promise<void> {
+    return this.store.delete(key);
+  }
+
+  async getDownloadUrl(key: string, options: DownloadUrlOptions = {}): Promise<string> {
+    const path = await this.store.getDownloadUrl(key);
+    const prefix = `${this.baseUrl}/`;
+    const objectKey = path.startsWith(prefix) ? objectKeyFromPath(path.slice(prefix.length)) : undefined;
+    if (objectKey === undefined) throw new Error("Local download URL does not match its base URL");
+    const { expires, signature } = await this.signer.sign(objectKey, options.expiresInSeconds);
+    return `${path}?${new URLSearchParams({ expires, signature }).toString()}`;
+  }
+
+  close(): void | Promise<void> {
+    return this.store.close();
+  }
+}

package/dist/templates/modules/object-storage-local/files/apps/api/src/storage-local/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-local/files/apps/api/src/storage-local/storage-local.module.spec.ts

@@ -1,8 +1,14 @@
 import { afterEach, describe, expect, it } from "bun:test";
+import { existsSync } from "node:fs";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { AppException } from "@podosoft/podokit-contracts";
 import { LocalObjectStore } from "@podosoft/podokit-runtime";
+import { Elysia } from "elysia";
+import type { RequestIdentity } from "../core/services";
+import { DownloadUrlSigner, SignedDownloadStore } from "./download-url";
+import { DOWNLOAD_BASE_URL, downloadSafetyHeaders, localStorageRoutes } from "./storage-local.module";
 
 let root: string | undefined;
 
@@ -11,15 +17,177 @@ afterEach(async () => {
   root = undefined;
 });
 
+interface Fixture {
+  directory: string;
+  storage: SignedDownloadStore;
+  signer: DownloadUrlSigner;
+}
+
+async function fixture(): Promise<Fixture> {
+  const directory = await mkdtemp(join(tmpdir(), "podokit-storage-"));
+  root = directory;
+  const signer = new DownloadUrlSigner(join(directory, ".podokit", "download-url.key"));
+  const storage = new SignedDownloadStore(
+    new LocalObjectStore({ rootDirectory: directory, publicBaseUrl: DOWNLOAD_BASE_URL }),
+    signer,
+    DOWNLOAD_BASE_URL,
+  );
+  return { directory, storage, signer };
+}
+
+function caller(userId: string | undefined, admin = false): RequestIdentity {
+  return {
+    userId: async () => userId,
+    isAdmin: async () => admin,
+    roles: async () => (admin ? ["admin"] : []),
+    activeOrganizationId: async () => undefined,
+  };
+}
+
+interface Reply {
+  status: number;
+  text: string;
+  contentType: string | null;
+  headers: Headers;
+}
+
+async function call(
+  { storage, signer }: Fixture,
+  identity: RequestIdentity,
+  method: "GET" | "PUT",
+  path: string,
+  content?: string,
+  headers: Record<string, string> = {},
+): Promise<Reply> {
+  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(localStorageRoutes(storage, signer, identity));
+  const response = await app.handle(new Request(`http://localhost${path}`, {
+    method,
+    headers: { ...(content === undefined ? {} : { "content-type": "application/json" }), ...headers },
+    ...(content === undefined ? {} : { body: JSON.stringify({ content }) }),
+  }));
+  return {
+    status: response.status,
+    text: await response.text(),
+    contentType: response.headers.get("content-type"),
+    headers: response.headers,
+  };
+}
+
+function code(reply: Reply): unknown {
+  return (JSON.parse(reply.text) as { code?: unknown }).code;
+}
+
 describe("local object storage provider", () => {
   it("stores and reads an object without allowing traversal", async () => {
-    root = await mkdtemp(join(tmpdir(), "podokit-storage-"));
-    const storage = new LocalObjectStore({ rootDirectory: root });
+    const { storage } = await fixture();
     await storage.put("uploads/hello.txt", "hello", { contentType: "text/plain" });
     expect(await storage.exists("uploads/hello.txt")).toBe(true);
-    expect(await storage.getDownloadUrl("uploads/hello.txt")).toBe(
-      "/files/content/uploads/hello.txt",
+    expect(await storage.getDownloadUrl("uploads/hello.txt")).toStartWith(
+      "/files/content/uploads/hello.txt?expires=",
     );
     await expect(storage.put("../outside.txt", "no")).rejects.toThrow("safe relative path");
   });
+
+  it("serves an object only through an unaltered signed URL", async () => {
+    const local = await fixture();
+    const anonymous = caller(undefined);
+    await local.storage.put("uploads/a/one.txt", "one", { contentType: "text/plain" });
+    await local.storage.put("uploads/b/two.txt", "two", { contentType: "text/plain" });
+    const signed = await local.storage.getDownloadUrl("uploads/a/one.txt");
+
+    const download = await call(local, anonymous, "GET", signed);
+    expect(download).toMatchObject({ status: 200, text: "one", contentType: "text/plain" });
+    expect(download.headers.get("content-length")).toBe("3");
+    expect(download.headers.get("last-modified")).toBeTruthy();
+    const etag = download.headers.get("etag") ?? "";
+    expect(etag).toMatch(/^"[^"]+"$/);
+    const revalidated = await call(local, anonymous, "GET", signed, undefined, { "if-none-match": etag });
+    expect(revalidated).toMatchObject({ status: 304, text: "" });
+
+    const unsigned = await call(local, anonymous, "GET", "/files/content/uploads/a/one.txt");
+    expect(unsigned.status).toBe(403);
+    expect(code(unsigned)).toBe("DOWNLOAD_URL_INVALID");
+
+    const swapped = await call(local, anonymous, "GET", signed.replace("a/one.txt", "b/two.txt"));
+    expect(swapped.status).toBe(403);
+
+    await local.storage.delete("uploads/a/one.txt");
+    const missing = await call(local, anonymous, "GET", signed);
+    expect(missing.status).toBe(404);
+    expect(code(missing)).toBe("STORAGE_OBJECT_NOT_FOUND");
+  });
+
+  it("limits the demo routes to administrators", async () => {
+    const local = await fixture();
+
+    const anonymous = await call(local, caller(undefined), "PUT", "/storage/hello", "x");
+    expect(anonymous.status).toBe(401);
+    expect(code(anonymous)).toBe("AUTH_REQUIRED");
+    for (const [method, path] of [
+      ["PUT", "/storage/hello"],
+      ["GET", "/storage/hello"],
+      ["GET", "/storage/hello/presigned"],
+    ] as const) {
+      const reply = await call(local, caller("user-1"), method, path, method === "PUT" ? "x" : undefined);
+      expect(reply.status).toBe(403);
+      expect(code(reply)).toBe("ADMIN_REQUIRED");
+    }
+    expect(existsSync(join(local.directory, "demo"))).toBe(false);
+  });
+
+  it("keeps administrator demo objects under the demo prefix", async () => {
+    const local = await fixture();
+    const admin = caller("admin-1", true);
+
+    expect((await call(local, admin, "PUT", "/storage/hello", "hi")).status).toBe(200);
+    expect(existsSync(join(local.directory, "demo", "hello"))).toBe(true);
+    const read = await call(local, admin, "GET", "/storage/hello");
+    expect(read).toMatchObject({ status: 200, text: "hi", contentType: "text/plain" });
+    expect(read.headers.get("content-length")).toBe("2");
+    expect(read.headers.get("x-content-type-options")).toBe("nosniff");
+    const presigned = JSON.parse((await call(local, admin, "GET", "/storage/hello/presigned")).text) as {
+      url: string;
+    };
+    expect(presigned.url).toStartWith("/files/content/demo/hello?");
+    expect((await call(local, caller(undefined), "GET", presigned.url)).text).toBe("hi");
+
+    for (const key of ["site%2Ffavicon", "..%2Fsite%2Ffavicon", ".podokit", "%2E%2E"]) {
+      const reply = await call(local, admin, "PUT", `/storage/${key}`, "x");
+      expect([400, 404]).toContain(reply.status);
+    }
+    expect(existsSync(join(local.directory, "site"))).toBe(false);
+    expect((await call(local, admin, "GET", "/storage/missing")).status).toBe(404);
+  });
+});
+
+describe("local download safety headers", () => {
+  it("renders only script-free types inline", () => {
+    expect(downloadSafetyHeaders("image/png")["content-disposition"]).toBe("inline");
+    expect(downloadSafetyHeaders("text/plain; charset=utf-8")["content-disposition"]).toBe("inline");
+    for (const type of ["text/html", "image/svg+xml", "application/xml", "application/javascript", undefined]) {
+      expect(downloadSafetyHeaders(type)["content-disposition"]).toBe("attachment");
+    }
+  });
+
+  it("always forbids sniffing and script execution", () => {
+    const headers = downloadSafetyHeaders("image/png");
+    expect(headers["x-content-type-options"]).toBe("nosniff");
+    expect(headers["content-security-policy"]).toBe("default-src 'none'; sandbox");
+  });
 });

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

@@ -1,60 +1,137 @@
+import { AppException } from "@podosoft/podokit-contracts";
 import {
   LocalObjectStore,
   OBJECT_STORAGE,
+  objectResponse,
   type ObjectData,
+  type ObjectStore,
 } from "@podosoft/podokit-runtime";
 import { Elysia, t } from "elysia";
-import { resolve } from "node:path";
-import type { AppPlugin, PodokitModule } from "../core/services";
+import { join, resolve } from "node:path";
+import {
+  ACCESS_POLICY,
+  REQUEST_IDENTITY,
+  type AppPlugin,
+  type ElysiaPlugin,
+  type PodokitModule,
+  type RequestIdentity,
+  type ServiceKey,
+} from "../core/services";
 import { PROVIDERS } from "../config/providers";
+import { DownloadUrlSigner, objectKeyFromPath, SignedDownloadStore } from "./download-url";
+import {
+  demoKeyParams,
+  demoObjectKey,
+  requireStorageAdmin,
+  storageObjectNotFound,
+} from "./storage-demo";
+
+export const DOWNLOAD_BASE_URL = "/files/content";
+export const LOCAL_DOWNLOAD_URLS = Symbol("local-download-urls") as ServiceKey<DownloadUrlSigner>;
 
-function responseBody(object: ObjectData): ReadableStream<Uint8Array> {
-  const iterator = object.body[Symbol.asyncIterator]();
-  return new ReadableStream<Uint8Array>({
-    async pull(controller): Promise<void> {
-      const next = await iterator.next();
-      if (next.done) controller.close();
-      else controller.enqueue(next.value);
-    },
-    async cancel(): Promise<void> {
-      await iterator.return?.();
-    },
-  });
+async function readObject(storage: ObjectStore, key: string): Promise<ObjectData> {
+  const object = await storage.get(key);
+  if (!object) throw storageObjectNotFound();
+  return object;
 }
 
-const localStoragePlugin: AppPlugin = ({ services }) => {
-  if (PROVIDERS["object-storage"] !== "local") {
-    return new Elysia({ name: "podokit.storage-local.inactive" });
-  }
-  const storage = services.resolve(OBJECT_STORAGE);
+// Local objects are served from the app's own origin with the type the uploader
+// declared. Only render types that cannot run script; everything else downloads,
+// and the sandbox policy blocks script even if a browser renders it anyway.
+const INLINE_CONTENT_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "image/avif",
+  "text/plain",
+]);
+
+export function downloadSafetyHeaders(contentType: string | undefined): Record<string, string> {
+  const mediaType = contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
+  return {
+    "x-content-type-options": "nosniff",
+    "content-security-policy": "default-src 'none'; sandbox",
+    "content-disposition": INLINE_CONTENT_TYPES.has(mediaType) ? "inline" : "attachment",
+  };
+}
+
+export function localStorageRoutes(
+  storage: ObjectStore,
+  signer: DownloadUrlSigner,
+  identity: RequestIdentity,
+): ElysiaPlugin {
   return new Elysia({ name: "podokit.storage-local" })
-    .get("/files/content/*", async ({ params, set }) => {
-      const object = await storage.get(params["*"]);
-      if (object.contentType) set.headers["content-type"] = object.contentType;
-      set.headers["content-length"] = String(object.size);
-      return new Response(responseBody(object));
+    .get("/files/content/*", async ({ request, params, query }) => {
+      const key = objectKeyFromPath(params["*"]);
+      if (key === undefined || !(await signer.verify(key, query.expires, query.signature))) {
+        throw new AppException(
+          "DOWNLOAD_URL_INVALID",
+          "The download URL is invalid or has expired",
+          403,
+        );
+      }
+      const object = await readObject(storage, key);
+      return objectResponse(request, object, { headers: downloadSafetyHeaders(object.contentType) });
     }, {
-      detail: { tags: ["files"], summary: "Read a local object" },
+      query: t.Object({
+        expires: t.Optional(t.String()),
+        signature: t.Optional(t.String()),
+      }),
+      detail: { tags: ["files"], summary: "Read a local object through a signed download URL" },
     })
-    .put("/storage/:key", async ({ params, body }) => {
-      await storage.put(params.key, body.content, { contentType: "text/plain" });
+    .put("/storage/:key", async ({ request, params, body }) => {
+      await requireStorageAdmin(identity, request);
+      await storage.put(demoObjectKey(params.key), body.content, { contentType: "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 ({ request, params }) => {
+      await requireStorageAdmin(identity, request);
+      return { url: await storage.getDownloadUrl(demoObjectKey(params.key)) };
+    }, {
+      params: demoKeyParams,
+      detail: { tags: ["storage"], summary: "Sign a demo object download URL (administrators only)" },
+    })
+    .get("/storage/:key", async ({ request, params }) => {
+      await requireStorageAdmin(identity, request);
+      const object = await readObject(storage, demoObjectKey(params.key));
+      return objectResponse(request, object, { headers: downloadSafetyHeaders(object.contentType) });
+    }, {
+      params: demoKeyParams,
+      detail: { tags: ["storage"], summary: "Read a demo object (administrators only)" },
     });
+}
+
+const localStoragePlugin: AppPlugin = ({ services }) => {
+  if (PROVIDERS["object-storage"] !== "local") {
+    return new Elysia({ name: "podokit.storage-local.inactive" });
+  }
+  return localStorageRoutes(
+    services.resolve(OBJECT_STORAGE),
+    services.resolve(LOCAL_DOWNLOAD_URLS),
+    services.resolve(REQUEST_IDENTITY),
+  );
 };
 
 export const storageLocalModule: PodokitModule = {
   name: "object-storage-local",
   configure: (_env, services): void => {
     if (PROVIDERS["object-storage"] !== "local") return;
-    const storage = new LocalObjectStore({
-      rootDirectory: resolve(process.env.LOCAL_STORAGE_PATH ?? "./data/files"),
-      publicBaseUrl: "/files/content",
-    });
+    const root = resolve(process.env.LOCAL_STORAGE_PATH ?? "./data/files");
+    const signer = new DownloadUrlSigner(join(root, ".podokit", "download-url.key"));
+    const storage = new SignedDownloadStore(
+      new LocalObjectStore({ rootDirectory: root, publicBaseUrl: DOWNLOAD_BASE_URL }),
+      signer,
+      DOWNLOAD_BASE_URL,
+    );
     services.register(OBJECT_STORAGE, storage, () => storage.close());
+    services.register(LOCAL_DOWNLOAD_URLS, signer);
+    // The signature is the authorization, as with an S3 presigned URL.
+    services.resolve(ACCESS_POLICY).register("GET", `${DOWNLOAD_BASE_URL}/*`, "public");
   },
   plugin: localStoragePlugin,
 };

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

@@ -0,0 +1,88 @@
+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",
+};
+
+type Playwright = PlaywrightWorkerArgs["playwright"];
+
+function uniqueKey(): string {
+  return `local-${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-local-${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: "L" } });
+  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("local storage: signed download URLs reach only the signed object", async ({ playwright }) => {
+  const ctx = await newContext(playwright);
+  const anonymous = await newContext(playwright);
+  const key = uniqueKey();
+  try {
+    test.skip(!(await signInAdmin(ctx)), "requires the auth module and the seeded administrator");
+    const presigned = await ctx.get(`/api/storage/${key}/presigned`);
+    const { url } = await presigned.json() as { url?: string };
+    test.skip(!url?.startsWith("/files/content/"), "object-storage provider is not local");
+    if (!url) throw new Error("presign response must include a url");
+    expect(url).toContain(`/files/content/demo/${key}?`);
+    expect((await ctx.put(`/api/storage/${key}`, { data: { content: "hello local" } })).ok()).toBeTruthy();
+
+    const download = await anonymous.get(`/api${url}`);
+    expect(download.ok()).toBeTruthy();
+    expect(await download.text()).toBe("hello local");
+
+    const unsigned = await anonymous.get(`/api${url.split("?")[0]}`);
+    expect(unsigned.status()).toBe(403);
+    expect(await unsigned.json()).toMatchObject({ error: { code: "DOWNLOAD_URL_INVALID" } });
+
+    const altered = await anonymous.get(`/api${url.replace(`demo/${key}`, `demo/${key}-other`)}`);
+    expect(altered.status()).toBe(403);
+  } finally {
+    await ctx.dispose();
+    await anonymous.dispose();
+  }
+});
+
+test("local storage demo routes are limited to administrators", async ({ playwright }) => {
+  const user = await newContext(playwright);
+  const key = uniqueKey();
+  try {
+    test.skip(!(await signUp(user)), "requires the auth module");
+    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 user.dispose();
+  }
+});

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

@@ -7,6 +7,9 @@
   "requiredProjectFiles": [
     "apps/api/src/config/providers.ts"
   ],
+  "requiredProjectContents": {
+    "apps/api/src/core/services.ts": ["isAdmin(request: Request): Promise<boolean>;"]
+  },
   "managedGlobs": [
     "apps/api/src/storage-local/**"
   ],
@@ -29,6 +32,8 @@
   ],
   "instructions": [
     "Local object storage is single-host. Back up LOCAL_STORAGE_PATH together with the database.",
-    "Keep the API at one replica or select the S3 provider."
+    "Keep the API at one replica or select the S3 provider.",
+    "Download URLs are signed and expire after one hour by default. The signing key lives in LOCAL_STORAGE_PATH/.podokit/download-url.key; deleting it invalidates every issued URL.",
+    "The /storage demo routes need the auth module and an administrator session, and only reach keys under demo/."
   ]
 }