@payloadcms/plugin-cloud-storage 3.89.0 → 3.90.0

package/dist/utilities/buildStoragePathData.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utilities/buildStoragePathData.spec.ts"],"sourcesContent":["import {\n  buildStoragePathData,\n  buildUploadStoragePathData,\n  isStoragePathWithinCollectionPrefix,\n} from './buildStoragePathData.js'\nimport { describe, expect, it } from 'vitest'\n\ndescribe('buildStoragePathData', () => {\n  describe('non-composite mode (useCompositePrefixes: false)', () => {\n    it('should preserve the key of a legacy document outside the collection prefix', () => {\n      const result = buildStoragePathData({\n        collectionPrefix: 'media/',\n        docPrefix: 'media-archive',\n        filename: 'test.png',\n        useCompositePrefixes: false,\n      })\n\n      expect(result).toEqual({\n        fileKey: 'media-archive/test.png',\n        sanitizedCollectionPrefix: 'media',\n        sanitizedDocPrefix: 'media-archive',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'media-archive/test.png',\n      })\n    })\n\n    it('should fallback to collectionPrefix when docPrefix is empty', () => {\n      const result = buildStoragePathData({\n        collectionPrefix: 'collection',\n        docPrefix: '',\n        filename: 'test.png',\n        useCompositePrefixes: false,\n      })\n      expect(result).toEqual({\n        fileKey: 'collection/test.png',\n        sanitizedCollectionPrefix: 'collection',\n        sanitizedDocPrefix: '',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'collection/test.png',\n      })\n    })\n\n    it('should fallback to collectionPrefix when docPrefix is undefined', () => {\n      const result = buildStoragePathData({\n        collectionPrefix: 'collection',\n        filename: 'test.png',\n        useCompositePrefixes: false,\n      })\n      expect(result).toEqual({\n        fileKey: 'collection/test.png',\n        sanitizedCollectionPrefix: 'collection',\n        sanitizedDocPrefix: '',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'collection/test.png',\n      })\n    })\n\n    it('should return only filename when both prefixes are empty', () => {\n      const result = buildStoragePathData({\n        filename: 'test.png',\n        useCompositePrefixes: false,\n      })\n      expect(result).toEqual({\n        fileKey: 'test.png',\n        sanitizedCollectionPrefix: '',\n        sanitizedDocPrefix: '',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'test.png',\n      })\n    })\n  })\n\n  describe('composite mode (useCompositePrefixes: true)', () => {\n    it('should combine collectionPrefix and docPrefix', () => {\n      const result = buildStoragePathData({\n        collectionPrefix: 'collection',\n        docPrefix: 'document',\n        filename: 'test.png',\n        useCompositePrefixes: true,\n      })\n      expect(result).toEqual({\n        fileKey: 'collection/document/test.png',\n        sanitizedCollectionPrefix: 'collection',\n        sanitizedDocPrefix: 'document',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'collection/document/test.png',\n      })\n    })\n\n    it('should work with only collectionPrefix', () => {\n      const result = buildStoragePathData({\n        collectionPrefix: 'collection',\n        filename: 'test.png',\n        useCompositePrefixes: true,\n      })\n      expect(result).toEqual({\n        fileKey: 'collection/test.png',\n        sanitizedCollectionPrefix: 'collection',\n        sanitizedDocPrefix: '',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'collection/test.png',\n      })\n    })\n\n    it('should work with only docPrefix', () => {\n      const result = buildStoragePathData({\n        docPrefix: 'document',\n        filename: 'test.png',\n        useCompositePrefixes: true,\n      })\n      expect(result).toEqual({\n        fileKey: 'document/test.png',\n        sanitizedCollectionPrefix: '',\n        sanitizedDocPrefix: 'document',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'document/test.png',\n      })\n    })\n\n    it('should return only filename when both prefixes are empty', () => {\n      const result = buildStoragePathData({\n        filename: 'test.png',\n        useCompositePrefixes: true,\n      })\n      expect(result).toEqual({\n        fileKey: 'test.png',\n        sanitizedCollectionPrefix: '',\n        sanitizedDocPrefix: '',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'test.png',\n      })\n    })\n  })\n\n  describe('collection prefix boundaries', () => {\n    it('should accept a file key within a slash-terminated collection prefix', () => {\n      expect(\n        isStoragePathWithinCollectionPrefix({\n          collectionPrefix: 'media/',\n          docPrefix: 'media/documents/test.png',\n        }),\n      ).toBe(true)\n    })\n  })\n\n  describe('sanitization', () => {\n    it.each(['./media/./images', 'media\\\\images', '/media//images'])(\n      'should canonicalize equivalent prefix paths',\n      (docPrefix) => {\n        const result = buildStoragePathData({ docPrefix, filename: 'test.png' })\n\n        expect(result).toEqual({\n          fileKey: 'media/images/test.png',\n          sanitizedCollectionPrefix: '',\n          sanitizedDocPrefix: 'media/images',\n          sanitizedFilename: 'test.png',\n          storageFilePath: 'media/images/test.png',\n        })\n      },\n    )\n\n    it('should remove path traversal segments from collectionPrefix', () => {\n      const result = buildStoragePathData({\n        collectionPrefix: '../../../etc',\n        filename: 'test.png',\n        useCompositePrefixes: false,\n      })\n      expect(result).toEqual({\n        fileKey: 'etc/test.png',\n        sanitizedCollectionPrefix: 'etc',\n        sanitizedDocPrefix: '',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'etc/test.png',\n      })\n      expect(result.fileKey).not.toContain('..')\n    })\n\n    it('should remove path traversal segments from docPrefix', () => {\n      const result = buildStoragePathData({\n        docPrefix: 'a/../../outside',\n        filename: 'test.png',\n        useCompositePrefixes: false,\n      })\n      expect(result).toEqual({\n        fileKey: 'a/outside/test.png',\n        sanitizedCollectionPrefix: '',\n        sanitizedDocPrefix: 'a/outside',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'a/outside/test.png',\n      })\n      expect(result.fileKey).not.toContain('..')\n    })\n\n    it('should remove control characters from prefixes', () => {\n      const result = buildStoragePathData({\n        collectionPrefix: 'test\\x00\\x1fprefix',\n        filename: 'test.png',\n        useCompositePrefixes: false,\n      })\n      expect(result).toEqual({\n        fileKey: 'testprefix/test.png',\n        sanitizedCollectionPrefix: 'testprefix',\n        sanitizedDocPrefix: '',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'testprefix/test.png',\n      })\n      expect(result.fileKey).not.toMatch(/[\\x00-\\x1f]/)\n    })\n\n    it('should normalize both prefixes after removing control characters in composite mode', () => {\n      const result = buildStoragePathData({\n        collectionPrefix: '.\\x00./collection',\n        docPrefix: '.\\x00./doc',\n        filename: 'test.png',\n        useCompositePrefixes: true,\n      })\n      expect(result).toEqual({\n        fileKey: 'collection/doc/test.png',\n        sanitizedCollectionPrefix: 'collection',\n        sanitizedDocPrefix: 'doc',\n        sanitizedFilename: 'test.png',\n        storageFilePath: 'collection/doc/test.png',\n      })\n      expect(result.fileKey).not.toContain('..')\n    })\n  })\n})\n\ndescribe('buildUploadStoragePathData', () => {\n  it.each([\n    ['invoices', false, 'media/invoices/file.png', 'media/invoices'],\n    ['media/invoices', false, 'media/invoices/file.png', 'media/invoices'],\n    ['', false, 'media/file.png', ''],\n    ['invoices', true, 'media/invoices/file.png', 'invoices'],\n  ] as const)(\n    'should persist a readable destination for %s (composite %s)',\n    (docPrefix, useCompositePrefixes, fileKey, storedPrefix) => {\n      const result = buildUploadStoragePathData({\n        collectionPrefix: 'media',\n        docPrefix,\n        filename: 'file.png',\n        useCompositePrefixes,\n      })\n\n      expect(result.storageFilePath).toBe(fileKey)\n      expect(result.sanitizedDocPrefix).toBe(storedPrefix)\n      expect(\n        buildStoragePathData({\n          collectionPrefix: 'media',\n          docPrefix: result.sanitizedDocPrefix,\n          filename: 'file.png',\n          useCompositePrefixes,\n        }).fileKey,\n      ).toBe(fileKey)\n    },\n  )\n})\n"],"names":["buildStoragePathData","buildUploadStoragePathData","isStoragePathWithinCollectionPrefix","describe","expect","it","result","collectionPrefix","docPrefix","filename","useCompositePrefixes","toEqual","fileKey","sanitizedCollectionPrefix","sanitizedDocPrefix","sanitizedFilename","storageFilePath","toBe","each","not","toContain","toMatch","storedPrefix"],"mappings":"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"}

