unbound-cli 1.14.0 → 1.15.0

package/src/lib/downloads.js

@@ -0,0 +1,343 @@
+/**
+ * The generated-download job flow: start, poll, fetch.
+ *
+ * A CSV export is prepared by a background worker and served from object
+ * storage, so every caller does the same three steps. They live here so
+ * `unbound download` and `analytics tool-use --format csv` cannot drift apart.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const api = require('../api');
+const output = require('../output');
+
+const DOWNLOADS_PATH = '/api/v1/downloads';
+const MAX_EXPORT_ROWS = 25000;
+
+const POLL_INTERVAL_MS = 2000;
+// The worker's own soft limit is 30 minutes. Waiting slightly past it means a
+// job that dies at that limit surfaces as its own failure rather than as ours.
+const MAX_WAIT_MS = 1_860_000;
+// How long a finished export stays fetchable, matching the server's retention.
+const RETENTION_HOURS = 6;
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * The download kinds the server offers, for help text and tab-completion.
+ *
+ * Advisory only — an unlisted kind is still sent through, so a producer added
+ * to the backend is usable without waiting for a CLI release. The server is the
+ * authority on what exists and answers 400 for anything it does not know.
+ */
+const KINDS = {
+  'logs-export': {
+    summary: 'Every LLM call: prompt, model, tokens, status, user and task ID.',
+    filters: ['model_ids', 'application_ids', 'status_codes', 'application_owner_email',
+      'application_types', 'tool_types'],
+  },
+  'logs-tasks-export': {
+    summary: 'One row per task (agent session), with its thread ID.',
+    filters: ['model_ids', 'tool_types', 'application_owner_email', 'user_ids'],
+  },
+  'analytics-export': {
+    summary: 'Tool Use rows. Needs dataset=terminal-runs|mcp-actions|unsanctioned|mcp-servers.',
+    filters: ['dataset', 'risk_levels', 'command_families', 'server', 'intent_attribution',
+      'policy_ids', 'tool_types', 'user_ids'],
+  },
+  'analytics-tasks-export': {
+    summary: 'Analytics > Tasks, optionally narrowed to one heatmap day.',
+    filters: ['user_ids', 'tool_types', 'date', 'tz'],
+  },
+  'users-export': {
+    summary: 'Analytics > Users: per-user cost, tokens and activity.',
+    filters: ['user_ids', 'sort_field', 'sort_order'],
+  },
+};
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function fetchHint(jobId) {
+  return `Fetch it within ${RETENTION_HOURS} hours:\n    unbound download get ${jobId}`;
+}
+
+function isJobId(value) {
+  return UUID_RE.test(String(value || '').trim());
+}
+
+// The server names the file, but it must not be able to choose where the file
+// lands. Keep the basename only, so "../../.zshrc" cannot escape the cwd.
+function safeFilename(name, fallback) {
+  const base = path.basename(String(name || '').trim());
+  return base && base !== '.' && base !== '..' ? base : fallback;
+}
+
+function formatBytes(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+}
+
+// Counting rows happens synchronously inside both calls below, and on a wide
+// window it measured ~4s against production. The 30s default left too little
+// headroom, so an export that was merely slow to admit failed as a timeout.
+const ADMISSION_TIMEOUT_MS = 120000;
+
+/** Ask how many rows a selection holds, without starting anything. */
+function checkCount(kind, queryString) {
+  return api.get(`${DOWNLOADS_PATH}/${kind}/count/${queryString ? `?${queryString}` : ''}`,
+    { timeoutMs: ADMISSION_TIMEOUT_MS });
+}
+
+/** Start a job. Resolves the job row; the file does not exist yet. */
+function startJob(kind, queryString) {
+  return api.post(`${DOWNLOADS_PATH}/${kind}/${queryString ? `?${queryString}` : ''}`,
+    { timeoutMs: ADMISSION_TIMEOUT_MS });
+}
+
+/**
+ * Start a job at a producer's own endpoint rather than the generic one.
+ *
+ * The analytics export lives behind its own path but enqueues the same job, and
+ * its admission runs the same synchronous count — so it needs the same timeout.
+ */
+function startExportAt(path) {
+  return api.post(path, { timeoutMs: ADMISSION_TIMEOUT_MS });
+}
+
+function getJob(jobId) {
+  return api.get(`${DOWNLOADS_PATH}/${jobId}/`);
+}
+
+/**
+ * Poll a job until it stops being queued or running.
+ *
+ * The interrupt handler is registered before the spinner's, which exits the
+ * process on its own SIGINT — registering after would mean never printing the
+ * job id, and an unreachable export is the whole reason `download get` exists.
+ */
+async function waitForJob(jobId, title) {
+  // A caller with no dataset to name degrades the label to just "export".
+  const label = title ? `${title} export` : 'export';
+  let spin = null;
+  const onInterrupt = () => {
+    if (spin) spin.stop();
+    output.info(`The ${label} is still being prepared. ${fetchHint(jobId)}`);
+    process.exit(130);
+  };
+  process.on('SIGINT', onInterrupt);
+  // Printed before the wait, not only on interrupt: a hard kill (a script's
+  // timeout, a closed terminal) never runs the handler, and without the id the
+  // finished file is unreachable for its whole retention window.
+  output.info(`Export ${jobId} started.`);
+  spin = output.spinner(`Preparing ${label}…`);
+
+  try {
+    const deadline = Date.now() + MAX_WAIT_MS;
+    for (;;) {
+      const job = await getJob(jobId);
+
+      if (job.status === 'completed') {
+        spin.stop();
+        return job;
+      }
+      if (job.status === 'failed') {
+        throw new Error(job.error || 'The export failed while it was being prepared.');
+      }
+      if (job.status === 'expired') {
+        throw new Error(`This export has expired. Exports are kept for ${RETENTION_HOURS} hours.`);
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `The ${label} is taking longer than expected and is still running.\n  ${fetchHint(jobId)}`
+        );
+      }
+
+      const rows = Number(job.row_count) || 0;
+      spin.update(rows > 0 ? `Preparing ${label}… ${rows.toLocaleString()} rows` : `Preparing ${label}…`);
+      await sleep(POLL_INTERVAL_MS);
+    }
+  } catch (err) {
+    spin.stop();
+    throw err;
+  } finally {
+    process.removeListener('SIGINT', onInterrupt);
+  }
+}
+
+/**
+ * Sign a URL for a finished job and stream it to disk or stdout.
+ *
+ * The presigned URL is a bearer capability for as long as it lives, so it is
+ * never printed, logged, or written anywhere — only piped straight through.
+ */
+/**
+ * Move the finished download onto its final path.
+ *
+ * A server-chosen name is linked rather than renamed. rename() replaces
+ * silently, and the whole transfer sits between the existence check and this
+ * point, so anything created in the meantime would be overwritten. link() fails
+ * with EEXIST instead, which is the guarantee this is supposed to make.
+ *
+ * An explicit -o is the user naming the file, so there rename is correct.
+ */
+function placeFile(partial, target, { replace, name }) {
+  if (replace) {
+    fs.renameSync(partial, target);
+    return;
+  }
+  try {
+    fs.linkSync(partial, target);
+  } catch (err) {
+    if (err.code === 'EEXIST') {
+      throw new Error(
+        `${name} already exists here. Pass -o <file> to choose where this export goes.`
+      );
+    }
+    throw err;
+  }
+  fs.unlinkSync(partial);
+}
+
+async function downloadJob(job, destinationPath, title) {
+  const { url, filename } = await api.get(`${DOWNLOADS_PATH}/${job.id}/url/`);
+  const name = safeFilename(filename || job.filename, `unbound-export-${job.id}.csv`);
+  const destination = destinationPath || (process.stdout.isTTY ? name : null);
+
+  // The server picks this name, so it must not land on top of anything: a
+  // backend could otherwise drop a file called `.zshrc` into whatever directory
+  // the command ran in. Checked up front only to fail before a long download;
+  // placeFile is what actually enforces it. An explicit -o is the user's own
+  // choice and may replace a file, but only once the download has succeeded.
+  if (destination && !destinationPath && fs.existsSync(path.resolve(destination))) {
+    throw new Error(
+      `${name} already exists here. Pass -o <file> to choose where this export goes.`
+    );
+  }
+
+  let target = null;
+  let partial = null;
+  try {
+    const { bytes } = await api.fetchToStream(url, {
+      onHeaders: () => {
+        if (!destination) return process.stdout;
+        target = path.resolve(destination);
+        // Written to a sibling temp file and renamed on success. Streaming
+        // straight to `target` would truncate an existing file the moment the
+        // stream opened, so a transfer that failed halfway would destroy it.
+        // 'wx' fails rather than following a symlink or reusing a leftover.
+        partial = `${target}.part-${process.pid}`;
+        return fs.createWriteStream(partial, { flags: 'wx', mode: 0o600 });
+      },
+    });
+
+    if (target) {
+      placeFile(partial, target, { replace: Boolean(destinationPath), name });
+      partial = null;
+      const rows = Number(job.row_count) || 0;
+      const what = title ? `${title} row(s)` : 'row(s)';
+      output.success(`Exported ${rows.toLocaleString()} ${what} to ${target} (${formatBytes(bytes)})`);
+    }
+    return target;
+  } catch (err) {
+    // A half-written export parses as valid CSV and reads as a complete one, so
+    // drop it. Only ever the temp file — the user's own file is untouched.
+    if (partial) {
+      try {
+        fs.unlinkSync(partial);
+      } catch {
+        // Nothing was written, or it is already gone.
+      }
+    }
+    throw err;
+  }
+}
+
+/** Start, wait, and save in one call. */
+async function runExport(kind, queryString, { output: destination, title } = {}) {
+  const job = await startJob(kind, queryString);
+  const finished = await waitForJob(job.id, title);
+  await downloadJob(finished, destination, title);
+  return finished;
+}
+
+/** Fetch an already-started job, waiting first if it is still running. */
+async function fetchExisting(jobId, { output: destination, title } = {}) {
+  if (!isJobId(jobId)) {
+    throw new Error(`"${jobId}" is not a valid export id. It looks like 4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6.`);
+  }
+  const job = await getJob(jobId);
+
+  if (job.status === 'failed') {
+    throw new Error(job.error || 'This export failed while it was being prepared.');
+  }
+  if (job.status === 'expired') {
+    throw new Error(`This export has expired. Exports are kept for ${RETENTION_HOURS} hours.`);
+  }
+  const ready = job.status === 'completed' ? job : await waitForJob(jobId, title);
+  await downloadJob(ready, destination, title);
+  return ready;
+}
+
+/**
+ * Turn a server refusal into something a human or an agent can act on.
+ *
+ * `byJobId` changes what a 404 means: looking up a job that does not exist, has
+ * been swept, or belongs to another organization is indistinguishable by
+ * design, and none of those are "the backend is too old".
+ */
+function describeError(err, what = 'export', { byJobId = false, listing = false } = {}) {
+  if (err instanceof api.ApiError) {
+    if (err.statusCode === 404) {
+      if (byJobId) {
+        return `No export with that ID. It may have expired — exports are kept for ${RETENTION_HOURS} hours.`;
+      }
+      // Reading a table and preparing a file fail for different reasons, and
+      // telling someone their backend lacks background exports when they only
+      // asked to list rows sends them after the wrong thing.
+      return listing
+        ? `This Unbound backend does not serve ${what} yet.`
+        : `This Unbound backend does not serve the ${what} yet. ` +
+          'It needs a backend version that includes background CSV exports.';
+    }
+    if (err.statusCode === 405) {
+      return `This Unbound backend is too old for this CLI: it still streams the ${what} ` +
+        'instead of preparing it in the background. Upgrade the backend, or pin the CLI to 1.14.0.';
+    }
+    if (err.statusCode === 403) {
+      return listing
+        ? 'Admin role required. Analytics > Tool Use is restricted to organization admins.'
+        : 'Admin role required. Exporting data is restricted to organization admins.';
+    }
+    if (err.statusCode === 422) {
+      const rows = Number(err.body?.row_count);
+      const limit = Number(err.body?.limit) || MAX_EXPORT_ROWS;
+      if (Number.isFinite(rows) && rows > 0) {
+        return `This selection holds ${rows.toLocaleString()} rows, over the ${limit.toLocaleString()}-row export limit. ` +
+          'Narrow the date range or add filters.';
+      }
+    }
+  }
+  return err.message;
+}
+
+module.exports = {
+  DOWNLOADS_PATH,
+  KINDS,
+  MAX_EXPORT_ROWS,
+  RETENTION_HOURS,
+  checkCount,
+  describeError,
+  downloadJob,
+  fetchExisting,
+  fetchHint,
+  formatBytes,
+  getJob,
+  isJobId,
+  placeFile,
+  runExport,
+  safeFilename,
+  startExportAt,
+  startJob,
+  waitForJob,
+};

