@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

package/src/plugins/media/api/query-key-defs.ts

@@ -5,6 +5,50 @@
  */
 
 import type { AssetListParams } from "./getters";
+import type { StackIdentity } from "@btst/stack/context";
+
+/** Identity-aware partition used by protected Media browser and SSR queries. */
+export type MediaIdentityPartition =
+	| StackIdentity
+	| `pending:${number}`
+	| `error:${number}`;
+
+/** Resolved Media service location that partitions shared React Query caches. */
+export interface MediaEndpointPartition {
+	/** Absolute origin of the resolved Media API. */
+	baseURL: string;
+	/** Path where the resolved Media API is mounted. */
+	basePath: string;
+}
+
+/** Stable structured endpoint discriminator used in Media query keys. */
+export function mediaEndpointDiscriminator(
+	endpoint: MediaEndpointPartition,
+): MediaEndpointPartition {
+	return {
+		baseURL: endpoint.baseURL,
+		basePath: endpoint.basePath,
+	};
+}
+
+/** Identity and endpoint scope shared by Media browser, SSR, and SSG keys. */
+export interface MediaQueryScope {
+	/** Optional identity partition for protected Media data. */
+	identity?: MediaIdentityPartition;
+	/** Browser-safe resolved Media service location. */
+	endpoint: MediaEndpointPartition;
+}
+
+/** Creates the browser-safe scope cell appended to Media list query keys. */
+export function mediaQueryScope(
+	identityPartition: MediaIdentityPartition | undefined,
+	endpoint: MediaEndpointPartition,
+): MediaQueryScope {
+	return {
+		...(identityPartition === undefined ? {} : { identity: identityPartition }),
+		endpoint: mediaEndpointDiscriminator(endpoint),
+	};
+}
 
 /**
  * Discriminator for the asset list cache key.
@@ -40,11 +84,29 @@ export function folderListDiscriminator(
 
 /** Full query key builders — use these with `queryClient.setQueryData()`. */
 export const MEDIA_QUERY_KEYS = {
-	assetsList: (params?: AssetListParams) =>
-		["mediaAssets", "list", assetListDiscriminator(params)] as const,
+	assetsList: (
+		params: AssetListParams | undefined,
+		identityPartition: MediaIdentityPartition | undefined,
+		endpoint: MediaEndpointPartition,
+	) =>
+		[
+			"mediaAssets",
+			"list",
+			assetListDiscriminator(params),
+			mediaQueryScope(identityPartition, endpoint),
+		] as const,
 
 	assetDetail: (id: string) => ["mediaAssets", "detail", id] as const,
 
-	foldersList: (parentId?: string | null) =>
-		["mediaFolders", "list", folderListDiscriminator(parentId)] as const,
+	foldersList: (
+		parentId: string | null | undefined,
+		identityPartition: MediaIdentityPartition | undefined,
+		endpoint: MediaEndpointPartition,
+	) =>
+		[
+			"mediaFolders",
+			"list",
+			folderListDiscriminator(parentId),
+			mediaQueryScope(identityPartition, endpoint),
+		] as const,
 };

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