package/dist/utilities/getFilePrefix.d.ts

@@ -1,20 +1,36 @@
-import type { CollectionConfig, PayloadRequest } from 'payload';
+import type { CollectionConfig, PayloadRequest, TypeWithID } from 'payload';
 /**
- * Resolves the file prefix from the highest-priority available source and
- * always returns a sanitized value.
+ * Resolves the folder a stored object lives under (semantic `prefix` plus `_objectKey`).
  *
- * Resolution order:
- * 1. `prefixQueryParam`
- * 2. `clientUploadContext.prefix`
- * 3. Stored document `prefix` from the database
- *
- * Resolved values are passed through `sanitizePrefix`.
+ * An already-authorized `doc` wins outright. Otherwise a verified `clientUploadContext` is used
+ * (its `prefix` re-contained with {@link buildUploadStoragePathData}, since it hasn't been verified against
+ * a signed receipt by every adapter). Otherwise the document is resolved with
+ * `overrideAccess: false`, any query-param prefix only narrows that lookup, and `_objectKey` is
+ * read from the resolved document.
  */
-export declare function getFilePrefix({ clientUploadContext, collection, filename, prefixQueryParam, req, }: {
+type GetFilePrefixArgs = {
     clientUploadContext?: unknown;
     collection: CollectionConfig;
+    collectionPrefix?: string;
+    doc?: {
+        _objectKey?: string;
+        prefix?: string;
+    } & TypeWithID;
     filename: string;
+    /**
+     * Only narrows the access-controlled fallback lookup below; never trusted or
+     * returned directly. Prefer passing the access-checked document as `doc` instead.
+     */
     prefixQueryParam?: string;
     req: PayloadRequest;
-}): Promise<string>;
+    useCompositePrefixes?: boolean;
+};
+export declare function getFilePrefix({ clientUploadContext, collection, collectionPrefix, doc, filename, prefixQueryParam, req, useCompositePrefixes, }: GetFilePrefixArgs): Promise<string>;
+/**
+ * Serve-path helper: resolves the authorized folder with {@link getFilePrefix}, then returns the
+ * full object key via {@link buildStoragePathData}. Read handlers use this so a key is never built from an
+ * unresolved prefix.
+ */
+export declare function getStorageFilePath(args: GetFilePrefixArgs): Promise<string>;
+export {};
 //# sourceMappingURL=getFilePrefix.d.ts.map

