@podosoft/podokit 1.1.5 → 1.2.0

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

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

@@ -0,0 +1,51 @@
+export const UPLOAD_KEY_PREFIX = "uploads/";
+
+const OWNER_SEGMENT = /^[A-Za-z0-9_-]{1,128}$/;
+const MAX_NAME_LENGTH = 128;
+
+export type UploadAccess = "allowed" | "forbidden" | "not-found";
+
+export interface UploadRequester {
+  userId: string | undefined;
+  admin: boolean;
+}
+
+/**
+ * Keys are `uploads/<userId>/<uuid>-<name>`. Without a signed-in user (an app
+ * without the auth module) the key has no owner segment, which is also the
+ * format every upload had before ownership existed.
+ */
+export function uploadKey(
+  userId: string | undefined,
+  fileName: string,
+  id: string = crypto.randomUUID(),
+): string {
+  const safeName = fileName.replace(/[^\w.-]+/g, "_").slice(-MAX_NAME_LENGTH);
+  const name = `${id}-${safeName}`;
+  if (userId === undefined) return `${UPLOAD_KEY_PREFIX}${name}`;
+  if (!OWNER_SEGMENT.test(userId)) {
+    throw new Error("The user id cannot be used as an upload key segment");
+  }
+  return `${UPLOAD_KEY_PREFIX}${userId}/${name}`;
+}
+
+/**
+ * Owners and administrators may read owned uploads. Unowned uploads are
+ * readable by administrators, and by requests without a user only when no
+ * identity provider is installed; with auth, such requests never reach the
+ * route because the session guard rejects them first.
+ */
+export function uploadAccess(key: string, requester: UploadRequester): UploadAccess {
+  if (!key.startsWith(UPLOAD_KEY_PREFIX)) return "not-found";
+  const segments = key.slice(UPLOAD_KEY_PREFIX.length).split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    return "not-found";
+  }
+  if (segments.length === 1) {
+    return requester.admin || requester.userId === undefined ? "allowed" : "forbidden";
+  }
+  if (segments.length === 2) {
+    return requester.admin || segments[0] === requester.userId ? "allowed" : "forbidden";
+  }
+  return "not-found";
+}

package/dist/templates/modules/file-upload/files/tests/api/files.api.spec.ts

@@ -1,20 +1,46 @@
-import { expect, test } from "@playwright/test";
+import { expect, test, type APIRequestContext, type APIResponse, type PlaywrightWorkerArgs } from "@playwright/test";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
 
