docs(bugs): add BUG-004 - StaticFiles CORS middleware not applied

Root cause analysis for "Failed to load volume: Failed to fetch" error.

Discovery: FastAPI/Starlette middleware doesn't propagate to mounted
sub-applications. The CORSMiddleware and CORPMiddleware only apply to
API routes, not the StaticFiles mount at /files/*.

Impact: NiiVue cannot fetch NIfTI files cross-origin (CRITICAL)

Proposed solutions:
A. Replace StaticFiles with explicit FileResponse routes (recommended)
B. ASGI middleware wrapper for StaticFiles
C. Reverse proxy CORS headers

Status: OPEN - Awaiting senior review

docs/bugs/004-staticfiles-cors-middleware-not-applied.md

@@ -0,0 +1,178 @@
+# Bug 004: CORS/CORP Middleware Not Applied to Mounted StaticFiles
+
+**Status**: OPEN
+**Date Found**: 2025-12-12
+**Severity**: CRITICAL (blocks NiiVue from loading NIfTI files)
+**Requires**: Senior Review
+
+---
+
+## Symptoms
+
+1. Frontend loads successfully at `https://vibecodermcswaggins-stroke-viewer-frontend.hf.space`
+2. Backend health check responds: `{"status":"healthy"}`
+3. Case dropdown populates (GET /api/cases works)
+4. Segmentation job runs successfully (39.5s, returns metrics)
+5. Results panel shows: Case, Dice Score (0.000), Volume (0.00 mL), Time (39.5s)
+6. **NiiVue viewer shows: "Failed to load volume: Failed to fetch"**
+
+![Screenshot showing the error](../assets/niivue-failed-to-fetch-screenshot.png)
+
+## Root Cause Analysis
+
+### The Core Issue: Starlette Middleware Architecture
+
+When FastAPI/Starlette mounts a sub-application (like `StaticFiles`), the parent app's middleware **does NOT propagate** to the mounted app.
+
+```python
+# main.py - Current implementation
+app = FastAPI(...)
+
+# These middlewares only apply to routes on `app` itself
+app.add_middleware(CORPMiddleware)  # For SharedArrayBuffer
+app.add_middleware(CORSMiddleware, allow_origins=CORS_ORIGINS, ...)
+
+# This creates a SEPARATE sub-application with its OWN middleware stack (empty!)
+app.mount("/files", StaticFiles(directory=str(RESULTS_DIR)), name="files")
+```
+
+**Result**:
+- API routes (`/api/*`) → Get CORS headers ✓
+- Static files (`/files/*`) → NO CORS headers ✗ (blocked by browser)
+
+### Evidence
+
+1. Backend logs show all requests succeed with 200 OK
+2. Browser DevTools Network tab would show CORS preflight failure for `/files/*` requests
+3. NiiVue's `loadVolumes()` throws "Failed to fetch" (generic browser CORS error)
+
+### Starlette Documentation Reference
+
+From [Starlette Middleware Docs](https://www.starlette.io/middleware/):
+> "Each sub-app owns its routers/middleware/lifecycle"
+
+From [FastAPI/Starlette Discussion #7319](https://github.com/fastapi/fastapi/discussions/7319):
+> "When using `app.mount()`, middleware on the parent app may not apply to mounted sub-apps"
+
+## Impact
+
+- **NiiVue cannot load NIfTI files** - Core functionality completely broken
+- **SharedArrayBuffer may not work** - CORP header also missing from static files
+- **All production users affected** - Cross-origin fetch blocked
+
+## Proposed Solutions
+
+### Solution A: Custom Route Instead of StaticFiles (Recommended)
+
+Replace `StaticFiles` mount with explicit route handlers that go through the main app's middleware:
+
+```python
+from fastapi.responses import FileResponse
+
+@router.get("/files/{job_id}/{case_id}/{filename}")
+async def get_result_file(job_id: str, case_id: str, filename: str):
+    """Serve NIfTI result files through main app (gets CORS headers)."""
+    file_path = RESULTS_DIR / job_id / case_id / filename
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail="File not found")
+    return FileResponse(
+        file_path,
+        media_type="application/gzip",  # .nii.gz
+        filename=filename,
+    )
+```
+
+**Pros**: Simple, uses existing middleware
+**Cons**: Less efficient than StaticFiles for large files (no sendfile)
+
+### Solution B: ASGI Middleware Wrapper for StaticFiles
+
+Wrap `StaticFiles` in a custom ASGI app that adds CORS headers:
+
+```python
+class CORSStaticFiles:
+    """StaticFiles wrapper that adds CORS headers."""
+
+    def __init__(self, directory: str, origins: list[str]):
+        self.static = StaticFiles(directory=directory)
+        self.origins = origins
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http":
+            # Add CORS headers to response
+            async def send_with_cors(message):
+                if message["type"] == "http.response.start":
+                    headers = dict(message.get("headers", []))
+                    origin = dict(scope.get("headers", [])).get(b"origin", b"").decode()
+                    if origin in self.origins:
+                        headers[b"access-control-allow-origin"] = origin.encode()
+                        headers[b"cross-origin-resource-policy"] = b"cross-origin"
+                    message["headers"] = list(headers.items())
+                await send(message)
+            return await self.static(scope, receive, send_with_cors)
+        return await self.static(scope, receive, send)
+
+# Usage
+app.mount("/files", CORSStaticFiles(str(RESULTS_DIR), CORS_ORIGINS))
+```
+
+**Pros**: Preserves StaticFiles efficiency
+**Cons**: More complex, custom ASGI code
+
+### Solution C: Nginx/Caddy Reverse Proxy
+
+Add CORS headers at the reverse proxy level (HF Spaces would need configuration access):
+
+**Pros**: Most efficient, proper separation of concerns
+**Cons**: HF Spaces may not support custom proxy config
+
+## Additional Issues Discovered
+
+### Issue 1: BACKEND_PUBLIC_URL Not Set
+
+The Dockerfile doesn't set `BACKEND_PUBLIC_URL`, relying on `--proxy-headers` and `request.base_url`. This is fragile:
+
+```dockerfile
+# Current (fragile)
+CMD ["uvicorn", "...:app", "--proxy-headers"]
+
+# Should add (robust)
+ENV BACKEND_PUBLIC_URL=https://vibecodermcswaggins-stroke-deepisles-demo.hf.space
+```
+
+### Issue 2: chmod "Operation not permitted" Warnings
+
+```
+chmod: changing permissions of '/app/weights/SEALS/nnUNet_trained_models/...': Operation not permitted
+```
+
+**Status**: Harmless - DeepISLES tries to chmod model weights but fails. The container can still READ the files, which is all that's needed. These are benign warnings, not errors.
+
+## Files Affected
+
+- `src/stroke_deepisles_demo/api/main.py` - Needs fix for static file CORS
+- `Dockerfile` - Should set `BACKEND_PUBLIC_URL` explicitly
+
+## Verification Steps
+
+After fix:
+1. Deploy updated backend to HF Spaces
+2. Clear browser cache
+3. Open frontend, select case, run segmentation
+4. Check browser DevTools → Network tab:
+   - `/files/*` requests should show `access-control-allow-origin` header
+5. NiiVue should load and display DWI + prediction overlay
+
+## References
+
+- [FastAPI/Starlette CORS Discussion #7319](https://github.com/fastapi/fastapi/discussions/7319)
+- [Starlette Middleware Stack](https://www.starlette.io/middleware/)
+- [FastAPI CORS Tutorial](https://fastapi.tiangolo.com/tutorial/cors/)
+- [CORSMiddleware not working with mounted apps](https://github.com/fastapi/fastapi/issues/1663)
+
+## Senior Review Questions
+
+1. **Solution preference**: Route-based (A) vs ASGI wrapper (B)?
+2. **BACKEND_PUBLIC_URL**: Set in Dockerfile or HF Space settings?
+3. **Testing**: Add integration test for static file CORS headers?
+4. **Monitoring**: How to detect this regression in future?

docs/bugs/README.md

@@ -4,7 +4,9 @@ This directory tracks bugs found during deployment to HuggingFace Spaces.
 
 ## Active Bugs
 
-None currently.
+| ID | Title | Severity | Status |
+|----|-------|----------|--------|
+| [004](./004-staticfiles-cors-middleware-not-applied.md) | CORS/CORP middleware not applied to mounted StaticFiles | **CRITICAL** | OPEN - Awaiting Senior Review |
 
 ## Fixed Bugs
 
@@ -20,7 +22,8 @@ Last audit: 2025-12-12
 
 | Check | Status | Notes |
 |-------|--------|-------|
-| CORS regex matches both URL formats | PASS | `r"https://.*stroke-viewer-frontend.*\.hf\.space"` |
+| CORS regex matches both URL formats | N/A | Replaced with exact-match list (PR #38) |
+| **CORS on StaticFiles mount** | **FAIL** | BUG-004: Middleware doesn't apply to mounted apps |
 | All URLs use HTTPS | PASS | `--proxy-headers` flag in Dockerfile |
 | File outputs to /tmp/ | PASS | Uses `/tmp/stroke-results/` |
 | Static files mounted after dir exists | PASS | `mkdir()` before `app.mount()` in main.py |
@@ -61,7 +64,14 @@ Based on research and experience, here are common issues to watch for:
 - `SPACE_ID` contains the space identifier
 - Use these to detect production environment
 
-### 6. Gateway Timeouts (SOLVED)
+### 6. chmod "Operation not permitted" Warnings (HARMLESS)
+DeepISLES tries to chmod model weight files but fails due to container permissions:
+```
+chmod: changing permissions of '/app/weights/SEALS/...': Operation not permitted
+```
+These are **benign warnings**, not errors. The container can still READ the files.
+
+### 7. Gateway Timeouts (SOLVED)
 - HF Spaces proxy has ~60 second timeout
 - Solution: Async job queue pattern with polling
 - POST returns immediately with job ID
@@ -106,8 +116,9 @@ The complete flow from frontend to backend and back:
 
 7. NiiVue fetches static files
    ├── Cross-origin fetch to backend /files/...
-   ├── CORS headers on static file response
-   └── Binary NIfTI files download
+   ├── ⚠️ BUG-004: StaticFiles mount doesn't get CORS headers!
+   ├── Browser blocks fetch (no Access-Control-Allow-Origin)
+   └── "Failed to load volume: Failed to fetch"
 
 8. Viewer displays
    └── NIfTI volumes rendered in WebGL canvas