CORS Policy for Browser Uploads: S3, R2, Presigned URLs, and ETag

What belongs in a browser upload CORS policy?

A browser upload policy needs to match the actual request that JavaScript sends. For object storage uploads, that usually means a frontend origin, a write method, upload headers, exposed response headers, and a preflight cache duration.

PUT vs POST browser uploads

A presigned PUT upload sends the file body directly to the object URL. A presigned POST upload usually submits form data with a policy, signature, key, and file field. Your CORS policy should include the method your backend generated.

• Use PUT when frontend code calls fetch(url, { method: 'PUT' }).
• Use POST when frontend code submits a form or FormData policy.
• Include HEAD when the app checks object existence or metadata after upload.

Upload headers that trigger preflight

Browsers send an OPTIONS preflight when the request is not a simple CORS request. Uploads frequently send headers such as Content-Type, checksum headers, or S3 metadata headers. The bucket policy must allow those headers.

[
  {
    "AllowedOrigins": ["https://app.example.com"],
    "AllowedMethods": ["PUT", "POST", "HEAD"],
    "AllowedHeaders": [
      "Content-Type",
      "x-amz-*"
    ],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

Should browser uploads use wildcard origins?

A wildcard origin is tempting for quick testing, but it is usually too broad for app uploads. Use exact origins for production uploads, especially when the request includes credentials, tenant-specific URLs, or sensitive object keys. Public read assets are a better fit for broader origins.

Why ETag needs ExposeHeaders

After an upload succeeds, many apps read ETag to store the uploaded object hash or confirm the write. The browser hides most response headers from JavaScript unless the CORS policy lists them in ExposeHeaders. If upload succeeds but response.headers.get("ETag") returns null, expose the header.

How to test a browser upload policy

1. Generate the presigned URL from your backend as usual.
2. Open DevTools and run the upload from the browser.
3. Find the OPTIONS request and copy origin, method, and request headers.
4. Paste your policy and those details into the CORS debugger.
5. Apply the suggested fixed config and retest the browser request.

Browser upload CORS checklist

• Origin includes protocol, host, and port.
• Methods include PUT or POST, not only GET.
• AllowedHeaders includes every preflight request header.
• ExposeHeaders includes ETag if the app reads it.
• Wildcard origins are avoided for credentialed or app-specific uploads.
• Localhost origins are included during development.

Generate and debug in one place

Use the S3/R2 CORS Generator & Debugger to create a starting policy, edit the JSON in Monaco, download provider-specific CLI JSON, and diagnose failed browser uploads from the same page.