package/src/output.js

@@ -1,3 +1,5 @@
+const { sanitizeForTerminal } = require('./chartRender');
+
 /**
  * Output formatting utilities for the Unbound CLI.
  * Provides table, JSON, and key-value output for terminal display.
@@ -49,6 +51,70 @@ function table(rows, columns) {
   }
 }
 
+const MIN_COLUMN_WIDTH = 6;
+
+function clip(value, width) {
+  // Sanitize before measuring: these cells carry commands and prompts recorded
+  // from agents, so an OSC or CSI sequence in one would otherwise reach the
+  // terminal and could rewrite the title, the clipboard, or earlier output.
+  const text = sanitizeForTerminal(value).replace(/\s+/g, ' ').trim();
+  if (text.length <= width) return text;
+  if (width <= 1) return text.slice(0, width);
+  return `${text.slice(0, width - 1)}…`;
+}
+
+/**
+ * Render log rows as a table that fits the terminal.
+ *
+ * Unlike table(), every cell is collapsed to one line and clipped to a share of
+ * the available width, so a 4KB prompt or a long command cannot flood the
+ * screen. Pass { wide: true } to print values in full.
+ *
+ * @param {string[]} headers
+ * @param {Array<string[]>} rows - cells aligned to headers
+ * @param {{wide?: boolean, maxWidth?: number}} [opts]
+ */
+function logTable(headers, rows, opts = {}) {
+  if (!rows || rows.length === 0) {
+    console.log(c.dim('No results found.'));
+    return;
+  }
+
+  const natural = headers.map((header, i) =>
+    Math.max(String(header).length, ...rows.map((row) => clip(row[i], Number.POSITIVE_INFINITY).length))
+  );
+
+  let widths = natural;
+  if (!opts.wide) {
+    // process.stdout.columns is undefined when piped, so fall back to the
+    // COLUMNS convention before the default.
+    const envColumns = Number.parseInt(process.env.COLUMNS, 10);
+    const terminalWidth =
+      opts.maxWidth || process.stdout.columns || (Number.isInteger(envColumns) && envColumns > 0 ? envColumns : 120);
+    const gutters = 2 * (headers.length - 1);
+    const budget = Math.max(terminalWidth - gutters, headers.length * MIN_COLUMN_WIDTH);
+    const total = natural.reduce((a, b) => a + b, 0);
+
+    if (total > budget) {
+      // Give every column its minimum first, then share what's left in
+      // proportion to how much each column actually wants.
+      const spare = Math.max(budget - headers.length * MIN_COLUMN_WIDTH, 0);
+      const over = natural.map((w) => Math.max(w - MIN_COLUMN_WIDTH, 0));
+      const overTotal = over.reduce((a, b) => a + b, 0) || 1;
+      widths = natural.map((w, i) =>
+        Math.min(w, MIN_COLUMN_WIDTH + Math.floor((over[i] / overTotal) * spare))
+      );
+    }
+  }
+
+  const line = (cells) =>
+    cells.map((cell, i) => clip(cell, widths[i]).padEnd(widths[i])).join('  ').trimEnd();
+
+  console.log(headers.map((h, i) => c.bold(c.dim(clip(h, widths[i]).padEnd(widths[i])))).join('  ').trimEnd());
+  console.log(widths.map((w) => '─'.repeat(w)).join('  '));
+  for (const row of rows) console.log(line(row));
+}
+
 function json(data) {
   console.log(JSON.stringify(data, null, 2));
 }
