Merge remote-tracking branch 'upstream/dev' into feat/obsidian-plugin

surfsense_backend/app/app.py

@@ -114,8 +114,19 @@ def _surfsense_error_handler(request: Request, exc: SurfSenseError) -> JSONRespo
 
 
 def _http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
-    """Wrap FastAPI/Starlette HTTPExceptions into the standard envelope."""
+    """Wrap FastAPI/Starlette HTTPExceptions into the standard envelope.
+
+    5xx sanitization policy:
+    - 500 responses are sanitized (replaced with ``GENERIC_5XX_MESSAGE``) because
+      they usually wrap raw internal errors and may leak sensitive info.
+    - Other 5xx statuses (501, 502, 503, 504, ...) are raised explicitly by
+      route code to communicate a specific, user-safe operational state
+      (e.g. 503 "Page purchases are temporarily unavailable."). Those details
+      are preserved so the frontend can render them, but the error is still
+      logged server-side.
+    """
     rid = _get_request_id(request)
+    should_sanitize = exc.status_code == 500
 
     # Structured dict details (e.g. {"code": "CAPTCHA_REQUIRED", "message": "..."})
     # are preserved so the frontend can parse them.
@@ -130,9 +141,9 @@ def _http_exception_handler(request: Request, exc: HTTPException) -> JSONRespons
                 exc.status_code,
                 message,
             )
-            if exc.status_code == 500:
-                message = GENERIC_5XX_MESSAGE
-                err_code = "INTERNAL_ERROR"
+        if should_sanitize:
+            message = GENERIC_5XX_MESSAGE
+            err_code = "INTERNAL_ERROR"
         body = {
             "error": {
                 "code": err_code,
@@ -159,8 +170,8 @@ def _http_exception_handler(request: Request, exc: HTTPException) -> JSONRespons
             exc.status_code,
             detail,
         )
-        if exc.status_code == 500:
-            detail = GENERIC_5XX_MESSAGE
+    if should_sanitize:
+        detail = GENERIC_5XX_MESSAGE
     code = _status_to_code(exc.status_code, detail)
     return _build_error_response(exc.status_code, detail, code=code, request_id=rid)
 

surfsense_backend/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surf-new-backend"
-version = "0.0.16"
+version = "0.0.19"
 description = "SurfSense Backend"
 requires-python = ">=3.12"
 dependencies = [

surfsense_backend/tests/unit/test_error_contract.py

@@ -70,6 +70,20 @@ def _make_test_app():
     async def raise_http_500():
         raise HTTPException(status_code=500, detail="secret db password leaked")
 
+    @app.get("/http-503")
+    async def raise_http_503():
+        raise HTTPException(
+            status_code=503,
+            detail="Page purchases are temporarily unavailable.",
+        )
+
+    @app.get("/http-502")
+    async def raise_http_502():
+        raise HTTPException(
+            status_code=502,
+            detail="Unable to create Stripe checkout session.",
+        )
+
     @app.get("/surfsense-connector")
     async def raise_connector():
         raise ConnectorError("GitHub API returned 401")
@@ -184,6 +198,20 @@ class TestHTTPExceptionHandler:
         assert body["error"]["message"] == GENERIC_5XX_MESSAGE
         assert body["error"]["code"] == "INTERNAL_ERROR"
 
+    def test_503_preserves_detail(self, client):
+        # Intentional 503s (e.g. feature flag off) must surface the developer
+        # message so the frontend can render actionable copy.
+        body = _assert_envelope(client.get("/http-503"), 503)
+        assert (
+            body["error"]["message"] == "Page purchases are temporarily unavailable."
+        )
+        assert body["error"]["message"] != GENERIC_5XX_MESSAGE
+
+    def test_502_preserves_detail(self, client):
+        body = _assert_envelope(client.get("/http-502"), 502)
+        assert body["error"]["message"] == "Unable to create Stripe checkout session."
+        assert body["error"]["message"] != GENERIC_5XX_MESSAGE
+
 
 # ---------------------------------------------------------------------------
 # SurfSenseError hierarchy

surfsense_backend/uv.lock

@@ -7947,7 +7947,7 @@ wheels = [
 
 [[package]]
 name = "surf-new-backend"
-version = "0.0.16"
+version = "0.0.19"
 source = { editable = "." }
 dependencies = [
     { name = "alembic" },