feat: disambiguate media files by prefix via query parameter

packages/payload/src/uploads/checkFileAccess.spec.ts

@@ -0,0 +1,99 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { Collection } from '../collections/config/types.js'
+import type { PayloadRequest } from '../types/index.js'
+
+vi.mock('../auth/executeAccess.js', () => ({
+  executeAccess: vi.fn(),
+}))
+
+import { executeAccess } from '../auth/executeAccess.js'
+
+import { checkFileAccess } from './checkFileAccess.js'
+
+const makeFindOne = (result: unknown = { id: '1', filename: 'logo.png' }) =>
+  vi.fn().mockResolvedValue(result)
+
+const makeCollection = (): Collection =>
+  ({
+    config: {
+      slug: 'test-media',
+      access: { read: vi.fn() },
+      upload: {},
+    },
+  }) as unknown as Collection
+
+const makeReq = (findOne: ReturnType<typeof vi.fn>): PayloadRequest =>
+  ({
+    t: vi.fn(),
+    payload: {
+      db: { findOne },
+    },
+  }) as unknown as PayloadRequest
+
+describe('checkFileAccess', () => {
+  beforeEach(() => {
+    vi.mocked(executeAccess).mockResolvedValue({})
+  })
+
+  describe('prefix filtering', () => {
+    it('should add prefix clause to where query when prefix is provided', async () => {
+      const findOne = makeFindOne()
+      const req = makeReq(findOne)
+      const collection = makeCollection()
+
+      await checkFileAccess({ collection, filename: 'logo.png', prefix: 'abc123', req })
+
+      const whereArg = findOne.mock.calls[0]?.[0]?.where
+      expect(whereArg?.and).toEqual(expect.arrayContaining([{ prefix: { equals: 'abc123' } }]))
+    })
+
+    it('should not add prefix clause to where query when prefix is omitted', async () => {
+      const findOne = makeFindOne()
+      const req = makeReq(findOne)
+      const collection = makeCollection()
+
+      await checkFileAccess({ collection, filename: 'logo.png', req })
+
+      const whereArg = findOne.mock.calls[0]?.[0]?.where
+      const hasPrefixCondition = whereArg?.and?.some(
+        (clause: Record<string, unknown>) => 'prefix' in clause,
+      )
+      expect(hasPrefixCondition).toBeFalsy()
+    })
+
+    it('should still include filename in where query when prefix is provided', async () => {
+      const findOne = makeFindOne()
+      const req = makeReq(findOne)
+      const collection = makeCollection()
+
+      await checkFileAccess({ collection, filename: 'logo.png', prefix: 'abc123', req })
+
+      const whereArg = findOne.mock.calls[0]?.[0]?.where
+      const filenameCondition = whereArg?.and?.[0]
+      expect(filenameCondition?.or).toEqual(
+        expect.arrayContaining([{ filename: { equals: 'logo.png' } }]),
+      )
+    })
+
+    it('should throw when no doc matches the given prefix', async () => {
+      const findOne = makeFindOne(null)
+      const req = makeReq(findOne)
+      const collection = makeCollection()
+
+      await expect(
+        checkFileAccess({ collection, filename: 'logo.png', prefix: 'nonexistent', req }),
+      ).rejects.toThrow()
+    })
+
+    it('should throw when filename contains path traversal sequence', async () => {
+      const findOne = makeFindOne()
+      const req = makeReq(findOne)
+      const collection = makeCollection()
+
+      await expect(
+        checkFileAccess({ collection, filename: '../etc/passwd', req }),
+      ).rejects.toThrow()
+    })
+  })
+})

packages/payload/src/uploads/checkFileAccess.ts

