✨(all) allow to display external images through proxy (#469)

Allow to users to display external images from their email
through a secure proxy endpoint to ensure security and privacy
and respect iframe csp policy.

Co-authored-by: =?UTF-8?q?Ri=C3=ABl=20Notermans?= <riel@mosa.cloud>

Author: jbpenrath

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to
 - Allow to search for spam messages
 - Add `is_trashed` flag to thread model
 - Add to select multiple threads in thread panel
+- Add image proxy endpoint to display external images in messages
 
 ### Changed
 

docs/env.md

@@ -286,6 +286,17 @@ _Those settings are deprecated and will be removed in the future._
 | `FEATURE_AI_SUMMARY` | `False` | Default enabled mode for summary AI features | Required |
 | `FEATURE_AI_AUTOLABELS` | `False` | Default enabled mode for label AI features | Required |
 
+### Image Proxy
+
+**Note**: By default `IMAGE_PROXY_MAX_SIZE` is set to 5MB. We do not encourage to increase this value as
+it can lead to memory exhaustion, increase at your own risk.
+
+| Variable | Default | Description | Required |
+|----------|---------|-------------|----------|
+| `IMAGE_PROXY_ENABLED` | `False` | Whether external images should be proxied | Optional |
+| `IMAGE_PROXY_MAX_SIZE` | `5242880` (5MB) | Maximum size in bytes for external images | Optional |
+| `IMAGE_PROXY_CACHE_TTL` | `2592000` (30 days) | Cache TTL in seconds for external images | Optional |
+
 ### Third-party Services
 
 #### Drive

src/backend/core/api/openapi.json

@@ -227,6 +227,11 @@
                                             "type": "integer",
                                             "description": "Maximum number of recipients per message (to + cc + bcc)",
                                             "readOnly": true
+                                        },
+                                        "IMAGE_PROXY_ENABLED": {
+                                            "type": "boolean",
+                                            "description": "Whether external images should be proxied",
+                                            "readOnly": true
                                         }
                                     },
                                     "required": [
@@ -241,7 +246,8 @@
                                         "MAX_OUTGOING_ATTACHMENT_SIZE",
                                         "MAX_OUTGOING_BODY_SIZE",
                                         "MAX_INCOMING_EMAIL_SIZE",
-                                        "MAX_RECIPIENTS_PER_MESSAGE"
+                                        "MAX_RECIPIENTS_PER_MESSAGE",
+                                        "IMAGE_PROXY_ENABLED"
                                     ]
                                 }
                             }
@@ -2418,6 +2424,57 @@
                 }
             }
         },
+        "/api/v1.0/mailboxes/{mailbox_id}/image-proxy/": {
+            "get": {
+                "operationId": "mailboxes_image_proxy_list",
+                "description": "Proxy an external image through the server.\n\n        This endpoint fetches images from external sources and serves them\n        through the application to protect user privacy. Requires the\n        IMAGE_PROXY_ENABLED environment variable to be set to true.\n        ",
+                "parameters": [
+                    {
+                        "in": "path",
+                        "name": "mailbox_id",
+                        "schema": {
+                            "type": "string"
+                        },
+                        "description": "ID of the mailbox",
+                        "required": true
+                    },
+                    {
+                        "in": "query",
+                        "name": "url",
+                        "schema": {
+                            "type": "string"
+                        },
+                        "description": "The external image URL to proxy",
+                        "required": true
+                    }
+                ],
+                "tags": [
+                    "mailboxes"
+                ],
+                "security": [
+                    {
+                        "cookieAuth": []
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Image content"
+                    },
+                    "400": {
+                        "description": "Invalid request"
+                    },
+                    "403": {
+                        "description": "Forbidden"
+                    },
+                    "413": {
+                        "description": "Image too large"
+                    },
+                    "502": {
+                        "description": "Failed to fetch external image"
+                    }
+                }
+            }
+        },
         "/api/v1.0/mailboxes/{mailbox_id}/message-templates/": {
             "get": {
                 "operationId": "mailboxes_message_templates_list",

src/backend/core/api/viewsets/blob.py

@@ -185,6 +185,8 @@ def download(self, request, pk=None):
                     f'attachment; filename="{attachment["name"]}"'
                 )
                 response["Content-Length"] = attachment["size"]
+                # Enable browser caching for 30 days (inline images benefit from this)
+                response["Cache-Control"] = "private, max-age=2592000"
 
             else:
                 # Get the blob
@@ -211,6 +213,8 @@ def download(self, request, pk=None):
                 # Add appropriate headers for download
                 response["Content-Disposition"] = f'attachment; filename="{filename}"'
                 response["Content-Length"] = blob.size
+                # Enable browser caching for 30 days (inline images benefit from this)
+                response["Cache-Control"] = "private, max-age=2592000"
 
             return response
 

src/backend/core/api/viewsets/config.py

@@ -96,6 +96,11 @@ class ConfigView(drf.views.APIView):
                             ),
                             "readOnly": True,
                         },
+                        "IMAGE_PROXY_ENABLED": {
+                            "type": "boolean",
+                            "description": "Whether external images should be proxied",
+                            "readOnly": True,
+                        },
                     },
                     "required": [
                         "ENVIRONMENT",
@@ -110,6 +115,7 @@ class ConfigView(drf.views.APIView):
                         "MAX_OUTGOING_BODY_SIZE",
                         "MAX_INCOMING_EMAIL_SIZE",
                         "MAX_RECIPIENTS_PER_MESSAGE",
+                        "IMAGE_PROXY_ENABLED",
                     ],
                 },
             )
@@ -127,6 +133,7 @@ def get(self, request):
             "LANGUAGE_CODE",
             "SCHEMA_CUSTOM_ATTRIBUTES_USER",
             "SCHEMA_CUSTOM_ATTRIBUTES_MAILDOMAIN",
+            "IMAGE_PROXY_ENABLED",
         ]
         dict_settings = {}
         for setting in array_settings: