@3sln/trove 0.0.3 → 0.0.5

package/packages/core/src/notifications/index.js

@@ -1,17 +1,25 @@
-// NotificationCenter — batches @mentions and flushes them on a configurable
-// interval, exactly as requested: as conversations mutate, mentions accumulate
-// per user; every `flushIntervalMs` we drain the batch, drop it into each user's
-// inbox, and fire a (bodyless) web push so their service worker wakes and pulls
-// the inbox. Push subscriptions, pending batches, and inboxes live in the
-// pluggable KeyValueStore, so this survives restarts and works multi-instance.
+// NotificationCenter — batches @mentions and drains them on a configurable
+// interval: as conversations mutate, mentions accumulate per user; every
+// `flushIntervalMs` we drain the batch, collapse it into one notification, drop that
+// into the user's inbox, and hand it to each delivery channel. Pending batches and
+// inboxes live in the pluggable KeyValueStore, so this survives restarts and works
+// multi-instance.
 //
-// Bodyless push (see webpush.js) means we never put mention text on a third-party
-// push service — the client fetches /api/notifications over its authenticated
-// channel instead.
+// The split worth keeping straight: the INBOX is the record, and it is written whether
+// or not anything can be delivered — /api/notifications serves it and a drive with no
+// channels configured still notifies people perfectly well. A CHANNEL is the part that
+// goes and tells someone, and it is allowed to fail. Web push is one channel (see
+// webpush.js); email or a chat workspace would be others, and nothing here knows the
+// difference between them.
+//
+// Bodyless push means mention text never reaches a third-party push service — the
+// client fetches /api/notifications over its authenticated channel instead. That is a
+// property of the web-push channel rather than of this file, but it is the reason the
+// inbox has to exist independently of delivery.
 
-import { assertPublicUrl } from '../util.js';
+import { TroveError } from '../errors.js';
+import { WebPushChannel } from './webpush.js';
 
-const NS_SUBS = 'push-subs'; // userId -> [subscription]
 const NS_PENDING = 'mentions-pending'; // userId -> [mention]
 const NS_INBOX = 'notifications-inbox'; // userId -> [notification]
 
@@ -19,21 +27,31 @@ export class NotificationCenter {
   /**
    * @param {object} deps
    * @param {import('../kv.js').KeyValueStore} deps.kv
-import { assertPublicUrl } from '../util.js';
-   * @param {import('./webpush.js').WebPushService} [deps.push]
+   * @param {import('./channel.js').NotificationChannel[]} [deps.channels] delivery
+   * @param {import('./webpush.js').WebPushService} [deps.push] the pre-channel
+   *   spelling of "web push": a bare service, wrapped into a channel here so there is
+   *   still exactly one delivery path.
    * @param {number} [deps.flushIntervalMs] default 30s
    * @param {number} [deps.inboxCap] keep at most N per user (default 200)
    */
-  constructor({ kv, push, flushIntervalMs = 30_000, inboxCap = 200 }) {
+  constructor({ kv, push, channels, flushIntervalMs = 30_000, inboxCap = 200 }) {
     this.kv = kv;
-    this.push = push || null;
+    this.channels = [
+      ...(channels || []),
+      ...(push ? [new WebPushChannel({ kv, service: push })] : []),
+    ];
     this.flushIntervalMs = flushIntervalMs;
     this.inboxCap = inboxCap;
     this._timer = null;
   }
 
+  /** A channel by id, for the callers that need a specific one. */
+  channel(id) {
+    return this.channels.find((c) => c.id === id) || null;
+  }
+
   vapidPublicKey() {
-    return this.push?.publicKey || null;
+    return this.channel('web-push')?.publicKey || null;
   }
 
   /** Queue mention events (from SidecarService.onMentions). */
@@ -45,8 +63,25 @@ import { assertPublicUrl } from '../util.js';
     }
   }
 
