@podosoft/podokit 1.1.6 → 1.2.0

package/dist/templates/modules/mailer/files/apps/api/src/mail/mailer.spec.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { SmtpConfig } from "@podosoft/podokit-auth";
+import type { Transporter } from "nodemailer";
+import { mailTransport, setMailConfigStore, setMailTransport } from "./mailer";
+
+function storeOf(read: () => SmtpConfig | null) {
+  let calls = 0;
+  return {
+    store: {
+      smtpConfig: async (): Promise<SmtpConfig | null> => {
+        calls += 1;
+        return read();
+      },
+    },
+    calls: (): number => calls,
+  };
+}
+
+afterEach(() => {
+  setMailTransport(null);
+});
+
+describe("mailer transport", () => {
+  test("reuses the transport while the SMTP settings are unchanged", async () => {
+    let smtp: SmtpConfig | null = { host: "smtp.example.com", port: 587, secure: false, user: "u", pass: "p" };
+    const { store, calls } = storeOf(() => smtp);
+    setMailConfigStore(store);
+
+    const first = await mailTransport();
+    expect(await mailTransport()).toBe(first);
+    smtp = { ...smtp };
+    expect(await mailTransport()).toBe(first);
+    expect(calls()).toBe(3);
+
+    smtp = { ...smtp, host: "smtp2.example.com" };
+    const second = await mailTransport();
+    expect(second).not.toBe(first);
+    expect(await mailTransport()).toBe(second);
+  });
+
+  test("falls back to the environment when the store fails, and honours an override", async () => {
+    setMailConfigStore({
+      smtpConfig: async () => {
+        throw new Error('relation "auth_config" does not exist');
+      },
+    });
+    const fallback = await mailTransport();
+    expect(fallback).toBeDefined();
+
+    const custom = { sendMail: async () => ({}) } as unknown as Transporter;
+    setMailTransport(custom);
+    expect(await mailTransport()).toBe(custom);
+  });
+});

package/dist/templates/modules/mailer/files/apps/api/src/mail/mailer.ts

@@ -1,17 +1,18 @@
 import nodemailer, { type Transporter } from "nodemailer";
 import { createConfigStore, type SmtpConfig } from "@podosoft/podokit-auth";
 
-// Reusable email sending. SMTP is resolved in priority order, applied live (short
-// TTL) so no restart is needed:
+// Reusable email sending. SMTP is resolved in priority order, applied live so no
+// restart is needed:
 //   1. admin-configured DB settings (auth_config) — only when the auth module is
-//      installed; read via the config store, which decrypts the SMTP password;
+//      installed; read from the shared config snapshot, which decrypts the SMTP
+//      password once per change and follows the snapshot TTL;
 //   2. SMTP_* env (fallback / production secrets-manager injection);
 //   3. none → a JSON transport that logs the message so dev links are grabbable.
 // The whole transport can also be overridden from app code (setMailTransport),
 // e.g. from apps/api/src/app.extensions.ts, to plug in a provider SDK.
 type MailConfigStore = Pick<ReturnType<typeof createConfigStore>, "smtpConfig">;
 let store: MailConfigStore | undefined;
-const TTL_MS = 3_000;
+const DEFAULT_FROM = "PodoKit <no-reply@example.com>";
 
 export function setMailConfigStore(configStore: MailConfigStore): void {
   store = configStore;
@@ -49,11 +50,19 @@ function buildTransport(smtp: SmtpConfig | null): Transporter {
   });
 }
 