@@ -7,10 +7,12 @@ import { Forbidden } from '../errors/Forbidden.js'
 export const checkFileAccess = async ({
   collection,
   filename,
+  prefix,
   req,
 }: {
   collection: Collection
   filename: string
+  prefix?: string
   req: PayloadRequest
 }): Promise<TypeWithID | undefined> => {
   if (filename.includes('../') || filename.includes('..\\')) {
@@ -49,6 +51,12 @@ export const checkFileAccess = async ({
       })
     }
 
+    if (typeof prefix === 'string') {
+      queryToBuild.and!.push({
+        prefix: { equals: prefix },
+      })
+    }
+
     const doc = await req.payload.db.findOne({
       collection: config.slug,
       req,

packages/payload/src/uploads/endpoints/getFile.ts

@@ -19,6 +19,7 @@ export const getFileHandler: PayloadHandler = async (req) => {
   const collection = getRequestCollection(req)
 
   const filename = req.routeParams?.filename as string
+  const prefix = req.searchParams?.get('prefix') ?? undefined
 
   if (!collection.config.upload) {
     throw new APIError(
@@ -30,6 +31,7 @@ export const getFileHandler: PayloadHandler = async (req) => {
   const accessResult = (await checkFileAccess({
     collection,
     filename,
+    prefix,
     req,
   }))!
 
@@ -48,6 +50,7 @@ export const getFileHandler: PayloadHandler = async (req) => {
         params: {
           collection: collection.config.slug,
           filename,
+          prefix,
         },
       })
       if (customResponse && customResponse instanceof Response) {

packages/payload/src/uploads/types.ts

@@ -245,7 +245,12 @@ export type UploadConfig = {
     args: {
       doc: TypeWithID
       headers?: Headers
-      params: { clientUploadContext?: unknown; collection: string; filename: string }
+      params: {
+        clientUploadContext?: unknown
+        collection: string
+        filename: string
+        prefix?: string
+      }
     },
   ) => Promise<Response> | Promise<void> | Response | void)[]
   /**

packages/plugin-cloud-storage/src/hooks/afterRead.ts

@@ -32,6 +32,9 @@ export const getAfterReadHook =
           filename,
           prefix,
         })
+      } else if (url && prefix) {
+        const separator = url.includes('?') ? '&' : '?'
+        url = `${url}${separator}prefix=${encodeURIComponent(prefix)}`
       }
     }
 

packages/plugin-cloud-storage/src/types.ts

@@ -63,7 +63,7 @@ export type StaticHandler = (
   args: {
     doc?: TypeWithID
     headers?: Headers
-    params: { clientUploadContext?: unknown; collection: string; filename: string }
+    params: { clientUploadContext?: unknown; collection: string; filename: string; prefix?: string }
   },
 ) => Promise<Response> | Response
 

packages/plugin-cloud-storage/src/utilities/getFilePrefix.spec.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { CollectionConfig, PayloadRequest } from 'payload'
+
+import { getFilePrefix } from './getFilePrefix.js'
+
+const makeReq = (docs: unknown[] = []) =>
+  ({
+    payload: {
+      find: vi.fn().mockResolvedValue({ docs }),
+    },
+  }) as unknown as PayloadRequest
+
+const makeCollection = (): CollectionConfig =>
+  ({ slug: 'media', upload: {} }) as unknown as CollectionConfig
+
+describe('getFilePrefix', () => {
+  describe('explicitPrefix shortcut', () => {
+    it('should return explicitPrefix immediately without querying the database', async () => {
+      const req = makeReq()
+
+      const result = await getFilePrefix({
+        collection: makeCollection(),
+        explicitPrefix: 'uuid-prefix',
+        filename: 'logo.png',
+        req,
+      })
+
+      expect(result).toBe('uuid-prefix')
+      expect(req.payload.find).not.toHaveBeenCalled()
+    })
+
+    it('should return an empty string when explicitPrefix is an empty string', async () => {
+      const req = makeReq()
+
+      const result = await getFilePrefix({
+        collection: makeCollection(),
+        explicitPrefix: '',
+        filename: 'logo.png',
+        req,
+      })
+
+      expect(result).toBe('')
+      expect(req.payload.find).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('database fallback', () => {
+    it('should query the database when explicitPrefix is not provided', async () => {
+      const req = makeReq([{ prefix: 'db-prefix' }])
+
+      const result = await getFilePrefix({
+        collection: makeCollection(),
+        filename: 'logo.png',
+        req,
+      })
+
+      expect(result).toBe('db-prefix')
+      expect(req.payload.find).toHaveBeenCalledOnce()
+    })
+
+    it('should return empty string when no document is found', async () => {
+      const req = makeReq([])
+
+      const result = await getFilePrefix({
+        collection: makeCollection(),
+        filename: 'logo.png',
+        req,
+      })
+
+      expect(result).toBe('')
+    })
+
+    it('should prioritize clientUploadContext prefix over database query', async () => {
+      const req = makeReq([{ prefix: 'db-prefix' }])
+
+      const result = await getFilePrefix({
+        clientUploadContext: { prefix: 'context-prefix' },
+        collection: makeCollection(),
+        filename: 'logo.png',
+        req,
+      })
+
+      expect(result).toBe('context-prefix')
+      expect(req.payload.find).not.toHaveBeenCalled()
+    })
+  })
+})

packages/plugin-cloud-storage/src/utilities/getFilePrefix.ts

@@ -3,14 +3,20 @@ import type { CollectionConfig, PayloadRequest, UploadConfig } from 'payload'
 export async function getFilePrefix({
   clientUploadContext,
   collection,
+  explicitPrefix,
   filename,
   req,
 }: {
   clientUploadContext?: unknown
   collection: CollectionConfig
+  explicitPrefix?: string
   filename: string
   req: PayloadRequest
 }): Promise<string> {
+  if (typeof explicitPrefix === 'string') {
+    return explicitPrefix
+  }
+
   // Prioritize from clientUploadContext if there is:
   if (
     clientUploadContext &&

packages/storage-s3/src/staticHandler.ts

@@ -62,7 +62,10 @@ export const getHandler = ({
   getStorageClient,
   signedDownloads,
 }: Args): StaticHandler => {
-  return async (req, { headers: incomingHeaders, params: { clientUploadContext, filename } }) => {
+  return async (
+    req,
+    { headers: incomingHeaders, params: { clientUploadContext, filename, prefix: explicitPrefix } },
+  ) => {
     let object: AWS.GetObjectOutput | undefined = undefined
     let streamed = false
 
@@ -74,7 +77,13 @@ export const getHandler = ({
     }
 
     try {
-      const prefix = await getFilePrefix({ clientUploadContext, collection, filename, req })
+      const prefix = await getFilePrefix({
+        clientUploadContext,
+        collection,
+        explicitPrefix,
+        filename,
+        req,
+      })
 
       const key = path.posix.join(prefix, filename)
 

packages/ui/src/elements/EditUpload/index.tsx

@@ -169,7 +169,8 @@ export const EditUpload: React.FC<EditUploadProps> = ({
     setFocalPosition({ x: xCenter, y: yCenter })
   }
 
-  const fileSrcToUse = imageCacheTag ? `${fileSrc}?${encodeURIComponent(imageCacheTag)}` : fileSrc
+  const queryChar = fileSrc?.includes('?') ? '&' : '?'
+  const fileSrcToUse = imageCacheTag ? `${fileSrc}${queryChar}${encodeURIComponent(imageCacheTag)}` : fileSrc
 
   return (
     <div className={baseClass}>

packages/ui/src/elements/PreviewSizes/index.tsx

@@ -99,7 +99,8 @@ export const PreviewSizes: React.FC<PreviewSizesProps> = ({ doc, imageCacheTag,
       return null
     }
     if (doc.url) {
-      return `${doc.url}${imageCacheTag ? `?${encodeURIComponent(imageCacheTag)}` : ''}`
+      const queryChar = doc.url.includes('?') ? '&' : '?'
+      return `${doc.url}${imageCacheTag ? `${queryChar}${encodeURIComponent(imageCacheTag)}` : ''}`
     }
   }
   useEffect(() => {

test/uploads/config.ts

@@ -36,6 +36,7 @@ import {
   noRestrictFileMimeTypesSlug,
   noRestrictFileTypesSlug,
   pdfOnlySlug,
+  prefixMediaSlug,
   reduceSlug,
   relationPreviewSlug,
   relationSlug,
@@ -1061,6 +1062,18 @@ export default buildConfigWithDefaults({
         ],
       },
     },
+    {
+      slug: prefixMediaSlug,
+      fields: [
+        {
+          name: 'prefix',
+          type: 'text',
+        },
+      ],
+      upload: {
+        staticDir: path.resolve(dirname, './prefix-media'),
+      },
+    },
   ],
   onInit: async (payload) => {
     if (process.env.SEED_IN_CONFIG_ONINIT !== 'false') {