@btst/stack 2.10.0 → 2.11.0

package/src/plugins/media/__tests__/getters.test.ts

@@ -8,6 +8,7 @@ import {
 	getAssetById,
 	listFolders,
 	getFolderById,
+	getFolderByName,
 } from "../api/getters";
 
 const createTestAdapter = (): Adapter => {
@@ -162,6 +163,30 @@ describe("media getters", () => {
 			expect(photoResult.items[0]!.filename).toBe("holiday-photo.jpg");
 		});
 
+		it("filters assets by tenantId", async () => {
+			await adapter.create({
+				model: "mediaAsset",
+				data: makeAsset({
+					filename: "tenant-a.jpg",
+					url: "https://example.com/a.jpg",
+				}),
+			});
+			const assetB = await adapter.create<{ id: string }>({
+				model: "mediaAsset",
+				data: {
+					...makeAsset({
+						filename: "tenant-b.jpg",
+						url: "https://example.com/b.jpg",
+					}),
+					tenantId: "tenant-b",
+				},
+			});
+
+			const result = await listAssets(adapter, { tenantId: "tenant-b" });
+			expect(result.items).toHaveLength(1);
+			expect(result.items[0]!.id).toBe(assetB.id);
+		});
+
 		it("paginates results with limit and offset", async () => {
 			for (let i = 0; i < 5; i++) {
 				await adapter.create({
@@ -231,6 +256,24 @@ describe("media getters", () => {
 			expect(result[1]!.name).toBe("Zeta");
 		});
 
+		it("filters folders by tenantId", async () => {
+			await adapter.create({
+				model: "mediaFolder",
+				data: makeFolder({ name: "No Tenant" }),
+			});
+			const tenantFolder = await adapter.create<{ id: string }>({
+				model: "mediaFolder",
+				data: {
+					...makeFolder({ name: "Tenant Folder" }),
+					tenantId: "tenant-x",
+				},
+			});
+
+			const result = await listFolders(adapter, { tenantId: "tenant-x" });
+			expect(result).toHaveLength(1);
+			expect(result[0]!.id).toBe(tenantFolder.id);
+		});
+
 		it("filters folders by parentId", async () => {
 			const root = await adapter.create<{ id: string }>({
 				model: "mediaFolder",
@@ -271,4 +314,116 @@ describe("media getters", () => {
 			expect(result!.name).toBe("Test Folder");
 		});
 	});
+
+	// ── getFolderByName ───────────────────────────────────────────────────────
+
+	describe("getFolderByName", () => {
+		it("returns null when no folder exists", async () => {
+			const result = await getFolderByName(adapter, "nonexistent");
+			expect(result).toBeNull();
+		});
+
+		it("finds a root-level folder by name with no parentId constraint", async () => {
+			await adapter.create({
+				model: "mediaFolder",
+				data: makeFolder({ name: "blog-gen-profile-1" }),
+			});
+
+			const result = await getFolderByName(adapter, "blog-gen-profile-1");
+			expect(result).not.toBeNull();
+			expect(result!.name).toBe("blog-gen-profile-1");
+		});
+
+		it("returns null when name matches but parentId does not", async () => {
+			const parent = await adapter.create<{ id: string }>({
+				model: "mediaFolder",
+				data: makeFolder({ name: "Parent" }),
+			});
+			await adapter.create({
+				model: "mediaFolder",
+				data: makeFolder({ name: "Child", parentId: parent.id }),
+			});
+
+			// Search for "Child" scoped to a different (non-existent) parent.
+			const result = await getFolderByName(adapter, "Child", "wrong-parent-id");
+			expect(result).toBeNull();
+		});
+
+		it("scopes lookup to root-level folders when parentId is null", async () => {
+			// Explicitly store parentId as null (mirrors how SQL adapters persist root folders).
+			const rootFolder = await adapter.create<{ id: string }>({
+				model: "mediaFolder",
+				data: { ...makeFolder({ name: "Images" }), parentId: null },
+			});
+			// A nested folder with the same name.
+			await adapter.create({
+				model: "mediaFolder",
+				data: makeFolder({ name: "Images", parentId: rootFolder.id }),
+			});
+
+			// Only the root-level "Images" (parentId = null) should be returned.
+			const result = await getFolderByName(adapter, "Images", null);
+			expect(result).not.toBeNull();
+			expect(result!.id).toBe(rootFolder.id);
+		});
+
+		it("finds a child folder scoped to the correct parentId", async () => {
+			const parentA = await adapter.create<{ id: string }>({
+				model: "mediaFolder",
+				data: makeFolder({ name: "Parent A" }),
+			});
+			const parentB = await adapter.create<{ id: string }>({
+				model: "mediaFolder",
+				data: makeFolder({ name: "Parent B" }),
+			});
+			const childOfA = await adapter.create<{ id: string }>({
+				model: "mediaFolder",
+				data: makeFolder({ name: "Child", parentId: parentA.id }),
+			});
+			await adapter.create({
+				model: "mediaFolder",
+				data: makeFolder({ name: "Child", parentId: parentB.id }),
+			});
+
+			const result = await getFolderByName(adapter, "Child", parentA.id);
+			expect(result).not.toBeNull();
+			expect(result!.id).toBe(childOfA.id);
+		});
+
+		it("filters by tenantId when provided", async () => {
+			await adapter.create({
+				model: "mediaFolder",
+				data: { ...makeFolder({ name: "blog-gen-abc" }), tenantId: "tenant-1" },
+			});
+			const folderT2 = await adapter.create<{ id: string }>({
+				model: "mediaFolder",
+				data: { ...makeFolder({ name: "blog-gen-abc" }), tenantId: "tenant-2" },
+			});
+
+			// Same name, different tenant — should only return the matching one.
+			const result = await getFolderByName(
+				adapter,
+				"blog-gen-abc",
+				undefined,
+				"tenant-2",
+			);
+			expect(result).not.toBeNull();
+			expect(result!.id).toBe(folderT2.id);
+		});
+
+		it("returns null when tenantId does not match", async () => {
+			await adapter.create({
+				model: "mediaFolder",
+				data: { ...makeFolder({ name: "blog-gen-xyz" }), tenantId: "tenant-1" },
+			});
+
+			const result = await getFolderByName(
+				adapter,
+				"blog-gen-xyz",
+				undefined,
+				"tenant-999",
+			);
+			expect(result).toBeNull();
+		});
+	});
 });

package/src/plugins/media/__tests__/mutations.test.ts

@@ -59,6 +59,21 @@ describe("media mutations", () => {
 			expect(asset.alt).toBe("A beautiful photo");
 		});
 
+		it("persists tenantId when provided", async () => {
+			const asset = await createAsset(adapter, {
+				...assetInput,
+				tenantId: "profile-abc",
+			});
+
+			expect(asset.tenantId).toBe("profile-abc");
+		});
+
+		it("leaves tenantId absent when not provided", async () => {
+			const asset = await createAsset(adapter, assetInput);
+
+			expect(asset.tenantId == null).toBe(true);
+		});
+
 		it("creates multiple independent assets", async () => {
 			await createAsset(adapter, {
 				...assetInput,
@@ -194,6 +209,21 @@ describe("media mutations", () => {
 			expect(folder.createdAt).toBeInstanceOf(Date);
 		});
 
+		it("persists tenantId when provided", async () => {
+			const folder = await createFolder(adapter, {
+				name: "Tenant Folder",
+				tenantId: "profile-xyz",
+			});
+
+			expect(folder.tenantId).toBe("profile-xyz");
+		});
+
+		it("leaves tenantId absent when not provided", async () => {
+			const folder = await createFolder(adapter, { name: "No Tenant" });
+
+			expect(folder.tenantId == null).toBe(true);
+		});
+
 		it("creates a nested folder with parentId", async () => {
 			const parent = await createFolder(adapter, { name: "Root" });
 			const child = await createFolder(adapter, {

package/src/plugins/media/api/adapters/local.ts

@@ -1,6 +1,6 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import * as crypto from "node:crypto";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as crypto from "crypto";
 import type { DirectStorageAdapter, UploadOptions } from "../storage-adapter";
 
 export interface LocalStorageAdapterOptions {

package/src/plugins/media/api/getters.ts

@@ -10,6 +10,7 @@ export interface AssetListParams {
 	query?: string;
 	offset?: number;
 	limit?: number;
+	tenantId?: string;
 }
 
 /**
@@ -27,6 +28,7 @@ export interface AssetListResult {
  */
 export interface FolderListParams {
 	parentId?: string | null;
+	tenantId?: string;
 }
 
 /**
@@ -64,6 +66,14 @@ export async function listAssets(
 		});
 	}
 
+	if (query.tenantId !== undefined) {
+		whereConditions.push({
+			field: "tenantId",
+			value: query.tenantId,
+			operator: "eq" as const,
+		});
+	}
+
 	const needsInMemoryFilter = !!query.query;
 	const dbWhere = whereConditions.length > 0 ? whereConditions : undefined;
 
@@ -136,22 +146,31 @@ export async function listFolders(
 	adapter: Adapter,
 	params?: FolderListParams,
 ): Promise<Folder[]> {
-	// Only add a where clause when parentId is explicitly provided as a string.
-	// Passing undefined (or no params) returns all folders unfiltered.
-	const where =
-		params?.parentId !== undefined
-			? [
-					{
-						field: "parentId",
-						value: params.parentId,
-						operator: "eq" as const,
-					},
-				]
-			: undefined;
+	const whereConditions: Array<{
+		field: string;
+		value: string | null;
+		operator: "eq";
+	}> = [];
+
+	if (params?.parentId !== undefined) {
+		whereConditions.push({
+			field: "parentId",
+			value: params.parentId,
+			operator: "eq" as const,
+		});
+	}
+
+	if (params?.tenantId !== undefined) {
+		whereConditions.push({
+			field: "tenantId",
+			value: params.tenantId,
+			operator: "eq" as const,
+		});
+	}
 
 	return adapter.findMany<Folder>({
 		model: "mediaFolder",
-		where,
+		where: whereConditions.length > 0 ? whereConditions : undefined,
 		sortBy: { field: "name", direction: "asc" },
 	});
 }
@@ -172,3 +191,35 @@ export async function getFolderById(
 		where: [{ field: "id", value: id, operator: "eq" as const }],
 	});
 }
+
+/**
+ * Find a single folder by name, optionally scoped to a specific parent and/or tenant.
+ * Pass `null` for `parentId` to search only root-level folders.
+ * Pass `undefined` for `parentId` to search regardless of parent.
+ * Returns `null` if no matching folder is found.
+ *
+ * Pure DB function — no hooks, no HTTP context.
+ * The caller is responsible for any access-control checks.
+ */
+export async function getFolderByName(
+	adapter: Adapter,
+	name: string,
+	parentId?: string | null,
+	tenantId?: string,
+): Promise<Folder | null> {
+	const where: Array<{
+		field: string;
+		value: string | null;
+		operator: "eq";
+	}> = [{ field: "name", value: name, operator: "eq" as const }];
+
+	if (parentId !== undefined) {
+		where.push({ field: "parentId", value: parentId, operator: "eq" as const });
+	}
+
+	if (tenantId !== undefined) {
+		where.push({ field: "tenantId", value: tenantId, operator: "eq" as const });
+	}
+
+	return adapter.findOne<Folder>({ model: "mediaFolder", where });
+}

package/src/plugins/media/api/index.ts

@@ -5,6 +5,7 @@ export {
 	getAssetById,
 	listFolders,
 	getFolderById,
+	getFolderByName,
 	type AssetListParams,
 	type AssetListResult,
 	type FolderListParams,

package/src/plugins/media/api/mutations.ts

@@ -12,6 +12,7 @@ export interface CreateAssetInput {
 	url: string;
 	folderId?: string;
 	alt?: string;
+	tenantId?: string;
 }
 
 /**
@@ -28,6 +29,7 @@ export interface UpdateAssetInput {
 export interface CreateFolderInput {
 	name: string;
 	parentId?: string;
+	tenantId?: string;
 }
 
 /**
@@ -51,6 +53,7 @@ export async function createAsset(
 			url: input.url,
 			folderId: input.folderId,
 			alt: input.alt,
+			tenantId: input.tenantId,
 			createdAt: new Date(),
 		},
 	});
@@ -114,6 +117,7 @@ export async function createFolder(
 		data: {
 			name: input.name,
 			parentId: input.parentId,
+			tenantId: input.tenantId,
 			createdAt: new Date(),
 		},
 	});

package/src/plugins/media/api/plugin.ts

@@ -15,6 +15,7 @@ import {
 	getAssetById,
 	listFolders,
 	getFolderById,
+	getFolderByName,
 } from "./getters";
 import {
 	createAsset,
@@ -187,6 +188,26 @@ export interface MediaBackendConfig {
 	 * Optional lifecycle hooks for the media backend plugin.
 	 */
 	hooks?: MediaBackendHooks;
+
+	/**
+	 * Optional function to resolve a tenant ID from the incoming request context.
+	 *
+	 * When provided, all asset and folder list/create operations through the HTTP
+	 * API are automatically scoped to the returned tenant ID:
+	 * - GET /media/assets  →  filters results to the resolved tenant
+	 * - POST /media/assets →  tags the created asset with the resolved tenant
+	 * - POST /media/upload →  tags the uploaded asset with the resolved tenant
+	 * - GET /media/folders →  filters results to the resolved tenant
+	 * - POST /media/folders → tags the created folder with the resolved tenant
+	 *
+	 * When absent, no tenant filtering is applied (existing behaviour).
+	 *
+	 * Returning `null` or `undefined` means "no tenant" for this request —
+	 * the operation proceeds without tenant scoping (useful for super-admin routes).
+	 */
+	resolveTenantId?: (
+		context: MediaApiContext,
+	) => Promise<string | null | undefined> | string | null | undefined;
 }
 
 /**
@@ -222,6 +243,11 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 			listFolders: (params?: Parameters<typeof listFolders>[1]) =>
 				listFolders(adapter, params),
 			getFolderById: (id: string) => getFolderById(adapter, id),
+			getFolderByName: (
+				name: string,
+				parentId?: string | null,
+				tenantId?: string,
+			) => getFolderByName(adapter, name, parentId, tenantId),
 		}),
 
 		routes: (adapter: Adapter) => {
@@ -231,6 +257,7 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 				allowedMimeTypes,
 				allowedUrlPrefixes,
 				hooks,
+				resolveTenantId,
 			} = config;
 
 			function validateMimeType(mimeType: string, ctx: { error: Function }) {
@@ -261,6 +288,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 					const { query, headers } = ctx;
 					const context: MediaApiContext = { query, headers };
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeListAssets) {
 						await runHookWithShim(
 							() => hooks.onBeforeListAssets!(query, context),
@@ -269,7 +300,7 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						);
 					}
 
-					return listAssets(adapter, query);
+					return listAssets(adapter, { ...query, tenantId });
 				},
 			);
 
@@ -285,6 +316,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeUpload) {
 						await runHookWithShim(
 							() =>
@@ -354,9 +389,12 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						if (!folder) {
 							throw ctx.error(404, { message: "Folder not found" });
 						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
 					}
 
-					const asset = await createAsset(adapter, ctx.body);
+					const asset = await createAsset(adapter, { ...ctx.body, tenantId });
 
 					if (hooks?.onAfterUpload) {
 						await hooks.onAfterUpload(asset, context);
@@ -384,6 +422,14 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
+					if (tenantId !== undefined && existing.tenantId !== tenantId) {
+						throw ctx.error(404, { message: "Asset not found" });
+					}
+
 					if (hooks?.onBeforeUpdateAsset) {
 						await runHookWithShim(
 							() => hooks.onBeforeUpdateAsset!(existing, ctx.body, context),
@@ -397,6 +443,9 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						if (!folder) {
 							throw ctx.error(404, { message: "Folder not found" });
 						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
 					}
 
 					const updated = await updateAsset(adapter, ctx.params.id, ctx.body);
@@ -419,11 +468,19 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					const asset = await getAssetById(adapter, ctx.params.id);
 					if (!asset) {
 						throw ctx.error(404, { message: "Asset not found" });
 					}
 
+					if (tenantId !== undefined && asset.tenantId !== tenantId) {
+						throw ctx.error(404, { message: "Asset not found" });
+					}
+
 					if (hooks?.onBeforeDelete) {
 						await runHookWithShim(
 							() => hooks.onBeforeDelete!(asset, context),
@@ -475,6 +532,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeListFolders) {
 						await runHookWithShim(
 							() => hooks.onBeforeListFolders!(filter, context),
@@ -483,7 +544,7 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						);
 					}
 
-					return listFolders(adapter, filter);
+					return listFolders(adapter, { ...filter, tenantId });
 				},
 			);
 
@@ -499,6 +560,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeCreateFolder) {
 						await runHookWithShim(
 							() => hooks.onBeforeCreateFolder!(ctx.body, context),
@@ -507,7 +572,17 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						);
 					}
 
-					return createFolder(adapter, ctx.body);
+					if (ctx.body.parentId) {
+						const folder = await getFolderById(adapter, ctx.body.parentId);
+						if (!folder) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
+					}
+
+					return createFolder(adapter, { ...ctx.body, tenantId });
 				},
 			);
 
@@ -517,15 +592,23 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 					method: "DELETE",
 				},
 				async (ctx) => {
+					const context: MediaApiContext = {
+						params: ctx.params,
+						headers: ctx.headers,
+					};
+
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					const folder = await getFolderById(adapter, ctx.params.id);
 					if (!folder) {
 						throw ctx.error(404, { message: "Folder not found" });
 					}
 
-					const context: MediaApiContext = {
-						params: ctx.params,
-						headers: ctx.headers,
-					};
+					if (tenantId !== undefined && folder.tenantId !== tenantId) {
+						throw ctx.error(404, { message: "Folder not found" });
+					}
 
 					if (hooks?.onBeforeDeleteFolder) {
 						await runHookWithShim(
@@ -625,6 +708,10 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 
 					const context: MediaApiContext = { headers: ctx.headers };
 
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeUpload) {
 						await runHookWithShim(
 							() =>
@@ -660,6 +747,9 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						if (!folder) {
 							throw ctx.error(404, { message: "Folder not found" });
 						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
 					}
 
 					const { url } = await storageAdapter.upload(buffer, {
@@ -680,6 +770,7 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 							size: file.size,
 							url,
 							folderId,
+							tenantId,
 						});
 					} catch (err) {
 						try {
@@ -721,6 +812,13 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 						headers: ctx.headers,
 					};
 
+					// Resolve tenant for auth checks and folder ownership validation.
+					// The token response does not embed tenantId — the follow-up POST /media/assets
+					// call tags the asset automatically via resolveTenantId.
+					const tenantId = resolveTenantId
+						? ((await resolveTenantId(context)) ?? undefined)
+						: undefined;
+
 					if (hooks?.onBeforeUpload) {
 						await runHookWithShim(
 							() =>
@@ -753,6 +851,9 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 								message: "Folder not found",
 							});
 						}
+						if (tenantId !== undefined && folder.tenantId !== tenantId) {
+							throw ctx.error(404, { message: "Folder not found" });
+						}
 						folderId = folder.id;
 					}
 					const filename = sanitizeS3KeySegment(ctx.body.filename);
@@ -782,6 +883,13 @@ export const mediaBackendPlugin = (config: MediaBackendConfig) =>
 
 					const context: MediaApiContext = { headers: ctx.headers };
 
+					// Resolve tenant for hook side-effects (e.g. auth checks). The token
+					// response does not embed tenantId — the follow-up POST /media/assets
+					// call tags the asset automatically via resolveTenantId.
+					if (resolveTenantId) {
+						await resolveTenantId(context);
+					}
+
 					if (!ctx.request) {
 						throw ctx.error(400, {
 							message: "Request object is not available",

package/src/plugins/media/db.ts

@@ -40,6 +40,10 @@ export const mediaSchema = createDbPlugin("media", {
 				type: "string",
 				required: false,
 			},
+			tenantId: {
+				type: "string",
+				required: false,
+			},
 			createdAt: {
 				type: "date",
 				defaultValue: () => new Date(),
@@ -61,6 +65,10 @@ export const mediaSchema = createDbPlugin("media", {
 					field: "id",
 				},
 			},
+			tenantId: {
+				type: "string",
+				required: false,
+			},
 			createdAt: {
 				type: "date",
 				defaultValue: () => new Date(),