feat: disambiguate media files by prefix via query parameter (#15844)

Add optional `?prefix=` query string support to the existing
`/api/:collection/file/:filename` endpoint to disambiguate files that
share the same filename but have different storage prefixes.

When a storage prefix (e.g., UUID or folder path) is used to make S3
keys unique, multiple documents can share the same `filename`. The
current endpoint resolves by filename alone, which can match the wrong
document in both access control and file retrieval.

- `checkFileAccess` accepts optional `prefix` and adds it to the `where`
clause alongside existing access filters
- `getFile` handler reads `prefix` from `req.searchParams` and threads
it to `checkFileAccess` and handler `params`
- `getFilePrefix` accepts `explicitPrefix` to skip the DB query when the
prefix is already known from the URL
- S3 `staticHandler` forwards `prefix` from params to `getFilePrefix`
- `afterRead` hook appends `?prefix=` to Payload-proxied URLs
- Added unit tests for `checkFileAccess` and `getFilePrefix`, and
integration tests for the endpoint'

---------

Co-authored-by: Jarrod Flesch <jarrodmflesch@gmail.com>

Author: tschwartz

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('..\\')) {
@@ -23,36 +25,33 @@ export const checkFileAccess = async ({
     config.access.read,
   )
 
+  const constraints: Where[] = []
+
   if (typeof accessResult === 'object') {
-    const queryToBuild: Where = {
-      and: [
-        {
-          or: [
-            {
-              filename: {
-                equals: filename,
-              },
-            },
-          ],
-        },
-        accessResult,
-      ],
+    constraints.push(accessResult)
+  }
+
+  if (typeof prefix === 'string') {
+    constraints.push({ prefix: { equals: prefix } })
+  }
+
+  if (constraints.length > 0) {
+    const filenameCondition: Where = {
+      or: [{ filename: { equals: filename } }],
     }
 
     if (config.upload.imageSizes) {
       config.upload.imageSizes.forEach(({ name }) => {
-        queryToBuild.and?.[0]?.or?.push({
-          [`sizes.${name}.filename`]: {
-            equals: filename,
-          },
+        filenameCondition.or!.push({
+          [`sizes.${name}.filename`]: { equals: filename },
         })
       })
     }
 
     const doc = await req.payload.db.findOne({
       collection: config.slug,
       req,
-      where: queryToBuild,
+      where: { and: [filenameCondition, ...constraints] },
     })
 
     if (!doc) {

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,116 @@
+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('prefixQueryParam shortcut', () => {
+    it('should return prefixQueryParam immediately without querying the database', async () => {
+      const req = makeReq()
+
+      const result = await getFilePrefix({
+        collection: makeCollection(),
+        prefixQueryParam: 'uuid-prefix',
+        filename: 'logo.png',
+        req,
+      })
+
+      expect(result).toBe('uuid-prefix')
+      expect(req.payload.find).not.toHaveBeenCalled()
+    })
+
+    it('should return an empty string when prefixQueryParam is an empty string', async () => {
+      const req = makeReq()
+
+      const result = await getFilePrefix({
+        collection: makeCollection(),
+        prefixQueryParam: '',
+        filename: 'logo.png',
+        req,
+      })
+
+      expect(result).toBe('')
+      expect(req.payload.find).not.toHaveBeenCalled()
+    })
+
+    it('should reject multi-encoded values', async () => {
+      const req = makeReq()
+
+      const result = await getFilePrefix({
+        collection: makeCollection(),
+        prefixQueryParam: '%252e%252e%252fsecret%252f..%252fok',
+        filename: 'logo.png',
+        req,
+      })
+
+      expect(result).toBe('')
+      expect(req.payload.find).not.toHaveBeenCalled()
+    })
+
+    it('should reject malformed percent-encoding', async () => {
+      const req = makeReq()
+
+      const result = await getFilePrefix({
+        collection: makeCollection(),
+        prefixQueryParam: '%E0%A4%A',
+        filename: 'logo.png',
+        req,
+      })
+
+      expect(result).toBe('')
+      expect(req.payload.find).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('database fallback', () => {
+    it('should query the database when prefixQueryParam 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

@@ -4,8 +4,21 @@ import type { CollectionConfig, PayloadRequest, UploadConfig } from 'payload'
  * Normalizes a storage prefix to ensure only valid path segments are included.
  */
 function sanitizePrefix(prefix: string): string {
+  let decodedPrefix: string
+
+  try {
+    decodedPrefix = decodeURIComponent(prefix)
+  } catch {
+    return ''
+  }
+
+  // Reject multi-encoded values (e.g. `%252f`) by allowing only a single decode pass.
+  if (/%[0-9a-f]{2}/i.test(decodedPrefix)) {
+    return ''
+  }
+
   return (
-    prefix
+    decodedPrefix
       .replace(/\\/g, '/')
       .split('/')
       .filter((segment) => segment !== '..' && segment !== '.')
@@ -16,17 +29,36 @@ function sanitizePrefix(prefix: string): string {
   )
 }
 
+/**
+ * Resolves the file prefix from the highest-priority available source and
+ * always returns a sanitized value.
+ *
+ * Resolution order:
+ * 1. `prefixQueryParam`
+ * 2. `clientUploadContext.prefix`
+ * 3. Stored document `prefix` from the database
+ *
+ * Query / client input is decoded once; malformed and multi-encoded values are
+ * rejected. Sanitization then normalizes slashes, removes `.` / `..` path
+ * traversal segments, strips leading slashes, and removes control characters.
+ */
 export async function getFilePrefix({
   clientUploadContext,
   collection,
   filename,
+  prefixQueryParam,
   req,
 }: {
   clientUploadContext?: unknown
   collection: CollectionConfig
   filename: string
+  prefixQueryParam?: string
   req: PayloadRequest
 }): Promise<string> {
+  if (typeof prefixQueryParam === 'string') {
+    return sanitizePrefix(prefixQueryParam)
+  }
+
   // Prioritize from clientUploadContext if there is:
   if (
     clientUploadContext &&