From caf89052f26c5d110fc97dfbc1fe84a4836161ef Mon Sep 17 00:00:00 2001
From: g-roliveira <125938946+g-roliveira@users.noreply.github.com>
Date: Mon, 16 Feb 2026 23:51:09 -0300
Subject: [PATCH] docs: clarify CSP and CORS requirements for S3 attachment
 downloads

---
 .env.template |  6 ++++++
 README.md     | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/.env.template b/.env.template
index 2d0f0e13..b666b555 100644
--- a/.env.template
+++ b/.env.template
@@ -465,6 +465,12 @@
 ## This adds the configured value to the 'Content-Security-Policy' headers 'connect-src' value.
 ## Multiple values must be separated with a whitespace. And only HTTPS values are allowed.
 ## Example: "https://my-addy-io.domain.tld https://my-simplelogin.domain.tld"
+## For S3-compatible attachment downloads, include your object storage origin
+## (for example Cloudflare R2 endpoint):
+## "https://<accountid>.r2.cloudflarestorage.com"
+## Note: This only configures CSP on Vaultwarden. You also need a CORS policy
+## on the object storage bucket/provider that allows your Vaultwarden DOMAIN
+## origin for download requests.
 # ALLOWED_CONNECT_SRC=""
 
 ## Number of seconds, on average, between login requests from the same IP address before rate limiting kicks in.
diff --git a/README.md b/README.md
index 220d33bf..f514b1f5 100644
--- a/README.md
+++ b/README.md
@@ -140,6 +140,38 @@ env:
 
 Use IAM/service account/environment credentials when possible. URI credentials are supported as a last resort.
 
+### Browser Attachment Downloads (CSP + CORS)
+
+For S3-compatible backends, attachment downloads from the Web Vault use presigned URLs. The browser downloads directly from the object storage endpoint.
+
+Configure both sides:
+
+- Vaultwarden CSP: allow the object-storage origin in `ALLOWED_CONNECT_SRC`.
+- Object storage CORS policy: allow your Vaultwarden origin (`DOMAIN`) for `GET`/`HEAD`.
+
+R2 example:
+
+```text
+ALLOWED_CONNECT_SRC="https://<accountid>.r2.cloudflarestorage.com"
+```
+
+```json
+[
+  {
+    "AllowedOrigins": ["https://vault.example.com"],
+    "AllowedMethods": ["GET", "HEAD"],
+    "AllowedHeaders": ["*"],
+    "ExposeHeaders": ["ETag", "Content-Length", "Content-Type", "Content-Disposition"],
+    "MaxAgeSeconds": 3600
+  }
+]
+```
+
+Troubleshooting:
+
+- `violates the document's Content Security Policy`: set `ALLOWED_CONNECT_SRC` correctly.
+- `No 'Access-Control-Allow-Origin' header`: fix CORS policy on the bucket/provider.
+
 <br>
 
 ## Get in touch