-  /** Drain all pending batches: inbox + push. Returns how many users notified. */
+  /**
+   * Drain all pending batches: inbox + push. Returns how many users notified.
+   *
+   * Concurrent calls collapse onto one drain. There are two callers — the interval
+   * timer, and maintenance on a runtime whose timers do not survive a request — and
+   * both can be live at once. Two drains reading the same pending batch would deliver
+   * it twice, because the read and the delete are not one operation.
+   *
+   * This makes one PROCESS safe, not a cluster: two servers over a shared KV can still
+   * both read a batch before either deletes it. That race predates this and wants a
+   * claim in the store to fix properly.
+   */
   async flush(now = Date.now()) {
+    if (this._draining) return this._draining;
+    this._draining = this.#drain(now).finally(() => { this._draining = null; });
+    return this._draining;
+  }
+
+  async #drain(now) {
     const pendingUsers = await this.kv.list(NS_PENDING);
     let notified = 0;
     for (const { key: userId, value: mentions } of pendingUsers) {
@@ -70,47 +105,41 @@ import { assertPublicUrl } from '../util.js';
       inbox.unshift(note);
       await this.kv.set(NS_INBOX, userId, inbox.slice(0, this.inboxCap));
       await this.kv.delete(NS_PENDING, userId);
-      await this.#pushTo(userId, note);
+      await this.#deliver(userId, note);
       notified++;
     }
     return notified;
   }
 
-  async #pushTo(userId, note) {
-    if (!this.push) return;
-    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
-    const alive = [];
-    for (const sub of subs) {
+  /**
+   * Hand one notification to every channel.
+   *
+   * Sequential and forgiving: a channel that throws is logged and the others still run.
+   * The inbox was written above, so a failed send costs the ping and not the
+   * notification — which is the whole reason the inbox is not itself a channel.
+   */
+  async #deliver(userId, note) {
+    for (const channel of this.channels) {
       try {
-        const res = await this.push.send(sub, { topic: 'mentions', urgency: 'normal' });
-        if (!res.gone) alive.push(sub);
-      } catch {
-        alive.push(sub); // transient — keep the subscription, retry next flush
+        await channel.deliver(userId, note);
+      } catch (err) {
+        console.error(`[trove] notification channel "${channel.id}" failed for ${userId}`, err);
       }
     }
-    if (alive.length !== subs.length) await this.kv.set(NS_SUBS, userId, alive);
   }
 
   // --- subscriptions & inbox (called by routes) ------------------------------
 
   async subscribePush(userId, subscription) {
-    if (!subscription?.endpoint) throw new Error('Invalid push subscription');
-    // The server POSTs to this endpoint, from inside its own network, on every flush.
-    // Left unchecked it is a request forgery primitive any user can register — cloud
-    // instance metadata being the obvious target. A real push service is on the public
-    // internet, so nothing legitimate is lost by refusing the rest.
-    assertPublicUrl(subscription.endpoint, 'Push endpoint');
-    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
-    if (!subs.some((s) => s.endpoint === subscription.endpoint)) {
-      subs.push(subscription);
-      await this.kv.set(NS_SUBS, userId, subs);
-    }
-    return { ok: true };
+    const channel = this.channel('web-push');
+    if (!channel) throw TroveError.unsupported('Web push is not configured');
+    return channel.subscribe(userId, subscription);
   }
+
   async unsubscribePush(userId, endpoint) {
-    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
-    await this.kv.set(NS_SUBS, userId, subs.filter((s) => s.endpoint !== endpoint));
-    return { ok: true };
+    const channel = this.channel('web-push');
+    if (!channel) throw TroveError.unsupported('Web push is not configured');
+    return channel.unsubscribe(userId, endpoint);
   }
 
   async inbox(userId) {

package/packages/core/src/notifications/webpush.js

@@ -18,6 +18,8 @@
 
 import { TroveError } from '../errors.js';
 import { withRetry } from '../retry.js';
+import { assertPublicUrl } from '../util.js';
+import { NotificationChannel } from './channel.js';
 
 const enc = new TextEncoder();
 
@@ -215,3 +217,111 @@ export class WebPushService {
     );
   }
 }
