@humaan/payload-storage-imagekit 2.6.2 → 2.7.0

package/dist/index.js

@@ -1,14 +1,17 @@
 import ImageKit, { toFile } from '@imagekit/nodejs';
 import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage';
+import { buildStoragePathData, buildUploadStoragePathData, getStorageFilePath, initClientUploads } from '@payloadcms/plugin-cloud-storage/utilities';
+import { openAsBlob } from 'node:fs';
 import path from 'node:path';
-import { getImageKitUploadAuthPath, isImageKitClientUploadContext } from './clientUploads.js';
+import { APIError } from 'payload';
+import { getRangeRequestInfo, isXmlMimeType, UPLOAD_CONTENT_SECURITY_POLICY } from 'payload/internal';
+import { validateMimeType } from 'payload/shared';
+import { imageKitUploadAuthPath, isImageKitReceiptContext } from './clientUploads.js';
+import { createImageKitClientUploadVerifier, getClientUploadStorageFilePath } from './clientUploadVerification.js';
 import { createImageKitUploadAuthHandler } from './endpoints/createImageKitUploadAuthHandler.js';
 import { getAdminThumbnailURL, getPrivateAdminThumbnailURL, isPdfMimeType, isVideoMimeType } from './getAdminThumbnailURL.js';
 import { getImageKitThumbnailSrc, getVideoPosterSrc } from './imageTransforms.js';
 const DEFAULT_SIGNED_URL_EXPIRES_IN = 900;
-// Payload's file-type detector samples this many bytes when validating binary uploads.
-const FILE_TYPE_DETECTION_SIZE = 4100;
-const FILE_TYPE_DETECTION_RANGE = `bytes=0-${FILE_TYPE_DETECTION_SIZE - 1}`;
 /**
  * ImageKit re-encodes some uploads and serves the smaller derivative from the plain
  * delivery URL — a 1.9 MB MP4 can come back as 868 KB. That is exactly what we want
@@ -19,6 +22,23 @@ const FILE_TYPE_DETECTION_RANGE = `bytes=0-${FILE_TYPE_DETECTION_SIZE - 1}`;
  */ const ORIGINAL_FILE_TRANSFORMATION = 'orig-true';
 const PRIVATE_COLLECTION_DESCRIPTION = 'Files in this collection are uploaded to ImageKit as private files and delivered through short-lived signed URLs.';
 const isPrivateCollectionConfig = (value)=>value !== true && typeof value === 'object' && value?.private === true;
