add CORS.md

CORS.md

@@ -0,0 +1,79 @@
+Let me first look at how your application is loading the audio files to understand the CORS requirements.
+
+[1 tool called]
+
+Looking at your code, I can see the `TrackCache` module uses `fetch()` to cache audio files from `feed.falsefinish.club`. For this to work when your player is hosted on `echo-reality.com`, the server at `feed.falsefinish.club` needs to send proper CORS headers.
+
+## What the owner of falsefinish.club needs to do
+
+The server hosting the audio files must add these HTTP response headers:
+
+```
+Access-Control-Allow-Origin: https://echo-reality.com
+Access-Control-Allow-Methods: GET, HEAD, OPTIONS
+Access-Control-Expose-Headers: ETag, Last-Modified, Content-Length
+```
+
+The `Expose-Headers` part is important because your `TrackCache` reads `ETag` and `Last-Modified` headers for cache validation (lines 1539-1554 in your code).
+
+### Server-specific configurations:
+
+**Nginx:**
+```nginx
+location / {
+    add_header 'Access-Control-Allow-Origin' 'https://echo-reality.com' always;
+    add_header 'Access-Control-Allow-Methods' 'GET, HEAD, OPTIONS' always;
+    add_header 'Access-Control-Expose-Headers' 'ETag, Last-Modified, Content-Length' always;
+    
+    # Handle preflight requests
+    if ($request_method = 'OPTIONS') {
+        add_header 'Access-Control-Allow-Origin' 'https://echo-reality.com';
+        add_header 'Access-Control-Allow-Methods' 'GET, HEAD, OPTIONS';
+        add_header 'Access-Control-Max-Age' 86400;
+        add_header 'Content-Length' 0;
+        return 204;
+    }
+}
+```
+
+**Apache (.htaccess):**
+```apache
+<IfModule mod_headers.c>
+    Header set Access-Control-Allow-Origin "https://echo-reality.com"
+    Header set Access-Control-Allow-Methods "GET, HEAD, OPTIONS"
+    Header set Access-Control-Expose-Headers "ETag, Last-Modified, Content-Length"
+</IfModule>
+```
+
+**Cloudflare (if used):** Add a Transform Rule or use a Cloudflare Worker to inject headers.
+
+**S3/CloudFront:** Configure CORS in the bucket settings:
+```json
+[
+    {
+        "AllowedOrigins": ["https://echo-reality.com"],
+        "AllowedMethods": ["GET", "HEAD"],
+        "AllowedHeaders": ["*"],
+        "ExposeHeaders": ["ETag", "Last-Modified", "Content-Length"],
+        "MaxAgeSeconds": 86400
+    }
+]
+```
+
+### For development/testing
+
+During development, you might want to allow multiple origins. Use a wildcard temporarily:
+```
+Access-Control-Allow-Origin: *
+```
+
+But for production, always specify the exact origin (`https://echo-reality.com`) for security.
+
+### Why this matters for your code
+
+Your `TrackCache.isStale()` function (lines 1519-1568) makes HEAD requests to check if files have changed. Without CORS headers:
+1. The `fetch()` calls fail with CORS errors
+2. Your code falls back to direct URLs (line 1753-1756), which works for playback but bypasses caching
+3. The `ETag` and `Last-Modified` headers won't be readable even if fetches succeed partially
+
+The current fallback behavior is good defensive code, but to enable actual caching benefits, those headers must be configured on `feed.falsefinish.club`.