+
+// --- as a notification channel --------------------------------------------------
+
+const NS_SUBS = 'push-subs'; // userId -> [subscription]
+
+/**
+ * Web push, as one way of reaching someone.
+ *
+ * Owns the subscriptions as well as the sending, because they are the same concern:
+ * a subscription is a push endpoint and means nothing to any other channel. It also
+ * owns the endpoints a browser uses to register one — the VAPID public key and the
+ * subscribe/unsubscribe pair — so a drive with no push configured does not answer on
+ * `/api/push/*` at all, rather than answering with a null.
+ */
+export class WebPushChannel extends NotificationChannel {
+  /**
+   * @param {object} o
+   * @param {import('../kv.js').KeyValueStore} o.kv where subscriptions live
+   * @param {WebPushService} [o.service] a ready service; otherwise built from the keys
+   * @param {string} [o.publicKey]
+   * @param {string} [o.privateKey]
+   * @param {string} [o.subject]
+   */
+  constructor({ kv, service, publicKey, privateKey, subject } = {}) {
+    super();
+    if (!kv) throw TroveError.invalid('WebPushChannel requires a kv store');
+    this.kv = kv;
+    this.service = service ?? new WebPushService({ publicKey, privateKey, subject });
+  }
+
+  get id() { return 'web-push'; }
+
+  /** The application server key a browser needs to subscribe. */
+  get publicKey() { return this.service.publicKey; }
+
+  async deliver(userId, note) {
+    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
+    const alive = [];
+    for (const sub of subs) {
+      try {
+        const res = await this.service.send(sub, { topic: 'mentions', urgency: 'normal' });
+        if (!res.gone) alive.push(sub);
+      } catch {
+        alive.push(sub); // transient — keep the subscription, retry next drain
+      }
+    }
+    if (alive.length !== subs.length) await this.kv.set(NS_SUBS, userId, alive);
+  }
+
+  async subscribe(userId, subscription) {
+    if (!subscription?.endpoint) throw TroveError.invalid('Invalid push subscription');
+    // The server POSTs to this endpoint, from inside its own network, on every drain.
+    // Left unchecked it is a request forgery primitive any user can register — cloud
+    // instance metadata being the obvious target. A real push service is on the public
+    // internet, so nothing legitimate is lost by refusing the rest.
+    assertPublicUrl(subscription.endpoint, 'Push endpoint');
+    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
+    if (!subs.some((s) => s.endpoint === subscription.endpoint)) {
+      subs.push(subscription);
+      await this.kv.set(NS_SUBS, userId, subs);
+    }
+    return { ok: true };
+  }
+
+  async unsubscribe(userId, endpoint) {
+    const subs = (await this.kv.get(NS_SUBS, userId)) || [];
+    await this.kv.set(NS_SUBS, userId, subs.filter((s) => s.endpoint !== endpoint));
+    return { ok: true };
+  }
+
+  /**
+   * The registration endpoints, owned here rather than by the core route table.
+   *
+   * They exist only when this channel does, which is the improvement over declaring
+   * them centrally: a drive with no VAPID keys used to answer `/api/push/vapid` with
+   * `{ publicKey: null }` and accept subscriptions it could never send to. Now there is
+   * no route at all, and a client that asks gets a 404 meaning what it says.
+   *
+   * The paths are unchanged, because the shipped web app calls them by name.
+   */
+  routes({ body, requirePrincipal }) {
+    return [
+      {
+        method: 'GET',
+        path: '/api/push/vapid',
+        handler: () => ({ publicKey: this.publicKey }),
+      },
+      {
+        method: 'POST',
+        path: '/api/push/subscribe',
+        handler: async ({ principal, req }) => {
+          requirePrincipal(principal);
+          const b = await body(req);
+          return this.subscribe(principal.id, b.subscription);
+        },
+      },
+      {
+        method: 'DELETE',
+        path: '/api/push/subscribe',
+        handler: async ({ principal, req }) => {
+          requirePrincipal(principal);
+          const b = await body(req);
+          return this.unsubscribe(principal.id, b.endpoint);
+        },
+      },
+    ];
+  }
+}

package/packages/core/src/sqlite-d1.js