@@ -80,13 +146,18 @@ function info(msg) {
 function spinner(message) {
   if (!process.stderr.isTTY) {
     console.error(message);
-    return { stop: () => {}, succeed: (msg) => success(msg), fail: (msg) => error(msg) };
+    // update() stays silent when piped: a progress line reprinted every poll
+    // would bury the real output in a log.
+    return { stop: () => {}, update: () => {}, succeed: (msg) => success(msg), fail: (msg) => error(msg) };
   }
 
   const frames = ['\u280B', '\u2819', '\u2839', '\u2838', '\u283C', '\u2834', '\u2826', '\u2827', '\u2807', '\u280F'];
   let i = 0;
+  let text = message;
   const interval = setInterval(() => {
-    process.stderr.write(`\r${c.cyan(frames[i++ % frames.length])} ${message}`);
+    // Clear to end of line first: a shorter message must not leave the tail of
+    // a longer one behind.
+    process.stderr.write(`\r\x1b[K${c.cyan(frames[i++ % frames.length])} ${text}`);
   }, 80);
 
   function clear() {
@@ -99,6 +170,7 @@ function spinner(message) {
 
   return {
     stop: clear,
+    update(msg) { text = msg; },
     succeed(msg) { clear(); success(msg); },
     fail(msg) { clear(); error(msg); },
   };
@@ -349,4 +421,4 @@ function multiSelect(message, options) {
   });
 }
 
-module.exports = { table, json, keyValue, success, error, warn, info, spinner, select, multiSelect, colors: c };
+module.exports = { table, logTable, json, keyValue, success, error, warn, info, spinner, select, multiSelect, colors: c };

package/test/analytics-columns.test.js

@@ -0,0 +1,68 @@
+const test = require('node:test');
+const assert = require('node:assert');
+
+const { DATASETS, selectTableColumns } = require('../src/commands/analytics');
+const { resolveFormat } = require('../src/lib/analytics-query');
+
+const TERMINAL_COLUMNS = [
+  'Timestamp', 'User', 'Email', 'AI Tool', 'Command Family', 'All Command Families',
+  'Command', 'User Prompt', 'Risk Score', 'Risk Reason', 'Initiator', 'Matched Policies',
+];
+
+test('the table view drops the wide columns that would flood a terminal', () => {
+  const rows = [TERMINAL_COLUMNS.map((_, i) => `v${i}`)];
+  const view = selectTableColumns(DATASETS.terminal, TERMINAL_COLUMNS, rows);
+
+  assert.deepStrictEqual(view.columns, DATASETS.terminal.tableColumns);
+  assert.ok(!view.columns.includes('User Prompt'));
+  assert.ok(!view.columns.includes('Risk Reason'));
+  assert.strictEqual(view.hidden, TERMINAL_COLUMNS.length - view.columns.length);
+});
+
+test('selected cells stay aligned with their headers', () => {
+  const rows = [TERMINAL_COLUMNS.map((name) => `value:${name}`)];
+  const view = selectTableColumns(DATASETS.terminal, TERMINAL_COLUMNS, rows);
+
+  view.columns.forEach((name, i) => {
+    assert.strictEqual(view.rows[0][i], `value:${name}`);
+  });
+});
+
+test('table columns keep the server order, not the order they are listed in', () => {
+  const view = selectTableColumns(DATASETS.terminal, TERMINAL_COLUMNS, []);
+  const serverOrder = TERMINAL_COLUMNS.filter((c) => view.columns.includes(c));
+  assert.deepStrictEqual(view.columns, serverOrder);
+});
+
+test('an unrecognised column set falls back to showing everything', () => {
+  const columns = ['Something', 'Else'];
+  const view = selectTableColumns(DATASETS.terminal, columns, [['a', 'b']]);
+  assert.deepStrictEqual(view.columns, columns);
+  assert.deepStrictEqual(view.rows, [['a', 'b']]);
+});
+
+test('every dataset names only columns the export actually returns', () => {
+  const known = {
+    'terminal-runs': TERMINAL_COLUMNS,
+    'mcp-actions': ['Timestamp', 'User', 'Email', 'AI Tool', 'MCP Server', 'MCP Tool',
+      'Targets', 'User Prompt', 'Risk Score', 'Risk Reason', 'Initiator', 'Matched Policies'],
+    unsanctioned: ['Timestamp', 'User', 'Email', 'AI Tool', 'MCP Server', 'MCP Tool',
+      'Status', 'Sanction Message', 'User Prompt'],
+    'mcp-servers': ['MCP Server', 'Actions', 'Average Risk Score'],
+  };
+
+  for (const dataset of Object.values(DATASETS)) {
+    for (const column of dataset.tableColumns) {
+      assert.ok(
+        known[dataset.key].includes(column),
+        `${dataset.key} lists "${column}", which the export does not return`,
+      );
+    }
+  }
+});
+
+// Commander used to default --format to "table", which made --json look like a
+// contradiction and broke `--json` on every subcommand.
+test('--json works when --format was never passed', () => {
+  assert.strictEqual(resolveFormat({ json: true, format: undefined }), 'json');
+});

package/test/analytics-export-job.test.js

@@ -0,0 +1,141 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const api = require('../src/api');
+const { describeError, safeFilename } = require('../src/lib/downloads');
+
+// `--format csv` no longer streams from our backend: it starts a job, polls it,
+// then pulls the finished file from a presigned S3 URL. That last hop is the
+// part worth pinning down, because it leaves our own origin — a credential sent
+// there goes to a third party, and a short file there reads as a complete CSV.
+
+function startServer(handler) {
+  const server = http.createServer(handler);
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => resolve({ server, port: server.address().port }));
+  });
+}
+
+function freshTmp() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'export-test-'));
+  return { dir, file: path.join(dir, 'out.csv') };
+}
+
+test('fetchToStream sends NO Authorization header (the API key must not reach S3)', async () => {
+  let seen = 'header-never-observed';
+  const { server, port } = await startServer((req, res) => {
+    seen = req.headers.authorization;
+    res.writeHead(200, { 'Content-Type': 'text/csv' });
+    res.end('a,b\n1,2\n');
+  });
+  const { dir, file } = freshTmp();
+  try {
+    await api.fetchToStream(`http://127.0.0.1:${port}/signed`, {
+      transport: http,
+      onHeaders: () => fs.createWriteStream(file),
+    });
+    assert.equal(seen, undefined, 'a presigned URL must be fetched with no credentials attached');
+    assert.equal(fs.readFileSync(file, 'utf8'), 'a,b\n1,2\n');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+    server.close();
+  }
+});
+
+test('fetchToStream refuses a redirect instead of following it to another host', async () => {
+  // A presigned URL points straight at the signing endpoint, so a Location
+  // header is either a misconfigured region or a response steering the client
+  // at a host nobody vetted. Following it would turn an export into an
+  // outbound request to somewhere the operator never chose.
+  let hops = 0;
+  const { server, port } = await startServer((req, res) => {
+    hops += 1;
+    res.writeHead(302, { Location: 'http://169.254.169.254/latest/meta-data/' });
+    res.end();
+  });
+  try {
+    await assert.rejects(
+      () => api.fetchToStream(`http://127.0.0.1:${port}/signed`, {
+        transport: http,
+        onHeaders: () => process.stdout,
+      }),
+      /redirected to somewhere unexpected/,
+    );
+    assert.equal(hops, 1, 'the redirect target must never be requested');
+  } finally {
+    server.close();
+  }
+});
+
+test('fetchToStream maps an expired signature (403) to a message that says what to do', async () => {
+  const { server, port } = await startServer((req, res) => {
+    res.writeHead(403, { 'Content-Type': 'application/xml' });
+    res.end('<Error><Code>AccessDenied</Code></Error>');
+  });
+  try {
+    await assert.rejects(
+      () => api.fetchToStream(`http://127.0.0.1:${port}/expired`, {
+        transport: http,
+        onHeaders: () => process.stdout,
+      }),
+      // S3 answers in XML, which means nothing to a CLI user.
+      /link has expired. Run the export again/,
+    );
+  } finally {
+    server.close();
+  }
+});
+
+test('fetchToStream rejects a non-http(s) URL rather than handing it to a transport', async () => {
+  await assert.rejects(
+    () => api.fetchToStream('file:///etc/passwd', { onHeaders: () => process.stdout }),
+    /Refusing to download from a file: URL/,
+  );
+});
+
+test('safeFilename keeps the basename so the server cannot pick where the file lands', () => {
+  assert.equal(safeFilename('../../.zshrc', 'fallback.csv'), '.zshrc');
+  assert.equal(safeFilename('/etc/passwd', 'fallback.csv'), 'passwd');
+  assert.equal(safeFilename('acme_logs_2026-07-01_to_2026-07-31.csv', 'f.csv'),
+    'acme_logs_2026-07-01_to_2026-07-31.csv');
+  assert.equal(safeFilename('..', 'fallback.csv'), 'fallback.csv');
+  assert.equal(safeFilename('', 'fallback.csv'), 'fallback.csv');
+  assert.equal(safeFilename(null, 'fallback.csv'), 'fallback.csv');
+});
+
+test('an over-limit export (422) reports the real row count and how to narrow it', () => {
+  const err = new api.ApiError(422, {
+    error: 'Too many rows', row_count: 47651, limit: 25000, exceeds_limit: true,
+  });
+  const message = describeError(err, 'Terminal Runs export');
+  assert.match(message, /47,651 rows/);
+  assert.match(message, /25,000-row export limit/);
+  // Says what to do without naming a flag: `download` has --last, `analytics`
+  // has --time-window, and this one message is shown by both.
+  assert.match(message, /Narrow the date range or add filters/);
+});
+
+test('a backend still on the streaming export (405) says so instead of "not found"', () => {
+  const message = describeError(new api.ApiError(405, {}), 'Terminal Runs export');
+  assert.match(message, /too old for this CLI/);
+});
+
+test('describeError works with no dataset, for `download get`', () => {
+  const message = describeError(new api.ApiError(403, {}));
+  assert.match(message, /Admin role required/);
+});
+
+// A 404 means different things on the two paths, and saying the wrong one sends
+// the reader off to check their backend version when the job simply expired.
+test('a 404 by job ID says the export is gone, not that the backend is too old', () => {
+  const byId = describeError(new api.ApiError(404, {}), 'export', { byJobId: true });
+  assert.match(byId, /No export with that ID/);
+  assert.doesNotMatch(byId, /backend/);
+
+  const byKind = describeError(new api.ApiError(404, {}), 'logs-export export');
+  assert.match(byKind, /does not serve/);
+});