fix(plugin-cloud-storage): dedupe filename in clientUploads signed URL (#16510)

AlessioGr · web-flow · commit 64b28604ad84 · 2026-05-06T12:57:28.000-04:00
Backports #16495
diff --git a/packages/payload/src/uploads/getSafeFilename.ts b/packages/payload/src/uploads/getSafeFilename.ts
@@ -34,13 +34,18 @@ type Args = {
   desiredFilename: string
   prefix?: string
   req: PayloadRequest
-  staticPath: string
+  /**
+   * Filesystem path where uploads are stored. When omitted, only the database
+   * is consulted for filename conflicts - useful for cloud-storage adapters
+   * that have no local filesystem.
+   */
+  staticPath?: string
 }
 
 /**
- * Generates a safe, unique filename by checking for conflicts in both the database
- * and filesystem. If a conflict exists, it increments a numeric suffix until a
- * unique name is found.
+ * Generates a safe, unique filename by checking for conflicts in the database
+ * and (when a `staticPath` is provided) the local filesystem. If a conflict
+ * exists, it increments a numeric suffix until a unique name is found.
  *
  * @param args.collectionSlug - The slug of the upload collection
  * @param args.desiredFilename - The original filename to make safe
@@ -71,13 +76,14 @@ export async function getSafeFileName({
     (await docWithFilenameExists({
       collectionSlug,
       filename: modifiedFilename,
-      path: staticPath,
+      path: staticPath ?? '',
       prefix,
       req,
     })) ||
-    (await fileExists(`${staticPath}/${modifiedFilename}`))
+    (staticPath ? await fileExists(`${staticPath}/${modifiedFilename}`) : false)
   ) {
     modifiedFilename = incrementName(modifiedFilename)
   }
+
   return modifiedFilename
 }
diff --git a/packages/plugin-cloud-storage/src/exports/utilities.ts b/packages/plugin-cloud-storage/src/exports/utilities.ts
@@ -1,4 +1,5 @@
 export { getFileKey } from '../utilities/getFileKey.js'
 export { getFilePrefix } from '../utilities/getFilePrefix.js'
 export { initClientUploads } from '../utilities/initClientUploads.js'
+export { resolveSignedURLKey } from '../utilities/resolveSignedURLKey.js'
 export { sanitizePrefix } from '../utilities/sanitizePrefix.js'
diff --git a/packages/plugin-cloud-storage/src/utilities/resolveSignedURLKey.ts b/packages/plugin-cloud-storage/src/utilities/resolveSignedURLKey.ts
@@ -0,0 +1,47 @@
+import type { PayloadRequest } from 'payload'
+
+import { getSafeFileName } from 'payload/internal'
+
+import { getFileKey } from './getFileKey.js'
+
+type Args = {
+  collectionPrefix?: string
+  collectionSlug: string
+  docPrefix?: string
+  filename: string
+  req: PayloadRequest
+  useCompositePrefixes?: boolean
+}
+
+/**
+ * Resolves the storage key for a clientUploads signed-URL request, deduping
+ * the filename via {@link getSafeFileName} so a duplicate upload does not
+ * overwrite an existing blob.
+ *
+ * The resolved `sanitizedFilename` is returned so the browser-side handler
+ * can update the form via `updateFilename`.
+ */
+export async function resolveSignedURLKey({
+  collectionPrefix = '',
+  collectionSlug,
+  docPrefix,
+  filename,
+  req,
+  useCompositePrefixes = false,
+}: Args) {
+  const sanitizedFilename = await getSafeFileName({
+    collectionSlug,
+    desiredFilename: filename,
+    prefix: docPrefix,
+    req,
+  })
+
+  const { fileKey, sanitizedDocPrefix } = getFileKey({
+    collectionPrefix,
+    docPrefix,
+    filename: sanitizedFilename,
+    useCompositePrefixes,
+  })
+
+  return { fileKey, sanitizedDocPrefix, sanitizedFilename }
+}
diff --git a/packages/storage-azure/src/client/AzureClientUploadHandler.ts b/packages/storage-azure/src/client/AzureClientUploadHandler.ts
@@ -3,7 +3,15 @@ import { createClientUploadHandler } from '@payloadcms/plugin-cloud-storage/clie
 import { formatAdminURL } from 'payload/shared'
 
 export const AzureClientUploadHandler = createClientUploadHandler({
-  handler: async ({ apiRoute, collectionSlug, docPrefix, file, serverHandlerPath, serverURL }) => {
+  handler: async ({
+    apiRoute,
+    collectionSlug,
+    docPrefix,
+    file,
+    serverHandlerPath,
+    serverURL,
+    updateFilename,
+  }) => {
     const endpointRoute = formatAdminURL({
       apiRoute,
       path: serverHandlerPath,
@@ -20,11 +28,20 @@ export const AzureClientUploadHandler = createClientUploadHandler({
       method: 'POST',
     })
 
-    const { docPrefix: sanitizedDocPrefix, url } = (await response.json()) as {
+    const {
+      docPrefix: sanitizedDocPrefix,
+      filename: sanitizedFilename,
+      url,
+    } = (await response.json()) as {
       docPrefix: string
+      filename?: string
       url: string
     }
 
+    if (sanitizedFilename && sanitizedFilename !== file.name) {
+      updateFilename(sanitizedFilename)
+    }
+
     await fetch(url, {
       body: file,
       headers: {
diff --git a/packages/storage-azure/src/generateSignedURL.ts b/packages/storage-azure/src/generateSignedURL.ts
@@ -3,7 +3,7 @@ import type { ClientUploadsAccess } from '@payloadcms/plugin-cloud-storage/types
 import type { PayloadHandler } from 'payload'
 
 import { BlobSASPermissions, generateBlobSASQueryParameters } from '@azure/storage-blob'
-import { getFileKey } from '@payloadcms/plugin-cloud-storage/utilities'
+import { resolveSignedURLKey } from '@payloadcms/plugin-cloud-storage/utilities'
 import { APIError, Forbidden } from 'payload'
 
 import type { AzureStorageOptions } from './index.js'
@@ -49,10 +49,12 @@ export const getGenerateSignedURLHandler = ({
       throw new Forbidden()
     }
 
-    const { fileKey, sanitizedDocPrefix } = getFileKey({
+    const { fileKey, sanitizedDocPrefix, sanitizedFilename } = await resolveSignedURLKey({
       collectionPrefix,
-      docPrefix: docPrefix || '',
+      collectionSlug,
+      docPrefix,
       filename,
+      req,
       useCompositePrefixes,
     })
 
@@ -72,6 +74,7 @@ export const getGenerateSignedURLHandler = ({
 
     return Response.json({
       docPrefix: sanitizedDocPrefix,
+      filename: sanitizedFilename,
       url: `${blobClient.url}?${sasToken.toString()}`,
     })
   }
diff --git a/packages/storage-gcs/src/client/GcsClientUploadHandler.ts b/packages/storage-gcs/src/client/GcsClientUploadHandler.ts
@@ -3,7 +3,15 @@ import { createClientUploadHandler } from '@payloadcms/plugin-cloud-storage/clie
 import { formatAdminURL } from 'payload/shared'
 
 export const GcsClientUploadHandler = createClientUploadHandler({
-  handler: async ({ apiRoute, collectionSlug, docPrefix, file, serverHandlerPath, serverURL }) => {
+  handler: async ({
+    apiRoute,
+    collectionSlug,
+    docPrefix,
+    file,
+    serverHandlerPath,
+    serverURL,
+    updateFilename,
+  }) => {
     const endpointRoute = formatAdminURL({
       apiRoute,
       path: serverHandlerPath,
@@ -20,11 +28,20 @@ export const GcsClientUploadHandler = createClientUploadHandler({
       method: 'POST',
     })
 
-    const { docPrefix: sanitizedDocPrefix, url } = (await response.json()) as {
+    const {
+      docPrefix: sanitizedDocPrefix,
+      filename: sanitizedFilename,
+      url,
+    } = (await response.json()) as {
       docPrefix: string
+      filename?: string
       url: string
     }
 
+    if (sanitizedFilename && sanitizedFilename !== file.name) {
+      updateFilename(sanitizedFilename)
+    }
+
     await fetch(url, {
       body: file,
       headers: { 'Content-Length': file.size.toString(), 'Content-Type': file.type },
diff --git a/packages/storage-gcs/src/generateSignedURL.ts b/packages/storage-gcs/src/generateSignedURL.ts
@@ -2,7 +2,7 @@ import type { Storage } from '@google-cloud/storage'
 import type { ClientUploadsAccess } from '@payloadcms/plugin-cloud-storage/types'
 import type { PayloadHandler } from 'payload'
 
-import { getFileKey } from '@payloadcms/plugin-cloud-storage/utilities'
+import { resolveSignedURLKey } from '@payloadcms/plugin-cloud-storage/utilities'
 import { APIError, Forbidden } from 'payload'
 
 import type { GcsStorageOptions } from './index.js'
@@ -49,10 +49,12 @@ export const getGenerateSignedURLHandler = ({
       throw new Forbidden()
     }
 
-    const { fileKey, sanitizedDocPrefix } = getFileKey({
+    const { fileKey, sanitizedDocPrefix, sanitizedFilename } = await resolveSignedURLKey({
       collectionPrefix,
+      collectionSlug,
       docPrefix,
       filename,
+      req,
       useCompositePrefixes,
     })
 
@@ -68,6 +70,7 @@ export const getGenerateSignedURLHandler = ({
 
     return Response.json({
       docPrefix: sanitizedDocPrefix,
+      filename: sanitizedFilename,
       url,
     })
   }
diff --git a/packages/storage-r2/src/client/R2ClientUploadHandler.ts b/packages/storage-r2/src/client/R2ClientUploadHandler.ts
@@ -22,6 +22,7 @@ export const R2ClientUploadHandler = createClientUploadHandler<R2StorageClientUp
     prefix,
     serverHandlerPath,
     serverURL,
+    updateFilename,
   }): Promise<R2StorageClientUploadContext | undefined> => {
     const { sanitizedDocPrefix } = getFileKey({
       collectionPrefix: prefix,
@@ -49,7 +50,14 @@ export const R2ClientUploadHandler = createClientUploadHandler<R2StorageClientUp
       throw new Error('Failed to initialize multipart upload')
     }
 
-    const multipartUpload = (await multipart.json()) as Pick<R2MultipartUpload, 'key' | 'uploadId'>
+    const { filename: sanitizedFilename, ...multipartUpload } = (await multipart.json()) as {
+      filename?: string
+    } & Pick<R2MultipartUpload, 'key' | 'uploadId'>
+
+    if (sanitizedFilename && sanitizedFilename !== file.name) {
+      updateFilename(sanitizedFilename)
+    }
+
     const multipartUploadedParts: R2UploadedPart[] = []
 
     params.multipartId = multipartUpload.uploadId
diff --git a/packages/storage-r2/src/handleMultiPartUpload.ts b/packages/storage-r2/src/handleMultiPartUpload.ts
@@ -1,7 +1,7 @@
 import type { ClientUploadsAccess } from '@payloadcms/plugin-cloud-storage/types'
 import type { PayloadHandler } from 'payload'
 
-import { getFileKey } from '@payloadcms/plugin-cloud-storage/utilities'
+import { resolveSignedURLKey } from '@payloadcms/plugin-cloud-storage/utilities'
 import { APIError, Forbidden } from 'payload'
 
 import type { R2StorageOptions } from './index.js'
@@ -52,10 +52,12 @@ export const getHandleMultiPartUpload =
     }
 
     const collectionPrefix = (typeof collectionConfig === 'object' && collectionConfig.prefix) || ''
-    const { fileKey } = getFileKey({
+    const { fileKey, sanitizedFilename } = await resolveSignedURLKey({
       collectionPrefix,
+      collectionSlug,
       docPrefix: params.docPrefix ?? undefined,
       filename: params.fileName,
+      req,
       useCompositePrefixes,
     })
 
@@ -88,6 +90,7 @@ export const getHandleMultiPartUpload =
       })
 
       return Response.json({
+        filename: sanitizedFilename,
         key: multipartUpload.key,
         uploadId: multipartUpload.uploadId,
       })
diff --git a/packages/storage-s3/src/client/S3ClientUploadHandler.ts b/packages/storage-s3/src/client/S3ClientUploadHandler.ts
@@ -3,7 +3,15 @@ import { createClientUploadHandler } from '@payloadcms/plugin-cloud-storage/clie
 import { formatAdminURL } from 'payload/shared'
 
 export const S3ClientUploadHandler = createClientUploadHandler({
-  handler: async ({ apiRoute, collectionSlug, docPrefix, file, serverHandlerPath, serverURL }) => {
+  handler: async ({
+    apiRoute,
+    collectionSlug,
+    docPrefix,
+    file,
+    serverHandlerPath,
+    serverURL,
+    updateFilename,
+  }) => {
     const endpointRoute = formatAdminURL({
       apiRoute,
       path: serverHandlerPath,
@@ -31,11 +39,20 @@ export const S3ClientUploadHandler = createClientUploadHandler({
       throw new Error(errors.reduce((acc, err) => `${acc ? `${acc}, ` : ''}${err.message}`, ''))
     }
 
-    const { docPrefix: sanitizedDocPrefix, url } = (await response.json()) as {
+    const {
+      docPrefix: sanitizedDocPrefix,
+      filename: sanitizedFilename,
+      url,
+    } = (await response.json()) as {
       docPrefix: string
+      filename?: string
       url: string
     }
 
+    if (sanitizedFilename && sanitizedFilename !== file.name) {
+      updateFilename(sanitizedFilename)
+    }
+
     // upload the file directly to S3 using the signed URL
     await fetch(url, {
       body: file,
diff --git a/packages/storage-s3/src/generateSignedURL.ts b/packages/storage-s3/src/generateSignedURL.ts
@@ -3,7 +3,7 @@ import type { PayloadHandler } from 'payload'
 
 import * as AWS from '@aws-sdk/client-s3'
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
-import { getFileKey } from '@payloadcms/plugin-cloud-storage/utilities'
+import { resolveSignedURLKey } from '@payloadcms/plugin-cloud-storage/utilities'
 import { APIError, Forbidden } from 'payload'
 
 import type { S3StorageOptions } from './index.js'
@@ -62,10 +62,12 @@ export const getGenerateSignedURLHandler = ({
       throw new Forbidden()
     }
 
-    const { fileKey, sanitizedDocPrefix } = getFileKey({
+    const { fileKey, sanitizedDocPrefix, sanitizedFilename } = await resolveSignedURLKey({
       collectionPrefix,
+      collectionSlug,
       docPrefix,
       filename,
+      req,
       useCompositePrefixes,
     })
 
@@ -100,6 +102,7 @@ export const getGenerateSignedURLHandler = ({
 
     return Response.json({
       docPrefix: sanitizedDocPrefix,
+      filename: sanitizedFilename,
       url,
     })
   }
diff --git a/test/storage-azure/config.ts b/test/storage-azure/config.ts
@@ -1,3 +1,4 @@
+import { BlobServiceClient } from '@azure/storage-blob'
 import { azureStorage } from '@payloadcms/storage-azure'
 import dotenv from 'dotenv'
 import { fileURLToPath } from 'node:url'
@@ -44,9 +45,10 @@ export default buildConfigWithDefaults({
         },
       },
       allowContainerCreate: process.env.AZURE_STORAGE_ALLOW_CONTAINER_CREATE === 'true',
-      baseURL: process.env.AZURE_STORAGE_ACCOUNT_BASEURL,
-      connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
-      containerName: process.env.AZURE_STORAGE_CONTAINER_NAME,
+      baseURL: process.env.AZURE_STORAGE_ACCOUNT_BASEURL!,
+      clientUploads: true,
+      connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING!,
+      containerName: process.env.AZURE_STORAGE_CONTAINER_NAME!,
     }),
   ],
   upload: uploadOptions,
diff --git a/test/storage-azure/int.spec.ts b/test/storage-azure/int.spec.ts
diff --git a/test/storage-azure/payload-types.ts b/test/storage-azure/payload-types.ts
