bunqueue-dashboard 0.0.32 → 0.0.33

package/agent/dbQueryWorker.ts

@@ -1,22 +1,45 @@
 /**
- * Disposable worker that runs ONE read-only query and posts the result back.
+ * Disposable worker that runs ONE read-only database operation and posts the
+ * result back: an arbitrary query or an atomic table CSV export.
  *
- * queryWithTimeout() (agent/db.ts) spawns one of these per /db/query request and
- * races it against a wall clock, so a runaway O(N^k) scan can't freeze the
- * agent's process-control endpoints. terminate() does NOT preempt a synchronous
- * sqlite3_step, though — it abandons the response, and this thread keeps running
- * until SQLite finishes, which is why db.ts caps how many can be alive at once.
- * The connection is opened readonly inside dbQuery, so nothing here can mutate
- * the store.
+ * queryWithTimeout() and exportWithTimeout() (agent/db.ts) spawn one of these
+ * per request and race it against a wall clock, so a runaway scan/sort can't
+ * freeze the agent's process-control endpoints. terminate() does NOT preempt a
+ * synchronous sqlite3_step, though — it abandons the response, and this thread
+ * keeps running until SQLite finishes, which is why db.ts caps how many can be
+ * alive at once. Both dbQuery and dbExportCsv open readonly connections, so
+ * nothing here can mutate the store.
  */
