From 36aceddb14a6f50c765d085cf685f12c322bce4b Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Mon, 17 Aug 2026 15:37:33 -0400
Subject: [PATCH 1/2] Allow Range through realm-server CORS and expose range
 response headers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Native audio/video elements cannot attach Authorization, so on protected
realms the host's auth service worker re-issues media requests as
mode:'cors' with the token injected. That rewrite turns the media element's
Range header into an author header needing preflight approval, and the
realm server's Access-Control-Allow-Headers did not include Range — the
preflight failed and the native player errored before any bytes flowed.

Range and If-Range join the CORS allow list, and Content-Range /
Accept-Ranges / Content-Length join both expose lists — the @koa/cors
exposeHeaders and the createResponse Access-Control-Expose-Headers, since
the latter replaces rather than merges with the former on any response a
realm handler produces.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/realm-server/server.ts               | 15 ++-
 .../realm-server/tests/cors-range-test.ts     | 91 +++++++++++++++++++
 packages/runtime-common/create-response.ts    |  5 +-
 3 files changed, 108 insertions(+), 3 deletions(-)
 create mode 100644 packages/realm-server/tests/cors-range-test.ts

diff --git a/packages/realm-server/server.ts b/packages/realm-server/server.ts
index c3cff5cff36..9f423041ade 100644
--- a/packages/realm-server/server.ts
+++ b/packages/realm-server/server.ts
@@ -1109,8 +1109,15 @@ export class RealmServer {
       .use(
         cors({
           origin: '*',
+          // Range/If-Range are here for native media playback: <audio>/<video>
+          // elements cannot attach Authorization, so the host's auth service
+          // worker re-issues their requests as mode:'cors' with the token
+          // injected. That rewrite turns the media element's Range header into
+          // an author header needing preflight approval — without Range in
+          // this list the preflight fails and the player errors before any
+          // bytes flow.
           allowHeaders:
-            'Authorization, Content-Type, If-Match, If-None-Match, X-Requested-With, X-Boxel-Client-Request-Id, X-Boxel-Assume-User, X-HTTP-Method-Override, X-Boxel-Disable-Module-Cache, X-Filename, X-Boxel-During-Prerender, X-Boxel-Consuming-Realm, X-Boxel-Job-Id, X-Boxel-Job-Priority, X-Boxel-Logging-Correlation-Id, X-Grafana-Device-Id, X-Grafana-Action',
+            'Authorization, Content-Type, If-Match, If-None-Match, If-Range, Range, X-Requested-With, X-Boxel-Client-Request-Id, X-Boxel-Assume-User, X-HTTP-Method-Override, X-Boxel-Disable-Module-Cache, X-Filename, X-Boxel-During-Prerender, X-Boxel-Consuming-Realm, X-Boxel-Job-Id, X-Boxel-Job-Priority, X-Boxel-Logging-Correlation-Id, X-Grafana-Device-Id, X-Grafana-Action',
           // Without an explicit expose list, @koa/cors only emits the
           // CORS-safelisted response headers (cache-control, content-*,
           // expires, last-modified, pragma). ETag is not on that list,
@@ -1121,7 +1128,11 @@ export class RealmServer {
           // protocol invisible to JS. Location/Retry-After are likewise
           // non-safelisted; expose them so a cross-origin client can read
           // the async-publish status monitor target off the 202 response.
-          exposeHeaders: 'ETag, Location, Retry-After',
+          // Content-Range/Accept-Ranges are what a cross-origin caller needs
+          // to reason about a 206 byte-range response (Content-Length is
+          // safelisted, but is listed for symmetry with the range pair).
+          exposeHeaders:
+            'ETag, Location, Retry-After, Content-Range, Accept-Ranges, Content-Length',
           allowMethods: 'GET,HEAD,PUT,POST,DELETE,PATCH,OPTIONS,QUERY',
           // Cache the preflight response for 24 h. Without this @koa/cors
           // omits Access-Control-Max-Age and Chrome falls back to its
diff --git a/packages/realm-server/tests/cors-range-test.ts b/packages/realm-server/tests/cors-range-test.ts
new file mode 100644
index 00000000000..3a369f0f2b9
--- /dev/null
+++ b/packages/realm-server/tests/cors-range-test.ts
@@ -0,0 +1,91 @@
+import QUnit from 'qunit';
+const { module, test } = QUnit;
+import { basename } from 'path';
+import type { Test, SuperTest } from 'supertest';
+import {
+  setupPermissionedRealmCached,
+  withRealmPath,
+  type RealmRequest,
+} from './helpers/index.ts';
+
+// CORS treatment of byte-range media requests. Native <audio>/<video>
+// elements cannot attach Authorization, so the host's auth service worker
+// re-issues their requests as mode:'cors' with the token injected. That
+// rewrite turns the media element's Range header into an author header
+// needing preflight approval, and makes the 206's descriptive headers
+// (Content-Range, Accept-Ranges) visible to the caller only when exposed.
+module(basename(import.meta.filename), function () {
+  module(
+    'Realm-specific Endpoints | CORS for Range requests',
+    function (hooks) {
+      let realmURL = new URL('http://127.0.0.1:4444/test/');
+      let request: RealmRequest;
+      let serverRequest: SuperTest<Test>;
+
+      setupPermissionedRealmCached(hooks, {
+        fixture: 'simple',
+        realmURL,
+        permissions: {
+          '*': ['read', 'write'],
+          '@node-test_realm:localhost': ['read', 'realm-owner'],
+        },
+        onRealmSetup: (args) => {
+          serverRequest = args.request;
+          request = withRealmPath(args.request, realmURL);
+        },
+      });
+
+      test('preflight approves Range and If-Range author headers', async function (assert) {
+        let response = await serverRequest
+          .options('/test/sample.png')
+          .set('Origin', 'https://app.example')
+          .set('Access-Control-Request-Method', 'GET')
+          .set(
+            'Access-Control-Request-Headers',
+            'range, if-range, authorization',
+          );
+
+        assert.strictEqual(response.status, 204, 'HTTP 204 status');
+        let allowed = (response.headers['access-control-allow-headers'] ?? '')
+          .toLowerCase()
+          .split(/,\s*/);
+        assert.true(allowed.includes('range'), 'Range is approved');
+        assert.true(allowed.includes('if-range'), 'If-Range is approved');
+        assert.true(
+          allowed.includes('authorization'),
+          'Authorization is approved',
+        );
+      });
+
+      test('a ranged response exposes its range headers to cross-origin JS', async function (assert) {
+        await request
+          .post('/sample.png')
+          .set('Content-Type', 'application/octet-stream')
+          .send(Buffer.from(new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])));
+
+        let response = await request
+          .get('/sample.png')
+          .set('Accept', 'image/*')
+          .set('Origin', 'https://app.example')
+          .set('Range', 'bytes=2-5');
+
+        assert.strictEqual(response.status, 206, 'HTTP 206 status');
+        let exposed = (response.headers['access-control-expose-headers'] ?? '')
+          .toLowerCase()
+          .split(/,\s*/);
+        assert.true(
+          exposed.includes('content-range'),
+          'Content-Range is exposed',
+        );
+        assert.true(
+          exposed.includes('accept-ranges'),
+          'Accept-Ranges is exposed',
+        );
+        assert.true(
+          exposed.includes('content-length'),
+          'Content-Length is exposed',
+        );
+      });
+    },
+  );
+});
diff --git a/packages/runtime-common/create-response.ts b/packages/runtime-common/create-response.ts
index b2e5df9c8e0..c658f743821 100644
--- a/packages/runtime-common/create-response.ts
+++ b/packages/runtime-common/create-response.ts
@@ -28,8 +28,11 @@ export function createResponse({
       // which is why `Retry-After` appears below: readiness pairs it with
       // `X-Boxel-Not-Ready` on a 503, and a cross-origin caller that could read
       // the stage but not the retry hint would only have half the answer.
+      // Content-Range/Accept-Ranges let a cross-origin caller reason about a
+      // 206 byte-range response (Content-Length is safelisted, but is listed
+      // for symmetry with the range pair).
       'Access-Control-Expose-Headers':
-        'X-Boxel-Realm-Url,X-Boxel-Realm-Public-Readable,X-Boxel-Realm-Archived,X-Boxel-Canonical-Path,X-Boxel-Not-Ready,Authorization,Cache-Control,ETag,Retry-After',
+        'X-Boxel-Realm-Url,X-Boxel-Realm-Public-Readable,X-Boxel-Realm-Archived,X-Boxel-Canonical-Path,X-Boxel-Not-Ready,Authorization,Cache-Control,ETag,Retry-After,Content-Range,Accept-Ranges,Content-Length',
     },
   });
 }

From dfc0ae5997681606116ec789485aed13ac4995cd Mon Sep 17 00:00:00 2001
From: Luke Melia <luke@lukemelia.com>
Date: Mon, 17 Aug 2026 22:45:11 -0400
Subject: [PATCH 2/2] Register range tests in the suite, fold CORS coverage
 into them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The realm-server test entrypoint loads an explicit file list, and neither
http-range-test nor range-request-test was on it, so none of the range or
CORS coverage was actually running in CI. Both are registered now.

The two CORS assertions move from their own module into range-request-test,
which stands up a byte-identical realm fixture — picking up its asserted
sample upload on the way. The exposure test now also pins
Access-Control-Allow-Origin, without which no expose list is consulted, and
the create-response comment states the real consumer of the exposed range
headers: the CORS-filtered Response the auth service worker hands the media
element via respondWith.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../realm-server/tests/cors-range-test.ts     | 91 -------------------
 packages/realm-server/tests/index.ts          |  2 +
 .../realm-server/tests/range-request-test.ts  | 61 +++++++++++++
 packages/runtime-common/create-response.ts    | 10 +-
 4 files changed, 70 insertions(+), 94 deletions(-)
 delete mode 100644 packages/realm-server/tests/cors-range-test.ts

diff --git a/packages/realm-server/tests/cors-range-test.ts b/packages/realm-server/tests/cors-range-test.ts
deleted file mode 100644
index 3a369f0f2b9..00000000000
--- a/packages/realm-server/tests/cors-range-test.ts
+++ /dev/null
@@ -1,91 +0,0 @@
-import QUnit from 'qunit';
-const { module, test } = QUnit;
-import { basename } from 'path';
-import type { Test, SuperTest } from 'supertest';
-import {
-  setupPermissionedRealmCached,
-  withRealmPath,
-  type RealmRequest,
-} from './helpers/index.ts';
-
-// CORS treatment of byte-range media requests. Native <audio>/<video>
-// elements cannot attach Authorization, so the host's auth service worker
-// re-issues their requests as mode:'cors' with the token injected. That
-// rewrite turns the media element's Range header into an author header
-// needing preflight approval, and makes the 206's descriptive headers
-// (Content-Range, Accept-Ranges) visible to the caller only when exposed.
-module(basename(import.meta.filename), function () {
-  module(
-    'Realm-specific Endpoints | CORS for Range requests',
-    function (hooks) {
-      let realmURL = new URL('http://127.0.0.1:4444/test/');
-      let request: RealmRequest;
-      let serverRequest: SuperTest<Test>;
-
-      setupPermissionedRealmCached(hooks, {
-        fixture: 'simple',
-        realmURL,
-        permissions: {
-          '*': ['read', 'write'],
-          '@node-test_realm:localhost': ['read', 'realm-owner'],
-        },
-        onRealmSetup: (args) => {
-          serverRequest = args.request;
-          request = withRealmPath(args.request, realmURL);
-        },
-      });
-
-      test('preflight approves Range and If-Range author headers', async function (assert) {
-        let response = await serverRequest
-          .options('/test/sample.png')
-          .set('Origin', 'https://app.example')
-          .set('Access-Control-Request-Method', 'GET')
-          .set(
-            'Access-Control-Request-Headers',
-            'range, if-range, authorization',
-          );
-
-        assert.strictEqual(response.status, 204, 'HTTP 204 status');
-        let allowed = (response.headers['access-control-allow-headers'] ?? '')
-          .toLowerCase()
-          .split(/,\s*/);
-        assert.true(allowed.includes('range'), 'Range is approved');
-        assert.true(allowed.includes('if-range'), 'If-Range is approved');
-        assert.true(
-          allowed.includes('authorization'),
-          'Authorization is approved',
-        );
-      });
-
-      test('a ranged response exposes its range headers to cross-origin JS', async function (assert) {
-        await request
-          .post('/sample.png')
-          .set('Content-Type', 'application/octet-stream')
-          .send(Buffer.from(new Uint8Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])));
-
-        let response = await request
-          .get('/sample.png')
-          .set('Accept', 'image/*')
-          .set('Origin', 'https://app.example')
-          .set('Range', 'bytes=2-5');
-
-        assert.strictEqual(response.status, 206, 'HTTP 206 status');
-        let exposed = (response.headers['access-control-expose-headers'] ?? '')
-          .toLowerCase()
-          .split(/,\s*/);
-        assert.true(
-          exposed.includes('content-range'),
-          'Content-Range is exposed',
-        );
-        assert.true(
-          exposed.includes('accept-ranges'),
-          'Accept-Ranges is exposed',
-        );
-        assert.true(
-          exposed.includes('content-length'),
-          'Content-Length is exposed',
-        );
-      });
-    },
-  );
-});
diff --git a/packages/realm-server/tests/index.ts b/packages/realm-server/tests/index.ts
index 764eb557fa1..9a8448da1c1 100644
--- a/packages/realm-server/tests/index.ts
+++ b/packages/realm-server/tests/index.ts
@@ -244,6 +244,8 @@ const ALL_TEST_FILES: string[] = [
   './file-watcher-events-test',
   './full-index-on-startup-test',
   './full-reindex-test',
+  './http-range-test',
+  './range-request-test',
   './http2-keepalive-test',
   './indexing-test',
   './lazy-mount-test',
diff --git a/packages/realm-server/tests/range-request-test.ts b/packages/realm-server/tests/range-request-test.ts
index 92f66bda873..7df29899ced 100644
--- a/packages/realm-server/tests/range-request-test.ts
+++ b/packages/realm-server/tests/range-request-test.ts
@@ -1,6 +1,7 @@
 import QUnit from 'qunit';
 const { module, test } = QUnit;
 import { basename } from 'path';
+import type { Test, SuperTest } from 'supertest';
 import {
   setupPermissionedRealmCached,
   withRealmPath,
@@ -16,6 +17,7 @@ module(basename(import.meta.filename), function () {
   module('Realm-specific Endpoints | Range requests', function (hooks) {
     let realmURL = new URL('http://127.0.0.1:4444/test/');
     let request: RealmRequest;
+    let serverRequest: SuperTest<Test>;
 
     setupPermissionedRealmCached(hooks, {
       fixture: 'simple',
@@ -25,6 +27,7 @@ module(basename(import.meta.filename), function () {
         '@node-test_realm:localhost': ['read', 'realm-owner'],
       },
       onRealmSetup: (args) => {
+        serverRequest = args.request;
         request = withRealmPath(args.request, realmURL);
       },
     });
@@ -223,5 +226,63 @@ module(basename(import.meta.filename), function () {
 
       assert.strictEqual(response.status, 304, 'HTTP 304 status');
     });
+
+    // CORS treatment of byte-range media requests. Native <audio>/<video>
+    // elements cannot attach Authorization, so the host's auth service worker
+    // re-issues their requests as mode:'cors' with the token injected. That
+    // rewrite turns the media element's Range header into an author header
+    // needing preflight approval, and makes the 206's descriptive headers
+    // (Content-Range, Accept-Ranges) visible to the player's loading stack
+    // only when exposed.
+    test('preflight approves Range and If-Range author headers', async function (assert) {
+      let response = await serverRequest
+        .options('/test/preflight.png')
+        .set('Origin', 'https://app.example')
+        .set('Access-Control-Request-Method', 'GET')
+        .set(
+          'Access-Control-Request-Headers',
+          'range, if-range, authorization',
+        );
+
+      assert.strictEqual(response.status, 204, 'HTTP 204 status');
+      let allowed = (response.headers['access-control-allow-headers'] ?? '')
+        .toLowerCase()
+        .split(/,\s*/);
+      assert.true(allowed.includes('range'), 'Range is approved');
+      assert.true(allowed.includes('if-range'), 'If-Range is approved');
+      assert.true(
+        allowed.includes('authorization'),
+        'Authorization is approved',
+      );
+    });
+
+    test('a ranged response exposes its range headers to cross-origin JS', async function (assert) {
+      await uploadSample('/cors-expose.png');
+      let response = await getSample('/cors-expose.png')
+        .set('Origin', 'https://app.example')
+        .set('Range', 'bytes=2-5');
+
+      assert.strictEqual(response.status, 206, 'HTTP 206 status');
+      assert.strictEqual(
+        response.headers['access-control-allow-origin'],
+        '*',
+        'the response is a CORS response, without which no expose list is consulted',
+      );
+      let exposed = (response.headers['access-control-expose-headers'] ?? '')
+        .toLowerCase()
+        .split(/,\s*/);
+      assert.true(
+        exposed.includes('content-range'),
+        'Content-Range is exposed',
+      );
+      assert.true(
+        exposed.includes('accept-ranges'),
+        'Accept-Ranges is exposed',
+      );
+      assert.true(
+        exposed.includes('content-length'),
+        'Content-Length is exposed',
+      );
+    });
   });
 });
diff --git a/packages/runtime-common/create-response.ts b/packages/runtime-common/create-response.ts
index c658f743821..e649c153b1a 100644
--- a/packages/runtime-common/create-response.ts
+++ b/packages/runtime-common/create-response.ts
@@ -28,9 +28,13 @@ export function createResponse({
       // which is why `Retry-After` appears below: readiness pairs it with
       // `X-Boxel-Not-Ready` on a 503, and a cross-origin caller that could read
       // the stage but not the retry hint would only have half the answer.
-      // Content-Range/Accept-Ranges let a cross-origin caller reason about a
-      // 206 byte-range response (Content-Length is safelisted, but is listed
-      // for symmetry with the range pair).
+      // Content-Range/Accept-Ranges must be exposed because the host's auth
+      // service worker hands the CORS-filtered Response from its own fetch()
+      // straight to the media element via respondWith. A header absent from
+      // this list is pruned from that filtered Response, so it is invisible
+      // to the player's loading stack, not just to app JS. Content-Length is
+      // CORS-safelisted and survives regardless; it is named alongside the
+      // pair so the range trio reads as one unit.
       'Access-Control-Expose-Headers':
         'X-Boxel-Realm-Url,X-Boxel-Realm-Public-Readable,X-Boxel-Realm-Archived,X-Boxel-Canonical-Path,X-Boxel-Not-Ready,Authorization,Cache-Control,ETag,Retry-After,Content-Range,Accept-Ranges,Content-Length',
     },