@od-oneapp/storage 2026.1.1301

package/src/actions/mediaActions.ts

@@ -0,0 +1,1071 @@
+/**
+ * @fileoverview Media storage server actions
+ *
+ * Provides Next.js server actions for media file operations including upload,
+ * download, delete, move, and list operations with authentication and validation.
+ *
+ * Features:
+ * - Authentication and authorization
+ * - Rate limiting
+ * - File validation (size, MIME type)
+ * - SSRF protection
+ * - Bulk operations
+ *
+ * @module @repo/storage/actions/mediaActions
+ */
+
+'use server';
+
+import { safeEnv } from '../../env';
+import { validateStorageKey } from '../../keys';
+import { checkRateLimit, getClientIP, getSession } from '../auth-helpers';
+import { STORAGE_CONSTANTS } from '../constants';
+import { getMultiStorage, getStorage } from '../server';
+import { validateMimeType, validateUrlForSSRF } from '../validation';
+
+import type {
+  BulkDeleteResponse,
+  BulkMoveResponse,
+  ListOptions,
+  MediaActionResponse,
+  StorageObject,
+  UploadOptions,
+} from '../../types';
+
+//==============================================================================
+// MEDIA STORAGE SERVER ACTIONS
+//==============================================================================
+
+/**
+ * Upload binary data to the configured storage provider with optional validations.
+ *
+ * Validations performed before upload include storage key safety checks, optional
+ * authentication and rate limiting, maximum file size enforcement, and MIME type
+ * validation when `options.allowedMimeTypes` and `options.contentType` are provided.
+ *
+ * @param key - Destination storage key (path) where the file will be stored
+ * @param data - File contents to upload (Buffer, ArrayBuffer, Blob, File, or ReadableStream)
+ * @param options - Upload options and validation overrides. Notable fields:
+ * - `maxFileSize` — override maximum allowed file size in bytes for this upload
+ * - `allowedMimeTypes` — list of permitted MIME types; validated against `options.contentType` if present
+ * - other provider-specific upload options (e.g., `contentType`, `metadata`) are passed through to the storage provider
+ * @returns An object with `success: true` and the uploaded `StorageObject` on success, or `success: false` and an `error` message on failure
+ */
+export async function uploadMediaAction(
+  key: string,
+  data: ArrayBuffer | Blob | Buffer | File | ReadableStream,
+  options?: UploadOptions & {
+    maxFileSize?: number;
+    allowedMimeTypes?: string[];
+  },
+): Promise<MediaActionResponse<StorageObject>> {
+  'use server';
+
+  // Get environment configuration once
+  const storageEnv = safeEnv();
+
+  // Authentication check (configurable)
+  const session = await getSession();
+  if (storageEnv.STORAGE_ENFORCE_AUTH && !session?.user) {
+    return {
+      success: false,
+      error: 'Unauthorized: Authentication required',
+    };
+  }
+
+  // Rate limiting
+  const identifier = session?.user?.id ?? getClientIP();
+  const rateLimitResult = await checkRateLimit(
+    identifier,
+    'storage:upload',
+    storageEnv.STORAGE_RATE_LIMIT_REQUESTS,
+    storageEnv.STORAGE_RATE_LIMIT_WINDOW_MS,
+  );
+  if (storageEnv.STORAGE_ENABLE_RATE_LIMIT && !rateLimitResult.allowed) {
+    return {
+      success: false,
+      error: 'Rate limit exceeded. Please try again later.',
+    };
+  }
+
+  try {
+    // Validate storage key to prevent path traversal
+    const keyValidation = validateStorageKey(key, {
+      maxLength: 1024,
+      forbiddenPatterns: [/\.\./, /\/\//],
+    });
+    if (!keyValidation.valid) {
+      return {
+        success: false,
+        error: `Invalid storage key: ${keyValidation.errors.join(', ')}`,
+      };
+    }
+
+    // Validate file size
+    const maxSize = options?.maxFileSize ?? storageEnv.STORAGE_MAX_FILE_SIZE;
+    let fileSize = 0;
+
+    if (data instanceof File || data instanceof Blob) {
+      fileSize = data.size;
+    } else if (data instanceof ArrayBuffer) {
+      fileSize = data.byteLength;
+    } else if (data instanceof Buffer) {
+      fileSize = data.length;
+    }
+
+    if (fileSize > maxSize) {
+      return {
+        success: false,
+        error: `File size ${fileSize} bytes exceeds maximum ${maxSize} bytes`,
+      };
+    }
+
+    // Validate MIME type if restrictions provided
+    if (options?.allowedMimeTypes && options.contentType) {
+      const mimeValidation = validateMimeType(options.contentType, options.allowedMimeTypes);
+      if (!mimeValidation.valid) {
+        return {
+          success: false,
+          error: mimeValidation.error ?? 'Invalid file type',
+        };
+      }
+    }
+
+    const result = await getStorage().upload(key, data, options);
+    return { success: true, data: result };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to upload media',
+    };
+  }
+}
+
+/**
+ * Get media file metadata
+ */
+export async function getMediaAction(key: string): Promise<MediaActionResponse<StorageObject>> {
+  'use server';
+  try {
+    const metadata = await getStorage().getMetadata(key);
+    return { success: true, data: metadata };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to get media metadata',
+    };
+  }
+}
+
+/**
+ * List media files
+ */
+export async function listMediaAction(
+  options?: ListOptions,
+): Promise<MediaActionResponse<StorageObject[]>> {
+  'use server';
+  try {
+    const items = await getStorage().list(options);
+    return { success: true, data: items };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to list media',
+    };
+  }
+}
+
+/**
+ * Delete a media file
+ */
+export async function deleteMediaAction(key: string): Promise<MediaActionResponse<void>> {
+  'use server';
+  try {
+    await getStorage().delete(key);
+    return { success: true };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to delete media',
+    };
+  }
+}
+
+/**
+ * Determine whether a media object exists at the given storage key.
+ *
+ * @param key - The storage key (path) of the media object to check
+ * @returns A response object whose `data` is `true` if the object exists, `false` otherwise. On error the response will have `success: false` and an `error` message
+ */
+export async function existsMediaAction(key: string): Promise<MediaActionResponse<boolean>> {
+  'use server';
+  try {
+    const exists = await getStorage().exists(key);
+    return { success: true, data: exists };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to check media existence',
+    };
+  }
+}
+
+/**
+ * Retrieve a public or signed URL for a media object.
+ *
+ * When the context is `product`, when `forceSign` is true, or when `expiresIn` is provided,
+ * a signed URL is returned using the specified or default expiry; otherwise a direct URL is returned.
+ *
+ * @param key - The storage key of the media object
+ * @param options.expiresIn - Expiration time in seconds for a signed URL
+ * @param options.context - Context of the media; `product` forces signed URLs for product photos
+ * @param options.forceSign - When true, force generation of a signed URL regardless of context
+ * @returns The URL for the storage key (signed if signing rules apply)
+ */
+export async function getMediaUrlAction(
+  key: string,
+  options?: {
+    expiresIn?: number;
+    context?: 'product' | 'user' | 'admin' | 'public';
+    forceSign?: boolean;
+  },
+): Promise<MediaActionResponse<string>> {
+  'use server';
+  try {
+    const storage = getStorage();
+
+    // Product photos always need signed URLs for protection
+    const isProductPhoto = options?.context === 'product' || key.includes('/products/');
+    const shouldSign = (isProductPhoto || options?.forceSign) ?? Boolean(options?.expiresIn);
+
+    if (shouldSign) {
+      const expiresIn =
+        options?.expiresIn ??
+        (isProductPhoto
+          ? STORAGE_CONSTANTS.PRODUCT_URL_EXPIRY_SECONDS
+          : STORAGE_CONSTANTS.UPLOAD_URL_EXPIRY_SECONDS);
+      const signedUrl = await storage.getUrl(key, { expiresIn });
+      return { success: true, data: signedUrl };
+    }
+
+    // For public content, return direct URL
+    const url = await storage.getUrl(key);
+    return { success: true, data: url };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to get media URL',
+    };
+  }
+}
+
+/**
+ * Generate signed URLs for multiple product media keys.
+ *
+ * Appends the provided `variant` to keys that reference Cloudflare Images and uses
+ * `options.expiresIn` or the product URL expiry constant as the signing duration.
+ *
+ * @param keys - Array of storage keys identifying product media items
+ * @param options - Optional settings: `expiresIn` (seconds) overrides the default signed URL expiry; `variant` is appended to Cloudflare Images keys to request a specific image variant
+ * @returns A MediaActionResponse whose `data` is an array of objects with the original `key` and the generated `url` when successful; on failure the response contains an error message
+ */
+export async function getProductMediaUrlsAction(
+  keys: string[],
+  options?: { expiresIn?: number; variant?: string },
+): Promise<MediaActionResponse<Array<{ key: string; url: string }>>> {
+  'use server';
+  try {
+    const storage = getStorage();
+    const expiresIn = options?.expiresIn ?? STORAGE_CONSTANTS.PRODUCT_URL_EXPIRY_SECONDS;
+
+    const mediaWithSignedUrls = await Promise.all(
+      keys.map(async key => {
+        let finalKey = key;
+
+        // For Cloudflare Images, append variant if specified
+        if (options?.variant && key.includes('cloudflare-images')) {
+          finalKey = `${key}/${options.variant}`;
+        }
+
+        const signedUrl = await storage.getUrl(finalKey, { expiresIn });
+
+        return {
+          key,
+          url: signedUrl,
+        };
+      }),
+    );
+
+    return {
+      success: true,
+      data: mediaWithSignedUrls,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to get product media URLs',
+    };
+  }
+}
+
+/**
+ * Get presigned upload URL for product photos (admin only)
+ */
+export async function getProductUploadUrlAction(
+  filename: string,
+  productId: string,
+  options?: {
+    expiresIn?: number;
+    contentType?: string;
+    maxSizeBytes?: number;
+  },
+): Promise<MediaActionResponse<{ uploadUrl: string; key: string }>> {
+  'use server';
+  try {
+    const storage = getStorage();
+    const key = `products/${productId}/${Date.now()}-${filename}`;
+
+    // Get presigned upload URL (this would depend on the storage provider)
+    // For now, return a structure that indicates what should be implemented
+    const uploadUrl = await storage.getUrl(key, {
+      expiresIn: options?.expiresIn ?? 1800, // 30 minutes for uploads
+    });
+
+    return {
+      success: true,
+      data: {
+        uploadUrl,
+        key,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to get product upload URL',
+    };
+  }
+}
+
+/**
+ * Download a media file
+ */
+export async function downloadMediaAction(key: string): Promise<MediaActionResponse<Blob>> {
+  'use server';
+  try {
+    const blob = await getStorage().download(key);
+    return { success: true, data: blob };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to download media',
+    };
+  }
+}
+
+//==============================================================================
+// BULK OPERATIONS
+//==============================================================================
+
+/**
+ * Delete multiple media files
+ */
+export async function bulkDeleteMediaAction(
+  keys: string[],
+): Promise<MediaActionResponse<BulkDeleteResponse>> {
+  'use server';
+  const results = {
+    succeeded: [] as string[],
+    failed: [] as { key: string; error: string }[],
+  };
+
+  try {
+    // Process deletions in parallel with error handling for each
+    await Promise.all(
+      keys.map(async key => {
+        try {
+          await getStorage().delete(key);
+          results.succeeded.push(key);
+        } catch (error) {
+          results.failed.push({
+            key,
+            error: error instanceof Error ? error.message : 'Unknown error',
+          });
+        }
+      }),
+    );
+
+    return {
+      success: results.failed.length === 0,
+      data: results,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Bulk delete operation failed',
+    };
+  }
+}
+
+/**
+ * Move/rename multiple media files
+ */
+export async function bulkMoveMediaAction(
+  operations: Array<{ sourceKey: string; destinationKey: string }>,
+): Promise<MediaActionResponse<BulkMoveResponse>> {
+  'use server';
+  const results = {
+    succeeded: [] as { sourceKey: string; destinationKey: string }[],
+    failed: [] as { sourceKey: string; destinationKey: string; error: string }[],
+  };
+
+  try {
+    // Process moves in parallel
+    await Promise.all(
+      operations.map(async ({ sourceKey, destinationKey }) => {
+        try {
+          // Download the file
+          const blob = await getStorage().download(sourceKey);
+
+          // Get metadata from source
+          const metadata = await getStorage().getMetadata(sourceKey);
+
+          // Upload to new location
+          await getStorage().upload(destinationKey, blob, {
+            contentType: metadata.contentType,
+          });
+
+          // Delete the source
+          await getStorage().delete(sourceKey);
+
+          results.succeeded.push({ sourceKey, destinationKey });
+        } catch (error) {
+          results.failed.push({
+            sourceKey,
+            destinationKey,
+            error: error instanceof Error ? error.message : 'Unknown error',
+          });
+        }
+      }),
+    );
+
+    return {
+      success: results.failed.length === 0,
+      data: results,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Bulk move operation failed',
+    };
+  }
+}
+
+//==============================================================================
+// BULK IMPORT OPERATIONS
+//==============================================================================
+
+/**
+ * Imports multiple external URLs into storage, processing them in configurable batches.
+ *
+ * Each source URL is validated for safety, fetched with a per-request timeout, and streamed
+ * into the chosen storage provider (or routed to Cloudflare Images for images when available).
+ * Successful imports are recorded with their destination key and resulting StorageObject;
+ * failures record the source URL and an error message. Processing continues after individual failures.
+ *
+ * @param imports - Array of import entries, each with a required `sourceUrl`, optional `destinationKey`
+ * (if omitted a key is generated), and optional `metadata` (altText, productId, userId, type).
+ * @param options - Optional settings:
+ * - `batchSize`: number of concurrent imports per batch (defaults to STORAGE_CONSTANTS.DEFAULT_BATCH_SIZE).
+ * - `provider`: name of the storage provider to use (if omitted uses default provider or Cloudflare Images for images).
+ * - `timeout`: per-request fetch timeout in milliseconds (defaults to STORAGE_CONSTANTS.DEFAULT_REQUEST_TIMEOUT_MS).
+ * @returns An object with:
+ * - `succeeded`: array of { sourceUrl, destinationKey, storageObject } for successful imports;
+ * - `failed`: array of { sourceUrl, error } for failed imports;
+ * - `totalProcessed`: total number of import attempts processed.
+ */
+export async function bulkImportFromUrlsAction(
+  imports: Array<{
+    sourceUrl: string;
+    destinationKey?: string;
+    metadata?: {
+      altText?: string;
+      productId?: string;
+      userId?: string;
+      type?: 'IMAGE' | 'VIDEO' | 'DOCUMENT';
+    };
+  }>,
+  options?: {
+    batchSize?: number;
+    provider?: string;
+    timeout?: number;
+  },
+): Promise<
+  MediaActionResponse<{
+    succeeded: Array<{
+      sourceUrl: string;
+      destinationKey: string;
+      storageObject: StorageObject;
+    }>;
+    failed: Array<{
+      sourceUrl: string;
+      error: string;
+    }>;
+    totalProcessed: number;
+  }>
+> {
+  'use server';
+
+  const results = {
+    succeeded: [] as Array<{
+      sourceUrl: string;
+      destinationKey: string;
+      storageObject: StorageObject;
+    }>,
+    failed: [] as Array<{
+      sourceUrl: string;
+      error: string;
+    }>,
+    totalProcessed: 0,
+  };
+
+  const batchSize = options?.batchSize ?? STORAGE_CONSTANTS.DEFAULT_BATCH_SIZE;
+  const timeout = options?.timeout ?? STORAGE_CONSTANTS.DEFAULT_REQUEST_TIMEOUT_MS;
+
+  try {
+    // Process imports in batches to avoid overwhelming the system
+    for (let i = 0; i < imports.length; i += batchSize) {
+      const batch = imports.slice(i, i + batchSize);
+
+      await Promise.all(
+        batch.map(async importItem => {
+          try {
+            // Validate URL to prevent SSRF attacks
+            const urlValidation = validateUrlForSSRF(importItem.sourceUrl);
+            if (!urlValidation.valid) {
+              throw new Error(urlValidation.error ?? 'Invalid or unsafe URL');
+            }
+
+            // Fetch with timeout
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+            const response = await fetch(importItem.sourceUrl, {
+              signal: controller.signal,
+              // Add additional security headers
+              headers: {
+                'User-Agent': 'Storage-Service/1.0',
+              },
+              // Prevent redirects to internal URLs
+              redirect: 'error',
+            });
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+              throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+
+            // Get content type and determine storage provider
+            const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
+            const isImage = contentType.startsWith('image/');
+
+            // Generate destination key if not provided
+            const destinationKey =
+              importItem.destinationKey ??
+              generateStorageKey(importItem.sourceUrl, importItem.metadata);
+
+            // Stream the content to storage
+            const storage = options?.provider
+              ? getMultiStorage().getProvider(options.provider)
+              : getStorage();
+
+            if (!storage) {
+              throw new Error('Storage provider not available');
+            }
+
+            // For images, use Cloudflare Images if configured
+            if (isImage && !options?.provider) {
+              const multiStorage = getMultiStorage();
+              const imageProvider = multiStorage.getProvider('cloudflare-images');
+              if (imageProvider) {
+                // Stream to Cloudflare Images
+                const blob = await response.blob();
+                const result = await imageProvider.upload(destinationKey, blob, {
+                  contentType,
+                  metadata: importItem.metadata,
+                });
+
+                results.succeeded.push({
+                  sourceUrl: importItem.sourceUrl,
+                  destinationKey,
+                  storageObject: result,
+                });
+                results.totalProcessed++;
+                return;
+              }
+            }
+
+            // Stream to default storage (R2 or local)
+            const stream = response.body;
+            if (!stream) {
+              throw new Error('No response body available');
+            }
+
+            const result = await storage.upload(destinationKey, stream, {
+              contentType,
+              metadata: importItem.metadata,
+            });
+
+            results.succeeded.push({
+              sourceUrl: importItem.sourceUrl,
+              destinationKey,
+              storageObject: result,
+            });
+            results.totalProcessed++;
+          } catch (error) {
+            results.failed.push({
+              sourceUrl: importItem.sourceUrl,
+              error: error instanceof Error ? error.message : 'Unknown error',
+            });
+            results.totalProcessed++;
+          }
+        }),
+      );
+    }
+
+    return {
+      success: results.failed.length === 0,
+      data: results,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Bulk import operation failed',
+      data: results,
+    };
+  }
+}
+
+/**
+ * Import a single media item from a remote HTTPS URL into storage.
+ *
+ * Validates the source URL for safety, fetches the resource, and uploads it to storage.
+ * If `options.onProgress` is provided and the response exposes a `content-length`, progress
+ * updates are emitted as a fraction between 0 and 1 during download.
+ *
+ * @param sourceUrl - The HTTPS URL of the resource to import; must pass SSRF-safe validation.
+ * @param destinationKey - Optional destination storage key; generated automatically when omitted.
+ * @param options.metadata - Optional metadata to attach to the uploaded object.
+ * @param options.onProgress - Optional callback invoked with a number in [0, 1] representing download progress.
+ * @returns On success, a response containing the uploaded `StorageObject`; on failure, a response containing an error message.
+ */
+export async function importFromUrlAction(
+  sourceUrl: string,
+  destinationKey?: string,
+  options?: {
+    metadata?: Record<string, any>;
+    onProgress?: (progress: number) => void;
+  },
+): Promise<MediaActionResponse<StorageObject>> {
+  'use server';
+
+  try {
+    // Validate URL to prevent SSRF attacks
+    const urlValidation = validateUrlForSSRF(sourceUrl);
+    if (!urlValidation.valid) {
+      throw new Error(urlValidation.error ?? 'Invalid or unsafe URL');
+    }
+
+    const response = await fetch(sourceUrl, {
+      // Add additional security headers
+      headers: {
+        'User-Agent': 'Storage-Service/1.0',
+      },
+      // Prevent redirects to internal URLs
+      redirect: 'error',
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch: ${response.status} ${response.statusText}`);
+    }
+
+    const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
+    const contentLength = response.headers.get('content-length');
+
+    // Generate key if not provided
+    const key = destinationKey ?? generateStorageKey(sourceUrl);
+
+    // For progress tracking, we need to read the stream manually
+    if (options?.onProgress && contentLength && response.body) {
+      const total = parseInt(contentLength);
+      let loaded = 0;
+
+      const reader = response.body.getReader();
+      const chunks: Uint8Array[] = [];
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        chunks.push(value);
+        loaded += value.length;
+        options.onProgress(loaded / total);
+      }
+
+      // Combine chunks into a single blob
+      const blob = new Blob(
+        chunks.map(
+          chunk =>
+            chunk.buffer.slice(
+              chunk.byteOffset,
+              chunk.byteOffset + chunk.byteLength,
+            ) as ArrayBuffer,
+        ),
+        { type: contentType },
+      );
+
+      const storage = getStorage();
+      const result = await storage.upload(key, blob, {
+        contentType,
+        metadata: options.metadata,
+      });
+
+      return { success: true, data: result };
+    } else {
+      // Simple stream without progress
+      const storage = getStorage();
+      const stream = response.body;
+
+      if (!stream) {
+        throw new Error('No response body available');
+      }
+
+      const result = await storage.upload(key, stream, {
+        contentType,
+        metadata: options?.metadata,
+      });
+
+      return { success: true, data: result };
+    }
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to import from URL',
+    };
+  }
+}
+
+/**
+ * Helper function to generate storage key from URL
+ */
+function generateStorageKey(sourceUrl: string, metadata?: Record<string, any>): string {
+  try {
+    const url = new URL(sourceUrl);
+    const filename = url.pathname.split('/').pop() ?? 'imported-file';
+    const timestamp = Date.now();
+
+    // Determine prefix based on metadata
+    let prefix = 'imports';
+    if (metadata?.productId) {
+      prefix = `products/${metadata.productId}`;
+    } else if (metadata?.userId) {
+      prefix = `users/${metadata.userId}`;
+    } else if (metadata?.type === 'IMAGE') {
+      prefix = 'images';
+    } else if (metadata?.type === 'VIDEO') {
+      prefix = 'videos';
+    } else if (metadata?.type === 'DOCUMENT') {
+      prefix = 'documents';
+    }
+
+    return `${prefix}/${timestamp}-${filename}`;
+  } catch {
+    // Fallback for invalid URLs
+    return `imports/${Date.now()}-imported-file`;
+  }
+}
+
+//==============================================================================
+// MULTI-STORAGE OPERATIONS
+//==============================================================================
+
+/**
+ * Upload to a specific storage provider
+ */
+export async function uploadToProviderAction(
+  providerName: string,
+  key: string,
+  data: ArrayBuffer | Blob | Buffer | File | ReadableStream,
+  options?: UploadOptions,
+): Promise<MediaActionResponse<StorageObject>> {
+  'use server';
+  try {
+    const provider = getMultiStorage().getProvider(providerName);
+    if (!provider) {
+      throw new Error(`Provider '${providerName}' not found`);
+    }
+    const result = await provider.upload(key, data, options);
+    return { success: true, data: result };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to upload to provider',
+    };
+  }
+}
+
+/**
+ * List available storage providers
+ */
+export async function listProvidersAction(): Promise<MediaActionResponse<string[]>> {
+  'use server';
+  try {
+    const providers = getMultiStorage().getProviderNames();
+    return { success: true, data: providers };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to list providers',
+    };
+  }
+}
+
+/**
+ * Copy media between providers
+ */
+export async function copyBetweenProvidersAction(
+  sourceProvider: string,
+  destinationProvider: string,
+  key: string,
+  options?: UploadOptions,
+): Promise<MediaActionResponse<StorageObject>> {
+  'use server';
+  try {
+    const multiStorage = getMultiStorage();
+    const source = multiStorage.getProvider(sourceProvider);
+    const destination = multiStorage.getProvider(destinationProvider);
+
+    if (!source) {
+      throw new Error(`Source provider '${sourceProvider}' not found`);
+    }
+    if (!destination) {
+      throw new Error(`Destination provider '${destinationProvider}' not found`);
+    }
+
+    // Download from source
+    const blob = await source.download(key);
+    const metadata = await source.getMetadata(key);
+
+    // Upload to destination
+    const result = await destination.upload(key, blob, {
+      contentType: metadata.contentType,
+      ...options,
+    });
+
+    return { success: true, data: result };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to copy between providers',
+    };
+  }
+}
+
+/**
+ * Create an empty folder (placeholder with trailing slash)
+ */
+export async function createFolderAction(
+  key: string,
+  options?: UploadOptions,
+): Promise<MediaActionResponse<StorageObject>> {
+  'use server';
+  try {
+    // Ensure key ends with slash for folder
+    const folderKey = key.endsWith('/') ? key : `${key}/`;
+
+    // Create empty folder by uploading empty content
+    const emptyContent = Buffer.from(new Uint8Array(0));
+    const result = await getStorage().upload(folderKey, emptyContent, {
+      contentType: 'application/x-directory',
+      ...options,
+    });
+
+    return { success: true, data: result };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to create folder',
+    };
+  }
+}
+
+/**
+ * Copy media between storage locations
+ */
+export async function copyMediaAction(
+  sourceKey: string,
+  destinationKey: string,
+  options?: UploadOptions,
+): Promise<MediaActionResponse<StorageObject>> {
+  'use server';
+  try {
+    // Download from source
+    const blob = await getStorage().download(sourceKey);
+
+    // Upload to destination
+    const result = await getStorage().upload(destinationKey, blob, {
+      contentType: options?.contentType,
+      ...options,
+    });
+
+    return { success: true, data: result };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to copy media',
+    };
+  }
+}
+
+/**
+ * Get presigned upload URL for direct client uploads
+ */
+export async function getPresignedUploadUrlAction(
+  key: string,
+  options?: { expiresIn?: number; contentType?: string },
+): Promise<MediaActionResponse<{ url: string; fields: Record<string, string>; expiresAt: Date }>> {
+  'use server';
+  try {
+    const provider = getStorage();
+
+    if (!provider.getPresignedUploadUrl) {
+      return {
+        success: false,
+        error: 'Provider does not support presigned URLs',
+      };
+    }
+
+    const result = await provider.getPresignedUploadUrl(key, options);
+
+    return { success: true, data: result };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to get presigned upload URL',
+    };
+  }
+}
+
+/**
+ * Get storage provider capabilities
+ */
+export async function getStorageCapabilitiesAction(): Promise<
+  MediaActionResponse<{
+    multipart: boolean;
+    presignedUrls: boolean;
+    progressTracking: boolean;
+    abortSignal: boolean;
+    metadata: boolean;
+    customDomains: boolean;
+    edgeCompatible: boolean;
+  }>
+> {
+  'use server';
+  try {
+    const provider = getStorage();
+    const capabilities = provider.getCapabilities?.() ?? {
+      multipart: false,
+      presignedUrls: false,
+      progressTracking: false,
+      abortSignal: false,
+      metadata: false,
+      customDomains: false,
+      edgeCompatible: false,
+    };
+
+    return { success: true, data: capabilities };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to get storage capabilities',
+    };
+  }
+}
+
+/**
+ * Validate a file's size, MIME type, and extension against provided constraints.
+ *
+ * Checks the file's byte size against `maxFileSize`, verifies the MIME type against
+ * `allowedMimeTypes` (supports wildcard patterns like `image/*`), and verifies the
+ * filename extension against `allowedExtensions`.
+ *
+ * @param file - The file to validate; must include `size`, `type`, and `name`.
+ * @param options.maxFileSize - Maximum allowed file size in bytes.
+ * @param options.allowedMimeTypes - Allowed MIME types; supports exact types and wildcards (e.g., `image/*`).
+ * @param options.allowedExtensions - Allowed file extensions including the leading dot (e.g., `.jpg`, `.png`).
+ * @returns An object with `valid` set to `true` when no validation errors were found, and `errors` listing any validation messages.
+ */
+export async function validateFileAction(
+  file: { size: number; type: string; name: string },
+  options?: {
+    maxFileSize?: number;
+    allowedMimeTypes?: string[];
+    allowedExtensions?: string[];
+  },
+): Promise<MediaActionResponse<{ valid: boolean; errors: string[] }>> {
+  'use server';
+  try {
+    const errors: string[] = [];
+
+    // Validate file size
+    if (options?.maxFileSize && file.size > options.maxFileSize) {
+      errors.push(`File size ${file.size} bytes exceeds maximum ${options.maxFileSize} bytes`);
+    }
+
+    // Validate MIME type
+    if (options?.allowedMimeTypes && options.allowedMimeTypes.length > 0) {
+      const normalizedMimeType = file.type.toLowerCase().trim();
+      const normalizedAllowed = options.allowedMimeTypes.map(t => t.toLowerCase().trim());
+
+      if (!normalizedAllowed.includes(normalizedMimeType)) {
+        // Check wildcard patterns
+        const wildcardMatch = normalizedAllowed.some(allowed => {
+          if (allowed.endsWith('/*')) {
+            const prefix = allowed.slice(0, -2);
+            return normalizedMimeType.startsWith(prefix);
+          }
+          return false;
+        });
+
+        if (!wildcardMatch) {
+          errors.push(
+            `MIME type '${file.type}' is not allowed. Allowed types: ${options.allowedMimeTypes.join(', ')}`,
+          );
+        }
+      }
+    }
+
+    // Validate file extension
+    if (options?.allowedExtensions && options.allowedExtensions.length > 0) {
+      const extension = file.name.match(/\.[^/.]+$/)?.[0]?.toLowerCase();
+      if (extension && !options.allowedExtensions.includes(extension)) {
+        errors.push(
+          `File extension ${extension} is not allowed. Allowed: ${options.allowedExtensions.join(', ')}`,
+        );
+      }
+    }
+
+    return {
+      success: true,
+      data: {
+        valid: errors.length === 0,
+        errors,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to validate file',
+    };
+  }
+}