-import { dbQuery, MissingDbError } from './db';
+import { type DbFilter, dbExportCsv, dbQuery, MissingDbError } from './db';
 
 declare const self: Worker;
 
 self.addEventListener('message', (ev: MessageEvent) => {
-  const { path, sql } = ev.data as { path: string; sql: string };
+  const request = ev.data as
+    | { kind?: 'query'; path: string; sql: string }
+    | {
+        kind: 'export';
+        path: string;
+        table: string;
+        orderBy?: string;
+        dir: 'asc' | 'desc';
+        filter?: DbFilter;
+      };
   try {
-    self.postMessage({ ok: true, result: dbQuery(path, sql) });
+    if (request.kind === 'export') {
+      const exported = dbExportCsv(
+        request.path,
+        request.table,
+        request.orderBy,
+        request.dir,
+        request.filter
+      );
+      // Transfer the bounded CSV buffer instead of cloning it or JSON-encoding
+      // up to 16 MiB a second time in either isolate.
+      self.postMessage({ ok: true, export: exported }, [exported.content.buffer]);
+    } else {
+      self.postMessage({ ok: true, result: dbQuery(request.path, request.sql) });
+    }
   } catch (e) {
     // postMessage can't carry the error class, so flag the one the route branches
     // on (MissingDbError → 404) and let db.ts rebuild it on the parent side.

package/agent/manager.ts

@@ -56,6 +56,10 @@ const STOP_TIMEOUT_MS = 8000;
  */
 const MAX_LINE = 8192;
 
+interface CancelablePipeReader {
+  cancel(reason?: unknown): Promise<void>;
+}
+
 function defaultConfig(): ServerConfig {
   return {
     command: process.env.BUNQUEUE_START_CMD || 'bunqueue start',
@@ -66,6 +70,92 @@ function defaultConfig(): ServerConfig {
   };
 }
 
+const CONFIG_KEYS = new Set<keyof ServerConfig>([
+  'command',
+  'httpPort',
+  'tcpPort',
+  'dataPath',
+  'extraEnv',
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function validatePort(name: 'httpPort' | 'tcpPort', value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 65_535) {
+    throw new Error(`${name} must be an integer between 1 and 65535`);
+  }
+  return value;
+}
+
+/**
+ * Validate an untrusted PUT /control/config body before any field is merged.
+ * Returning a fresh object (including a fresh extraEnv) makes setConfig atomic:
+ * one invalid field cannot leave earlier fields applied, and the caller cannot
+ * mutate the accepted config later through a retained object reference.
+ */
+export function validateConfigPatch(value: unknown): Partial<ServerConfig> {
+  if (!isRecord(value)) throw new Error('Config must be an object');
+
+  for (const key of Object.keys(value)) {
+    if (!CONFIG_KEYS.has(key as keyof ServerConfig)) {
+      throw new Error(`Unknown config key: ${key}`);
+    }
+  }
+
+  const patch: Partial<ServerConfig> = {};
+  if (Object.hasOwn(value, 'command')) {
+    if (typeof value.command !== 'string' || value.command.trim() === '') {
+      throw new Error('command must be a non-empty string');
+    }
+    patch.command = value.command;
+  }
+  if (Object.hasOwn(value, 'httpPort')) {
+    patch.httpPort = validatePort('httpPort', value.httpPort);
+  }
+  if (Object.hasOwn(value, 'tcpPort')) {
+    patch.tcpPort = validatePort('tcpPort', value.tcpPort);
+  }
+  if (Object.hasOwn(value, 'dataPath')) {
+    if (typeof value.dataPath !== 'string') throw new Error('dataPath must be a string');
+    patch.dataPath = value.dataPath;
+  }
+  if (Object.hasOwn(value, 'extraEnv')) {
+    if (!isRecord(value.extraEnv)) {
+      throw new Error('extraEnv must be an object containing only string values');
+    }
+    const entries = Object.entries(value.extraEnv);
+    for (const [key, entry] of entries) {
+      if (typeof entry !== 'string') {
+        throw new Error(`extraEnv.${key} must be a string`);
+      }
+    }
+    // fromEntries defines "__proto__" as ordinary data instead of invoking the
+    // legacy Object.prototype setter via indexed assignment.
+    patch.extraEnv = Object.fromEntries(entries) as Record<string, string>;
+  }
+  return patch;
+}
+
+/** Validate the complete snapshot start() is about to pass to the child. */
+function validateServerConfig(value: unknown): ServerConfig {
+  if (!isRecord(value)) throw new Error('Config must be an object');
+  const config = validateConfigPatch(value);
+  for (const key of CONFIG_KEYS) {
+    if (!Object.hasOwn(value, key)) {
+      throw new Error(`Missing config key: ${key}`);
+    }
+  }
+  return config as ServerConfig;
+}
+
+function copyConfig(config: ServerConfig): ServerConfig {
+  return { ...config, extraEnv: { ...config.extraEnv } };
+}
+
 export class ProcessManager {
   private proc: ReturnType<typeof Bun.spawn> | null = null;
   private status: Status = 'stopped';
@@ -91,9 +181,27 @@ export class ProcessManager {
   private stopping: Promise<StatusSnapshot> | null = null;
   /** Latched by shutdown(): once set, start() refuses to spawn a new child. */
   private shuttingDown = false;
+  /** Active stdout/stderr readers, grouped by the process generation they own. */
+  private pipeReaders = new Map<number, Set<CancelablePipeReader>>();
+
+  /**
+   * Actively break pending reader.read() calls for a finished generation. A
+   * descendant may inherit the child's pipe descriptor and keep it open after
+   * the managed process exits; token checks alone cannot release that reader.
+   */
+  private cancelPipes(token: number): void {
+    const readers = this.pipeReaders.get(token);
+    if (!readers) return;
+    this.pipeReaders.delete(token);
+    for (const reader of readers) {
+      void reader.cancel('process generation ended').catch(() => {
+        /* already closed/cancelled */
+      });
+    }
+  }
 
   getConfig(): ServerConfig {
-    return this.config;
+    return copyConfig(this.config);
   }
 
   /**
@@ -103,8 +211,13 @@ export class ProcessManager {
    * changed in place.
    */
   setConfig(patch: Partial<ServerConfig>): ServerConfig {
-    this.config = { ...this.config, ...patch, extraEnv: patch.extraEnv ?? this.config.extraEnv };
-    return this.config;
+    const valid = validateConfigPatch(patch);
+    this.config = {
+      ...this.config,
+      ...valid,
+      extraEnv: valid.extraEnv ?? this.config.extraEnv,
+    };
+    return copyConfig(this.config);
   }
 
   getStatus(): StatusSnapshot {
@@ -113,8 +226,8 @@ export class ProcessManager {
       pid: this.proc?.pid ?? null,
       startedAt: this.startedAt,
       exitCode: this.exitCode,
-      config: this.config,
-      runningConfig: this.runningConfig,
+      config: copyConfig(this.config),
+      runningConfig: this.runningConfig ? copyConfig(this.runningConfig) : null,
     };
   }
 
@@ -173,16 +286,14 @@ export class ProcessManager {
     const statusAfterWait = this.status as Status;
     if (statusAfterWait === 'running' || statusAfterWait === 'starting') return this.getStatus();
 
-    // Validate BEFORE mutating status / burning a proc token. Doing it after
-    // (as this once did) means a bad command leaves the manager wedged: an
-    // empty command stranded the previous generation's dead pid + runningConfig
-    // (its stop()/onExit finalizers were already token-stale), and a non-string
-    // `command` from PUT /control/config threw out of `.trim()` with status
-    // pinned at 'starting', disabling every UI control until the agent restarts.
-    const command = typeof this.config.command === 'string' ? this.config.command : '';
-    const parts = command.trim().split(/\s+/);
+    // Validate the COMPLETE launch snapshot BEFORE mutating status / burning a
+    // proc token. setConfig() already validates API patches, but defaultConfig()
+    // also reads environment values; e.g. HTTP_PORT=70000 must not reach spawn.
+    // Doing this later can wedge status at 'starting' and strand stale process
+    // metadata when validation throws.
+    const launchConfig = validateServerConfig(this.config);
+    const parts = launchConfig.command.trim().split(/\s+/);
     const [cmd, ...args] = parts;
-    if (!cmd) throw new Error('Empty command');
 
     this.status = 'starting';
     this.exitCode = null;
@@ -193,10 +304,10 @@ export class ProcessManager {
     // while runningConfig (and the agent's /health probe) reported the old port.
     const env: Record<string, string> = {
       ...(process.env as Record<string, string>),
-      ...this.config.extraEnv,
-      HTTP_PORT: String(this.config.httpPort),
-      TCP_PORT: String(this.config.tcpPort),
-      BUNQUEUE_DATA_PATH: this.config.dataPath,
+      ...launchConfig.extraEnv,
+      HTTP_PORT: String(launchConfig.httpPort),
+      TCP_PORT: String(launchConfig.tcpPort),
+      BUNQUEUE_DATA_PATH: launchConfig.dataPath,
     };
 
     try {
@@ -205,6 +316,9 @@ export class ProcessManager {
         stdout: 'pipe',
         stderr: 'pipe',
         onExit: (_p, code) => {
+          // Always tear down this generation's readers, even if shared state
+          // already belongs to a replacement process.
+          this.cancelPipes(token);
           // Ignore the exit of a process a newer start() has already replaced.
           if (this.procToken !== token) return;
           this.exitCode = code ?? null;
@@ -227,45 +341,69 @@ export class ProcessManager {
 
     this.startedAt = Date.now();
     this.status = 'running';
-    this.runningConfig = { ...this.config, extraEnv: { ...this.config.extraEnv } };
-    this.push('sys', `started: ${this.config.command} (pid ${this.proc.pid})`);
+    this.runningConfig = copyConfig(launchConfig);
+    this.push('sys', `started: ${launchConfig.command} (pid ${this.proc.pid})`);
     // stdout/stderr are spawned as pipes, so they are ReadableStreams at
     // runtime; Bun types them as a union that also includes a numeric fd.
-    void this.pipe(this.proc.stdout as unknown as ReadableStream<Uint8Array>, 'stdout');
-    void this.pipe(this.proc.stderr as unknown as ReadableStream<Uint8Array>, 'stderr');
+    void this.pipe(this.proc.stdout as unknown as ReadableStream<Uint8Array>, 'stdout', token);
+    void this.pipe(this.proc.stderr as unknown as ReadableStream<Uint8Array>, 'stderr', token);
     return this.getStatus();
   }
 
-  private async pipe(stream: ReadableStream<Uint8Array>, name: 'stdout' | 'stderr'): Promise<void> {
+  private async pipe(
+    stream: ReadableStream<Uint8Array>,
+    name: 'stdout' | 'stderr',
+    token: number
+  ): Promise<void> {
     const reader = stream.getReader();
+    let readers = this.pipeReaders.get(token);
+    if (!readers) {
+      readers = new Set();
+      this.pipeReaders.set(token, readers);
+    }
+    readers.add(reader);
     const decoder = new TextDecoder();
     let buffer = '';
     try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buffer += decoder.decode(value, { stream: true });
-        let i: number;
-        while ((i = buffer.indexOf('\n')) !== -1) {
-          const line = buffer.slice(0, i);
-          buffer = buffer.slice(i + 1);
-          if (line.trim()) this.push(name, line);
-        }
-        // No newline in sight: flush in MAX_LINE slices instead of letting the
-        // buffer (and the eventual single LogLine) grow to the whole output.
-        while (buffer.length > MAX_LINE) {
-          this.push(name, buffer.slice(0, MAX_LINE));
-          buffer = buffer.slice(MAX_LINE);
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          // A process can exit while a descendant keeps its inherited pipe
+          // open. If a replacement has started by the time bytes arrive, those
+          // bytes belong to the obsolete generation and must never enter the
+          // current log view.
+          if (this.procToken !== token) return;
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          let i: number;
+          while ((i = buffer.indexOf('\n')) !== -1) {
+            const line = buffer.slice(0, i);
+            buffer = buffer.slice(i + 1);
+            if (line.trim() && this.procToken === token) this.push(name, line);
+          }
+          // No newline in sight: flush in MAX_LINE slices instead of letting the
+          // buffer (and the eventual single LogLine) grow to the whole output.
+          while (buffer.length > MAX_LINE) {
+            if (this.procToken !== token) return;
+            this.push(name, buffer.slice(0, MAX_LINE));
+            buffer = buffer.slice(MAX_LINE);
+          }
         }
+      } catch {
+        /* stream closed */
       }
-    } catch {
-      /* stream closed */
+      if (this.procToken !== token) return;
+      // Flush the final chunk when the stream ends without a trailing newline
+      // (e.g. a crash cause written via a bare write()) — otherwise the last,
+      // often most important, line never reaches the log buffer.
+      const tail = buffer + decoder.decode();
+      if (tail.trim() && this.procToken === token) this.push(name, tail);
+    } finally {
+      const activeReaders = this.pipeReaders.get(token);
+      activeReaders?.delete(reader);
+      if (activeReaders?.size === 0) this.pipeReaders.delete(token);
+      reader.releaseLock();
     }
-    // Flush the final chunk when the stream ends without a trailing newline
-    // (e.g. a crash cause written via a bare write()) — otherwise the last,
-    // often most important, line never reaches the log buffer.
-    const tail = buffer + decoder.decode();
-    if (tail.trim()) this.push(name, tail);
   }
 
   async stop(): Promise<StatusSnapshot> {
@@ -333,6 +471,9 @@ export class ProcessManager {
       ]).finally(() => clearTimeout(reapTimer));
       if (!reaped) this.push('sys', `pid ${proc.pid} did not exit after SIGKILL — giving up on it`);
     }
+    // onExit normally performs this cancellation. Repeat it idempotently for
+    // a process whose `exited` promise/callback never settles after SIGKILL.
+    this.cancelPipes(token);
     // Only finalize shared state if no newer start() replaced this generation
     // while we awaited — otherwise we'd null out the wrong (live) process.
     if (this.procToken !== token) return this.getStatus();

package/agent/server.ts

@@ -18,28 +18,45 @@
  *     cover a *same-origin* request: a page whose DNS name is rebound to
  *     127.0.0.1 issues same-origin GETs that carry no `Origin` header, so it
  *     could otherwise read /control/status, /control/logs and the /db/*
- *     inspector (job payloads) even with a token set (the token exempts reads).
+ *     inspector (job payloads). When the agent is reachable beyond loopback,
+ *     every route also requires the configured token; Host validation remains
+ *     necessary because it rejects the rebound request before any data leaves.
  *     When `allowedHosts` is configured, a request whose `Host` header names a
  *     hostname outside the allowlist is rejected (403) — the rebinding page's
  *     `Host` is the attacker's domain, never a loopback/allowlisted host.
- *  4. Optional bearer token (AGENT_TOKEN): when set, state-changing requests
- *     must present it (`Authorization: Bearer <t>` or `x-agent-token: <t>`).
+ *  4. Optional bearer token (AGENT_TOKEN): on loopback, when set, changing
+ *     requests must present it. A network-facing caller must set
+ *     `requireTokenForAll`, which protects reads and writes alike.
  */
-import { type DbFilter, dbCell, dbInfo, dbRows, dbSchema, dbTables, MissingDbError, queryWithTimeout } from './db';
-import type { ProcessManager, ServerConfig } from './manager';
+import {
+  type DbFilter,
+  dbCell,
+  DbExportBusyError,
+  DbExportUnavailableError,
+  dbInfo,
+  dbRows,
+  dbSchema,
+  dbTables,
+  exportWithTimeout,
+  MissingDbError,
+  queryWithTimeout,
+} from './db';
+import { type ProcessManager, validateConfigPatch } from './manager';
 
 export interface AgentOptions {
   allowedOrigins: string[];
   /**
    * DNS-rebinding defense: when set (non-empty), a request whose `Host` header
    * resolves to a hostname outside this list is rejected. Compared by hostname
-   * only (port stripped). Leave undefined to disable the check — e.g. when the
-   * agent is fronted by a proxy that already validates Host, or bound to a
-   * non-loopback interface where the user opted into network exposure.
+   * only (port stripped). Leave undefined only for a loopback-only integration
+   * or when a trusted front proxy has already enforced Host. Network-facing
+   * listeners must configure this allowlist.
    */
   allowedHosts?: string[];
-  /** When set, POST/PUT requests must present this token. */
+  /** On loopback, when set, POST/PUT requests must present this token. */
   token?: string;
+  /** Network exposure: require `token` on every non-OPTIONS request, including reads. */
+  requireTokenForAll?: boolean;
 }
 
 const DEFAULT_ORIGINS = ['http://localhost:5273', 'http://127.0.0.1:5273'];
@@ -94,14 +111,14 @@ export function isOriginAllowed(origin: string | null, allowed: string[]): boole
 }
 
 /**
- * Host-header allowlist. Disabled (always true) when `allowed` is undefined. A
- * missing Host header is a non-browser/loopback caller and is allowed; a
- * present Host must match by hostname. A DNS-rebinding page always sends its
- * own domain as Host, so it fails this check.
+ * Host-header allowlist. Disabled (always true) when `allowed` is undefined.
+ * Once enabled it is fail-closed: a real HTTP request always has Host, and
+ * accepting a missing one would create an avoidable bypass for unusual proxy
+ * paths. A DNS-rebinding page sends its own domain as Host, so it fails too.
  */
 export function isHostAllowed(host: string | null, allowed?: string[]): boolean {
   if (!allowed) return true;
-  if (!host) return true; // non-browser caller — no Host header
+  if (!host) return false;
   return allowed.includes(hostnameOf(host));
 }
 
@@ -119,7 +136,7 @@ export function corsHeaders(origin: string | null, allowed: string[]): Record<st
 }
 
 function tokenOk(req: Request, token?: string): boolean {
-  if (!token) return true;
+  if (!token) return false;
   const auth = req.headers.get('authorization') ?? '';
   const bearer = auth.startsWith('Bearer ') ? auth.slice(7) : '';
   return bearer === token || req.headers.get('x-agent-token') === token;
@@ -130,7 +147,7 @@ function tokenOk(req: Request, token?: string): boolean {
  * ProcessManager and policy, returns an async (req) => Response.
  */
 export function createFetchHandler(mgr: ProcessManager, opts: AgentOptions) {
-  const { allowedOrigins, allowedHosts, token } = opts;
+  const { allowedOrigins, allowedHosts, token, requireTokenForAll = false } = opts;
 
   const json = (data: unknown, status: number, origin: string | null): Response =>
     new Response(JSON.stringify(data), {
@@ -149,9 +166,15 @@ export function createFetchHandler(mgr: ProcessManager, opts: AgentOptions) {
           signal: AbortSignal.timeout(1500),
         });
         if (res.ok) {
-          const h = (await res.json()) as { ok?: boolean; version?: string };
-          healthy = h.ok !== false;
-          version = h.version;
+          const body: unknown = await res.json();
+          if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+            const health = body as Record<string, unknown>;
+            // HTTP 2xx alone is not a Bunqueue health verdict: an unrelated
+            // process, proxy fallback, or malformed payload can also return it.
+            // Fail closed unless the semantic health flag is exactly true.
+            healthy = health.ok === true;
+            if (typeof health.version === 'string') version = health.version;
+          }
         }
       } catch {
         /* not up yet */
@@ -166,10 +189,6 @@ export function createFetchHandler(mgr: ProcessManager, opts: AgentOptions) {
     const method = req.method;
     const origin = req.headers.get('origin');
 
-    if (method === 'OPTIONS') {
-      return new Response(null, { status: 204, headers: corsHeaders(origin, allowedOrigins) });
-    }
-
     // DNS-rebinding defense: reject a same-origin request whose Host header is
     // an attacker domain rebound to loopback (no Origin header would be sent,
     // so the Origin gate below can't see it). No-op when allowedHosts is unset.
@@ -182,16 +201,20 @@ export function createFetchHandler(mgr: ProcessManager, opts: AgentOptions) {
       return json({ ok: false, error: 'Origin not allowed' }, 403, origin);
     }
 
-    // The optional AGENT_TOKEN gates STATE-CHANGING requests only. Read-only
-    // GETs (including the /db/* inspector, which can expose job payloads) are
-    // protected by the Origin allowlist alone — a drive-by cross-origin page
-    // can't read the response (no ACAO for its origin), which is the real
-    // threat. Reads intentionally remain available without a token for local
-    // dashboards that don't configure AGENT_TOKEN; when a token is configured,
-    // the browser client does send it, but only POST/PUT require it.
-    // Non-browser local callers on loopback are trusted for reads.
+    // Preflight never needs a bearer token, but Host and Origin are security
+    // boundaries in their own right and therefore fail closed before this 204.
+    if (method === 'OPTIONS') {
+      return new Response(null, { status: 204, headers: corsHeaders(origin, allowedOrigins) });
+    }
+
+    // Preserve zero-config LOOPBACK use: there, reads stay open and a configured
+    // token gates mutations. A network-facing listener sets requireTokenForAll,
+    // because Origin alone cannot authenticate curl/no-Origin callers and the db
+    // inspector contains job payloads. Misconfiguration fails closed: enabling
+    // the all-route gate without a token makes every real route answer 401.
     const mutating = method === 'POST' || method === 'PUT';
-    if (mutating && !tokenOk(req, token)) {
+    const authRequired = requireTokenForAll || (mutating && Boolean(token));
+    if (authRequired && !tokenOk(req, token)) {
       return json({ ok: false, error: 'Unauthorized' }, 401, origin);
     }
 
@@ -214,7 +237,7 @@ export function createFetchHandler(mgr: ProcessManager, opts: AgentOptions) {
 
       if (pathname === '/control/config' && method === 'GET') return json(mgr.getConfig(), 200, origin);
       if (pathname === '/control/config' && method === 'PUT') {
-        const patch = (await req.json()) as Partial<ServerConfig>;
+        const patch = validateConfigPatch(await req.json());
         return json(mgr.setConfig(patch), 200, origin);
       }
 
@@ -235,12 +258,71 @@ export function createFetchHandler(mgr: ProcessManager, opts: AgentOptions) {
         const segs = pathname.slice('/db/tables/'.length).split('/');
         const table = decodeURIComponent(segs[0] ?? '');
         const sub = segs[1];
+        if (segs.length === 2 && sub === 'export') {
+          const sp = new URL(req.url).searchParams;
+          const allowedParams = new Set(['orderBy', 'dir', 'fcol', 'fop', 'fval']);
+          for (const key of sp.keys()) {
+            if (!allowedParams.has(key)) throw new Error(`Unknown database export option: ${key}`);
+            if (sp.getAll(key).length !== 1) {
+              throw new Error(`Duplicate database export option: ${key}`);
+            }
+          }
+
+          const orderByParam = sp.get('orderBy');
+          if (orderByParam === '') throw new Error('Database export orderBy must not be empty');
+          const dirParam = sp.get('dir');
+          if (dirParam !== null && dirParam !== 'asc' && dirParam !== 'desc') {
+            throw new Error('Database export dir must be "asc" or "desc"');
+          }
+          const fCol = sp.get('fcol');
+          const fOp = sp.get('fop');
+          const fVal = sp.get('fval');
+          const hasAnyFilterPart = fCol !== null || fOp !== null || fVal !== null;
+          let filter: DbFilter | undefined;
+          if (hasAnyFilterPart) {
+            if (!fCol || !fVal || (fOp !== 'contains' && fOp !== 'eq' && fOp !== 'ne')) {
+              throw new Error('Database export filter requires valid fcol, fop and fval values');
+            }
+            filter = { column: fCol, op: fOp, value: fVal };
+          }
+
+          const exported = await exportWithTimeout(
+            mgr.getConfig().dataPath,
+            table,
+            orderByParam ?? undefined,
+            dirParam === 'desc' ? 'desc' : 'asc',
+            filter,
+            req.signal
+          );
+          return new Response(exported.content, {
+            status: 200,
+            headers: {
+              'Content-Type': 'text/csv; charset=utf-8',
+              'Content-Length': String(exported.bytes),
+              // Keep Content-Length equal to the authoritative export-byte contract;
+              // intermediaries must not transparently recompress this body.
+              'Cache-Control': 'no-store, no-transform',
+              'X-Content-Type-Options': 'nosniff',
+              'X-Bunqueue-Db-Export-Version': '1',
+              'X-Bunqueue-Db-Export-Table': encodeURIComponent(exported.table),
+              'X-Bunqueue-Db-Export-Rows': String(exported.rowCount),
+              'X-Bunqueue-Db-Export-Bytes': String(exported.bytes),
+              'X-Bunqueue-Db-Export-Cap': exported.cap ?? 'none',
+              'Access-Control-Expose-Headers':
+                'Content-Length, X-Bunqueue-Db-Export-Version, X-Bunqueue-Db-Export-Table, X-Bunqueue-Db-Export-Rows, X-Bunqueue-Db-Export-Bytes, X-Bunqueue-Db-Export-Cap',
+              ...corsHeaders(origin, allowedOrigins),
+            },
+          });
+        }
         if (segs.length === 2 && sub === 'schema') {
           return json({ ok: true, ...dbSchema(mgr.getConfig().dataPath, table) }, 200, origin);
         }
         if (segs.length === 2 && sub === 'cell') {
           const sp = new URL(req.url).searchParams;
-          const rowid = Number(sp.get('rowid'));
+          // Keep rowid textual through the HTTP boundary. Number() rounded
+          // values above 2^53 before SQLite ever saw the bound parameter.
+          const rowid = sp.get('rowid');
+          if (rowid === null) throw new Error('rowid is required');
           const column = sp.get('column') ?? '';
           return json(
             { ok: true, ...dbCell(mgr.getConfig().dataPath, table, rowid, column) },
@@ -276,7 +358,14 @@ export function createFetchHandler(mgr: ProcessManager, opts: AgentOptions) {
     } catch (e) {
       // A missing database file is an expected pre-first-start condition — 404
       // so the UI can show "no database yet" distinctly from a real read error.
-      const status = e instanceof MissingDbError ? 404 : 400;
+      const status =
+        e instanceof MissingDbError
+          ? 404
+          : e instanceof DbExportBusyError
+            ? 429
+            : e instanceof DbExportUnavailableError
+              ? 503
+              : 400;
       return json({ ok: false, error: (e as Error).message ?? String(e) }, status, origin);
     }
   };