@podosoft/podokit 1.1.6 → 1.2.0

package/dist/templates/modules/auth/files/apps/api/src/auth/feature-gate.ts

@@ -18,29 +18,35 @@ const FEATURE_PATHS: Array<{ flag: FeatureFlag; prefixes: string[] }> = [
   { flag: "oidcProvider", prefixes: ["/oauth2/", "/.well-known/openid-configuration", "/.well-known/oauth-authorization-server", "/.well-known/oauth-protected-resource"] },
 ];
 
-const CACHE_TTL_MS = 3_000;
+export type FeatureFlags = Record<FeatureFlag, boolean>;
 
-export type SignupOpenCheck = () => Promise<boolean>;
-export type AppSettingsReader = () => Promise<Array<{ key: string; value: string }>>;
+/** Live settings the gate reads per request, normally the shared settings snapshot. */
+export interface FeatureGateSettings {
+  flags: () => Promise<FeatureFlags>;
+  signupOpen: () => Promise<boolean>;
+}
+
+/** Public registration is the default until an administrator explicitly closes it. */
+export function signupOpenFrom(settings: ReadonlyMap<string, string>): boolean {
+  return settings.get("site.allowSignup") !== "false";
+}
 
-/** Public registration is the default until an administrator explicitly closes
- *  it. The short cache keeps every auth flow on the same live site-setting
- *  policy without rebuilding the Better Auth instance. */
-export function createSignupOpenCheck(readSettings: AppSettingsReader): SignupOpenCheck {
-  let signupOpen = true;
-  let fetchedAt = 0;
+/** A settings read failure keeps public sign-up open. */
+export async function readSignupOpen(signupOpen: () => Promise<boolean>): Promise<boolean> {
+  try {
+    return await signupOpen();
+  } catch {
+    return true;
+  }
+}
 
-  return async (): Promise<boolean> => {
-    if (Date.now() - fetchedAt < CACHE_TTL_MS) return signupOpen;
-    try {
-      const rows = await readSettings();
-      signupOpen = rows.find((row) => row.key === "site.allowSignup")?.value !== "false";
-    } catch {
-      signupOpen = true;
-    }
-    fetchedAt = Date.now();
-    return signupOpen;
-  };
+/** A settings read failure applies the shipped defaults. */
+export async function readFeatureFlags(flags: () => Promise<FeatureFlags>): Promise<FeatureFlags> {
+  try {
+    return await flags();
+  } catch {
+    return { ...FLAG_DEFAULTS };
+  }
 }
 
 /** Administrator-created users are intentional and remain available when the
@@ -60,45 +66,28 @@ export function assertUserCreationAllowed(signupOpen: boolean, requestPath?: str
 
 /** Server-side enforcement for the admin Settings toggles: requests to a disabled
  *  feature's endpoints are rejected with 404, so "off" is a real boundary rather
- *  than hidden UI. Flags are read from app_setting through a small TTL cache
- *  (a toggle takes effect within ~CACHE_TTL_MS); before the migration has run,
- *  the shipped defaults apply. */
-export function createFeatureGate(
-  readSettings: AppSettingsReader,
-  isSignupOpen: SignupOpenCheck = createSignupOpenCheck(readSettings),
-) {
-  let cache: Record<FeatureFlag, boolean> = { ...FLAG_DEFAULTS };
-  let fetchedAt = 0;
-
-  async function flags(): Promise<Record<FeatureFlag, boolean>> {
-    if (Date.now() - fetchedAt < CACHE_TTL_MS) return cache;
-    try {
-      const rows = await readSettings();
-      const next = { ...FLAG_DEFAULTS };
-      for (const row of rows) {
-        if (row.key in FLAG_DEFAULTS) next[row.key as FeatureFlag] = row.value === "true";
-      }
-      cache = next;
-    } catch {
-      cache = { ...FLAG_DEFAULTS };
-    }
-    fetchedAt = Date.now();
-    return cache;
+ *  than hidden UI. Throws the API error for a rejected path. */
+export async function enforceFeatureGate(path: string, settings: FeatureGateSettings): Promise<void> {
+  // Reject explicit sign-up endpoints early. OAuth starts remain available so
+  // existing social users can sign in; their new-user callback is enforced by
+  // the database hook that uses this same policy.
+  if (path === "/sign-up/email" || path.startsWith("/sign-up/")) {
+    assertUserCreationAllowed(await readSignupOpen(settings.signupOpen), path);
+    return;
   }
+  const feature = FEATURE_PATHS.find((f) =>
+    f.prefixes.some((p) => path === p || path.startsWith(p)),
+  );
+  if (!feature) return;
+  const enabled = (await readFeatureFlags(settings.flags))[feature.flag];
+  if (!enabled) throw new APIError("NOT_FOUND", { message: "This feature is disabled." });
+}
 
+/** Better Auth middleware over {@link enforceFeatureGate}. The settings come from
+ *  the shared snapshot (a toggle takes effect within its TTL); before the
+ *  migration has run, the shipped defaults apply. */
+export function createFeatureGate(settings: FeatureGateSettings): ReturnType<typeof createAuthMiddleware> {
   return createAuthMiddleware(async (ctx) => {
-    // Reject explicit sign-up endpoints early. OAuth starts remain available so
-    // existing social users can sign in; their new-user callback is enforced by
-    // the database hook that uses this same policy.
-    if (ctx.path === "/sign-up/email" || ctx.path.startsWith("/sign-up/")) {
-      assertUserCreationAllowed(await isSignupOpen(), ctx.path);
-      return;
-    }
-    const feature = FEATURE_PATHS.find((f) =>
-      f.prefixes.some((p) => ctx.path === p || ctx.path.startsWith(p)),
-    );
-    if (!feature) return;
-    const enabled = (await flags())[feature.flag];
-    if (!enabled) throw new APIError("NOT_FOUND", { message: "This feature is disabled." });
+    await enforceFeatureGate(ctx.path, settings);
   });
 }

package/dist/templates/modules/auth/files/apps/api/src/auth-config/auth-config.service.ts

@@ -10,7 +10,9 @@ import {
   SUPPORTED_PROVIDER_IDS,
   SUPPORTED_SOCIAL_PROVIDERS,
 } from "@podosoft/podokit-auth";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { refreshAuthNow } from "../auth/auth-provider";
+import { authConfigParam } from "./config-param";
 
 export type SocialProviderView = {
   id: string;
@@ -102,7 +104,10 @@ function booleanField(source: Record<string, unknown>, key: string, fallback: bo
 }
 
 export class AuthConfigService {
-  constructor(private readonly sql: SQL) {}
+  constructor(
+    private readonly sql: SQL,
+    private readonly provider: DatabaseProviderName = "postgres",
+  ) {}
 
   private async rows(): Promise<AuthConfigRow[]> {
     return this.sql<AuthConfigRow[]>`
@@ -119,7 +124,7 @@ export class AuthConfigService {
   }
 
   private async upsert(row: AuthConfigRow): Promise<void> {
-    const config = object(row.config);
+    const config = authConfigParam(this.provider, object(row.config));
     await this.sql`
       INSERT INTO "auth_config" ("key", "enabled", "config", "secret", "updatedAt")
       VALUES (${row.key}, ${row.enabled}, ${config}, ${row.secret}, CURRENT_TIMESTAMP)

package/dist/templates/modules/auth/files/apps/api/src/auth-config/config-param.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import { authConfigParam } from "./config-param";
+
+describe("auth config parameters", () => {
+  it("binds JSON text that SQLite stores and reads back", async () => {
+    const sql = new SQL("sqlite://:memory:");
+    await sql`CREATE TABLE "auth_config" ("key" text PRIMARY KEY, "config" text NOT NULL DEFAULT '{}')`;
+    const config = { allowDelete: true, hibp: true };
+
+    await sql`INSERT INTO "auth_config" ("key", "config") VALUES (${"server"}, ${authConfigParam("sqlite", config)})`;
+
+    const [row] = await sql<Array<{ config: unknown }>>`SELECT "config" FROM "auth_config"`;
+    expect(typeof row?.config).toBe("string");
+    expect(JSON.parse(String(row?.config))).toEqual(config);
+    await sql.close();
+  });
+
+  it("keeps an object for PostgreSQL jsonb", () => {
+    const config = { clientId: "id" };
+    expect(authConfigParam("postgres", config)).toBe(config);
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth-config/config-param.ts

@@ -0,0 +1,10 @@
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+
+// PostgreSQL stores a jsonb object only when bound as an object (P-022), while
+// SQLite keeps the column as text and rejects object parameters.
+export function authConfigParam(
+  provider: DatabaseProviderName,
+  config: Record<string, unknown>,
+): Record<string, unknown> | string {
+  return provider === "sqlite" ? JSON.stringify(config) : config;
+}

package/dist/templates/modules/auth/files/apps/api/src/settings/flag-defaults.ts

@@ -27,3 +27,13 @@ export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
 };
 
 export const FEATURE_FLAGS = Object.keys(FLAG_DEFAULTS) as FeatureFlag[];
+
+/** Stored values override the shipped defaults; a missing row keeps the default. */
+export function flagsFrom(settings: ReadonlyMap<string, string>): Record<FeatureFlag, boolean> {
+  const flags = { ...FLAG_DEFAULTS };
+  for (const flag of FEATURE_FLAGS) {
+    const stored = settings.get(flag);
+    if (stored !== undefined) flags[flag] = stored === "true";
+  }
+  return flags;
+}

package/dist/templates/modules/auth/files/apps/api/src/settings/settings.service.spec.ts

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, setSystemTime, test } from "bun:test";
+import type { SQL } from "bun";
+import { createConfigStore, type AppSettingRow, type ConfigVersions } from "@podosoft/podokit-auth";
+import { SettingsService } from "./settings.service";
+
+type Row = AppSettingRow & { updatedAt: number };
+
+/** In-memory app_setting table with the same upsert semantics as the service's SQL. */
+function table() {
+  const rows = new Map<string, Row>();
+  let clock = 1;
+  const sql = (async (_strings: TemplateStringsArray, ...values: unknown[]) => {
+    const [key, value] = values as [string, string];
+    rows.set(key, { key, value, updatedAt: clock++ });
+    return [];
+  }) as unknown as SQL;
+  const store = () => createConfigStore({
+    list: async () => [],
+    listSettings: async () => [...rows.values()].map(({ key, value }) => ({ key, value })),
+    versions: async (): Promise<ConfigVersions> => ({
+      authConfig: "0:",
+      appSettings: `${rows.size}:${Math.max(0, ...[...rows.values()].map((row) => row.updatedAt))}`,
+    }),
+  });
+  return { rows, sql, store };
+}
+
+describe("SettingsService", () => {
+  let now = Date.UTC(2026, 0, 1);
+  beforeEach(() => {
+    now = Date.UTC(2026, 0, 1);
+    setSystemTime(new Date(now));
+  });
+  afterEach(() => {
+    setSystemTime();
+  });
+
+  test("applies a local write at once and reports the change", async () => {
+    const { sql, store } = table();
+    let changes = 0;
+    const settings = new SettingsService(sql, store(), async () => {
+      changes += 1;
+    });
+    expect(await settings.getBool("require2fa")).toBe(false);
+    const flags = await settings.setMany({ require2fa: true });
+    expect(flags.require2fa).toBe(true);
+    expect(await settings.getBool("require2fa")).toBe(true);
+    expect(changes).toBe(1);
+  });
+
+  test("follows another replica's write within the snapshot TTL", async () => {
+    const { sql, store } = table();
+    const replicaA = new SettingsService(sql, store());
+    const replicaB = new SettingsService(sql, store());
+    expect(await replicaB.getBool("require2fa")).toBe(false);
+
+    await replicaA.setMany({ require2fa: true });
+    expect(await replicaB.getBool("require2fa")).toBe(false);
+    setSystemTime(new Date(now + 3_100));
+    expect(await replicaB.getBool("require2fa")).toBe(true);
+    expect((await replicaB.flags()).require2fa).toBe(true);
+  });
+
+  test("falls back to the shipped defaults when app_setting is unavailable", async () => {
+    const settings = new SettingsService(table().sql, createConfigStore({
+      list: async () => [],
+      listSettings: async () => [],
+      versions: async () => {
+        throw new Error('relation "app_setting" does not exist');
+      },
+    }));
+    expect(await settings.flags()).toMatchObject({ twoFactor: true, phoneNumber: false, require2fa: false });
+  });
+
+  test("returns a copy of the flags", async () => {
+    const { sql, store } = table();
+    const settings = new SettingsService(sql, store());
+    (await settings.flags()).require2fa = true;
+    expect(await settings.getBool("require2fa")).toBe(false);
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/settings/settings.service.ts

@@ -1,53 +1,56 @@
 import type { SQL } from "bun";
-import { FLAG_DEFAULTS, FEATURE_FLAGS, type FeatureFlag } from "./flag-defaults";
+import type { ConfigStore } from "@podosoft/podokit-auth";
+import { FEATURE_FLAGS, flagsFrom, type FeatureFlag } from "./flag-defaults";
 
 export { FEATURE_FLAGS, type FeatureFlag };
 
-interface AppSettingRow {
-  key: string;
-  value: string;
-}
+export type SettingsSnapshot = Pick<ConfigStore, "selectSettings" | "invalidate">;
 
-/** DB-backed feature flags with migration defaults as the source of truth. */
+/** DB-backed feature flags with migration defaults as the source of truth. Reads
+ *  come from the shared settings snapshot, so every replica follows a change
+ *  within the snapshot TTL; a write here applies on this replica at once. */
 export class SettingsService {
-  private cache = new Map<string, string>();
-
-  constructor(private readonly sql: SQL) {}
+  private readonly current: () => Promise<Record<FeatureFlag, boolean>>;
+
+  constructor(
+    private readonly sql: SQL,
+    private readonly snapshot: SettingsSnapshot,
+    private readonly onChange: () => Promise<void> = async () => undefined,
+  ) {
+    this.current = snapshot.selectSettings(flagsFrom);
+  }
 
+  /** Reload the snapshot from the database. */
   async refresh(): Promise<void> {
-    try {
-      const rows = await this.sql<AppSettingRow[]>`
-        SELECT "key", "value" FROM "app_setting"
-      `;
-      this.cache = new Map(rows.map((row) => [row.key, row.value]));
-    } catch {
-      this.cache = new Map();
-    }
+    this.snapshot.invalidate();
+    await this.current();
   }
 
-  getBool(flag: FeatureFlag): boolean {
-    const stored = this.cache.get(flag);
-    return stored === undefined ? FLAG_DEFAULTS[flag] : stored === "true";
+  async getBool(flag: FeatureFlag): Promise<boolean> {
+    return (await this.current())[flag];
   }
 
-  flags(): Record<FeatureFlag, boolean> {
-    return Object.fromEntries(
-      FEATURE_FLAGS.map((flag) => [flag, this.getBool(flag)]),
-    ) as Record<FeatureFlag, boolean>;
+  async flags(): Promise<Record<FeatureFlag, boolean>> {
+    return { ...(await this.current()) };
   }
 
   async setMany(update: Partial<Record<FeatureFlag, boolean>>): Promise<Record<FeatureFlag, boolean>> {
-    for (const flag of FEATURE_FLAGS) {
-      const value = update[flag];
-      if (typeof value !== "boolean") continue;
-      await this.sql`
-        INSERT INTO "app_setting" ("key", "value", "updatedAt")
-        VALUES (${flag}, ${String(value)}, CURRENT_TIMESTAMP)
-        ON CONFLICT ("key") DO UPDATE
-        SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
-      `;
+    try {
+      for (const flag of FEATURE_FLAGS) {
+        const value = update[flag];
+        if (typeof value !== "boolean") continue;
+        await this.sql`
+          INSERT INTO "app_setting" ("key", "value", "updatedAt")
+          VALUES (${flag}, ${String(value)}, CURRENT_TIMESTAMP)
+          ON CONFLICT ("key") DO UPDATE
+          SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
+        `;
+      }
+    } finally {
+      // Also after a failure: earlier rows of the update may have been written.
+      await this.refresh();
     }
-    await this.refresh();
+    await this.onChange();
     return this.flags();
   }
 }

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

@@ -7,8 +7,8 @@
     ".claude/skills/podokit-configure-auth/**"
   ],
   "dependencies": {
-    "@podosoft/podokit-auth": "^0.4.0",
-    "@podosoft/podokit-contracts": "^0.4.0",
+    "@podosoft/podokit-auth": "^0.5.0",
+    "@podosoft/podokit-contracts": "^0.5.0",
     "better-auth": "^1.7.7",
     "pg": "^8.12.0",
     "@better-auth/api-key": "^1.7.7",

package/dist/templates/modules/file-upload/files/apps/api/src/files/files.module.spec.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "bun:test";
+import { AppException } from "@podosoft/podokit-contracts";
+import type { ObjectBody, ObjectInfo, ObjectStore } from "@podosoft/podokit-runtime";
+import { Elysia } from "elysia";
+import type { RequestIdentity } from "../core/services";
+import { filesRoutes } from "./files.module";
+
+async function bytes(body: ObjectBody): Promise<Uint8Array> {
+  if (typeof body === "string") return Buffer.from(body);
+  if (body instanceof Uint8Array) return body;
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of body) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
+
+function streamOf(value: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller): void {
+      controller.enqueue(value);
+      controller.close();
+    },
+  });
+}
+
+function memoryStore(): ObjectStore {
+  const objects = new Map<string, Uint8Array>();
+  const info = (key: string): ObjectInfo | null => {
+    const value = objects.get(key);
+    return value
+      ? { key, size: value.byteLength, etag: `"${value.byteLength}"`, lastModified: new Date(0) }
+      : null;
+  };
+  return {
+    put: async (key, body, options) => {
+      const value = await bytes(body);
+      objects.set(key, value);
+      return { key, size: value.byteLength, ...options };
+    },
+    get: async (key) => {
+      const found = info(key);
+      const value = objects.get(key);
+      return found && value ? { ...found, body: streamOf(value) } : null;
+    },
+    stat: async (key) => info(key),
+    list: async (prefix) => ({ keys: [...objects.keys()].filter((key) => key.startsWith(prefix)).sort() }),
+    exists: async (key) => objects.has(key),
+    delete: async (key) => {
+      objects.delete(key);
+    },
+    getDownloadUrl: async (key) => `https://storage.example.com/${key}`,
+    close: () => undefined,
+  };
+}
+
+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;
+  body: Record<string, unknown>;
+}
+
+async function send(store: ObjectStore, identity: RequestIdentity, request: Request): Promise<Reply> {
+  const app = new Elysia()
+    .onError(({ error, set }) => {
+      if (!(error instanceof AppException)) return undefined;
+      set.status = error.statusCode;
+      return { code: error.code };
+    })
+    .use(filesRoutes(store, identity));
+  const response = await app.handle(request);
+  return { status: response.status, body: await response.json() as Record<string, unknown> };
+}
+
+async function upload(store: ObjectStore, identity: RequestIdentity): Promise<string> {
+  const form = new FormData();
+  form.append("file", new File(["hello"], "hello.txt", { type: "text/plain" }));
+  const reply = await send(store, identity, new Request("http://localhost/files", {
+    method: "POST",
+    body: form,
+  }));
+  expect(reply.status).toBe(201);
+  return String(reply.body.key);
+}
+
+function presign(store: ObjectStore, identity: RequestIdentity, key: string): Promise<Reply> {
+  return send(store, identity, new Request(`http://localhost/files/${encodeURIComponent(key)}/url`));
+}
+
+describe("file upload routes", () => {
+  it("stores uploads under the uploader and presigns them for the owner", async () => {
+    const store = memoryStore();
+    const key = await upload(store, caller("user_1"));
+
+    expect(key).toMatch(/^uploads\/user_1\/[0-9a-f-]{36}-hello\.txt$/);
+    expect(await presign(store, caller("user_1"), key)).toEqual({
+      status: 200,
+      body: { url: `https://storage.example.com/${key}` },
+    });
+  });
+
+  it("refuses another user's upload but lets an administrator presign it", async () => {
+    const store = memoryStore();
+    const key = await upload(store, caller("user_1"));
+
+    expect(await presign(store, caller("user_2"), key)).toEqual({
+      status: 403,
+      body: { code: "FILE_FORBIDDEN" },
+    });
+    expect((await presign(store, caller("admin_1", true), key)).status).toBe(200);
+  });
+
+  it("does not presign keys outside uploads", async () => {
+    const store = memoryStore();
+    for (const key of ["site/favicon", "profile-images/a.png", "demo/hello"]) {
+      expect(await presign(store, caller("admin_1", true), key)).toEqual({
+        status: 404,
+        body: { code: "FILE_NOT_FOUND" },
+      });
+    }
+  });
+
+  it("treats uploads from before ownership as administrator-only", async () => {
+    const store = memoryStore();
+    const legacy = "uploads/0b5f6b7e-8c1d-4d6e-9f00-112233445566-old.txt";
+
+    expect((await presign(store, caller("user_1"), legacy)).status).toBe(403);
+    expect((await presign(store, caller("admin_1", true), legacy)).status).toBe(200);
+  });
+});

package/dist/templates/modules/file-upload/files/apps/api/src/files/files.module.ts

@@ -1,13 +1,19 @@
+import { AppException } from "@podosoft/podokit-contracts";
 import { Elysia, t } from "elysia";
-import { OBJECT_STORAGE } from "@podosoft/podokit-runtime";
-import type { AppPlugin, PodokitModule } from "../core/services";
+import { OBJECT_STORAGE, type ObjectStore } from "@podosoft/podokit-runtime";
+import {
+  REQUEST_IDENTITY,
+  type AppPlugin,
+  type ElysiaPlugin,
+  type PodokitModule,
+  type RequestIdentity,
+} from "../core/services";
+import { uploadAccess, uploadKey } from "./upload-keys";
 
-const filesPlugin: AppPlugin = ({ services }) => {
-  const storage = services.resolve(OBJECT_STORAGE);
+export function filesRoutes(storage: ObjectStore, identity: RequestIdentity): ElysiaPlugin {
   return new Elysia({ name: "podokit.files" })
-    .post("/files", async ({ body, set }) => {
-      const safeName = body.file.name.replace(/[^\w.-]+/g, "_");
-      const key = `uploads/${crypto.randomUUID()}-${safeName}`;
+    .post("/files", async ({ request, body, set }) => {
+      const key = uploadKey(await identity.userId(request), body.file.name);
       await storage.put(
         key,
         new Uint8Array(await body.file.arrayBuffer()),
@@ -19,13 +25,28 @@ const filesPlugin: AppPlugin = ({ services }) => {
       body: t.Object({ file: t.File() }),
       detail: { tags: ["files"], summary: "Upload a file" },
     })
-    .get("/files/:key/url", async ({ params }) => ({
-      url: await storage.getDownloadUrl(params.key),
-    }), {
-      params: t.Object({ key: t.String({ minLength: 1 }) }),
-      detail: { tags: ["files"], summary: "Presign a file download" },
+    .get("/files/:key/url", async ({ request, params }) => {
+      const access = uploadAccess(params.key, {
+        userId: await identity.userId(request),
+        admin: await identity.isAdmin(request),
+      });
+      if (access === "not-found") throw new AppException("FILE_NOT_FOUND", "File not found", 404);
+      if (access === "forbidden") {
+        throw new AppException("FILE_FORBIDDEN", "You cannot access this file", 403);
+      }
+      return { url: await storage.getDownloadUrl(params.key) };
+    }, {
+      params: t.Object({ key: t.String({ minLength: 1, maxLength: 1024 }) }),
+      detail: {
+        tags: ["files"],
+        summary: "Presign a download of your upload",
+        description: "Pass the upload key URL-encoded as one path segment. Owners and administrators only.",
+      },
     });
-};
+}
+
+const filesPlugin: AppPlugin = ({ services }) =>
+  filesRoutes(services.resolve(OBJECT_STORAGE), services.resolve(REQUEST_IDENTITY));
 
 export const filesModule: PodokitModule = {
   name: "file-upload",

package/dist/templates/modules/file-upload/files/apps/api/src/files/upload-keys.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "bun:test";
+import { uploadAccess, uploadKey } from "./upload-keys";
+
+const id = "0b5f6b7e-8c1d-4d6e-9f00-112233445566";
+
+describe("uploadKey", () => {
+  it("places a signed-in user's upload under their id", () => {
+    expect(uploadKey("user_1", "my photo.png", id)).toBe(`uploads/user_1/${id}-my_photo.png`);
+  });
+
+  it("keeps the unowned format when there is no signed-in user", () => {
+    expect(uploadKey(undefined, "a.txt", id)).toBe(`uploads/${id}-a.txt`);
+  });
+
+  it("keeps file names to one bounded segment", () => {
+    expect(uploadKey("u", "../../etc/passwd", id)).toBe(`uploads/u/${id}-.._.._etc_passwd`);
+    expect(uploadKey("u", `${"x".repeat(300)}.png`, id)).toBe(`uploads/u/${id}-${"x".repeat(124)}.png`);
+  });
+
+  it("refuses a user id that is not a safe key segment", () => {
+    expect(() => uploadKey("../admin", "a.txt", id)).toThrow("upload key segment");
+  });
+});
+
+describe("uploadAccess", () => {
+  const owner = { userId: "user_1", admin: false };
+  const other = { userId: "user_2", admin: false };
+  const admin = { userId: "admin_1", admin: true };
+  const anonymous = { userId: undefined, admin: false };
+
+  it("lets owners and administrators read owned uploads", () => {
+    const key = `uploads/user_1/${id}-a.txt`;
+    expect(uploadAccess(key, owner)).toBe("allowed");
+    expect(uploadAccess(key, admin)).toBe("allowed");
+    expect(uploadAccess(key, other)).toBe("forbidden");
+    expect(uploadAccess(key, anonymous)).toBe("forbidden");
+  });
+
+  it("keeps unowned uploads from signed-in users who are not administrators", () => {
+    const key = `uploads/${id}-a.txt`;
+    expect(uploadAccess(key, owner)).toBe("forbidden");
+    expect(uploadAccess(key, admin)).toBe("allowed");
+    expect(uploadAccess(key, anonymous)).toBe("allowed");
+  });
+
+  it("does not presign keys owned by other features", () => {
+    for (const key of [
+      "site/favicon",
+      "profile-images/a.png",
+      "demo/hello",
+      "uploads/",
+      "uploads/user_1/",
+      "uploads/../site/favicon",
+      "uploads/user_1/../user_2/a.txt",
+      "uploads/user_1/nested/a.txt",
+    ]) {
+      expect(uploadAccess(key, admin)).toBe("not-found");
+    }
+  });
+});