package/dist/utilities/getFilePrefix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getFilePrefix.d.ts","sourceRoot":"","sources":["../../src/utilities/getFilePrefix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAgB,MAAM,SAAS,CAAA;AAI7E;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,EAClC,mBAAmB,EACnB,UAAU,EACV,QAAQ,EACR,gBAAgB,EAChB,GAAG,GACJ,EAAE;IACD,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,UAAU,EAAE,gBAAgB,CAAA;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,GAAG,EAAE,cAAc,CAAA;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoClB"}
+{"version":3,"file":"getFilePrefix.d.ts","sourceRoot":"","sources":["../../src/utilities/getFilePrefix.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAgB,MAAM,SAAS,CAAA;AAMzF;;;;;;;;GAQG;AAEH,KAAK,iBAAiB,GAAG;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,UAAU,EAAE,gBAAgB,CAAA;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,GAAG,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,CAAA;IAC3D,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,GAAG,EAAE,cAAc,CAAA;IACnB,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B,CAAA;AACD,wBAAsB,aAAa,CAAC,EAClC,mBAAmB,EACnB,UAAU,EACV,gBAAgB,EAChB,GAAG,EACH,QAAQ,EACR,gBAAgB,EAChB,GAAG,EACH,oBAA4B,GAC7B,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuErC;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CASjF"}

package/dist/utilities/getFilePrefix.js

@@ -1,46 +1,90 @@
+import { buildPrefixWithObjectKey } from './buildPrefixWithObjectKey.js';
+import { buildStoragePathData, buildUploadStoragePathData } from './buildStoragePathData.js';
 import { sanitizePrefix } from './sanitizePrefix.js';
-/**
- * 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
- *
- * Resolved values are passed through `sanitizePrefix`.
- */ export async function getFilePrefix({ clientUploadContext, collection, filename, prefixQueryParam, req }) {
-    if (typeof prefixQueryParam === 'string') {
-        return sanitizePrefix(prefixQueryParam);
+export async function getFilePrefix({ clientUploadContext, collection, collectionPrefix, doc, filename, prefixQueryParam, req, useCompositePrefixes = false }) {
+    // The serve path already loaded and authorized this document — trust it over any
+    // client-supplied upload context or query prefix.
+    if (doc) {
+        return buildPrefixWithObjectKey({
+            objectKey: doc._objectKey,
+            prefix: doc.prefix
+        });
     }
-    // Prioritize from clientUploadContext if there is:
+    // Client uploads call handlers without a document yet. Re-contain the claimed
+    // prefix — it hasn't been verified against a signed receipt by every adapter.
     if (clientUploadContext && typeof clientUploadContext === 'object' && 'prefix' in clientUploadContext && typeof clientUploadContext.prefix === 'string') {
-        return sanitizePrefix(clientUploadContext.prefix);
+        const contextObjectKey = '_objectKey' in clientUploadContext ? clientUploadContext._objectKey : undefined;
+        const containedPrefix = buildUploadStoragePathData({
+            collectionPrefix,
+            docPrefix: clientUploadContext.prefix,
+            filename,
+            useCompositePrefixes
+        }).sanitizedDocPrefix;
+        return buildPrefixWithObjectKey({
+            objectKey: contextObjectKey,
+            prefix: containedPrefix
+        });
     }
+    // Reads without a query prefix or read-access constraints skip the endpoint's document lookup.
     const imageSizes = collection?.upload?.imageSizes || [];
+    const filenameClause = {
+        or: [
+            {
+                filename: {
+                    equals: filename
+                }
+            },
+            ...imageSizes.map((imageSize)=>({
+                    [`sizes.${imageSize.name}.filename`]: {
+                        equals: filename
+                    }
+                }))
+        ]
+    };
+    // Only filter by prefix when the collection persists a `prefix` field (querying a missing field throws).
+    const hasPrefixField = collection.fields?.some((field)=>'name' in field && field.name === 'prefix');
+    const where = typeof prefixQueryParam === 'string' && hasPrefixField ? {
+        and: [
+            filenameClause,
+            {
+                prefix: {
+                    equals: sanitizePrefix(prefixQueryParam)
+                }
+            }
+        ]
+    } : filenameClause;
     const files = await req.payload.find({
         collection: collection.slug,
         depth: 0,
         draft: true,
         limit: 1,
+        overrideAccess: false,
         pagination: false,
-        where: {
-            or: [
-                {
-                    filename: {
-                        equals: filename
-                    }
-                },
-                ...imageSizes.map((imageSize)=>({
-                        [`sizes.${imageSize.name}.filename`]: {
-                            equals: filename
-                        }
-                    }))
-            ]
-        }
+        req,
+        select: {
+            _objectKey: true,
+            prefix: true
+        },
+        where
+    });
+    const found = files?.docs?.[0];
+    return buildPrefixWithObjectKey({
+        objectKey: found?._objectKey,
+        prefix: found?.prefix
     });
-    const prefix = files?.docs?.[0]?.prefix;
-    return prefix ? sanitizePrefix(prefix) : '';
+}
+/**
+ * Serve-path helper: resolves the authorized folder with {@link getFilePrefix}, then returns the
+ * full object key via {@link buildStoragePathData}. Read handlers use this so a key is never built from an
+ * unresolved prefix.
+ */ export async function getStorageFilePath(args) {
+    const docPrefix = await getFilePrefix(args);
+    return buildStoragePathData({
+        collectionPrefix: args.collectionPrefix,
+        docPrefix,
+        filename: args.filename,
+        useCompositePrefixes: args.useCompositePrefixes
+    }).storageFilePath;
 }
 
 //# sourceMappingURL=getFilePrefix.js.map

package/dist/utilities/getFilePrefix.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utilities/getFilePrefix.ts"],"sourcesContent":["import type { CollectionConfig, PayloadRequest, UploadConfig } from 'payload'\n\nimport { sanitizePrefix } from './sanitizePrefix.js'\n\n/**\n * Resolves the file prefix from the highest-priority available source and\n * always returns a sanitized value.\n *\n * Resolution order:\n * 1. `prefixQueryParam`\n * 2. `clientUploadContext.prefix`\n * 3. Stored document `prefix` from the database\n *\n * Resolved values are passed through `sanitizePrefix`.\n */\nexport async function getFilePrefix({\n  clientUploadContext,\n  collection,\n  filename,\n  prefixQueryParam,\n  req,\n}: {\n  clientUploadContext?: unknown\n  collection: CollectionConfig\n  filename: string\n  prefixQueryParam?: string\n  req: PayloadRequest\n}): Promise<string> {\n  if (typeof prefixQueryParam === 'string') {\n    return sanitizePrefix(prefixQueryParam)\n  }\n\n  // Prioritize from clientUploadContext if there is:\n  if (\n    clientUploadContext &&\n    typeof clientUploadContext === 'object' &&\n    'prefix' in clientUploadContext &&\n    typeof clientUploadContext.prefix === 'string'\n  ) {\n    return sanitizePrefix(clientUploadContext.prefix)\n  }\n\n  const imageSizes = (collection?.upload as UploadConfig)?.imageSizes || []\n\n  const files = await req.payload.find({\n    collection: collection.slug,\n    depth: 0,\n    draft: true,\n    limit: 1,\n    pagination: false,\n    where: {\n      or: [\n        {\n          filename: { equals: filename },\n        },\n        ...imageSizes.map((imageSize) => ({\n          [`sizes.${imageSize.name}.filename`]: { equals: filename },\n        })),\n      ],\n    },\n  })\n  const prefix = files?.docs?.[0]?.prefix\n  return prefix ? sanitizePrefix(prefix as string) : ''\n}\n"],"names":["sanitizePrefix","getFilePrefix","clientUploadContext","collection","filename","prefixQueryParam","req","prefix","imageSizes","upload","files","payload","find","slug","depth","draft","limit","pagination","where","or","equals","map","imageSize","name","docs"],"mappings":"AAEA,SAASA,cAAc,QAAQ,sBAAqB;AAEpD;;;;;;;;;;CAUC,GACD,OAAO,eAAeC,cAAc,EAClCC,mBAAmB,EACnBC,UAAU,EACVC,QAAQ,EACRC,gBAAgB,EAChBC,GAAG,EAOJ;IACC,IAAI,OAAOD,qBAAqB,UAAU;QACxC,OAAOL,eAAeK;IACxB;IAEA,mDAAmD;IACnD,IACEH,uBACA,OAAOA,wBAAwB,YAC/B,YAAYA,uBACZ,OAAOA,oBAAoBK,MAAM,KAAK,UACtC;QACA,OAAOP,eAAeE,oBAAoBK,MAAM;IAClD;IAEA,MAAMC,aAAa,AAACL,YAAYM,QAAyBD,cAAc,EAAE;IAEzE,MAAME,QAAQ,MAAMJ,IAAIK,OAAO,CAACC,IAAI,CAAC;QACnCT,YAAYA,WAAWU,IAAI;QAC3BC,OAAO;QACPC,OAAO;QACPC,OAAO;QACPC,YAAY;QACZC,OAAO;YACLC,IAAI;gBACF;oBACEf,UAAU;wBAAEgB,QAAQhB;oBAAS;gBAC/B;mBACGI,WAAWa,GAAG,CAAC,CAACC,YAAe,CAAA;wBAChC,CAAC,CAAC,MAAM,EAAEA,UAAUC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE;4BAAEH,QAAQhB;wBAAS;oBAC3D,CAAA;aACD;QACH;IACF;IACA,MAAMG,SAASG,OAAOc,MAAM,CAAC,EAAE,EAAEjB;IACjC,OAAOA,SAASP,eAAeO,UAAoB;AACrD"}
+{"version":3,"sources":["../../src/utilities/getFilePrefix.ts"],"sourcesContent":["import type { CollectionConfig, PayloadRequest, TypeWithID, UploadConfig } from 'payload'\n\nimport { buildPrefixWithObjectKey } from './buildPrefixWithObjectKey.js'\nimport { buildStoragePathData, buildUploadStoragePathData } from './buildStoragePathData.js'\nimport { sanitizePrefix } from './sanitizePrefix.js'\n\n/**\n * Resolves the folder a stored object lives under (semantic `prefix` plus `_objectKey`).\n *\n * An already-authorized `doc` wins outright. Otherwise a verified `clientUploadContext` is used\n * (its `prefix` re-contained with {@link buildUploadStoragePathData}, since it hasn't been verified against\n * a signed receipt by every adapter). Otherwise the document is resolved with\n * `overrideAccess: false`, any query-param prefix only narrows that lookup, and `_objectKey` is\n * read from the resolved document.\n */\n\ntype GetFilePrefixArgs = {\n  clientUploadContext?: unknown\n  collection: CollectionConfig\n  collectionPrefix?: string\n  doc?: { _objectKey?: string; prefix?: string } & TypeWithID\n  filename: string\n  /**\n   * Only narrows the access-controlled fallback lookup below; never trusted or\n   * returned directly. Prefer passing the access-checked document as `doc` instead.\n   */\n  prefixQueryParam?: string\n  req: PayloadRequest\n  useCompositePrefixes?: boolean\n}\nexport async function getFilePrefix({\n  clientUploadContext,\n  collection,\n  collectionPrefix,\n  doc,\n  filename,\n  prefixQueryParam,\n  req,\n  useCompositePrefixes = false,\n}: GetFilePrefixArgs): Promise<string> {\n  // The serve path already loaded and authorized this document — trust it over any\n  // client-supplied upload context or query prefix.\n  if (doc) {\n    return buildPrefixWithObjectKey({ objectKey: doc._objectKey, prefix: doc.prefix })\n  }\n\n  // Client uploads call handlers without a document yet. Re-contain the claimed\n  // prefix — it hasn't been verified against a signed receipt by every adapter.\n  if (\n    clientUploadContext &&\n    typeof clientUploadContext === 'object' &&\n    'prefix' in clientUploadContext &&\n    typeof clientUploadContext.prefix === 'string'\n  ) {\n    const contextObjectKey: string | undefined =\n      '_objectKey' in clientUploadContext\n        ? ((clientUploadContext as { _objectKey?: unknown })._objectKey as string)\n        : undefined\n    const containedPrefix = buildUploadStoragePathData({\n      collectionPrefix,\n      docPrefix: clientUploadContext.prefix,\n      filename,\n      useCompositePrefixes,\n    }).sanitizedDocPrefix\n    return buildPrefixWithObjectKey({\n      objectKey: contextObjectKey,\n      prefix: containedPrefix,\n    })\n  }\n\n  // Reads without a query prefix or read-access constraints skip the endpoint's document lookup.\n  const imageSizes = (collection?.upload as UploadConfig)?.imageSizes || []\n\n  const filenameClause = {\n    or: [\n      {\n        filename: { equals: filename },\n      },\n      ...imageSizes.map((imageSize) => ({\n        [`sizes.${imageSize.name}.filename`]: { equals: filename },\n      })),\n    ],\n  }\n\n  // Only filter by prefix when the collection persists a `prefix` field (querying a missing field throws).\n  const hasPrefixField = collection.fields?.some(\n    (field) => 'name' in field && field.name === 'prefix',\n  )\n  const where =\n    typeof prefixQueryParam === 'string' && hasPrefixField\n      ? { and: [filenameClause, { prefix: { equals: sanitizePrefix(prefixQueryParam) } }] }\n      : filenameClause\n\n  const files = await req.payload.find({\n    collection: collection.slug,\n    depth: 0,\n    draft: true,\n    limit: 1,\n    overrideAccess: false,\n    pagination: false,\n    req,\n    select: {\n      _objectKey: true,\n      prefix: true,\n    },\n    where,\n  })\n\n  const found = files?.docs?.[0] as { _objectKey?: string; prefix?: string } | undefined\n  return buildPrefixWithObjectKey({ objectKey: found?._objectKey, prefix: found?.prefix })\n}\n\n/**\n * Serve-path helper: resolves the authorized folder with {@link getFilePrefix}, then returns the\n * full object key via {@link buildStoragePathData}. Read handlers use this so a key is never built from an\n * unresolved prefix.\n */\nexport async function getStorageFilePath(args: GetFilePrefixArgs): Promise<string> {\n  const docPrefix = await getFilePrefix(args)\n\n  return buildStoragePathData({\n    collectionPrefix: args.collectionPrefix,\n    docPrefix,\n    filename: args.filename,\n    useCompositePrefixes: args.useCompositePrefixes,\n  }).storageFilePath\n}\n"],"names":["buildPrefixWithObjectKey","buildStoragePathData","buildUploadStoragePathData","sanitizePrefix","getFilePrefix","clientUploadContext","collection","collectionPrefix","doc","filename","prefixQueryParam","req","useCompositePrefixes","objectKey","_objectKey","prefix","contextObjectKey","undefined","containedPrefix","docPrefix","sanitizedDocPrefix","imageSizes","upload","filenameClause","or","equals","map","imageSize","name","hasPrefixField","fields","some","field","where","and","files","payload","find","slug","depth","draft","limit","overrideAccess","pagination","select","found","docs","getStorageFilePath","args","storageFilePath"],"mappings":"AAEA,SAASA,wBAAwB,QAAQ,gCAA+B;AACxE,SAASC,oBAAoB,EAAEC,0BAA0B,QAAQ,4BAA2B;AAC5F,SAASC,cAAc,QAAQ,sBAAqB;AA0BpD,OAAO,eAAeC,cAAc,EAClCC,mBAAmB,EACnBC,UAAU,EACVC,gBAAgB,EAChBC,GAAG,EACHC,QAAQ,EACRC,gBAAgB,EAChBC,GAAG,EACHC,uBAAuB,KAAK,EACV;IAClB,iFAAiF;IACjF,kDAAkD;IAClD,IAAIJ,KAAK;QACP,OAAOR,yBAAyB;YAAEa,WAAWL,IAAIM,UAAU;YAAEC,QAAQP,IAAIO,MAAM;QAAC;IAClF;IAEA,8EAA8E;IAC9E,8EAA8E;IAC9E,IACEV,uBACA,OAAOA,wBAAwB,YAC/B,YAAYA,uBACZ,OAAOA,oBAAoBU,MAAM,KAAK,UACtC;QACA,MAAMC,mBACJ,gBAAgBX,sBACX,AAACA,oBAAiDS,UAAU,GAC7DG;QACN,MAAMC,kBAAkBhB,2BAA2B;YACjDK;YACAY,WAAWd,oBAAoBU,MAAM;YACrCN;YACAG;QACF,GAAGQ,kBAAkB;QACrB,OAAOpB,yBAAyB;YAC9Ba,WAAWG;YACXD,QAAQG;QACV;IACF;IAEA,+FAA+F;IAC/F,MAAMG,aAAa,AAACf,YAAYgB,QAAyBD,cAAc,EAAE;IAEzE,MAAME,iBAAiB;QACrBC,IAAI;YACF;gBACEf,UAAU;oBAAEgB,QAAQhB;gBAAS;YAC/B;eACGY,WAAWK,GAAG,CAAC,CAACC,YAAe,CAAA;oBAChC,CAAC,CAAC,MAAM,EAAEA,UAAUC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE;wBAAEH,QAAQhB;oBAAS;gBAC3D,CAAA;SACD;IACH;IAEA,yGAAyG;IACzG,MAAMoB,iBAAiBvB,WAAWwB,MAAM,EAAEC,KACxC,CAACC,QAAU,UAAUA,SAASA,MAAMJ,IAAI,KAAK;IAE/C,MAAMK,QACJ,OAAOvB,qBAAqB,YAAYmB,iBACpC;QAAEK,KAAK;YAACX;YAAgB;gBAAER,QAAQ;oBAAEU,QAAQtB,eAAeO;gBAAkB;YAAE;SAAE;IAAC,IAClFa;IAEN,MAAMY,QAAQ,MAAMxB,IAAIyB,OAAO,CAACC,IAAI,CAAC;QACnC/B,YAAYA,WAAWgC,IAAI;QAC3BC,OAAO;QACPC,OAAO;QACPC,OAAO;QACPC,gBAAgB;QAChBC,YAAY;QACZhC;QACAiC,QAAQ;YACN9B,YAAY;YACZC,QAAQ;QACV;QACAkB;IACF;IAEA,MAAMY,QAAQV,OAAOW,MAAM,CAAC,EAAE;IAC9B,OAAO9C,yBAAyB;QAAEa,WAAWgC,OAAO/B;QAAYC,QAAQ8B,OAAO9B;IAAO;AACxF;AAEA;;;;CAIC,GACD,OAAO,eAAegC,mBAAmBC,IAAuB;IAC9D,MAAM7B,YAAY,MAAMf,cAAc4C;IAEtC,OAAO/C,qBAAqB;QAC1BM,kBAAkByC,KAAKzC,gBAAgB;QACvCY;QACAV,UAAUuC,KAAKvC,QAAQ;QACvBG,sBAAsBoC,KAAKpC,oBAAoB;IACjD,GAAGqC,eAAe;AACpB"}

package/dist/utilities/getFilePrefix.spec.js

@@ -1,80 +1,226 @@
 import { describe, expect, it, vi } from 'vitest';
 import { getFilePrefix } from './getFilePrefix.js';
-const makeReq = (docs = [])=>({
+const makeReq = ({ docs = [] } = {})=>({
         payload: {
             find: vi.fn().mockResolvedValue({
                 docs
             })
         }
     });
-const makeCollection = ()=>({
+const makeCollection = ({ hasPrefixField = false } = {})=>({
         slug: 'media',
+        fields: hasPrefixField ? [
+            {
+                name: 'prefix',
+                type: 'text'
+            }
+        ] : [],
         upload: {}
     });
+const whereOf = (req)=>JSON.stringify(req.payload.find.mock.calls[0][0].where);
 describe('getFilePrefix', ()=>{
-    describe('prefixQueryParam shortcut', ()=>{
-        it('should return prefixQueryParam immediately without querying the database', async ()=>{
-            const req = makeReq();
+    it('prefers an already-authorized document over a client upload context or query prefix', async ()=>{
+        const req = makeReq({
+            docs: [
+                {
+                    prefix: 'db-prefix'
+                }
+            ]
+        });
+        const doc = {
+            id: 1,
+            prefix: 'invoices'
+        };
+        const result = await getFilePrefix({
+            clientUploadContext: {
+                prefix: 'reference-prefix'
+            },
+            collection: makeCollection(),
+            collectionPrefix: 'media',
+            doc,
+            filename: 'logo.png',
+            prefixQueryParam: 'query-prefix',
+            req
+        });
+        expect(result).toBe('invoices');
+        expect(req.payload.find).not.toHaveBeenCalled();
+    });
+    it('does not fall back to a lookup when the checked document has no prefix', async ()=>{
+        const req = makeReq({
+            docs: [
+                {
+                    prefix: 'db-prefix'
+                }
+            ]
+        });
+        const result = await getFilePrefix({
+            collection: makeCollection(),
+            collectionPrefix: 'media',
+            doc: {
+                id: 1
+            },
+            filename: 'logo.png',
+            req
+        });
+        expect(result).toBe('');
+        expect(req.payload.find).not.toHaveBeenCalled();
+    });
+    it('contains a client upload context prefix beneath the collection prefix', async ()=>{
+        const req = makeReq({
+            docs: [
+                {
+                    prefix: 'invoices'
+                }
+            ]
+        });
+        const result = await getFilePrefix({
+            clientUploadContext: {
+                prefix: 'invoices'
+            },
+            collection: makeCollection(),
+            collectionPrefix: 'media',
+            filename: 'file.png',
+            req
+        });
+        expect(result).toBe('media/invoices');
+        expect(req.payload.find).not.toHaveBeenCalled();
+    });
+    describe('authorized document (trusted)', ()=>{
+        it('folds the object key into the document prefix and skips the database', async ()=>{
+            const req = makeReq({
+                docs: [
+                    {
+                        prefix: 'db-prefix'
+                    }
+                ]
+            });
             const result = await getFilePrefix({
                 collection: makeCollection(),
-                prefixQueryParam: 'uuid-prefix',
+                doc: {
+                    id: 1,
+                    _objectKey: 'abc123',
+                    prefix: 'doc-prefix'
+                },
                 filename: 'logo.png',
                 req
             });
-            expect(result).toBe('uuid-prefix');
+            expect(result).toBe('doc-prefix/abc123');
             expect(req.payload.find).not.toHaveBeenCalled();
         });
-        it('should return an empty string when prefixQueryParam is an empty string', async ()=>{
+        it('returns the document prefix alone when it has no object key', async ()=>{
             const req = makeReq();
             const result = await getFilePrefix({
                 collection: makeCollection(),
-                prefixQueryParam: '',
+                doc: {
+                    id: 1,
+                    prefix: 'doc-prefix'
+                },
                 filename: 'logo.png',
                 req
             });
-            expect(result).toBe('');
-            expect(req.payload.find).not.toHaveBeenCalled();
+            expect(result).toBe('doc-prefix');
         });
-        it('should reject multi-encoded values', async ()=>{
+        it('sanitizes the document prefix', async ()=>{
             const req = makeReq();
             const result = await getFilePrefix({
                 collection: makeCollection(),
-                prefixQueryParam: '%252e%252e%252fsecret%252f..%252fok',
+                doc: {
+                    id: 1,
+                    prefix: '../secret'
+                },
                 filename: 'logo.png',
                 req
             });
-            expect(result).toBe('');
-            expect(req.payload.find).not.toHaveBeenCalled();
+            expect(result).toBe('secret');
         });
-        it('should reject malformed percent-encoding', async ()=>{
+    });
+    describe('verified clientUploadContext (trusted)', ()=>{
+        it('folds the server-owned object key into the prefix and skips the database', async ()=>{
             const req = makeReq();
             const result = await getFilePrefix({
+                clientUploadContext: {
+                    _objectKey: 'abc123',
+                    prefix: 'documents'
+                },
                 collection: makeCollection(),
-                prefixQueryParam: '%E0%A4%A',
                 filename: 'logo.png',
                 req
             });
-            expect(result).toBe('');
+            expect(result).toBe('documents/abc123');
             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'
-                }
-            ]);
+        it('returns the prefix alone when the context has no object key', async ()=>{
+            const req = makeReq();
             const result = await getFilePrefix({
+                clientUploadContext: {
+                    prefix: 'documents'
+                },
                 collection: makeCollection(),
                 filename: 'logo.png',
                 req
             });
-            expect(result).toBe('db-prefix');
+            expect(result).toBe('documents');
+        });
+    });
+    describe('access-controlled database resolution', ()=>{
+        it('does NOT short-circuit on a client-supplied prefix — the access-controlled query still runs', async ()=>{
+            const req = makeReq({
+                docs: [
+                    {
+                        _objectKey: 'abc123',
+                        prefix: 'documents'
+                    }
+                ]
+            });
+            await getFilePrefix({
+                collection: makeCollection({
+                    hasPrefixField: true
+                }),
+                filename: 'logo.png',
+                prefixQueryParam: 'documents',
+                req
+            });
+            // A client-supplied prefix must not bypass the access-controlled lookup.
             expect(req.payload.find).toHaveBeenCalledOnce();
         });
-        it('should return empty string when no document is found', async ()=>{
-            const req = makeReq([]);
+        it('queries with access control enabled', async ()=>{
+            const req = makeReq({
+                docs: [
+                    {
+                        prefix: 'db-prefix'
+                    }
+                ]
+            });
+            await getFilePrefix({
+                collection: makeCollection(),
+                filename: 'logo.png',
+                req
+            });
+            expect(req.payload.find).toHaveBeenCalledWith(expect.objectContaining({
+                overrideAccess: false,
+                req
+            }));
+        });
+        it('folds the stored object key into the resolved prefix', async ()=>{
+            const req = makeReq({
+                docs: [
+                    {
+                        _objectKey: 'abc123',
+                        prefix: 'db-prefix'
+                    }
+                ]
+            });
+            const result = await getFilePrefix({
+                collection: makeCollection(),
+                filename: 'logo.png',
+                req
+            });
+            expect(result).toBe('db-prefix/abc123');
+        });
+        it('returns an empty string when no document is found', async ()=>{
+            const req = makeReq({
+                docs: []
+            });
             const result = await getFilePrefix({
                 collection: makeCollection(),
                 filename: 'logo.png',
@@ -82,12 +228,14 @@ describe('getFilePrefix', ()=>{
             });
             expect(result).toBe('');
         });
-        it('should prioritize clientUploadContext prefix over database query', async ()=>{
-            const req = makeReq([
-                {
-                    prefix: 'db-prefix'
-                }
-            ]);
+        it('prioritizes a verified clientUploadContext over the database query', async ()=>{
+            const req = makeReq({
+                docs: [
+                    {
+                        prefix: 'db-prefix'
+                    }
+                ]
+            });
             const result = await getFilePrefix({
                 clientUploadContext: {
                     prefix: 'context-prefix'
@@ -100,6 +248,44 @@ describe('getFilePrefix', ()=>{
             expect(req.payload.find).not.toHaveBeenCalled();
         });
     });
+    describe('client prefix as a disambiguation filter only', ()=>{
+        it('adds the prefix filter when the collection persists a prefix field', async ()=>{
+            const req = makeReq({
+                docs: [
+                    {
+                        prefix: 'documents'
+                    }
+                ]
+            });
+            await getFilePrefix({
+                collection: makeCollection({
+                    hasPrefixField: true
+                }),
+                filename: 'logo.png',
+                prefixQueryParam: 'documents',
+                req
+            });
+            expect(whereOf(req)).toContain('prefix');
+        });
+        it('omits the prefix filter when the collection has no prefix field (avoids querying a missing field)', async ()=>{
+            const req = makeReq({
+                docs: [
+                    {
+                        prefix: ''
+                    }
+                ]
+            });
+            await getFilePrefix({
+                collection: makeCollection({
+                    hasPrefixField: false
+                }),
+                filename: 'logo.png',
+                prefixQueryParam: 'anything',
+                req
+            });
+            expect(whereOf(req)).not.toContain('prefix');
+        });
+    });
 });
 
 //# sourceMappingURL=getFilePrefix.spec.js.map

package/dist/utilities/getFilePrefix.spec.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utilities/getFilePrefix.spec.ts"],"sourcesContent":["import { describe, expect, it, vi } from 'vitest'\n\nimport type { CollectionConfig, PayloadRequest } from 'payload'\n\nimport { getFilePrefix } from './getFilePrefix.js'\n\nconst makeReq = (docs: unknown[] = []) =>\n  ({\n    payload: {\n      find: vi.fn().mockResolvedValue({ docs }),\n    },\n  }) as unknown as PayloadRequest\n\nconst makeCollection = (): CollectionConfig =>\n  ({ slug: 'media', upload: {} }) as unknown as CollectionConfig\n\ndescribe('getFilePrefix', () => {\n  describe('prefixQueryParam shortcut', () => {\n    it('should return prefixQueryParam immediately without querying the database', async () => {\n      const req = makeReq()\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        prefixQueryParam: 'uuid-prefix',\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('uuid-prefix')\n      expect(req.payload.find).not.toHaveBeenCalled()\n    })\n\n    it('should return an empty string when prefixQueryParam is an empty string', async () => {\n      const req = makeReq()\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        prefixQueryParam: '',\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('')\n      expect(req.payload.find).not.toHaveBeenCalled()\n    })\n\n    it('should reject multi-encoded values', async () => {\n      const req = makeReq()\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        prefixQueryParam: '%252e%252e%252fsecret%252f..%252fok',\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('')\n      expect(req.payload.find).not.toHaveBeenCalled()\n    })\n\n    it('should reject malformed percent-encoding', async () => {\n      const req = makeReq()\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        prefixQueryParam: '%E0%A4%A',\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('')\n      expect(req.payload.find).not.toHaveBeenCalled()\n    })\n  })\n\n  describe('database fallback', () => {\n    it('should query the database when prefixQueryParam is not provided', async () => {\n      const req = makeReq([{ prefix: 'db-prefix' }])\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('db-prefix')\n      expect(req.payload.find).toHaveBeenCalledOnce()\n    })\n\n    it('should return empty string when no document is found', async () => {\n      const req = makeReq([])\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('')\n    })\n\n    it('should prioritize clientUploadContext prefix over database query', async () => {\n      const req = makeReq([{ prefix: 'db-prefix' }])\n\n      const result = await getFilePrefix({\n        clientUploadContext: { prefix: 'context-prefix' },\n        collection: makeCollection(),\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('context-prefix')\n      expect(req.payload.find).not.toHaveBeenCalled()\n    })\n  })\n})\n"],"names":["describe","expect","it","vi","getFilePrefix","makeReq","docs","payload","find","fn","mockResolvedValue","makeCollection","slug","upload","req","result","collection","prefixQueryParam","filename","toBe","not","toHaveBeenCalled","prefix","toHaveBeenCalledOnce","clientUploadContext"],"mappings":"AAAA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,EAAEC,EAAE,QAAQ,SAAQ;AAIjD,SAASC,aAAa,QAAQ,qBAAoB;AAElD,MAAMC,UAAU,CAACC,OAAkB,EAAE,GAClC,CAAA;QACCC,SAAS;YACPC,MAAML,GAAGM,EAAE,GAAGC,iBAAiB,CAAC;gBAAEJ;YAAK;QACzC;IACF,CAAA;AAEF,MAAMK,iBAAiB,IACpB,CAAA;QAAEC,MAAM;QAASC,QAAQ,CAAC;IAAE,CAAA;AAE/Bb,SAAS,iBAAiB;IACxBA,SAAS,6BAA6B;QACpCE,GAAG,4EAA4E;YAC7E,MAAMY,MAAMT;YAEZ,MAAMU,SAAS,MAAMX,cAAc;gBACjCY,YAAYL;gBACZM,kBAAkB;gBAClBC,UAAU;gBACVJ;YACF;YAEAb,OAAOc,QAAQI,IAAI,CAAC;YACpBlB,OAAOa,IAAIP,OAAO,CAACC,IAAI,EAAEY,GAAG,CAACC,gBAAgB;QAC/C;QAEAnB,GAAG,0EAA0E;YAC3E,MAAMY,MAAMT;YAEZ,MAAMU,SAAS,MAAMX,cAAc;gBACjCY,YAAYL;gBACZM,kBAAkB;gBAClBC,UAAU;gBACVJ;YACF;YAEAb,OAAOc,QAAQI,IAAI,CAAC;YACpBlB,OAAOa,IAAIP,OAAO,CAACC,IAAI,EAAEY,GAAG,CAACC,gBAAgB;QAC/C;QAEAnB,GAAG,sCAAsC;YACvC,MAAMY,MAAMT;YAEZ,MAAMU,SAAS,MAAMX,cAAc;gBACjCY,YAAYL;gBACZM,kBAAkB;gBAClBC,UAAU;gBACVJ;YACF;YAEAb,OAAOc,QAAQI,IAAI,CAAC;YACpBlB,OAAOa,IAAIP,OAAO,CAACC,IAAI,EAAEY,GAAG,CAACC,gBAAgB;QAC/C;QAEAnB,GAAG,4CAA4C;YAC7C,MAAMY,MAAMT;YAEZ,MAAMU,SAAS,MAAMX,cAAc;gBACjCY,YAAYL;gBACZM,kBAAkB;gBAClBC,UAAU;gBACVJ;YACF;YAEAb,OAAOc,QAAQI,IAAI,CAAC;YACpBlB,OAAOa,IAAIP,OAAO,CAACC,IAAI,EAAEY,GAAG,CAACC,gBAAgB;QAC/C;IACF;IAEArB,SAAS,qBAAqB;QAC5BE,GAAG,mEAAmE;YACpE,MAAMY,MAAMT,QAAQ;gBAAC;oBAAEiB,QAAQ;gBAAY;aAAE;YAE7C,MAAMP,SAAS,MAAMX,cAAc;gBACjCY,YAAYL;gBACZO,UAAU;gBACVJ;YACF;YAEAb,OAAOc,QAAQI,IAAI,CAAC;YACpBlB,OAAOa,IAAIP,OAAO,CAACC,IAAI,EAAEe,oBAAoB;QAC/C;QAEArB,GAAG,wDAAwD;YACzD,MAAMY,MAAMT,QAAQ,EAAE;YAEtB,MAAMU,SAAS,MAAMX,cAAc;gBACjCY,YAAYL;gBACZO,UAAU;gBACVJ;YACF;YAEAb,OAAOc,QAAQI,IAAI,CAAC;QACtB;QAEAjB,GAAG,oEAAoE;YACrE,MAAMY,MAAMT,QAAQ;gBAAC;oBAAEiB,QAAQ;gBAAY;aAAE;YAE7C,MAAMP,SAAS,MAAMX,cAAc;gBACjCoB,qBAAqB;oBAAEF,QAAQ;gBAAiB;gBAChDN,YAAYL;gBACZO,UAAU;gBACVJ;YACF;YAEAb,OAAOc,QAAQI,IAAI,CAAC;YACpBlB,OAAOa,IAAIP,OAAO,CAACC,IAAI,EAAEY,GAAG,CAACC,gBAAgB;QAC/C;IACF;AACF"}
+{"version":3,"sources":["../../src/utilities/getFilePrefix.spec.ts"],"sourcesContent":["import type { CollectionConfig, PayloadRequest } from 'payload'\n\nimport { describe, expect, it, vi } from 'vitest'\n\nimport { getFilePrefix } from './getFilePrefix.js'\n\nconst makeReq = ({ docs = [] }: { docs?: unknown[] } = {}) =>\n  ({\n    payload: {\n      find: vi.fn().mockResolvedValue({ docs }),\n    },\n  }) as unknown as PayloadRequest\n\nconst makeCollection = ({\n  hasPrefixField = false,\n}: { hasPrefixField?: boolean } = {}): CollectionConfig =>\n  ({\n    slug: 'media',\n    fields: hasPrefixField ? [{ name: 'prefix', type: 'text' }] : [],\n    upload: {},\n  }) as unknown as CollectionConfig\n\nconst whereOf = (req: PayloadRequest) =>\n  JSON.stringify(\n    (req.payload.find as unknown as { mock: { calls: [{ where: unknown }][] } }).mock.calls[0][0]\n      .where,\n  )\n\ndescribe('getFilePrefix', () => {\n  it('prefers an already-authorized document over a client upload context or query prefix', async () => {\n    const req = makeReq({ docs: [{ prefix: 'db-prefix' }] })\n    const doc = { id: 1, prefix: 'invoices' }\n\n    const result = await getFilePrefix({\n      clientUploadContext: { prefix: 'reference-prefix' },\n      collection: makeCollection(),\n      collectionPrefix: 'media',\n      doc,\n      filename: 'logo.png',\n      prefixQueryParam: 'query-prefix',\n      req,\n    })\n\n    expect(result).toBe('invoices')\n    expect(req.payload.find).not.toHaveBeenCalled()\n  })\n\n  it('does not fall back to a lookup when the checked document has no prefix', async () => {\n    const req = makeReq({ docs: [{ prefix: 'db-prefix' }] })\n\n    const result = await getFilePrefix({\n      collection: makeCollection(),\n      collectionPrefix: 'media',\n      doc: { id: 1 },\n      filename: 'logo.png',\n      req,\n    })\n\n    expect(result).toBe('')\n    expect(req.payload.find).not.toHaveBeenCalled()\n  })\n\n  it('contains a client upload context prefix beneath the collection prefix', async () => {\n    const req = makeReq({ docs: [{ prefix: 'invoices' }] })\n\n    const result = await getFilePrefix({\n      clientUploadContext: { prefix: 'invoices' },\n      collection: makeCollection(),\n      collectionPrefix: 'media',\n      filename: 'file.png',\n      req,\n    })\n\n    expect(result).toBe('media/invoices')\n    expect(req.payload.find).not.toHaveBeenCalled()\n  })\n\n  describe('authorized document (trusted)', () => {\n    it('folds the object key into the document prefix and skips the database', async () => {\n      const req = makeReq({ docs: [{ prefix: 'db-prefix' }] })\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        doc: { id: 1, _objectKey: 'abc123', prefix: 'doc-prefix' },\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('doc-prefix/abc123')\n      expect(req.payload.find).not.toHaveBeenCalled()\n    })\n\n    it('returns the document prefix alone when it has no object key', async () => {\n      const req = makeReq()\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        doc: { id: 1, prefix: 'doc-prefix' },\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('doc-prefix')\n    })\n\n    it('sanitizes the document prefix', async () => {\n      const req = makeReq()\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        doc: { id: 1, prefix: '../secret' },\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('secret')\n    })\n  })\n\n  describe('verified clientUploadContext (trusted)', () => {\n    it('folds the server-owned object key into the prefix and skips the database', async () => {\n      const req = makeReq()\n\n      const result = await getFilePrefix({\n        clientUploadContext: { _objectKey: 'abc123', prefix: 'documents' },\n        collection: makeCollection(),\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('documents/abc123')\n      expect(req.payload.find).not.toHaveBeenCalled()\n    })\n\n    it('returns the prefix alone when the context has no object key', async () => {\n      const req = makeReq()\n\n      const result = await getFilePrefix({\n        clientUploadContext: { prefix: 'documents' },\n        collection: makeCollection(),\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('documents')\n    })\n  })\n\n  describe('access-controlled database resolution', () => {\n    it('does NOT short-circuit on a client-supplied prefix — the access-controlled query still runs', async () => {\n      const req = makeReq({ docs: [{ _objectKey: 'abc123', prefix: 'documents' }] })\n\n      await getFilePrefix({\n        collection: makeCollection({ hasPrefixField: true }),\n        filename: 'logo.png',\n        prefixQueryParam: 'documents',\n        req,\n      })\n\n      // A client-supplied prefix must not bypass the access-controlled lookup.\n      expect(req.payload.find).toHaveBeenCalledOnce()\n    })\n\n    it('queries with access control enabled', async () => {\n      const req = makeReq({ docs: [{ prefix: 'db-prefix' }] })\n\n      await getFilePrefix({\n        collection: makeCollection(),\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(req.payload.find).toHaveBeenCalledWith(\n        expect.objectContaining({ overrideAccess: false, req }),\n      )\n    })\n\n    it('folds the stored object key into the resolved prefix', async () => {\n      const req = makeReq({ docs: [{ _objectKey: 'abc123', prefix: 'db-prefix' }] })\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('db-prefix/abc123')\n    })\n\n    it('returns an empty string when no document is found', async () => {\n      const req = makeReq({ docs: [] })\n\n      const result = await getFilePrefix({\n        collection: makeCollection(),\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('')\n    })\n\n    it('prioritizes a verified clientUploadContext over the database query', async () => {\n      const req = makeReq({ docs: [{ prefix: 'db-prefix' }] })\n\n      const result = await getFilePrefix({\n        clientUploadContext: { prefix: 'context-prefix' },\n        collection: makeCollection(),\n        filename: 'logo.png',\n        req,\n      })\n\n      expect(result).toBe('context-prefix')\n      expect(req.payload.find).not.toHaveBeenCalled()\n    })\n  })\n\n  describe('client prefix as a disambiguation filter only', () => {\n    it('adds the prefix filter when the collection persists a prefix field', async () => {\n      const req = makeReq({ docs: [{ prefix: 'documents' }] })\n\n      await getFilePrefix({\n        collection: makeCollection({ hasPrefixField: true }),\n        filename: 'logo.png',\n        prefixQueryParam: 'documents',\n        req,\n      })\n\n      expect(whereOf(req)).toContain('prefix')\n    })\n\n    it('omits the prefix filter when the collection has no prefix field (avoids querying a missing field)', async () => {\n      const req = makeReq({ docs: [{ prefix: '' }] })\n\n      await getFilePrefix({\n        collection: makeCollection({ hasPrefixField: false }),\n        filename: 'logo.png',\n        prefixQueryParam: 'anything',\n        req,\n      })\n\n      expect(whereOf(req)).not.toContain('prefix')\n    })\n  })\n})\n"],"names":["describe","expect","it","vi","getFilePrefix","makeReq","docs","payload","find","fn","mockResolvedValue","makeCollection","hasPrefixField","slug","fields","name","type","upload","whereOf","req","JSON","stringify","mock","calls","where","prefix","doc","id","result","clientUploadContext","collection","collectionPrefix","filename","prefixQueryParam","toBe","not","toHaveBeenCalled","_objectKey","toHaveBeenCalledOnce","toHaveBeenCalledWith","objectContaining","overrideAccess","toContain"],"mappings":"AAEA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,EAAEC,EAAE,QAAQ,SAAQ;AAEjD,SAASC,aAAa,QAAQ,qBAAoB;AAElD,MAAMC,UAAU,CAAC,EAAEC,OAAO,EAAE,EAAwB,GAAG,CAAC,CAAC,GACtD,CAAA;QACCC,SAAS;YACPC,MAAML,GAAGM,EAAE,GAAGC,iBAAiB,CAAC;gBAAEJ;YAAK;QACzC;IACF,CAAA;AAEF,MAAMK,iBAAiB,CAAC,EACtBC,iBAAiB,KAAK,EACO,GAAG,CAAC,CAAC,GACjC,CAAA;QACCC,MAAM;QACNC,QAAQF,iBAAiB;YAAC;gBAAEG,MAAM;gBAAUC,MAAM;YAAO;SAAE,GAAG,EAAE;QAChEC,QAAQ,CAAC;IACX,CAAA;AAEF,MAAMC,UAAU,CAACC,MACfC,KAAKC,SAAS,CACZ,AAACF,IAAIZ,OAAO,CAACC,IAAI,CAA4Dc,IAAI,CAACC,KAAK,CAAC,EAAE,CAAC,EAAE,CAC1FC,KAAK;AAGZxB,SAAS,iBAAiB;IACxBE,GAAG,uFAAuF;QACxF,MAAMiB,MAAMd,QAAQ;YAAEC,MAAM;gBAAC;oBAAEmB,QAAQ;gBAAY;aAAE;QAAC;QACtD,MAAMC,MAAM;YAAEC,IAAI;YAAGF,QAAQ;QAAW;QAExC,MAAMG,SAAS,MAAMxB,cAAc;YACjCyB,qBAAqB;gBAAEJ,QAAQ;YAAmB;YAClDK,YAAYnB;YACZoB,kBAAkB;YAClBL;YACAM,UAAU;YACVC,kBAAkB;YAClBd;QACF;QAEAlB,OAAO2B,QAAQM,IAAI,CAAC;QACpBjC,OAAOkB,IAAIZ,OAAO,CAACC,IAAI,EAAE2B,GAAG,CAACC,gBAAgB;IAC/C;IAEAlC,GAAG,0EAA0E;QAC3E,MAAMiB,MAAMd,QAAQ;YAAEC,MAAM;gBAAC;oBAAEmB,QAAQ;gBAAY;aAAE;QAAC;QAEtD,MAAMG,SAAS,MAAMxB,cAAc;YACjC0B,YAAYnB;YACZoB,kBAAkB;YAClBL,KAAK;gBAAEC,IAAI;YAAE;YACbK,UAAU;YACVb;QACF;QAEAlB,OAAO2B,QAAQM,IAAI,CAAC;QACpBjC,OAAOkB,IAAIZ,OAAO,CAACC,IAAI,EAAE2B,GAAG,CAACC,gBAAgB;IAC/C;IAEAlC,GAAG,yEAAyE;QAC1E,MAAMiB,MAAMd,QAAQ;YAAEC,MAAM;gBAAC;oBAAEmB,QAAQ;gBAAW;aAAE;QAAC;QAErD,MAAMG,SAAS,MAAMxB,cAAc;YACjCyB,qBAAqB;gBAAEJ,QAAQ;YAAW;YAC1CK,YAAYnB;YACZoB,kBAAkB;YAClBC,UAAU;YACVb;QACF;QAEAlB,OAAO2B,QAAQM,IAAI,CAAC;QACpBjC,OAAOkB,IAAIZ,OAAO,CAACC,IAAI,EAAE2B,GAAG,CAACC,gBAAgB;IAC/C;IAEApC,SAAS,iCAAiC;QACxCE,GAAG,wEAAwE;YACzE,MAAMiB,MAAMd,QAAQ;gBAAEC,MAAM;oBAAC;wBAAEmB,QAAQ;oBAAY;iBAAE;YAAC;YAEtD,MAAMG,SAAS,MAAMxB,cAAc;gBACjC0B,YAAYnB;gBACZe,KAAK;oBAAEC,IAAI;oBAAGU,YAAY;oBAAUZ,QAAQ;gBAAa;gBACzDO,UAAU;gBACVb;YACF;YAEAlB,OAAO2B,QAAQM,IAAI,CAAC;YACpBjC,OAAOkB,IAAIZ,OAAO,CAACC,IAAI,EAAE2B,GAAG,CAACC,gBAAgB;QAC/C;QAEAlC,GAAG,+DAA+D;YAChE,MAAMiB,MAAMd;YAEZ,MAAMuB,SAAS,MAAMxB,cAAc;gBACjC0B,YAAYnB;gBACZe,KAAK;oBAAEC,IAAI;oBAAGF,QAAQ;gBAAa;gBACnCO,UAAU;gBACVb;YACF;YAEAlB,OAAO2B,QAAQM,IAAI,CAAC;QACtB;QAEAhC,GAAG,iCAAiC;YAClC,MAAMiB,MAAMd;YAEZ,MAAMuB,SAAS,MAAMxB,cAAc;gBACjC0B,YAAYnB;gBACZe,KAAK;oBAAEC,IAAI;oBAAGF,QAAQ;gBAAY;gBAClCO,UAAU;gBACVb;YACF;YAEAlB,OAAO2B,QAAQM,IAAI,CAAC;QACtB;IACF;IAEAlC,SAAS,0CAA0C;QACjDE,GAAG,4EAA4E;YAC7E,MAAMiB,MAAMd;YAEZ,MAAMuB,SAAS,MAAMxB,cAAc;gBACjCyB,qBAAqB;oBAAEQ,YAAY;oBAAUZ,QAAQ;gBAAY;gBACjEK,YAAYnB;gBACZqB,UAAU;gBACVb;YACF;YAEAlB,OAAO2B,QAAQM,IAAI,CAAC;YACpBjC,OAAOkB,IAAIZ,OAAO,CAACC,IAAI,EAAE2B,GAAG,CAACC,gBAAgB;QAC/C;QAEAlC,GAAG,+DAA+D;YAChE,MAAMiB,MAAMd;YAEZ,MAAMuB,SAAS,MAAMxB,cAAc;gBACjCyB,qBAAqB;oBAAEJ,QAAQ;gBAAY;gBAC3CK,YAAYnB;gBACZqB,UAAU;gBACVb;YACF;YAEAlB,OAAO2B,QAAQM,IAAI,CAAC;QACtB;IACF;IAEAlC,SAAS,yCAAyC;QAChDE,GAAG,+FAA+F;YAChG,MAAMiB,MAAMd,QAAQ;gBAAEC,MAAM;oBAAC;wBAAE+B,YAAY;wBAAUZ,QAAQ;oBAAY;iBAAE;YAAC;YAE5E,MAAMrB,cAAc;gBAClB0B,YAAYnB,eAAe;oBAAEC,gBAAgB;gBAAK;gBAClDoB,UAAU;gBACVC,kBAAkB;gBAClBd;YACF;YAEA,yEAAyE;YACzElB,OAAOkB,IAAIZ,OAAO,CAACC,IAAI,EAAE8B,oBAAoB;QAC/C;QAEApC,GAAG,uCAAuC;YACxC,MAAMiB,MAAMd,QAAQ;gBAAEC,MAAM;oBAAC;wBAAEmB,QAAQ;oBAAY;iBAAE;YAAC;YAEtD,MAAMrB,cAAc;gBAClB0B,YAAYnB;gBACZqB,UAAU;gBACVb;YACF;YAEAlB,OAAOkB,IAAIZ,OAAO,CAACC,IAAI,EAAE+B,oBAAoB,CAC3CtC,OAAOuC,gBAAgB,CAAC;gBAAEC,gBAAgB;gBAAOtB;YAAI;QAEzD;QAEAjB,GAAG,wDAAwD;YACzD,MAAMiB,MAAMd,QAAQ;gBAAEC,MAAM;oBAAC;wBAAE+B,YAAY;wBAAUZ,QAAQ;oBAAY;iBAAE;YAAC;YAE5E,MAAMG,SAAS,MAAMxB,cAAc;gBACjC0B,YAAYnB;gBACZqB,UAAU;gBACVb;YACF;YAEAlB,OAAO2B,QAAQM,IAAI,CAAC;QACtB;QAEAhC,GAAG,qDAAqD;YACtD,MAAMiB,MAAMd,QAAQ;gBAAEC,MAAM,EAAE;YAAC;YAE/B,MAAMsB,SAAS,MAAMxB,cAAc;gBACjC0B,YAAYnB;gBACZqB,UAAU;gBACVb;YACF;YAEAlB,OAAO2B,QAAQM,IAAI,CAAC;QACtB;QAEAhC,GAAG,sEAAsE;YACvE,MAAMiB,MAAMd,QAAQ;gBAAEC,MAAM;oBAAC;wBAAEmB,QAAQ;oBAAY;iBAAE;YAAC;YAEtD,MAAMG,SAAS,MAAMxB,cAAc;gBACjCyB,qBAAqB;oBAAEJ,QAAQ;gBAAiB;gBAChDK,YAAYnB;gBACZqB,UAAU;gBACVb;YACF;YAEAlB,OAAO2B,QAAQM,IAAI,CAAC;YACpBjC,OAAOkB,IAAIZ,OAAO,CAACC,IAAI,EAAE2B,GAAG,CAACC,gBAAgB;QAC/C;IACF;IAEApC,SAAS,iDAAiD;QACxDE,GAAG,sEAAsE;YACvE,MAAMiB,MAAMd,QAAQ;gBAAEC,MAAM;oBAAC;wBAAEmB,QAAQ;oBAAY;iBAAE;YAAC;YAEtD,MAAMrB,cAAc;gBAClB0B,YAAYnB,eAAe;oBAAEC,gBAAgB;gBAAK;gBAClDoB,UAAU;gBACVC,kBAAkB;gBAClBd;YACF;YAEAlB,OAAOiB,QAAQC,MAAMuB,SAAS,CAAC;QACjC;QAEAxC,GAAG,qGAAqG;YACtG,MAAMiB,MAAMd,QAAQ;gBAAEC,MAAM;oBAAC;wBAAEmB,QAAQ;oBAAG;iBAAE;YAAC;YAE7C,MAAMrB,cAAc;gBAClB0B,YAAYnB,eAAe;oBAAEC,gBAAgB;gBAAM;gBACnDoB,UAAU;gBACVC,kBAAkB;gBAClBd;YACF;YAEAlB,OAAOiB,QAAQC,MAAMgB,GAAG,CAACO,SAAS,CAAC;QACrC;IACF;AACF"}

package/dist/utilities/resolveSignedURLKey.d.ts

@@ -1,4 +1,5 @@
 import type { PayloadRequest } from 'payload';
+import type { ClientUploadContext } from '../types.js';
 type Args = {
     collectionPrefix?: string;
     collectionSlug: string;
@@ -12,13 +13,23 @@ type Args = {
  * the filename via {@link getSafeFileName} so a duplicate upload does not
  * overwrite an existing blob.
  *
+ * A per-upload segment is persisted in `_objectKey` (not `prefix`), so the stored `prefix`
+ * and `filename` stay clean.
+ *
  * The resolved `sanitizedFilename` is returned so the browser-side handler
  * can update the form via `updateFilename`.
+ *
+ * The semantic prefix is resolved with {@link buildUploadPrefix} and the final key with
+ * {@link buildUploadStoragePathData}, so the receipt only ever signs a key beneath the configured
+ * collection prefix.
  */
 export declare function resolveSignedURLKey({ collectionPrefix, collectionSlug, docPrefix, filename, req, useCompositePrefixes, }: Args): Promise<{
+    _objectKey: `${string}-${string}-${string}-${string}-${string}`;
+    clientUploadContext: ClientUploadContext;
     fileKey: string;
     sanitizedDocPrefix: string;
     sanitizedFilename: string;
+    storageFilePath: string;
 }>;
 export {};
 //# sourceMappingURL=resolveSignedURLKey.d.ts.map