-let transport = buildTransport(null);
-let transportFrom = process.env.MAIL_FROM ?? "PodoKit <no-reply@example.com>";
-let hasSmtp = false;
-let checkedAt = 0;
-let signature = "";
+type MailSetup = {
+  smtp: SmtpConfig | null;
+  signature: string;
+  transport: Transporter;
+  from: string;
+};
+
+let setup: MailSetup = {
+  smtp: null,
+  signature: "null",
+  transport: buildTransport(null),
+  from: process.env.MAIL_FROM ?? DEFAULT_FROM,
+};
 let override: Transporter | null = null;
 
 /** Override the transport from app code (e.g. a provider SDK). Pass null to
@@ -62,31 +71,44 @@ export function setMailTransport(custom: Transporter | null): void {
   override = custom;
 }
 
-async function getTransport(): Promise<Transporter> {
-  if (override) return override;
-  if (checkedAt !== 0 && Date.now() - checkedAt < TTL_MS) return transport;
-  checkedAt = Date.now();
+/** The config-driven setup. The store returns the same SMTP object until the
+ *  config changes, and the transport is rebuilt only when its settings differ. */
+async function currentSetup(): Promise<MailSetup> {
+  const smtp = await resolveSmtp();
+  if (smtp === setup.smtp) return setup;
+  const signature = JSON.stringify(smtp);
+  if (signature === setup.signature) {
+    setup = { ...setup, smtp };
+    return setup;
+  }
   try {
-    const smtp = await resolveSmtp();
-    const next = JSON.stringify(smtp ?? null);
-    if (next !== signature) {
-      transport = buildTransport(smtp);
-      transportFrom = smtp?.from ?? process.env.MAIL_FROM ?? "PodoKit <no-reply@example.com>";
-      hasSmtp = !!smtp;
-      signature = next;
-    }
+    setup = {
+      smtp,
+      signature,
+      transport: buildTransport(smtp),
+      from: smtp?.from ?? process.env.MAIL_FROM ?? DEFAULT_FROM,
+    };
   } catch {
     /* keep the last-good transport */
   }
-  return transport;
+  return setup;
+}
+
+/** The transport `sendMail` uses now: the override, or the one built from SMTP config. */
+export async function mailTransport(): Promise<Transporter> {
+  return override ?? (await currentSetup()).transport;
 }
 
 export type Mail = { to: string; subject: string; text: string; html?: string };
 
 export async function sendMail(mail: Mail): Promise<void> {
-  const t = await getTransport();
-  const info = await t.sendMail({ from: transportFrom, ...mail });
-  if (!override && !hasSmtp) {
+  if (override) {
+    await override.sendMail({ from: setup.from, ...mail });
+    return;
+  }
+  const current = await currentSetup();
+  const info = await current.transport.sendMail({ from: current.from, ...mail });
+  if (!current.smtp) {
     // JSON transport: surface the message so the link is grabbable from logs.
     console.log(`[mailer] no SMTP configured; message not delivered:\n${info.message as string}`);
   }

package/dist/templates/modules/mailer/module.manifest.json

@@ -5,7 +5,7 @@
   "targetApp": "api",
   "dependencies": {
     "nodemailer": "^9.0.5",
-    "@podosoft/podokit-auth": "^0.4.0"
+    "@podosoft/podokit-auth": "^0.5.0"
   },
   "devDependencies": {
     "@types/nodemailer": "^8.0.1"

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

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LocalObjectStore } from "@podosoft/podokit-runtime";
+import { DownloadUrlSigner, objectKeyFromPath, SignedDownloadStore } from "./download-url";
+
+let root: string | undefined;
+
+async function tempRoot(): Promise<string> {
+  root = await mkdtemp(join(tmpdir(), "podokit-download-url-"));
+  return root;
+}
+
+afterEach(async () => {
+  if (root) await rm(root, { recursive: true, force: true });
+  root = undefined;
+});
+
+describe("DownloadUrlSigner", () => {
+  it("accepts only the signed key before it expires", async () => {
+    const keyFile = join(await tempRoot(), ".podokit", "download-url.key");
+    const now = 1_700_000_000_000;
+    const signer = new DownloadUrlSigner(keyFile, () => now);
+    const { expires, signature } = await signer.sign("uploads/a/file.txt", 60);
+
+    expect(expires).toBe(String(now / 1000 + 60));
+    expect(await signer.verify("uploads/a/file.txt", expires, signature)).toBe(true);
+    expect(await signer.verify("uploads/b/file.txt", expires, signature)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", String(Number(expires) + 1), signature)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", expires, `${signature.slice(0, -2)}AA`)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", undefined, signature)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", expires, undefined)).toBe(false);
+    expect(await signer.verify("uploads/a/file.txt", "1e9", signature)).toBe(false);
+
+    const later = new DownloadUrlSigner(keyFile, () => now + 61_000);
+    expect(await later.verify("uploads/a/file.txt", expires, signature)).toBe(false);
+  });
+
+  it("persists one private key for every signer that shares the key file", async () => {
+    const keyFile = join(await tempRoot(), ".podokit", "download-url.key");
+    const [first, second] = [new DownloadUrlSigner(keyFile), new DownloadUrlSigner(keyFile)];
+    const [signed] = await Promise.all([first.sign("demo/hello"), second.sign("demo/other")]);
+
+    expect(await second.verify("demo/hello", signed.expires, signed.signature)).toBe(true);
+    expect((await stat(keyFile)).mode & 0o777).toBe(0o600);
+  });
+
+  it("caps the lifetime at seven days", async () => {
+    const keyFile = join(await tempRoot(), "download-url.key");
+    const signer = new DownloadUrlSigner(keyFile, () => 0);
+    const { expires } = await signer.sign("demo/hello", 365 * 24 * 60 * 60);
+    expect(Number(expires)).toBe(7 * 24 * 60 * 60);
+  });
+});
+
+describe("objectKeyFromPath", () => {
+  it("decodes each path segment and rejects malformed encodings", () => {
+    expect(objectKeyFromPath("uploads/user%20one/a.txt")).toBe("uploads/user one/a.txt");
+    expect(objectKeyFromPath("uploads/%E0%A4%A")).toBeUndefined();
+  });
+});
+
+describe("SignedDownloadStore", () => {
+  it("adds a verifiable signature to local download URLs", async () => {
+    const directory = await tempRoot();
+    const signer = new DownloadUrlSigner(join(directory, ".podokit", "download-url.key"));
+    const store = new SignedDownloadStore(
+      new LocalObjectStore({ rootDirectory: directory, publicBaseUrl: "/files/content" }),
+      signer,
+      "/files/content",
+    );
+    await store.put("uploads/user one.txt", "hello", { contentType: "text/plain" });
+
+    const url = new URL(await store.getDownloadUrl("uploads/user one.txt"), "http://localhost");
+    expect(url.pathname).toBe("/files/content/uploads/user%20one.txt");
+    expect(
+      await signer.verify(
+        "uploads/user one.txt",
+        url.searchParams.get("expires") ?? undefined,
+        url.searchParams.get("signature") ?? undefined,
+      ),
+    ).toBe(true);
+    await expect(store.getDownloadUrl("../outside.txt")).rejects.toThrow("safe relative path");
+  });
+});

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");
+  });
 });