Admin panel breaking presigned S3 URLs due to adding query parameters

[SimonVreman]

When using presigned S3 URLs for secure image access, the admin panel automatically appends a date query string to image requests (e.g., ?2025-01-10). This breaks the presigned URLs since they are cryptographically signed for the exact URL, and any modification invalidates the signature. See the following excerpt from the codebase (ui package, src/elements/PreviewSizes/index.tsx):

const generateImageUrl = (doc) => {
  if (!doc.filename) {
    return null
  }
  if (doc.url) {
    return `${doc.url}${imageCacheTag ? `?${imageCacheTag}` : ''}`
  }
}

Setup

• Private S3 bucket
• Using presigned URLs to serve images, after read hook
• PayloadCMS admin panel for content management

Expected behavior

Admin panel should display images using the exact presigned URLs, image requests should succeed with the valid signatures

Actual Behavior

• Admin panel appends ?[date] to image URLs
• Modified URLs no longer match the signed URLs
• Image requests fail with signature validation errors

I've only come up with submitting a PR to remove the image caching situation; though this would cause issues for those serving images with a constant url. So we probably want a way to circumvent this selectively, as to not re-introduce caching issues.

Any insights or suggestions would be greatly appreciated!

[SimonVreman]

A sub-discussion to add to this; modifying the images without changing the url causes them to be in browser cache when used in places without this trick, right? So if one builds a front-end using the Payload API, they manually need to make sure the edited image is fetched, and not the one from browser cache.

[rajtilak-2020]

You're correct! If you serve images with a static URL and modify the images without updating the URL (or appending a cache-busting query string), browsers will often serve the cached version of the image. This is because browsers rely on the URL to determine whether they should re-fetch a resource.

This issue becomes relevant when you're:

1. Serving images via a front-end using the Payload API.
2. Modifying images without changing the URL.

---

Why This Happens

• Browser caching is designed to improve performance by reducing redundant network requests.
• If the browser has cached an image, it will use the cached version unless the URL changes (or cache expiration headers are set to force revalidation).

When using presigned URLs, appending a cache-busting query string like ?timestamp ensures the browser sees it as a new resource, avoiding this caching problem. However, this becomes tricky if your admin panel appends query strings that break the presigned URLs.

---

Mitigation Strategies

Here’s how you can ensure the correct (updated) images are fetched:

---

1. Use Cache-Busting Query Strings Intelligently

For non-presigned URLs, append a cache-busting query string whenever the image changes. A common practice is to use a versioning system:

const generateImageUrl = (doc, version = null) => {
  if (!doc.filename) {
    return null;
  }

  if (doc.url) {
    return `${doc.url}${version ? `?v=${version}` : ''}`;
  }
};

• On image update: Increment the version field (e.g., in your database or metadata).
• Frontend integration: Pass the updated version to ensure the latest image is fetched.

For example:

generateImageUrl(imageDoc, imageDoc.version);

---

2. Control Caching with HTTP Headers

If query strings are not an option (e.g., with presigned URLs), configure caching policies at the server level. AWS S3 allows you to control cache behavior via headers such as:

• Cache-Control: no-cache: Ensures the browser always revalidates with the server.
• Cache-Control: max-age=3600: Specifies how long (in seconds) the browser should cache the file.

Set these headers when uploading images to S3:

const params = {
  Bucket: bucketName,
  Key: objectKey,
  Body: imageBuffer,
  ContentType: 'image/jpeg',
  CacheControl: 'no-cache', // or 'max-age=3600'
};
s3.upload(params, (err, data) => { /* handle response */ });

---

3. Generate Unique URLs for Modified Images

When an image is updated, give it a new URL by changing the filename or key. This ensures the browser fetches the updated image.

For example:

• Original: https://example.com/images/image1.jpg
• Updated: https://example.com/images/image1_v2.jpg

You can automate this by appending a timestamp or version number to the filename during updates.

---

4. Use a Proxy for Image Management

If you’re using Payload’s API to serve images, implement a backend proxy that:

• Handles presigned URLs internally.
• Adds cache-busting query strings for non-presigned URLs.
• Can serve updated images reliably without exposing direct S3 URLs.

Example:

• Frontend requests: /api/images/image1
• Backend dynamically generates the correct URL: https://example-bucket.s3.amazonaws.com/image1?X-Amz-Signature=...

---

5. Manage Client-Side Caching for Specific Scenarios

On the client side, you can programmatically bypass the browser cache if needed:

const loadUpdatedImage = (url) => {
  const cacheBustingQuery = `?_=${new Date().getTime()}`;
  return `${url}${url.includes('?') ? '&' : '?'}${cacheBustingQuery}`;
};

Use this approach only if you need to bypass caching for certain cases (e.g., during updates or previews).

---

Best Approach for Your Use Case

If you are using a Payload API front-end:

1. Append a version-based query string to URLs for non-presigned images.
2. For presigned S3 URLs, use short cache lifetimes (e.g., 1 hour) to mitigate caching issues.
3. Consider using a proxy endpoint to centralize image management and simplify URL handling.

[Lippur]

Wonderful contribution, but even though the interfaces may appear similar at first glance, this is in fact GitHub Discussions, not the ChatGPT chat window. Although the two might be easy to confuse, the author is presumably competent enough to have opened the correct window in this case, and is probably not interested in discussing the issue with ChatGPT.

[SimonVreman]

Woah! I just didn't pay enough attention - this was currently being solved coincidentally. #10319 should resolve this, disabling the cache tags allows for signed urls to work.