+const XML_FAMILY_MIME_TYPES = [
+    'application/xml',
+    'image/svg+xml',
+    'text/xml'
+];
+const collectionCanStoreXml = (collection)=>{
+    const upload = collection.upload;
+    if (!upload || upload === true) {
+        return Boolean(upload);
+    }
+    // Payload skips MIME and content restrictions when this escape hatch is enabled.
+    if (upload.allowRestrictedFileTypes) {
+        return true;
+    }
+    const allowedMimeTypes = upload.mimeTypes;
+    return !allowedMimeTypes?.length || allowedMimeTypes.some((mimeType)=>mimeType.includes('*') || isXmlMimeType(mimeType)) || XML_FAMILY_MIME_TYPES.some((mimeType)=>validateMimeType(mimeType, allowedMimeTypes));
+};
 /**
  * Whether a specific document is private. The flag stored on the document at upload time
  * (`imagekit.isPrivate`) is the source of truth — a file's privacy on ImageKit is fixed
@@ -36,7 +56,6 @@ const normalizeFolder = (folder)=>{
     return `/${normalized}`;
 };
 const getCollectionFolder = (rootFolder, collectionSlug)=>path.posix.join(rootFolder, collectionSlug);
-const getFilePath = (rootFolder, collectionSlug, filename)=>path.posix.join(getCollectionFolder(rootFolder, collectionSlug), filename);
 const findImageKitFileId = async (imagekit, filePath)=>{
     const parentPath = path.posix.dirname(filePath);
     const name = path.posix.basename(filePath);
@@ -87,63 +106,66 @@ const findUploadDocumentByFilename = async ({ collection, filename, prefix, req
         }
     });
 };
-const applyClientUploadContextToData = (data, clientUploadContext, buildThumbnailURL = getAdminThumbnailURL, isPrivate = false)=>{
-    if (!isImageKitClientUploadContext(clientUploadContext)) {
-        return data;
-    }
+const applyVerifiedClientUploadToData = (data, uploaded, buildThumbnailURL = getAdminThumbnailURL, isPrivate)=>{
     data.imagekit = {
-        fileId: clientUploadContext.fileId,
-        // Record the collection's privacy at upload time; this is the file's permanent
-        // ImageKit status and the source of truth for delivery.
+        fileId: uploaded.fileId,
         isPrivate,
-        thumbnailUrl: clientUploadContext.thumbnailUrl,
-        url: clientUploadContext.url
+        thumbnailUrl: uploaded.thumbnailUrl,
+        url: uploaded.url
     };
     // Preserve the admin preview when the original file was already uploaded client-side.
     data.thumbnailURL = buildThumbnailURL(data);
     return data;
 };
-const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFolder, signedUrlExpiresIn, urlEndpoint })=>{
-    const fetchUploadedFile = async (fileURL, range)=>{
-        const response = range ? await fetch(fileURL, {
-            headers: {
-                Range: range
-            }
-        }) : await fetch(fileURL);
-        if (!response.ok) {
-            throw new Error(`imagekitStorage: failed to fetch uploaded file from ImageKit (${response.status}).`);
+const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFolder, signedUrlExpiresIn, urlEndpoint, verifyClientUpload })=>{
+    const fetchUploadedFile = async ({ fileSize, fileURL, mimeType, range })=>{
+        const rangeResult = getRangeRequestInfo({
+            fileSize,
+            rangeHeader: range ?? null
+        });
+        if (rangeResult.type === 'invalid') {
+            return new Response(null, {
+                headers: new Headers(rangeResult.headers),
+                status: rangeResult.status
+            });
         }
-        return response;
-    };
-    const fetchUploadedFilePrefix = async ({ fileSize, fileURL, mimeType })=>{
-        const response = await fetchUploadedFile(fileURL, FILE_TYPE_DETECTION_RANGE);
-        const contentLength = Number(response.headers.get('Content-Length'));
-        const contentRange = response.headers.get('Content-Range');
-        const rangeMatch = contentRange?.match(/^bytes 0-(\d+)\/(\d+)$/);
-        const rangeEnd = rangeMatch ? Number(rangeMatch[1]) : Number.NaN;
-        const totalSize = rangeMatch ? Number(rangeMatch[2]) : Number.NaN;
-        const expectedLength = Math.min(fileSize, FILE_TYPE_DETECTION_SIZE);
-        if (response.status !== 206 || !rangeMatch || !Number.isSafeInteger(contentLength) || contentLength !== expectedLength || !Number.isSafeInteger(rangeEnd) || rangeEnd + 1 !== contentLength || totalSize !== fileSize) {
-            // Deliberately not awaited. Under the instrumented `fetch` that Next.js and
-            // Vercel install, this promise never settles, so awaiting it swallows the error
-            // and hangs the request until the function times out (5 minutes on Vercel)
-            // instead of surfacing a 500.
-            void response.body?.cancel().catch(()=>{});
-            throw new Error('imagekitStorage: ImageKit returned an invalid video range response.');
+        const normalizedRange = rangeResult.type === 'partial' ? `bytes=${rangeResult.rangeStart}-${rangeResult.rangeEnd}` : undefined;
+        // Payload cancels image probes after reading a bounded prefix. Next.js memoizes
+        // GET responses by teeing their streams; cancelling one branch can then wait
+        // forever for its unread cached sibling. An explicit signal opts out of that
+        // memoization, while no-store also excludes these reads from the data cache.
+        const response = await fetch(fileURL, {
+            cache: 'no-store',
+            ...normalizedRange ? {
+                headers: {
+                    Range: normalizedRange
+                }
+            } : {},
+            signal: new AbortController().signal
+        });
+        if (!response.ok || response.status !== rangeResult.status) {
+            void response.body?.cancel().catch(()=>undefined);
+            throw new Error(`imagekitStorage: ImageKit returned an unexpected file response (${response.status}).`);
         }
-        const filePrefix = await response.arrayBuffer();
-        if (filePrefix.byteLength !== contentLength) {
-            throw new Error('imagekitStorage: ImageKit returned an invalid video range body.');
+        const upstreamLength = response.headers.get('Content-Length');
+        const expectedLength = rangeResult.headers['Content-Length'];
+        const upstreamRange = response.headers.get('Content-Range');
+        const expectedRange = rangeResult.type === 'partial' ? rangeResult.headers['Content-Range'] : undefined;
+        if (upstreamLength !== null && upstreamLength !== expectedLength || expectedRange && upstreamRange !== expectedRange) {
+            void response.body?.cancel().catch(()=>undefined);
+            throw new Error('imagekitStorage: ImageKit returned mismatched file content metadata.');
         }
-        return new Response(filePrefix, {
-            headers: {
-                'Content-Length': String(filePrefix.byteLength),
-                'Content-Type': mimeType
-            },
-            status: 200
+        const headers = new Headers(rangeResult.headers);
+        headers.set('Content-Type', mimeType);
+        if (isXmlMimeType(mimeType)) {
+            headers.set('Content-Security-Policy', UPLOAD_CONTENT_SECURITY_POLICY);
+        }
+        return new Response(response.body, {
+            headers,
+            status: response.status
         });
     };
-    return ({ collection })=>{
+    return ({ collection, prefix = getCollectionFolder(rootFolder, collection.slug) })=>{
         const isPrivate = privateSlugs.has(collection.slug);
         // Sign a relative ImageKit path against the configured urlEndpoint. We always sign
         // a computed path (never a stored absolute URL) because ImageKit's signature is
@@ -224,7 +246,14 @@ const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFo
                                         if (!filename) {
                                             return undefined;
                                         }
-                                        return buildSignedURL(getFilePath(rootFolder, collection.slug, filename));
+                                        const source = data || {};
+                                        const documentPrefix = path.posix.join(source.prefix || prefix, source._objectKey || '');
+                                        const storageFilePath = buildStoragePathData({
+                                            collectionPrefix: prefix,
+                                            docPrefix: documentPrefix,
+                                            filename
+                                        }).storageFilePath;
+                                        return buildSignedURL(`/${storageFilePath}`);
                                     }
                                 ]
                             },
@@ -243,29 +272,44 @@ const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFo
                     label: 'ImageKit'
                 }
             ],
-            generateURL: ({ filename })=>client.helper.buildSrc({
-                    src: getFilePath(rootFolder, collection.slug, filename),
+            generateURL: ({ filename, prefix: documentPrefix = '' })=>client.helper.buildSrc({
+                    src: `/${buildStoragePathData({
+                        collectionPrefix: prefix,
+                        docPrefix: documentPrefix,
+                        filename
+                    }).storageFilePath}`,
                     urlEndpoint
                 }),
-            handleDelete: async ({ doc, filename })=>{
+            handleDelete: async ({ doc, storageFilePath })=>{
                 const storedFileId = doc.imagekit?.fileId;
-                const fileId = storedFileId || await findImageKitFileId(client, getFilePath(rootFolder, collection.slug, filename));
+                const fileId = storedFileId || await findImageKitFileId(client, `/${storageFilePath.replace(/^\/+/, '')}`);
                 if (!fileId) {
                     return;
                 }
                 await client.files.delete(fileId);
             },
-            handleUpload: async ({ clientUploadContext, data, file })=>{
-                if (isImageKitClientUploadContext(clientUploadContext)) {
-                    return applyClientUploadContextToData(data, clientUploadContext, buildThumbnailURL, isPrivate);
+            handleUpload: async ({ clientUploadContext, data, file, storageFilePath })=>{
+                if (clientUploadContext) {
+                    const uploaded = await verifyClientUpload({
+                        collectionSlug: collection.slug,
+                        context: clientUploadContext
+                    });
+                    return applyVerifiedClientUploadToData(data, uploaded, buildThumbnailURL, isPrivate);
                 }
-                const uploadFile = await toFile(file.buffer, file.filename, {
+                // ImageKit's `toFile()` consumes async iterables before starting the request. A file-backed
+                // Blob keeps temporary-file uploads lazy so FormData can stream them from disk instead.
+                const uploadSource = file.tempFilePath ? await openAsBlob(file.tempFilePath, {
+                    type: file.mimeType
+                }) : file.buffer;
+                const uploadFile = await toFile(uploadSource, file.filename, {
                     type: file.mimeType
                 });
+                const uploadFolder = path.posix.dirname(`/${storageFilePath.replace(/^\/+/, '')}`);
+                const uploadFilename = path.posix.basename(storageFilePath);
                 const uploaded = await client.files.upload({
                     file: uploadFile,
-                    fileName: file.filename,
-                    folder: getCollectionFolder(rootFolder, collection.slug),
+                    fileName: uploadFilename,
+                    folder: uploadFolder,
                     useUniqueFileName: false,
                     ...isPrivate ? {
                         isPrivateFile: true
@@ -282,44 +326,30 @@ const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFo
                 // `data` yet at this point, so fall back to the uploaded file's name.
                 data.thumbnailURL = buildThumbnailURL({
                     ...data,
-                    filename: data.filename || file.filename
+                    filename: data.filename || uploadFilename
                 });
                 return data;
             },
+            requiresClientUploadReceipt: true,
             staticHandler: async (req, args)=>{
                 const requestURL = new URL(req.url || 'http://localhost');
                 const tr = requestURL.searchParams.get('tr');
                 const hasClientUploadContext = 'clientUploadContext' in args.params;
                 if (hasClientUploadContext) {
                     const clientUploadContext = args.params.clientUploadContext;
-                    if (!isImageKitClientUploadContext(clientUploadContext)) {
-                        throw new Error('imagekitStorage: client upload context is invalid.');
-                    }
-                    const expectedFilePath = getFilePath(rootFolder, args.params.collection, args.params.filename);
-                    const fileId = clientUploadContext.fileId;
-                    if (typeof fileId !== 'string' || !fileId) {
-                        throw new Error('imagekitStorage: client upload is missing its file ID.');
+                    if (!isImageKitReceiptContext(clientUploadContext)) {
+                        throw new APIError('Invalid ImageKit client upload context.', 400);
                     }
-                    const uploadedFile = await client.files.get(fileId);
-                    const uploadedFileMime = uploadedFile.mime;
-                    const uploadedFileSize = uploadedFile.size;
-                    const metadataMatchesUpload = uploadedFile.fileId === fileId && uploadedFile.filePath === expectedFilePath && uploadedFile.name === args.params.filename && typeof uploadedFileMime === 'string' && typeof uploadedFile.url === 'string' && typeof uploadedFileSize === 'number' && Number.isSafeInteger(uploadedFileSize) && uploadedFileSize > 0 && Boolean(uploadedFile.isPrivateFile) === isPrivate && (typeof clientUploadContext.size !== 'number' || uploadedFileSize === clientUploadContext.size);
-                    if (!metadataMatchesUpload || typeof uploadedFileMime !== 'string' || typeof uploadedFileSize !== 'number') {
-                        throw new Error('imagekitStorage: client upload metadata did not match.');
-                    }
-                    // Replace browser-provided values before hooks persist the upload context.
-                    Object.assign(clientUploadContext, {
-                        name: uploadedFile.name,
-                        fileId: uploadedFile.fileId,
-                        filePath: uploadedFile.filePath,
-                        fileType: uploadedFile.fileType,
-                        mimeType: uploadedFileMime,
-                        size: uploadedFileSize,
-                        thumbnailUrl: uploadedFile.thumbnail,
-                        url: uploadedFile.url
+                    const uploadedFile = await verifyClientUpload({
+                        collectionSlug: collection.slug,
+                        context: clientUploadContext
+                    });
+                    const expectedFilePath = getClientUploadStorageFilePath({
+                        collectionPrefix: prefix,
+                        context: clientUploadContext
                     });
-                    const verifiedFileURL = isPrivate ? buildSignedURL(expectedFilePath, ORIGINAL_FILE_TRANSFORMATION) : client.helper.buildSrc({
-                        src: expectedFilePath,
+                    const verifiedFileURL = isPrivate ? buildSignedURL(`/${expectedFilePath}`, ORIGINAL_FILE_TRANSFORMATION) : client.helper.buildSrc({
+                        src: `/${expectedFilePath}`,
                         transformation: [
                             {
                                 raw: ORIGINAL_FILE_TRANSFORMATION
@@ -327,14 +357,12 @@ const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFo
                         ],
                         urlEndpoint
                     });
-                    if (isVideoMimeType(uploadedFileMime)) {
-                        return fetchUploadedFilePrefix({
-                            fileSize: uploadedFileSize,
-                            fileURL: verifiedFileURL,
-                            mimeType: uploadedFileMime
-                        });
-                    }
-                    return fetchUploadedFile(verifiedFileURL);
+                    return fetchUploadedFile({
+                        fileSize: uploadedFile.size,
+                        fileURL: verifiedFileURL,
+                        mimeType: uploadedFile.mimeType,
+                        range: req.headers.get('Range')
+                    });
                 }
                 const doc = args.doc || await findUploadDocumentByFilename({
                     collection: args.params.collection,
@@ -342,11 +370,43 @@ const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFo
                     prefix: args.params.prefix,
                     req
                 });
+                const storageFilePath = await getStorageFilePath({
+                    collection,
+                    collectionPrefix: prefix,
+                    doc: doc || undefined,
+                    filename: args.params.filename,
+                    prefixQueryParam: args.params.prefix,
+                    req
+                });
+                const imageKitPath = `/${storageFilePath.replace(/^\/+/, '')}`;
+                const mimeType = doc?.mimeType;
+                // XML-family uploads (including SVG) must pass through Payload so its CSP is
+                // present even when ImageKit uses a custom, same-origin delivery domain.
+                if (typeof mimeType === 'string' && isXmlMimeType(mimeType)) {
+                    const filesize = doc?.filesize;
+                    if (typeof filesize !== 'number' || !Number.isSafeInteger(filesize) || filesize < 0) {
+                        throw new APIError('Stored ImageKit file metadata is incomplete.', 500);
+                    }
+                    const fileURL = isDocumentPrivate(doc, isPrivate) ? buildSignedURL(imageKitPath, ORIGINAL_FILE_TRANSFORMATION) : client.helper.buildSrc({
+                        src: imageKitPath,
+                        transformation: [
+                            {
+                                raw: ORIGINAL_FILE_TRANSFORMATION
+                            }
+                        ],
+                        urlEndpoint
+                    });
+                    return fetchUploadedFile({
+                        fileSize: filesize,
+                        fileURL,
+                        mimeType,
+                        range: req.headers.get('Range')
+                    });
+                }
                 // Sign based on the document's stored status, not the collection's current
                 // setting, so files keep working if the collection's privacy is changed later.
                 if (isDocumentPrivate(doc, isPrivate)) {
-                    const mimeType = doc?.mimeType;
-                    let signSrc = getFilePath(rootFolder, args.params.collection, args.params.filename);
+                    let signSrc = imageKitPath;
                     // A `tr` request for a video/PDF is a thumbnail request (the plain transform
                     // can't render a preview); serve ImageKit's generated thumbnail instead.
                     if (tr && isVideoMimeType(mimeType)) {
@@ -357,7 +417,7 @@ const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFo
                     return Response.redirect(buildSignedURL(signSrc, tr), 302);
                 }
                 const imageKitURL = client.helper.buildSrc({
-                    src: getStoredImageKitURL(doc) || getFilePath(rootFolder, args.params.collection, args.params.filename),
+                    src: getStoredImageKitURL(doc) || imageKitPath,
                     transformation: tr ? [
                         {
                             raw: tr
@@ -370,14 +430,15 @@ const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFo
         };
     };
 };
-const toCloudStorageCollections = (collections, adapter, privateSlugs, disablePayloadAccessControl)=>{
+const toCloudStorageCollections = (collections, adapter, privateSlugs, rootFolder, disablePayloadAccessControl)=>{
     const mappedCollections = {};
     for (const collectionSlug of Object.keys(collections)){
         mappedCollections[collectionSlug] = {
             adapter,
             disableLocalStorage: true,
             // Private files require Payload access control so URLs can be signed at serve time.
-            disablePayloadAccessControl: privateSlugs.has(collectionSlug) ? undefined : disablePayloadAccessControl
+            disablePayloadAccessControl: privateSlugs.has(collectionSlug) ? undefined : disablePayloadAccessControl,
+            prefix: getCollectionFolder(rootFolder, collectionSlug)
         };
     }
     return mappedCollections;
@@ -397,15 +458,34 @@ export const imagekitStorage = (pluginOptions)=>(config)=>{
             throw new Error('imagekitStorage: `collections` must include at least one upload collection.');
         }
         const privateSlugs = new Set(Object.entries(collections).filter(([, value])=>isPrivateCollectionConfig(value)).map(([slug])=>slug));
+        const configuredSlugs = new Set(Object.keys(collections));
         if (disablePayloadAccessControl && privateSlugs.size > 0) {
             throw new Error('imagekitStorage: `disablePayloadAccessControl` cannot be used with private collections. Private files require Payload access control to remain enabled so URLs can be signed at serve time.');
         }
+        if (disablePayloadAccessControl) {
+            const xmlCollectionSlugs = (config.collections || []).filter((collection)=>configuredSlugs.has(collection.slug) && collectionCanStoreXml(collection)).map((collection)=>collection.slug);
+            if (xmlCollectionSlugs.length > 0) {
+                throw new Error(`imagekitStorage: \`disablePayloadAccessControl\` cannot be used with collections that can store XML-family files (${xmlCollectionSlugs.join(', ')}). XML-family files require Payload's file route so its Content Security Policy is applied. Configure a MIME allow list that excludes SVG/XML, or keep Payload access control enabled.`);
+            }
+        }
         const signedUrlExpiresIn = typeof signedUrlExpiresInOption === 'number' && signedUrlExpiresInOption > 0 ? signedUrlExpiresInOption : DEFAULT_SIGNED_URL_EXPIRES_IN;
         const apiRoute = config.routes?.api ?? '/api';
         const rootFolder = normalizeFolder(folder);
         const imageKitClient = new ImageKit({
             privateKey
         });
+        const collectionSecurity = Object.fromEntries((config.collections || []).filter((collection)=>configuredSlugs.has(collection.slug)).map((collection)=>[
+                collection.slug,
+                {
+                    collection,
+                    isPrivate: privateSlugs.has(collection.slug),
+                    prefix: getCollectionFolder(rootFolder, collection.slug)
+                }
+            ]));
+        const verifyClientUpload = createImageKitClientUploadVerifier({
+            client: imageKitClient,
+            collections: collectionSecurity
+        });
         const adapter = imagekitAdapter({
             apiRoute,
             client: imageKitClient,
@@ -413,9 +493,9 @@ export const imagekitStorage = (pluginOptions)=>(config)=>{
             privateSlugs,
             rootFolder,
             signedUrlExpiresIn,
-            urlEndpoint
+            urlEndpoint,
+            verifyClientUpload
         });
-        const configuredSlugs = new Set(Object.keys(collections));
         const configWithCropDisabled = {
             ...config,
             collections: (config.collections || []).map((collection)=>{
@@ -424,7 +504,6 @@ export const imagekitStorage = (pluginOptions)=>(config)=>{
                 }
                 const isCollectionPrivate = privateSlugs.has(collection.slug);
                 const buildThumbnailURL = (doc)=>isDocumentPrivate(doc, isCollectionPrivate) ? getPrivateAdminThumbnailURL(doc, collection.slug, apiRoute) : getAdminThumbnailURL(doc);
-                const beforeDocumentControls = collection.admin?.components?.edit?.beforeDocumentControls || [];
                 const collectionOptions = collections[collection.slug];
                 const collectionFocalPoint = collectionOptions !== true && typeof collectionOptions === 'object' && typeof collectionOptions.focalPoint === 'boolean' ? collectionOptions.focalPoint : undefined;
                 // Surface a "this is a private collection" note in the list and edit views.
@@ -437,37 +516,60 @@ export const imagekitStorage = (pluginOptions)=>(config)=>{
                 } : collection.admin;
                 return {
                     ...collection,
-                    admin: clientUploads ? {
-                        ...baseAdmin || {},
-                        components: {
-                            ...collection.admin?.components || {},
-                            edit: {
-                                ...collection.admin?.components?.edit || {},
-                                beforeDocumentControls: [
-                                    ...beforeDocumentControls,
-                                    {
-                                        clientProps: {
-                                            authPath: getImageKitUploadAuthPath(collection.slug),
-                                            collectionSlug: collection.slug,
-                                            folder: getCollectionFolder(rootFolder, collection.slug),
-                                            isPrivate: isCollectionPrivate,
-                                            publicKey
-                                        },
-                                        path: '@humaan/payload-storage-imagekit/client#ImageKitUploadHandler'
-                                    }
-                                ]
-                            }
-                        }
-                    } : baseAdmin,
+                    admin: baseAdmin,
                     hooks: {
                         ...collection.hooks || {},
                         beforeChange: [
                             ...collection.hooks?.beforeChange || [],
-                            ({ data, req })=>{
+                            async ({ data, req })=>{
                                 if (!isRecord(data) || !req.file?.clientUploadContext) {
                                     return data;
                                 }
-                                return applyClientUploadContextToData(data, req.file.clientUploadContext, buildThumbnailURL, isCollectionPrivate);
+                                const context = req.file.clientUploadContext;
+                                const requestMimeType = req.file.mimetype.split(';', 1)[0]?.trim().toLowerCase();
+                                if (!isImageKitReceiptContext(context) || context.filename !== data.filename || context.filename !== req.file.name || context.expectedMimeType !== requestMimeType || // Payload can clear req.file.size when preparing an in-memory image.
+                                // generateFileData preserves the original size on the document.
+                                context.expectedSize !== data.filesize) {
+                                    throw new APIError('ImageKit client upload reference does not match this request.', 400);
+                                }
+                                const uploaded = await verifyClientUpload({
+                                    collectionSlug: collection.slug,
+                                    context
+                                });
+                                // A provider file can only be claimed once, including through legacy receipts.
+                                // The unique file ID index also rejects concurrent claims.
+                                const existing = await req.payload.db.findOne({
+                                    collection: collection.slug,
+                                    req,
+                                    where: {
+                                        'imagekit.fileId': {
+                                            equals: uploaded.fileId
+                                        }
+                                    }
+                                });
+                                if (existing) {
+                                    throw new APIError('This ImageKit client upload receipt has already been used.', 400);
+                                }
+                                data.filename = uploaded.name;
+                                data.filesize = uploaded.size;
+                                data.mimeType = uploaded.mimeType;
+                                return applyVerifiedClientUploadToData(data, uploaded, buildThumbnailURL, isCollectionPrivate);
+                            }
+                        ],
+                        beforeOperation: [
+                            ...collection.hooks?.beforeOperation || [],
+                            ({ args, operation, req })=>{
+                                if (operation !== 'create' && operation !== 'update' || req.context?.skipCloudStorage || !req.file || req.file.clientUploadContext || !('data' in args) || !isRecord(args.data) || typeof args.data.prefix !== 'string') {
+                                    return args;
+                                }
+                                // Payload checks filename uniqueness before cloud storage's beforeChange
+                                // normalizes the prefix. Use the persisted form during that lookup too.
+                                args.data.prefix = buildUploadStoragePathData({
+                                    collectionPrefix: getCollectionFolder(rootFolder, collection.slug),
+                                    docPrefix: args.data.prefix,
+                                    filename: req.file.name
+                                }).sanitizedDocPrefix;
+                                return args;
                             }
                         ]
                     },
@@ -488,24 +590,63 @@ export const imagekitStorage = (pluginOptions)=>(config)=>{
                         crop: false
                     }
                 };
-            }),
-            endpoints: clientUploads ? [
-                ...config.endpoints || [],
+            })
+        };
+        const uploadCollections = Object.fromEntries(Object.keys(collections).map((collectionSlug)=>[
+                collectionSlug,
                 {
-                    handler: createImageKitUploadAuthHandler({
-                        client: imageKitClient,
-                        collections
-                    }),
-                    method: 'get',
-                    path: `${getImageKitUploadAuthPath(':collection')}`
+                    isPrivate: privateSlugs.has(collectionSlug),
+                    prefix: getCollectionFolder(rootFolder, collectionSlug)
                 }
-            ] : config.endpoints
-        };
-        return cloudStoragePlugin({
+            ]));
+        initClientUploads({
+            clientHandler: '@humaan/payload-storage-imagekit/client#ImageKitUploadHandler',
+            collections: uploadCollections,
+            config: configWithCropDisabled,
+            enabled: enabled !== false && Boolean(clientUploads),
+            serverHandler: createImageKitUploadAuthHandler({
+                access: typeof clientUploads === 'object' ? clientUploads.access : undefined,
+                collections: uploadCollections,
+                privateKey,
+                publicKey,
+                verifyClientUpload
+            }),
+            serverHandlerPath: imageKitUploadAuthPath
+        });
+        const output = cloudStoragePlugin({
             alwaysInsertFields,
-            collections: toCloudStorageCollections(collections, adapter, privateSlugs, disablePayloadAccessControl),
+            collections: toCloudStorageCollections(collections, adapter, privateSlugs, rootFolder, disablePayloadAccessControl),
             enabled
         })(configWithCropDisabled);
+        // Make the provider identity unique at persistence time to reject concurrent receipt replays.
+        // Keep the legacy object key index for existing uploads.
+        output.collections = (output.collections || []).map((collection)=>{
+            if (!configuredSlugs.has(collection.slug)) {
+                return collection;
+            }
+            return {
+                ...collection,
+                fields: collection.fields.map((field)=>{
+                    if ('name' in field && field.name === '_objectKey') {
+                        return {
+                            ...field,
+                            unique: true
+                        };
+                    }
+                    if (field.type === 'group' && 'name' in field && field.name === 'imagekit') {
+                        return {
+                            ...field,
+                            fields: field.fields.map((metadataField)=>'name' in metadataField && metadataField.name === 'fileId' ? {
+                                    ...metadataField,
+                                    unique: true
+                                } : metadataField)
+                        };
+                    }
+                    return field;
+                })
+            };
+        });
+        return output;
     };
 export { migrateFolder } from './migrate.js';
 // Backward-compatible alias