@@ -10,8 +10,9 @@ import type {
  * Pure function — no DB access, no hooks.
  */
 export function serializeAsset(asset: Asset): SerializedAsset {
+	const { updatedAt: _updatedAt, ...value } = asset;
 	return {
-		...asset,
+		...value,
 		createdAt: asset.createdAt.toISOString(),
 	};
 }
@@ -21,8 +22,9 @@ export function serializeAsset(asset: Asset): SerializedAsset {
  * Pure function — no DB access, no hooks.
  */
 export function serializeFolder(folder: Folder): SerializedFolder {
+	const { updatedAt: _updatedAt, ...value } = folder;
 	return {
-		...folder,
+		...value,
 		createdAt: folder.createdAt.toISOString(),
 	};
 }

package/src/plugins/media/api/storage-adapter.ts

@@ -70,6 +70,8 @@ export interface VercelBlobTokenOptions {
 	addRandomSuffix?: boolean;
 	allowedContentTypes?: string[];
 	maximumSizeInBytes?: number;
+	/** Server-normalized upload context bound into the signed client token. */
+	tokenPayload?: string;
 }
 
 /**
@@ -79,7 +81,6 @@ export interface VercelBlobTokenOptions {
 export interface VercelBlobCallbackBlob {
 	url: string;
 	pathname: string;
-	[key: string]: unknown;
 }
 
 export interface VercelBlobGenerateClientTokenBody {
@@ -88,6 +89,7 @@ export interface VercelBlobGenerateClientTokenBody {
 		pathname: string;
 		multipart: boolean;
 		clientPayload: string | null;
+		callbackUrl?: string;
 	};
 }
 
@@ -118,6 +120,15 @@ export interface VercelBlobHandlerCallbacks {
 	) => Promise<VercelBlobTokenOptions | void> | VercelBlobTokenOptions | void;
 }
 
+/** Provider-verified upload context carried by a completion callback. */
+export interface VerifiedVercelBlobCallback {
+	pathname: string;
+	mimeType: string;
+	size?: number;
+	folderId?: string;
+	tenantId?: string;
+}
+
 /**
  * Vercel Blob storage adapter — uses the `@vercel/blob/client` `handleUpload`
  * protocol. The same endpoint handles both token generation and upload
@@ -132,9 +143,16 @@ export interface VercelBlobStorageAdapter {
 	 */
 	readonly urlHostnameSuffix: string;
 	/**
-	 * Process a raw request from `@vercel/blob/client`'s `upload()` or from
-	 * Vercel Blob's upload-completion webhook. Returns a JSON-serialisable object
-	 * that should be sent back as the response body.
+	 * Verify the provider signature and parse only server-issued token context.
+	 * This runs before a completion callback is allowed onto a public auth path.
+	 */
+	verifyCallback(
+		request: Request,
+		body: VercelBlobUploadCompletedBody,
+	): Promise<VerifiedVercelBlobCallback>;
+	/**
+	 * Process a client-token request or Vercel Blob's upload-completion webhook.
+	 * Returns a JSON-serialisable object that should be sent as the response body.
 	 */
 	handleRequest(
 		request: Request,

package/src/plugins/media/asset-url.ts

@@ -0,0 +1,14 @@
+import type { SerializedAsset } from "./types";
+
+export function resolveMediaAsset(
+	asset: SerializedAsset,
+	apiBaseURL: string | undefined,
+): SerializedAsset {
+	if (!apiBaseURL) return asset;
+	try {
+		const url = new URL(asset.url, apiBaseURL).href;
+		return url === asset.url ? asset : { ...asset, url };
+	} catch {
+		return asset;
+	}
+}

package/src/plugins/media/client/components/media-picker/asset-card.tsx

@@ -3,8 +3,14 @@ import type { SerializedAsset } from "../../../types";
 import { cn } from "@workspace/ui/lib/utils";
 import { File, Check, Copy, Trash2 } from "lucide-react";
 import { isImage, formatBytes } from "./utils";
-import { useCan, useNotify, useStack, useTranslate } from "@btst/stack/context";
+import {
+	PermissionAccess,
+	useNotify,
+	useStack,
+	useTranslate,
+} from "@btst/stack/context";
 import { AssetPreviewButton } from "./asset-preview-button";
+import { mediaPermissions } from "../../../permissions";
 
 export function AssetCard({
 	asset,
@@ -20,15 +26,15 @@ export function AssetCard({
 	const t = useTranslate();
 	const notify = useNotify();
 	const { mutateAsync: deleteAsset } = useDeleteAsset();
-	const { can: canDelete } = useCan({
-		resource: "media:asset",
-		action: "delete",
-		params: { id: asset.id },
-	});
 	const { api, router } = useStack();
 	const ImageComponent = router?.Image;
 	const imageAsset = isImage(asset.mimeType);
 	const selectable = typeof onToggle === "function";
+	const facts = {
+		assetId: asset.id,
+		...(asset.folderId ? { folderId: asset.folderId } : {}),
+		mimeType: asset.mimeType,
+	};
 
 	const copyUrl = async () => {
 		let fullUrl: string;
@@ -46,7 +52,6 @@ export function AssetCard({
 	};
 
 	const handleDelete = async () => {
-		if (!canDelete) return;
 		if (onDelete) {
 			await onDelete(asset.id);
 			return;
@@ -73,101 +78,103 @@ export function AssetCard({
 	};
 
 	return (
-		<div
-			role={selectable ? "button" : undefined}
-			tabIndex={selectable ? 0 : undefined}
-			data-testid="media-asset-item"
-			onClick={onToggle}
-			onKeyDown={(e) => {
-				if (selectable && (e.key === "Enter" || e.key === " ")) {
-					e.preventDefault();
-					onToggle();
-				}
-			}}
-			className={cn(
-				"group relative cursor-pointer rounded-md border bg-muted/30 p-1 transition-all hover:border-ring hover:shadow-sm",
-				!selectable && "cursor-default",
-				selected && "border-ring ring-1 ring-ring",
-			)}
-		>
-			{/* Thumbnail */}
-			<div className="flex h-28 items-center justify-center overflow-hidden rounded bg-muted">
-				{imageAsset ? (
-					ImageComponent ? (
-						<ImageComponent
-							src={asset.url}
-							alt={asset.alt || asset.originalName}
-							className="h-full w-full object-cover"
-							width={160}
-							height={80}
-						/>
-					) : (
-						<img
-							src={asset.url}
-							alt={asset.alt || asset.originalName}
-							className="h-full w-full object-cover"
-							loading="lazy"
-						/>
-					)
-				) : (
-					<File className="size-8 text-muted-foreground" />
+		<PermissionAccess permission={mediaPermissions.asset.read(facts)}>
+			<div
+				role={selectable ? "button" : undefined}
+				tabIndex={selectable ? 0 : undefined}
+				data-testid="media-asset-item"
+				onClick={onToggle}
+				onKeyDown={(e) => {
+					if (selectable && (e.key === "Enter" || e.key === " ")) {
+						e.preventDefault();
+						onToggle();
+					}
+				}}
+				className={cn(
+					"group relative cursor-pointer rounded-md border bg-muted/30 p-1 transition-all hover:border-ring hover:shadow-sm",
+					!selectable && "cursor-default",
+					selected && "border-ring ring-1 ring-ring",
 				)}
-			</div>
-
-			{/* Name + size */}
-			<div className="mt-1 px-0.5">
-				<p
-					className="truncate text-xs font-medium leading-tight"
-					title={asset.originalName}
-				>
-					{asset.originalName}
-				</p>
-				<p className="text-[10px] text-muted-foreground">
-					{formatBytes(asset.size)}
-				</p>
-			</div>
-
-			{/* Selection indicator */}
-			{selected && (
-				<div className="absolute right-1 top-1 rounded-full bg-primary p-0.5 text-primary-foreground">
-					<Check className="size-3" />
+			>
+				{/* Thumbnail */}
+				<div className="flex h-28 items-center justify-center overflow-hidden rounded bg-muted">
+					{imageAsset ? (
+						ImageComponent ? (
+							<ImageComponent
+								src={asset.url}
+								alt={asset.alt || asset.originalName}
+								className="h-full w-full object-cover"
+								width={160}
+								height={80}
+							/>
+						) : (
+							<img
+								src={asset.url}
+								alt={asset.alt || asset.originalName}
+								className="h-full w-full object-cover"
+								loading="lazy"
+							/>
+						)
+					) : (
+						<File className="size-8 text-muted-foreground" />
+					)}
 				</div>
-			)}
 
-			<div className="absolute right-1 top-1 hidden gap-1 group-hover:flex">
-				{api?.baseURL ? (
-					<button
-						type="button"
-						title={t("media.actions.copyUrl", "Copy URL")}
-						onClick={(e) => {
-							e.stopPropagation();
-							void copyUrl();
-						}}
-						className="rounded bg-background/80 p-0.5 shadow hover:bg-background"
-					>
-						<Copy className="size-3" />
-					</button>
-				) : null}
-				{imageAsset ? (
-					<AssetPreviewButton
-						asset={asset}
-						className="rounded bg-background/80 p-0.5 shadow hover:bg-background"
-					/>
-				) : null}
-				{canDelete ? (
-					<button
-						type="button"
-						title={t("media.actions.delete", "Delete")}
-						onClick={(e) => {
-							e.stopPropagation();
-							void handleDelete();
-						}}
-						className="rounded bg-destructive/80 p-0.5 text-white hover:bg-destructive"
+				{/* Name + size */}
+				<div className="mt-1 px-0.5">
+					<p
+						className="truncate text-xs font-medium leading-tight"
+						title={asset.originalName}
 					>
-						<Trash2 className="size-3" />
-					</button>
-				) : null}
+						{asset.originalName}
+					</p>
+					<p className="text-[10px] text-muted-foreground">
+						{formatBytes(asset.size)}
+					</p>
+				</div>
+
+				{/* Selection indicator */}
+				{selected && (
+					<div className="absolute right-1 top-1 rounded-full bg-primary p-0.5 text-primary-foreground">
+						<Check className="size-3" />
+					</div>
+				)}
+
+				<div className="absolute right-1 top-1 hidden gap-1 group-hover:flex">
+					{api?.baseURL ? (
+						<button
+							type="button"
+							title={t("media.actions.copyUrl", "Copy URL")}
+							onClick={(e) => {
+								e.stopPropagation();
+								void copyUrl();
+							}}
+							className="rounded bg-background/80 p-0.5 shadow hover:bg-background"
+						>
+							<Copy className="size-3" />
+						</button>
+					) : null}
+					{imageAsset ? (
+						<AssetPreviewButton
+							asset={asset}
+							className="rounded bg-background/80 p-0.5 shadow hover:bg-background"
+						/>
+					) : null}
+					<PermissionAccess permission={mediaPermissions.asset.delete(facts)}>
+						<button
+							type="button"
+							title={t("media.actions.delete", "Delete")}
+							onClick={(e) => {
+								e.stopPropagation();
+								void handleDelete();
+							}}
+							className="rounded bg-destructive/80 p-0.5 text-white hover:bg-destructive"
+						>
+							<Trash2 className="size-3" />
+						</button>
+					</PermissionAccess>
+				</div>
 			</div>
-		</div>
+		</PermissionAccess>
 	);
 }

package/src/plugins/media/client/components/media-picker/folder-tree.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import {
 	useFolders,
 	useDeleteFolder,
@@ -9,7 +9,8 @@ import { FolderPlus } from "lucide-react";
 import { Input } from "@workspace/ui/components/input";
 import { Check, Folder, Trash2, ChevronRight, FolderOpen } from "lucide-react";
 import { cn } from "@workspace/ui/lib/utils";
-import { useCan, useNotify, useTranslate } from "@btst/stack/context";
+import { PermissionAccess, useNotify, useTranslate } from "@btst/stack/context";
+import { mediaPermissions } from "../../../permissions";
 
 export function FolderTree({
 	selectedId,
@@ -20,20 +21,27 @@ export function FolderTree({
 }) {
 	const t = useTranslate();
 	const notify = useNotify();
-	const { data: rootFoldersRaw = [] } = useFolders(null);
-	const rootFolders =
-		rootFoldersRaw as import("../../../types").SerializedFolder[];
+	const { data: foldersRaw = [] } = useFolders();
+	const folders = foldersRaw as import("../../../types").SerializedFolder[];
+	const { foldersById, foldersByParent } = useMemo(() => {
+		const byId = new Map<string, SerializedFolder>();
+		const byParent = new Map<string | null, SerializedFolder[]>();
+		for (const folder of folders) {
+			byId.set(folder.id, folder);
+			const parentId = folder.parentId ?? null;
+			const siblings = byParent.get(parentId) ?? [];
+			siblings.push(folder);
+			byParent.set(parentId, siblings);
+		}
+		return { foldersById: byId, foldersByParent: byParent };
+	}, [folders]);
+	const rootFolders = foldersByParent.get(null) ?? [];
+	const selectedFolder = selectedId ? foldersById.get(selectedId) : undefined;
 	const [newFolderName, setNewFolderName] = useState("");
 	const [isCreating, setIsCreating] = useState(false);
 	const { mutateAsync: deleteFolder } = useDeleteFolder();
-	const { can: canCreateFolder } = useCan({
-		resource: "media:folder",
-		action: "create",
-	});
-	const { can: canDeleteFolder } = useCan({
-		resource: "media:folder",
-		action: "delete",
-		params: selectedId ? { id: selectedId } : undefined,
+	const createPermission = mediaPermissions.folder.create({
+		...(selectedId ? { parentId: selectedId } : {}),
 	});
 	const createFolderForm = useCreateFolderForm({
 		parentId: selectedId ?? undefined,
@@ -44,14 +52,13 @@ export function FolderTree({
 	});
 
 	const handleCreateFolder = async () => {
-		if (!canCreateFolder) return;
 		const name = newFolderName.trim();
 		if (!name) return;
 		await createFolderForm.submit({ name });
 	};
 
 	const handleDeleteFolder = async () => {
-		if (!selectedId || !canDeleteFolder) return;
+		if (!selectedId) return;
 		if (
 			!confirm(
 				t(
@@ -80,7 +87,7 @@ export function FolderTree({
 				<span className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
 					{t("media.folders.title", "Folders")}
 				</span>
-				{canCreateFolder ? (
+				<PermissionAccess permission={createPermission}>
 					<button
 						type="button"
 						title={t("media.folders.new", "New folder")}
@@ -89,40 +96,42 @@ export function FolderTree({
 					>
 						<FolderPlus className="size-3.5 text-muted-foreground" />
 					</button>
-				) : null}
+				</PermissionAccess>
 			</div>
 
-			{isCreating && canCreateFolder && (
-				<div className="flex gap-1 px-2 pb-1">
-					<Input
-						autoFocus
-						value={newFolderName}
-						onChange={(e) => {
-							setNewFolderName(e.target.value);
-							createFolderForm.clearErrors();
-						}}
-						placeholder={t("media.folders.namePlaceholder", "Folder name")}
-						className="h-6 text-xs"
-						onKeyDown={(e) => {
-							if (e.key === "Enter") void handleCreateFolder();
-							if (e.key === "Escape") setIsCreating(false);
-						}}
-					/>
-					<button
-						type="button"
-						onClick={handleCreateFolder}
-						disabled={createFolderForm.isSubmitting || !newFolderName.trim()}
-						title={t("media.folders.create", "Create folder")}
-						className="rounded px-1 py-0.5 text-xs hover:bg-muted"
-					>
-						<Check className="size-3" />
-					</button>
-					{createFolderForm.fieldErrors.name ? (
-						<p className="text-xs text-destructive">
-							{String(createFolderForm.fieldErrors.name)}
-						</p>
-					) : null}
-				</div>
+			{isCreating && (
+				<PermissionAccess permission={createPermission}>
+					<div className="flex gap-1 px-2 pb-1">
+						<Input
+							autoFocus
+							value={newFolderName}
+							onChange={(e) => {
+								setNewFolderName(e.target.value);
+								createFolderForm.clearErrors();
+							}}
+							placeholder={t("media.folders.namePlaceholder", "Folder name")}
+							className="h-6 text-xs"
+							onKeyDown={(e) => {
+								if (e.key === "Enter") void handleCreateFolder();
+								if (e.key === "Escape") setIsCreating(false);
+							}}
+						/>
+						<button
+							type="button"
+							onClick={handleCreateFolder}
+							disabled={createFolderForm.isSubmitting || !newFolderName.trim()}
+							title={t("media.folders.create", "Create folder")}
+							className="rounded px-1 py-0.5 text-xs hover:bg-muted"
+						>
+							<Check className="size-3" />
+						</button>
+						{createFolderForm.fieldErrors.name ? (
+							<p className="text-xs text-destructive">
+								{String(createFolderForm.fieldErrors.name)}
+							</p>
+						) : null}
+					</div>
+				</PermissionAccess>
 			)}
 
 			<div className="flex-1 overflow-y-auto overscroll-contain">
@@ -146,23 +155,33 @@ export function FolderTree({
 					<FolderTreeItem
 						key={folder.id}
 						folder={folder}
+						foldersByParent={foldersByParent}
 						selectedId={selectedId}
 						onSelect={onSelect}
 					/>
 				))}
 			</div>
 
-			{selectedId && canDeleteFolder && (
-				<div className="border-t px-2 py-1">
-					<button
-						type="button"
-						onClick={() => void handleDeleteFolder()}
-						className="flex items-center gap-1 text-xs text-destructive hover:underline"
-					>
-						<Trash2 className="size-3" />
-						{t("media.folders.delete", "Delete folder")}
-					</button>
-				</div>
+			{selectedId && selectedFolder && (
+				<PermissionAccess
+					permission={mediaPermissions.folder.delete({
+						folderId: selectedId,
+						...(selectedFolder.parentId
+							? { parentId: selectedFolder.parentId }
+							: {}),
+					})}
+				>
+					<div className="border-t px-2 py-1">
+						<button
+							type="button"
+							onClick={() => void handleDeleteFolder()}
+							className="flex items-center gap-1 text-xs text-destructive hover:underline"
+						>
+							<Trash2 className="size-3" />
+							{t("media.folders.delete", "Delete folder")}
+						</button>
+					</div>
+				</PermissionAccess>
 			)}
 		</div>
 	);
@@ -170,17 +189,19 @@ export function FolderTree({
 
 export function FolderTreeItem({
 	folder,
+	foldersByParent,
 	selectedId,
 	onSelect,
 	depth = 0,
 }: {
 	folder: SerializedFolder;
+	foldersByParent: ReadonlyMap<string | null, readonly SerializedFolder[]>;
 	selectedId: string | null;
 	onSelect: (id: string | null) => void;
 	depth?: number;
 }) {
 	const [expanded, setExpanded] = useState(false);
-	const { data: children = [] } = useFolders(folder.id);
+	const children = foldersByParent.get(folder.id) ?? [];
 
 	return (
 		<div>
@@ -218,6 +239,7 @@ export function FolderTreeItem({
 					<FolderTreeItem
 						key={child.id}
 						folder={child}
+						foldersByParent={foldersByParent}
 						selectedId={selectedId}
 						onSelect={onSelect}
 						depth={depth + 1}