@@ -23,6 +23,19 @@ import { SqliteDatabase, SqliteProvider } from './sqlite.js';
 // The keys the server co-locates in one database — see LocalSqliteProvider.
 const CORE_KEYS = new Set(['metadata', 'kv', 'plugins', 'search']);
 
+// D1 answers `PRAGMA journal_mode = WAL` with SQLITE_AUTH: setting a pragma is not
+// something a D1 client may do. The shared metadata schema opens with two of them, and
+// that runs in SqliteStore.init() — so the first request a Workers drive ever served
+// died, and every one after it, on a statement that is pure local-file housekeeping and
+// means nothing here. Dropped rather than made conditional at the call site: this is the
+// one place that knows it is talking to D1.
+//
+// Only ASSIGNMENTS. `PRAGMA table_info(nodes)` is a query, D1 supports it, and the trash
+// migration reads it to decide whether it has already run — filtering that too would
+// silently re-run migrations.
+const PRAGMA_ASSIGNMENT = /^\s*PRAGMA\s+[\w.]+\s*=/i;
+const notAPragmaAssignment = (statement) => !PRAGMA_ASSIGNMENT.test(statement);
+
 /** Split a multi-statement DDL script into individual statements. */
 function splitStatements(sql) {
   // Good enough for the schema DDL Trove ships, which contains no semicolons inside
@@ -51,7 +64,7 @@ class D1Database extends SqliteDatabase {
     // D1's own exec() is documented as slow and unsuitable for anything hot; it is also
     // inconsistent about multi-statement input across versions. Batching prepared
     // statements is both faster and atomic, which is what schema setup wants.
-    const statements = splitStatements(sql);
+    const statements = splitStatements(sql).filter(notAPragmaAssignment);
     if (!statements.length) return;
     if (statements.length === 1) {
       await this.d1.prepare(statements[0]).run();

package/packages/core/src/sqlite-driver.js

@@ -3,6 +3,18 @@
 // expose the same statement API — prepare().run/get/all(...params), exec() for
 // raw/multi-statement SQL, close() — and differ only in the constructor, so
 // callers get one `db` handle that behaves identically under either runtime.
+//
+// Both also load extensions, which is what sqlite-vec needs for a durable vector index:
+// node:sqlite via `allowExtension` at construction, bun:sqlite natively. The one place
+// that is not true is macOS under Bun, where the system libsqlite3 Bun links is built
+// without extension support — see useExtensionCapableSqlite below.
+//
+// better-sqlite3 is deliberately not used here. It would add a native dependency that
+// every consumer installs, including Workers deployments that can never call it, in
+// exchange for a feature set both built-ins already have — and it does not survive the
+// trade: constructing one under Bun 1.2.23 and 1.3.14 on macOS arm64 aborts the process
+// with `NAPI FATAL ERROR`, which is a panic rather than a throw and so cannot even be
+// caught and fallen back from.
 
 import { TroveError } from './errors.js';
 
@@ -22,9 +34,69 @@ export async function openDatabase(pathOrMemory = ':memory:') {
   return db;
 }
 
+// Held in a variable so a bundler cannot read it.
+//
+// `await import('bun:sqlite')` behind a `typeof Bun` guard still fails to BUILD for
+// Workers: esbuild resolves a literal specifier statically, and a guard is a runtime
+// thing that says nothing about what the bundler does with the module graph. The result
+// was a wrangler build that could not link, from an import that would never have run.
+// A non-literal specifier is not resolvable at build time, so it survives as a runtime
+// import — which the guard then never reaches.
+const BUN_SQLITE = 'bun:sqlite';
+
+// Where a SQLite that can load extensions tends to live on macOS. Ordered: an explicit
+// setting wins, then Homebrew on Apple Silicon, then Homebrew on Intel.
+const MACOS_SQLITE_CANDIDATES = [
+  '/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib',
+  '/usr/local/opt/sqlite/lib/libsqlite3.dylib',
+];
+
+let customSqliteTried = false;
+
+/**
+ * Point Bun at a SQLite that can load extensions, on the one platform where it cannot.
+ *
+ * `bun:sqlite` supports extensions natively — `loadExtension` is right there and works
+ * on Linux with nothing special. macOS is the exception, and not because of Bun: the
+ * SYSTEM libsqlite3 that Bun links by default is built without
+ * SQLITE_ENABLE_LOAD_EXTENSION, so the call comes back "This build of sqlite3 does not
+ * support dynamic extension loading". The effect is that sqlite-vec cannot load, and
+ * semantic search silently degrades to an in-memory index rebuilt on every restart —
+ * on developer laptops specifically, which is where it is least likely to be noticed.
+ *
+ * `setCustomSQLite` is Bun's documented answer. It has to happen before any database is
+ * opened, hence doing it here rather than at the point extensions are wanted.
+ *
+ * Best-effort throughout: if no capable library is installed we leave Bun on the system
+ * one and the sqlite-vec store degrades exactly as it did before, with its own warning.
+ * Set TROVE_SQLITE_LIB to override the search.
+ */
+async function useExtensionCapableSqlite(Database) {
+  if (customSqliteTried || process.platform !== 'darwin') return;
+  customSqliteTried = true;
+  if (typeof Database.setCustomSQLite !== 'function') return;
+
+  const configured = process.env.TROVE_SQLITE_LIB;
+  const { existsSync } = await import('node:fs');
+  const candidates = configured ? [configured] : MACOS_SQLITE_CANDIDATES;
+  for (const lib of candidates) {
+    if (!existsSync(lib)) continue;
+    try {
+      Database.setCustomSQLite(lib);
+      return;
+    } catch { /* keep looking; the default is still a working database */ }
+  }
+  // Only worth saying when it was asked for explicitly — otherwise this is the ordinary
+  // case of a machine without Homebrew sqlite, and the vector store says its own piece.
+  if (configured) {
+    console.warn(`[trove] TROVE_SQLITE_LIB=${configured} could not be used; falling back to the system SQLite`);
+  }
+}
+
 async function open(pathOrMemory) {
   if (typeof Bun !== 'undefined') {
-    const { Database } = await import('bun:sqlite');
+    const { Database } = await import(BUN_SQLITE);
+    await useExtensionCapableSqlite(Database);
     return new Database(pathOrMemory);
   }
   try {

package/packages/core/src/storage/diagnose.js

@@ -0,0 +1,234 @@
+// Is the backing store actually usable from a browser?
+//
+// This exists because of a failure that cost a day. A drive was serving its file list
+// fine, and every file opened to a spinner that never resolved. The server was healthy,
+// the storage was healthy, the download endpoint returned 200 in 300ms — and the browser
+// still could not read a single byte, because the R2 bucket had no CORS policy. Nothing
+// in the system knew: CORS is enforced in the browser, so the server's own request to
+// the same bucket succeeded, and the only evidence was a console message in one tab.
+//
+// So the check has to be the browser's check. A CORS preflight is an ordinary OPTIONS
+// request that anyone can send, including us — and a preflight never touches the object,
+// so it works against a key that does not exist and costs nothing. Sending it against a
+// presigned URL and reading the response headers is exactly what a browser does before
+// it will hand a response to a page. If it fails for us it fails for them.
+//
+// The point is not detection for its own sake. Each finding carries the command that
+// fixes it: a diagnostic that says "CORS is misconfigured" to someone who did not know
+// buckets had a CORS policy has told them nothing they can act on.
+
+/** A key that need not exist — a preflight is answered without looking one up. */
+const PROBE_KEY = '.trove-cors-probe';
+
+/**
+ * Every code this module can produce.
+ *
+ * Exported because the caller that raises these as issues also has to CLEAR the ones a
+ * later check no longer reports — that is what makes fixing the bucket make the warning
+ * go away. Deriving the clear-set from the same list the checks use means a new finding
+ * cannot be added without becoming clearable.
+ */
+export const STORAGE_ISSUE_CODES = [
+  'storage-unreachable',
+  'cors-missing',
+  'cors-origin',
+  'cors-headers',
+  'cors-expose',
+  'cors-unknown',
+];
+
+/** Headers the client sends on a download, so a policy that omits them breaks reads. */
+const NEEDED_REQUEST_HEADERS = ['range'];
+
+/**
+ * Headers the client must be able to READ off the response.
+ *
+ * Cross-origin responses expose almost nothing by default, and these are not cosmetic:
+ * without `content-range` the text viewer cannot tell a truncated file from a whole one,
+ * and without `accept-ranges` seeking in audio and video is not offered at all.
+ *
+ * Checked against a real GET rather than the preflight — see where this is used.
+ */
+const NEEDED_EXPOSED_HEADERS = ['content-range', 'content-length'];
+
+const csv = (value) => String(value || '').toLowerCase().split(',').map((s) => s.trim()).filter(Boolean);
+
+/**
+ * Diagnose one collection's backing store.
+ *
+ * Ordered: an unreachable store short-circuits, because "CORS is not configured" is a
+ * misleading thing to say about a bucket whose credentials are wrong.
+ *
+ * @param {object} deps
+ * @param {import('./interface.js').StorageBackend} deps.storage
+ * @param {string} [deps.origin]  the browser origin to check against — the drive's own
+ *   public URL. Omitted means the CORS check is skipped rather than guessed at: a policy
+ *   is allowed to be origin-specific, so checking the wrong origin invents a problem.
+ * @param {string} [deps.driver]  store driver key, to word the remedy for it
+ * @param {typeof fetch} [deps.fetchImpl]
+ * @returns {Promise<Array<{code: string, severity: string, title: string, detail: string, remedy?: string}>>}
+ */
+export async function diagnoseStorage({ storage, origin = null, driver = null, fetchImpl = null } = {}) {
+  const findings = [];
+  if (!storage) return findings;
+  const doFetch = fetchImpl || (typeof fetch === 'function' ? fetch : null);
+
+  // --- can we talk to it at all? ---------------------------------------------
+  try {
+    await storage.list({ limit: 1 });
+  } catch (err) {
+    findings.push({
+      code: 'storage-unreachable',
+      severity: 'error',
+      title: 'The backing store could not be reached',
+      detail: err?.message || String(err),
+      remedy:
+        'Check the collection’s store settings: the bucket or directory must exist, and '
+        + 'for an S3-compatible store the endpoint, region and credentials must all be for '
+        + 'that bucket. A wrong endpoint and a wrong key look identical from here.',
+    });
+    return findings;
+  }
+
+  // --- does the browser get to read it? --------------------------------------
+  // Only when downloads go straight from the browser to the store. A drive that proxies
+  // its bytes through the server is same-origin all the way, and CORS never applies —
+  // reporting a bucket policy as missing there would be a problem the admin cannot have.
+  const caps = storage.capabilities || {};
+  if (!caps.presignDownload) return findings;
+  if (!origin || !doFetch) return findings;
+
+  let url;
+  try {
+    url = await storage.presignGet(PROBE_KEY, { expiresIn: 60 });
+  } catch {
+    // A store that claims presignDownload and cannot presign is a bug, not a
+    // configuration problem, and it will surface far more loudly elsewhere.
+    return findings;
+  }
+
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: 'OPTIONS',
+      headers: {
+        origin,
+        'access-control-request-method': 'GET',
+        'access-control-request-headers': NEEDED_REQUEST_HEADERS.join(','),
+      },
+    });
+  } catch (err) {
+    findings.push({
+      code: 'cors-unknown',
+      severity: 'warning',
+      title: 'Could not check whether the store allows browser access',
+      detail: `The preflight request to the store failed: ${err?.message || err}`,
+      remedy: 'This is usually a network or endpoint problem rather than a CORS one — '
+        + 'confirm the store’s endpoint is reachable from the server.',
+    });
+    return findings;
+  }
+
+  const allowOrigin = res.headers.get('access-control-allow-origin');
+  if (!allowOrigin) {
+    findings.push({
+      code: 'cors-missing',
+      severity: 'error',
+      title: 'The store does not allow browser access, so files will not open',
+      detail:
+        `A CORS preflight from ${origin} was answered without an `
+        + `Access-Control-Allow-Origin header (HTTP ${res.status}). Browsers will refuse `
+        + 'every download, including previews and thumbnails, while the file list and '
+        + 'search keep working normally.',
+      remedy: corsRemedy(origin, driver),
+    });
+    return findings;
+  }
+
+  if (allowOrigin !== '*' && allowOrigin.toLowerCase() !== origin.toLowerCase()) {
+    findings.push({
+      code: 'cors-origin',
+      severity: 'error',
+      title: 'The store allows a different origin than this drive',
+      detail: `It allows "${allowOrigin}", but this drive is served from "${origin}". `
+        + 'A policy naming the wrong origin is refused exactly like no policy at all.',
+      remedy: corsRemedy(origin, driver),
+    });
+    return findings;
+  }
+
+  // Allowed, but possibly not for everything we send or need back. These are warnings:
+  // opening a small file will work, so the drive is usable — it is seeking in a video
+  // and reading the head of a large file that break.
+  const allowHeaders = csv(res.headers.get('access-control-allow-headers'));
+  const missingRequest = allowHeaders.includes('*')
+    ? []
+    : NEEDED_REQUEST_HEADERS.filter((h) => !allowHeaders.includes(h));
+  if (missingRequest.length) {
+    findings.push({
+      code: 'cors-headers',
+      severity: 'warning',
+      title: 'The store’s CORS policy blocks ranged reads',
+      detail: `It does not allow the ${missingRequest.join(', ')} request header, so seeking `
+        + 'in audio and video, and previewing the start of a large file, will fail. Whole-file '
+        + 'downloads are unaffected.',
+      remedy: corsRemedy(origin, driver),
+    });
+  }
+
+  // Exposed headers are read off the ACTUAL response, not the preflight — that is where
+  // the spec puts them and where the browser looks. Some stores echo them on a preflight
+  // and some do not, so checking the OPTIONS response reports a correctly configured
+  // bucket as broken. A GET for a key that does not exist is answered 404 WITH the CORS
+  // headers when a policy matches, which is all this needs.
+  let actual;
+  try {
+    actual = await doFetch(url, { method: 'GET', headers: { origin } });
+  } catch {
+    // The preflight already passed, so the policy is in place; failing to complete this
+    // second request says nothing more about it. Warning here would be guessing.
+    return findings;
+  }
+
+  const exposed = csv(actual.headers.get('access-control-expose-headers'));
+  const missingExposed = exposed.includes('*')
+    ? []
+    : NEEDED_EXPOSED_HEADERS.filter((h) => !exposed.includes(h));
+  if (missingExposed.length) {
+    findings.push({
+      code: 'cors-expose',
+      severity: 'warning',
+      title: 'The store hides response headers the viewer needs',
+      detail: `${missingExposed.join(', ')} are not in exposeHeaders, so the browser cannot read `
+        + 'them. Trove cannot then tell a truncated preview from a complete file, and will '
+        + 'not offer seeking.',
+      remedy: corsRemedy(origin, driver),
+    });
+  }
+
+  return findings;
+}
+
+/** The policy this drive needs, as something that can be pasted. */
+export function corsPolicy(origin) {
+  return [{
+    AllowedOrigins: [origin],
+    AllowedMethods: ['GET', 'PUT', 'HEAD'],
+    AllowedHeaders: ['content-type', 'range'],
+    ExposeHeaders: ['ETag', 'Content-Length', 'Content-Type', 'Content-Range', 'Accept-Ranges'],
+    MaxAgeSeconds: 3600,
+  }];
+}
+
+function corsRemedy(origin, driver) {
+  const json = JSON.stringify(corsPolicy(origin), null, 2);
+  // R2 is the common case for a Workers deployment and its tooling is not the AWS CLI,
+  // so name it explicitly rather than leaving the admin to translate.
+  const r2 = driver === 's3'
+    ? '\n\nOn Cloudflare R2, save the JSON above as cors.json and run:\n'
+      + '  wrangler r2 bucket cors put <bucket> --file cors.json\n\n'
+      + 'On AWS S3:\n'
+      + '  aws s3api put-bucket-cors --bucket <bucket> --cors-configuration file://cors.json'
+    : '';
+  return `Allow this origin on the bucket. The policy Trove needs:\n\n${json}${r2}`;
+}