-async function session(playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"]) {
+type Playwright = PlaywrightWorkerArgs["playwright"];
+
+interface Session {
+  ctx: APIRequestContext;
+  /** Undefined when the app has no auth module. */
+  userId: string | undefined;
+}
+
+async function session(playwright: Playwright): Promise<Session> {
   const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
   const email = `files-${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: "F" } }).catch(() => undefined);
-  return ctx;
+  const current = await ctx.get("/api/auth/get-session");
+  const body = current.ok() ? await current.json() as { user?: { id?: string } } | null : null;
+  return { ctx, userId: body?.user?.id };
 }
 
-test("file upload: multipart upload returns a key and url @smoke", async ({ playwright }) => {
-  const ctx = await session(playwright);
-  const res = await ctx.post("/api/files", {
-    multipart: { file: { name: "hello.txt", mimeType: "text/plain", buffer: Buffer.from("hi there") } },
+function upload(ctx: APIRequestContext, text = "hi there"): Promise<APIResponse> {
+  return ctx.post("/api/files", {
+    multipart: { file: { name: "hello.txt", mimeType: "text/plain", buffer: Buffer.from(text) } },
   });
+}
+
+async function uploadedKey(ctx: APIRequestContext): Promise<string> {
+  const res = await upload(ctx);
+  test.skip(res.status() >= 500, "selected object storage is not reachable");
+  expect(res.status(), await res.text()).toBe(201);
+  return (await res.json() as { key: string }).key;
+}
+
+// Keys contain slashes, so they travel URL-encoded as one path segment.
+function presign(ctx: APIRequestContext, key: string): Promise<APIResponse> {
+  return ctx.get(`/api/files/${encodeURIComponent(key)}/url`);
+}
+
+test("file upload: multipart upload returns a key and url @smoke", async ({ playwright }) => {
+  const { ctx, userId } = await session(playwright);
+  const res = await upload(ctx);
   const responseText = await res.text();
   test.skip(res.status() >= 500, "selected object storage is not reachable");
   expect(res.ok(), `upload returned ${res.status()}: ${responseText}`).toBeTruthy();
@@ -24,13 +50,48 @@ test("file upload: multipart upload returns a key and url @smoke", async ({ play
   if (typeof body !== "object" || body === null) throw new Error("upload response must be an object");
   const response = body as Record<string, unknown>;
   expect(typeof response.key).toBe("string");
-  expect(String(response.url)).toContain("http");
+  if (userId) expect(String(response.key)).toMatch(new RegExp(`^uploads/${userId}/[0-9a-f-]{36}-hello\\.txt$`));
+  // S3 returns an absolute presigned URL; local storage returns a signed API path.
+  expect(String(response.url)).toMatch(/^(https?:\/\/|\/files\/content\/)/);
   await ctx.dispose();
 });
 
 test("file upload: a request with no file is a 400", async ({ playwright }) => {
-  const ctx = await session(playwright);
+  const { ctx } = await session(playwright);
   const res = await ctx.post("/api/files", { multipart: { notfile: "x" } });
   expect(res.status()).toBe(400);
   await ctx.dispose();
 });
+
+test("file upload: the uploader can presign their own file", async ({ playwright }) => {
+  const { ctx } = await session(playwright);
+  try {
+    const key = await uploadedKey(ctx);
+    const res = await presign(ctx, key);
+    expect(res.status(), await res.text()).toBe(200);
+    const { url } = await res.json() as { url: string };
+    expect(url).toContain(key.split("/").pop() ?? key);
+  } finally {
+    await ctx.dispose();
+  }
+});
+
+test("file upload: users cannot presign another user's file", async ({ playwright }) => {
+  const owner = await session(playwright);
+  const other = await session(playwright);
+  try {
+    test.skip(!owner.userId || !other.userId, "requires the auth module");
+    const key = await uploadedKey(owner.ctx);
+
+    const forbidden = await presign(other.ctx, key);
+    expect(forbidden.status()).toBe(403);
+    expect(await forbidden.json()).toMatchObject({ error: { code: "FILE_FORBIDDEN" } });
+
+    const foreign = await presign(other.ctx, "site/favicon");
+    expect(foreign.status()).toBe(404);
+    expect(await foreign.json()).toMatchObject({ error: { code: "FILE_NOT_FOUND" } });
+  } finally {
+    await owner.ctx.dispose();
+    await other.ctx.dispose();
+  }
+});

package/dist/templates/modules/file-upload/module.manifest.json

@@ -1,9 +1,12 @@
 {
   "manifestVersion": 3,
   "name": "file-upload",
-  "description": "Multipart file upload endpoint that stores files via object storage and returns a presigned URL.",
+  "description": "Multipart file upload endpoint that stores each user's files via object storage and presigns them only for the uploader or an administrator.",
   "requiresCapabilities": ["object-storage"],
   "targetApp": "api",
+  "requiredProjectContents": {
+    "apps/api/src/core/services.ts": ["isAdmin(request: Request): Promise<boolean>;"]
+  },
   "env": [],
   "inject": [
     { "file": "apps/api/src/app.ts", "marker": "// podokit:end:imports", "text": "import { filesModule } from \"./files/files.module\";" },
@@ -11,7 +14,10 @@
   ],
   "instructions": [
     "Configure the selected object-storage provider before uploading files.",
-    "Upload a file:  curl -F 'file=@./some.png' localhost:5002/files",
-    "The response includes { key, url } — an S3 presigned URL or a local download URL."
+    "Uploads are stored as uploads/<userId>/<uuid>-<name>. Add the auth module so every upload has an owner.",
+    "Upload a file:  curl -b cookies.txt -F 'file=@./some.png' localhost:5002/files",
+    "The response includes { key, url } — an S3 presigned URL or a signed local download URL.",
+    "Presign it again (owner or administrator, key URL-encoded):  curl -b cookies.txt localhost:5002/files/uploads%2F<userId>%2F<file>/url",
+    "Uploads stored before per-user keys (uploads/<file>) can only be presigned by administrators."
   ]
 }

package/dist/templates/modules/job-progress/files/apps/api/src/progress/job-progress.module.ts

@@ -1,46 +1,40 @@
-import { JOBS, type JobQueue, type Unsubscribe } from "@podosoft/podokit-runtime";
+import { AppException } from "@podosoft/podokit-contracts";
+import { JOBS, type JobQueue } from "@podosoft/podokit-runtime";
 import { Elysia, t } from "elysia";
-import type { AppPlugin, PodokitModule, ServiceKey } from "../core/services";
+import {
+  REQUEST_IDENTITY,
+  type AppPlugin,
+  type ElysiaPlugin,
+  type PodokitModule,
+  type RequestIdentity,
+  type ServiceKey,
+} from "../core/services";
 import { SSE_EVENTS } from "../events/events.module";
-import { processProgress } from "./progress.processor";
-
-class ProgressWorker {
-  private unsubscribe?: Unsubscribe;
-
-  constructor(
-    private readonly queue: JobQueue,
-    private readonly publish: (event: unknown) => Promise<void>,
-  ) {}
-
-  async connect(): Promise<void> {
-    this.unsubscribe = await this.queue.process("progress", async (payload, job) => {
-      await processProgress(payload, (progress) => this.publish({
-        type: "job-progress",
-        jobId: job.id,
-        progress,
-      }));
-    });
-  }
-
-  async close(): Promise<void> {
-    await this.unsubscribe?.();
-  }
-}
+import { PROGRESS_JOB } from "./progress.processor";
+import { ProgressWorker } from "./progress.worker";
 
 const PROGRESS_WORKER = Symbol("progress-worker") as ServiceKey<ProgressWorker>;
 
-const progressPlugin: AppPlugin = ({ services }) => {
-  const queue = services.resolve(JOBS);
+export function progressRoutes(queue: JobQueue, identity: RequestIdentity): ElysiaPlugin {
   return new Elysia({ name: "podokit.job-progress" })
-    .post("/progress", async ({ body, set }) => {
-      const job = await queue.enqueue("progress", { steps: body.steps ?? 5 });
+    .post("/progress", async ({ request, body, set }) => {
+      const ownerId = await identity.userId(request);
+      if (!ownerId) throw new AppException("AUTH_REQUIRED", "Authentication is required", 401);
+      const job = await queue.enqueue(PROGRESS_JOB, { steps: body.steps ?? 5, ownerId });
       set.status = 201;
       return { jobId: job.id };
     }, {
       body: t.Object({ steps: t.Optional(t.Integer({ minimum: 1, maximum: 100 })) }),
-      detail: { tags: ["progress"], summary: "Start a progress job" },
+      detail: {
+        tags: ["progress"],
+        summary: "Start a progress job",
+        description: "Progress is published on the `job-progress` topic to the caller only.",
+      },
     });
-};
+}
+
+const progressPlugin: AppPlugin = ({ services }) =>
+  progressRoutes(services.resolve(JOBS), services.resolve(REQUEST_IDENTITY));
 
 export const jobProgressModule: PodokitModule = {
   name: "job-progress",

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.bridge.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, mock } from "bun:test";
-import { processProgress } from "./progress.processor";
+import { processProgress, progressEvent, progressPayload } from "./progress.processor";
 
 describe("progress processor", () => {
   it("publishes provider-neutral progress updates", async () => {
@@ -10,4 +10,19 @@ describe("progress processor", () => {
     expect(values).toEqual([25, 50, 75, 100]);
     expect(delay).toHaveBeenCalledTimes(4);
   });
+
+  it("reads the owner from the job payload", () => {
+    expect(progressPayload({ steps: 2, ownerId: "alice" })).toEqual({ steps: 2, ownerId: "alice" });
+    expect(progressPayload({ ownerId: "" })).toEqual({});
+    expect(progressPayload({ ownerId: 7 })).toEqual({});
+    expect(progressPayload(null)).toEqual({});
+  });
+
+  it("addresses progress events to the owner", () => {
+    expect(progressEvent("job-1", "alice", 40)).toEqual({
+      topic: "job-progress",
+      audience: { userIds: ["alice"] },
+      data: { jobId: "job-1", progress: 40 },
+    });
+  });
 });

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.processor.ts

@@ -1,11 +1,38 @@
+import type { EventEnvelope } from "../events/event-envelope";
+
+export const PROGRESS_JOB = "progress";
+export const JOB_PROGRESS_TOPIC = "job-progress";
+
 export interface ProgressPayload {
   steps?: number;
+  /** The user who started the job; only that user receives its progress. */
+  ownerId?: string;
+}
+
+export interface JobProgress {
+  jobId: string;
+  progress: number;
 }
 
-function payload(value: unknown): ProgressPayload {
+export function progressPayload(value: unknown): ProgressPayload {
   if (!value || typeof value !== "object" || Array.isArray(value)) return {};
-  const steps = (value as Record<string, unknown>).steps;
-  return typeof steps === "number" ? { steps } : {};
+  const { steps, ownerId } = value as Record<string, unknown>;
+  return {
+    ...(typeof steps === "number" ? { steps } : {}),
+    ...(typeof ownerId === "string" && ownerId.length > 0 ? { ownerId } : {}),
+  };
+}
+
+export function progressEvent(
+  jobId: string,
+  ownerId: string,
+  progress: number,
+): EventEnvelope<JobProgress> {
+  return {
+    topic: JOB_PROGRESS_TOPIC,
+    audience: { userIds: [ownerId] },
+    data: { jobId, progress },
+  };
 }
 
 export async function processProgress(
@@ -13,7 +40,7 @@ export async function processProgress(
   publish: (progress: number) => Promise<void>,
   delay: (milliseconds: number) => Promise<unknown> = Bun.sleep,
 ): Promise<{ done: true }> {
-  const steps = payload(value).steps ?? 5;
+  const steps = progressPayload(value).steps ?? 5;
   for (let index = 1; index <= steps; index += 1) {
     await delay(400);
     const progress = Math.round((index / steps) * 100);

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.worker.spec.ts

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { AppException } from "@podosoft/podokit-contracts";
+import {
+  MemoryEventBus,
+  type JobHandler,
+  type JobQueue,
+  type JobReference,
+} from "@podosoft/podokit-runtime";
+import { Elysia } from "elysia";
+import type { RequestIdentity } from "../core/services";
+import type { EventStream, StreamFrame } from "../events/event-stream";
+import { EventsService } from "../events/events.service";
+import { ReadinessService } from "../health/readiness.service";
+import { progressRoutes } from "./job-progress.module";
+import { JOB_PROGRESS_TOPIC } from "./progress.processor";
+import { ProgressWorker } from "./progress.worker";
+
+interface FakeQueue extends JobQueue {
+  enqueued: Array<{ name: string; payload: unknown }>;
+  run(payload: unknown, job: JobReference): Promise<void>;
+}
+
+function fakeQueue(): FakeQueue {
+  const handlers = new Map<string, JobHandler>();
+  const enqueued: Array<{ name: string; payload: unknown }> = [];
+  return {
+    enqueued,
+    enqueue: async (name, payload) => {
+      enqueued.push({ name, payload });
+      return { id: `job-${enqueued.length}`, name };
+    },
+    get: async () => null,
+    process: async (name, handler) => {
+      handlers.set(name, handler);
+      return () => {
+        handlers.delete(name);
+      };
+    },
+    run: async (payload, job) => {
+      const handler = handlers.get(job.name);
+      if (!handler) throw new Error(`no handler for ${job.name}`);
+      await handler(payload, job);
+    },
+    close: () => undefined,
+  };
+}
+
+const cleanups: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+  for (const cleanup of cleanups.splice(0)) await cleanup();
+});
+
+async function harness(): Promise<{ events: EventsService; queue: FakeQueue }> {
+  const events = new EventsService(new MemoryEventBus(), new ReadinessService());
+  await events.connect();
+  const queue = fakeQueue();
+  const worker = new ProgressWorker(queue, (event) => events.publishAsync(event), async () => undefined);
+  await worker.connect();
+  cleanups.push(async () => {
+    await worker.close();
+    await events.close();
+  });
+  return { events, queue };
+}
+
+function stream(events: EventsService, userId: string): Promise<EventStream> {
+  return events.open({ userId, roles: [] }, [JOB_PROGRESS_TOPIC, "marker"], new AbortController().signal);
+}
+
+function decoded(frame: StreamFrame | undefined): unknown {
+  return frame?.kind === "event" ? JSON.parse(frame.data) : frame;
+}
+
+async function progressBeforeMarker(events: EventsService, target: EventStream): Promise<unknown[]> {
+  await events.publishAsync({ topic: "marker", data: "end" });
+  const frames: unknown[] = [];
+  for (;;) {
+    const frame = decoded(await target.next());
+    if (JSON.stringify(frame) === JSON.stringify({ topic: "marker", data: "end" })) return frames;
+    frames.push(frame);
+  }
+}
+
+describe("progress worker", () => {
+  it("sends a job's progress only to the user who started it", async () => {
+    const { events, queue } = await harness();
+    const owner = await stream(events, "alice");
+    const other = await stream(events, "bob");
+
+    await queue.run({ steps: 2, ownerId: "alice" }, { id: "job-1", name: "progress" });
+
+    expect(await progressBeforeMarker(events, owner)).toEqual([
+      { topic: JOB_PROGRESS_TOPIC, data: { jobId: "job-1", progress: 50 } },
+      { topic: JOB_PROGRESS_TOPIC, data: { jobId: "job-1", progress: 100 } },
+    ]);
+    expect(await progressBeforeMarker(events, other)).toEqual([]);
+  });
+
+  it("publishes nothing for a job without an owner", async () => {
+    const { events, queue } = await harness();
+    const listener = await stream(events, "alice");
+    await queue.run({ steps: 2 }, { id: "legacy", name: "progress" });
+    expect(await progressBeforeMarker(events, listener)).toEqual([]);
+  });
+});
+
+describe("progress routes", () => {
+  const identity = (userId: string | undefined): RequestIdentity => ({
+    userId: async () => userId,
+    isAdmin: async () => false,
+    roles: async () => [],
+    activeOrganizationId: async () => undefined,
+  });
+
+  async function start(queue: JobQueue, userId: string | undefined): Promise<Response> {
+    const app = new Elysia()
+      .onError(({ error, set }) => {
+        if (!(error instanceof AppException)) return undefined;
+        set.status = error.statusCode;
+        return { code: error.code };
+      })
+      .use(progressRoutes(queue, identity(userId)));
+    return app.handle(new Request("http://localhost/progress", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ steps: 3 }),
+    }));
+  }
+
+  it("records the caller as the job owner", async () => {
+    const queue = fakeQueue();
+    const response = await start(queue, "alice");
+    expect(response.status).toBe(201);
+    expect(await response.json()).toEqual({ jobId: "job-1" });
+    expect(queue.enqueued).toEqual([{ name: "progress", payload: { steps: 3, ownerId: "alice" } }]);
+  });
+
+  it("requires a signed-in user", async () => {
+    const queue = fakeQueue();
+    const response = await start(queue, undefined);
+    expect(response.status).toBe(401);
+    expect(queue.enqueued).toEqual([]);
+  });
+});

package/dist/templates/modules/job-progress/files/apps/api/src/progress/progress.worker.ts

@@ -0,0 +1,37 @@
+import type { JobQueue, Unsubscribe } from "@podosoft/podokit-runtime";
+import type { EventEnvelope } from "../events/event-envelope";
+import {
+  PROGRESS_JOB,
+  processProgress,
+  progressEvent,
+  progressPayload,
+} from "./progress.processor";
+
+export class ProgressWorker {
+  private unsubscribe?: Unsubscribe;
+
+  constructor(
+    private readonly queue: JobQueue,
+    private readonly publish: (event: EventEnvelope) => Promise<void>,
+    private readonly delay?: (milliseconds: number) => Promise<unknown>,
+  ) {}
+
+  async connect(): Promise<void> {
+    this.unsubscribe = await this.queue.process(PROGRESS_JOB, async (payload, job) => {
+      // Jobs enqueued before progress had owners run without publishing,
+      // because there is nobody they may be shown to.
+      const ownerId = progressPayload(payload).ownerId;
+      await processProgress(
+        payload,
+        async (progress) => {
+          if (ownerId) await this.publish(progressEvent(job.id, ownerId, progress));
+        },
+        this.delay,
+      );
+    });
+  }
+
+  async close(): Promise<void> {
+    await this.unsubscribe?.();
+  }
+}