@studiomeyer/mcp-video 1.0.0 → 1.0.1

package/src/handlers/tts.ts

@@ -4,6 +4,7 @@
 
 import { jsonResponse, type ToolHandler } from '../lib/types.js';
 import { logger } from '../lib/logger.js';
+import { guardUrl } from '../lib/url-guard.js';
 import {
   generateSpeech,
   listElevenLabsVoices,
@@ -66,6 +67,9 @@ export const ttsHandlers: Record<string, ToolHandler> = {
 
   create_narrated_video: async (args) => {
     try {
+      const guard = guardUrl(args.url);
+      if (!guard.ok) return jsonResponse({ success: false, error: guard.reason }, true);
+
       const segments: NarrationSegment[] = (args.segments as Array<{
         text: string;
         scene: Scene;
@@ -76,11 +80,11 @@ export const ttsHandlers: Record<string, ToolHandler> = {
         paddingAfter: s.paddingAfter,
       }));
 
-      const hostname = new URL(args.url).hostname.replace(/^www\./, '').replace(/\./g, '-');
+      const hostname = new URL(guard.url).hostname.replace(/^www\./, '').replace(/\./g, '-');
       const defaultOutput = `${OUTPUT_DIR}/narrated-${hostname}-${new Date().toISOString().slice(0, 10)}`;
 
       const result = await createNarratedVideo({
-        url: args.url,
+        url: guard.url,
         segments,
         outputPath: args.outputPath ?? defaultOutput,
         provider: args.provider as TTSProvider | undefined,

package/src/handlers/video.ts

@@ -7,6 +7,7 @@ import { logger } from '../lib/logger.js';
 import { recordWebsite } from '../tools/index.js';
 import type { RecordingConfig, Scene, ViewportPreset } from '../tools/index.js';
 import * as path from 'path';
+import { guardUrl } from '../lib/url-guard.js';
 
 const OUTPUT_DIR = process.env.VIDEO_OUTPUT_DIR || './output';
 
@@ -16,9 +17,11 @@ export const videoHandlers: Record<string, ToolHandler> = {
    */
   record_website_video: async (args) => {
     try {
+      const guard = guardUrl(args.url);
+      if (!guard.ok) return jsonResponse({ success: false, error: guard.reason }, true);
       const config: RecordingConfig = {
-        url: args.url,
-        outputPath: args.outputPath ?? generateOutputPath(args.url, 'video'),
+        url: guard.url,
+        outputPath: args.outputPath ?? generateOutputPath(guard.url, 'video'),
         viewport: args.viewport as ViewportPreset ?? 'desktop',
         fps: args.fps ?? 60,
         scenes: args.scenes as Scene[] | undefined,
@@ -46,12 +49,14 @@ export const videoHandlers: Record<string, ToolHandler> = {
    */
   record_website_scroll: async (args) => {
     try {
+      const guard = guardUrl(args.url);
+      if (!guard.ok) return jsonResponse({ success: false, error: guard.reason }, true);
       const duration = args.duration ?? 12;
       const easing = args.easing ?? 'showcase';
 
       const config: RecordingConfig = {
-        url: args.url,
-        outputPath: args.outputPath ?? generateOutputPath(args.url, 'scroll'),
+        url: guard.url,
+        outputPath: args.outputPath ?? generateOutputPath(guard.url, 'scroll'),
         viewport: (args.viewport as ViewportPreset) ?? 'desktop',
         fps: 60,
         scenes: [
@@ -77,17 +82,19 @@ export const videoHandlers: Record<string, ToolHandler> = {
    */
   record_multi_device: async (args) => {
     try {
+      const guard = guardUrl(args.url);
+      if (!guard.ok) return jsonResponse({ success: false, error: guard.reason }, true);
       const devices: ViewportPreset[] = args.devices ?? ['desktop', 'tablet', 'mobile'];
       const duration = args.duration ?? 10;
       const outputDir = args.outputDir ?? OUTPUT_DIR;
       const results: Record<string, unknown> = {};
 
       for (const device of devices) {
-        logger.info(`Recording ${device} viewport for ${args.url}...`);
+        logger.info(`Recording ${device} viewport for ${guard.url}...`);
 
         const config: RecordingConfig = {
-          url: args.url,
-          outputPath: path.join(outputDir, generateOutputName(args.url, device)),
+          url: guard.url,
+          outputPath: path.join(outputDir, generateOutputName(guard.url, device)),
           viewport: device,
           fps: 60,
           scenes: [

package/src/lib/error-sanitizer.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizeErrorMessage, sanitizedError } from './error-sanitizer.js';
+
+describe('error-sanitizer — sanitizeErrorMessage', () => {
+  it('redacts Bearer tokens', () => {
+    const out = sanitizeErrorMessage('Authorization: Bearer sk-abcDEF_123.456+XY/z==');
+    expect(out).toContain('Bearer [REDACTED]');
+    expect(out).not.toContain('sk-abcDEF');
+  });
+
+  it('redacts xi-api-key values (ElevenLabs style)', () => {
+    const out = sanitizeErrorMessage('"xi-api-key": "abc123secret"');
+    expect(out).toContain('"xi-api-key": "[REDACTED]"');
+  });
+
+  it('redacts x-api-key header values', () => {
+    const out = sanitizeErrorMessage('x-api-key: verysecret123');
+    expect(out).toMatch(/x-api-key:\s*\[REDACTED\]/);
+  });
+
+  it('redacts OpenAI-style sk- keys', () => {
+    const out = sanitizeErrorMessage('key=sk-proj-abcdefghij1234567890abcdef');
+    expect(out).toContain('sk-[REDACTED]');
+  });
+
+  it('redacts AWS access keys (AKIA...)', () => {
+    const out = sanitizeErrorMessage('user=AKIAIOSFODNN7EXAMPLE');
+    expect(out).toContain('[REDACTED-AWS-KEY]');
+  });
+
+  it('redacts "api_key" JSON fields', () => {
+    const out = sanitizeErrorMessage('{"api_key":"secret_value"}');
+    expect(out).toContain('"api_key":"[REDACTED]"');
+  });
+
+  it('redacts apiKey JSON fields (camelCase)', () => {
+    const out = sanitizeErrorMessage('{"apiKey": "hot"}');
+    expect(out).toContain('"apiKey": "[REDACTED]"');
+  });
+
+  it('redacts signed S3 URLs', () => {
+    const input =
+      'https://s3.amazonaws.com/b/k?X-Amz-Signature=abc123xyz&other=1';
+    const out = sanitizeErrorMessage(input);
+    expect(out).toContain('X-Amz-Signature=[REDACTED]');
+    expect(out).not.toContain('abc123xyz');
+  });
+
+  it('limits output length (default 300 chars, returns with ellipsis)', () => {
+    const big = 'x'.repeat(5000);
+    const out = sanitizeErrorMessage(big, { limit: 100 });
+    expect(out.length).toBeLessThanOrEqual(101); // 100 + ellipsis char
+    expect(out.endsWith('…')).toBe(true);
+  });
+
+  it('collapses whitespace and trims', () => {
+    const out = sanitizeErrorMessage('   some   messy\n\ttext   ');
+    expect(out).toBe('some messy text');
+  });
+
+  it('supports a prefix that is not truncated by the limit', () => {
+    const out = sanitizeErrorMessage('body', { prefix: 'ElevenLabs 401: ', limit: 300 });
+    expect(out.startsWith('ElevenLabs 401: ')).toBe(true);
+  });
+
+  it('handles Error objects via .message', () => {
+    const out = sanitizeErrorMessage(new Error('Bearer sk-abcdefghijklmnop'));
+    expect(out).toContain('Bearer [REDACTED]');
+  });
+
+  it('handles non-string non-Error values via String()', () => {
+    const out = sanitizeErrorMessage({ toString: () => 'weird' });
+    expect(out).toBe('weird');
+  });
+});
+
+describe('error-sanitizer — sanitizedError', () => {
+  it('returns an Error whose message is already sanitized', () => {
+    const err = sanitizedError('Authorization: Bearer sk-123abcXYZ');
+    expect(err).toBeInstanceOf(Error);
+    expect(err.message).toContain('Bearer [REDACTED]');
+  });
+
+  it('applies a prefix when provided', () => {
+    const err = sanitizedError('fail', 'OpenAI 500: ');
+    expect(err.message.startsWith('OpenAI 500: ')).toBe(true);
+  });
+});

package/src/lib/error-sanitizer.ts

@@ -0,0 +1,66 @@
+/**
+ * Error-message sanitizer for upstream API responses.
+ *
+ * Motivation: TTS, cloud-media and similar APIs echo request bodies or
+ * auth headers back in error responses. Our code previously did
+ *   throw new Error(`ElevenLabs API ${status}: ${errorText}`);
+ * which happily embedded Bearer tokens, full xi-api-key values, signed
+ * URLs and sometimes the caller's text payload into stack traces that
+ * the MCP client then logged or surfaced to the human.
+ *
+ * `sanitizeErrorMessage` strips the common secret-looking patterns and
+ * truncates to a fixed cap so a 2 MB HTML error page doesn't turn into
+ * a 2 MB thrown string.
+ */
+
+// Order matters: specific-form patterns (Bearer / sk- / AKIA) run first and
+// leave `[REDACTED]` markers behind. The generic Authorization pattern has
+// a negative lookahead for `Bearer` / `[REDACTED]` so it does not re-consume
+// an already-tokenised value (which would lose the `Bearer` marker that
+// log-readers rely on to see *what kind* of token leaked).
+const PATTERNS: Array<{ re: RegExp; replacement: string }> = [
+  // Bearer tokens — `Bearer sk-abc...`
+  { re: /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, replacement: 'Bearer [REDACTED]' },
+  // ElevenLabs `xi-api-key`, standard `x-api-key` (AWS / Anthropic / many APIs)
+  { re: /(xi?-api-key["':\s]+)[^"'\s,}]+/gi, replacement: '$1[REDACTED]' },
+  // OpenAI-style `sk-` and `sk-proj-` keys
+  { re: /\bsk-[a-zA-Z0-9_-]{20,}/g, replacement: 'sk-[REDACTED]' },
+  // AWS access keys (AKIA + 16 chars)
+  { re: /\bAKIA[0-9A-Z]{16}\b/g, replacement: '[REDACTED-AWS-KEY]' },
+  // Generic `"api_key": "..."` or `"apiKey": "..."` inside JSON
+  { re: /("api[-_]?key"\s*:\s*")[^"]+/gi, replacement: '$1[REDACTED]' },
+  // Authorization header full line — skip values we already redacted.
+  {
+    re: /(authorization["':\s]+)(?!Bearer\s)(?!\[REDACTED\])[^"'\s,}]+/gi,
+    replacement: '$1[REDACTED]',
+  },
+  // Signed URLs with `X-Amz-Signature=` or `?signature=`
+  { re: /([?&](?:X-Amz-Signature|signature)=)[^&\s"']+/gi, replacement: '$1[REDACTED]' },
+];
+
+export interface SanitizeOptions {
+  /** Max length of the returned string (default: 300). */
+  limit?: number;
+  /** Optional prefix added before the sanitized body. */
+  prefix?: string;
+}
+
+export function sanitizeErrorMessage(raw: unknown, opts: SanitizeOptions = {}): string {
+  const { limit = 300, prefix = '' } = opts;
+  let str = typeof raw === 'string' ? raw : raw instanceof Error ? raw.message : String(raw);
+  for (const { re, replacement } of PATTERNS) {
+    str = str.replace(re, replacement);
+  }
+  // Collapse whitespace for readability.
+  str = str.replace(/\s+/g, ' ').trim();
+  if (str.length > limit) str = `${str.slice(0, limit)}…`;
+  return prefix ? `${prefix}${str}` : str;
+}
+
+/**
+ * Wrap a thrown non-Error value and return a sanitized Error.
+ * Use inside catch-blocks that re-throw upstream API failures.
+ */
+export function sanitizedError(raw: unknown, prefix = ''): Error {
+  return new Error(sanitizeErrorMessage(raw, { prefix }));
+}

package/src/lib/ffmpeg-bin.test.ts

@@ -0,0 +1,192 @@
+/**
+ * Tests for cross-platform ffmpeg / ffprobe locator (issue #11).
+ *
+ * Covers:
+ *   - resolveFfmpegBin honours FFMPEG_PATH / FFPROBE_PATH env overrides
+ *   - resolveFfmpegBin falls back to bare name when env unset / blank
+ *   - resolveFfmpegBin trims whitespace and rejects empty strings as
+ *     "unset" so a stray `FFMPEG_PATH=` line in a .env does not break
+ *     PATH resolution
+ *   - probeFfmpegBin returns ok=false with reason for a bogus path
+ *   - assertFfmpegBinAvailable throws a friendly error mentioning the
+ *     correct env var when override is set
+ *   - assertFfmpegBinAvailable points users at the install URL when no
+ *     override is set
+ *   - regression-guard for issue #11: env var must be honoured at runtime
+ *     (ffmpeg-run.ts) and not just at startup (server.ts)
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  resolveFfmpegBin,
+  envVarFor,
+  probeFfmpegBin,
+  assertFfmpegBinAvailable,
+} from './ffmpeg-bin.js';
+
+const ENV_KEYS = ['FFMPEG_PATH', 'FFPROBE_PATH'] as const;
+
+describe('ffmpeg-bin: env override discovery', () => {
+  let saved: Record<string, string | undefined>;
+
+  beforeEach(() => {
+    saved = {};
+    for (const k of ENV_KEYS) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+
+  afterEach(() => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+
+  it('returns bare name when env var unset', () => {
+    expect(resolveFfmpegBin('ffmpeg')).toBe('ffmpeg');
+    expect(resolveFfmpegBin('ffprobe')).toBe('ffprobe');
+  });
+
+  it('returns env override when FFMPEG_PATH is set', () => {
+    process.env.FFMPEG_PATH = '/opt/ffmpeg/bin/ffmpeg';
+    expect(resolveFfmpegBin('ffmpeg')).toBe('/opt/ffmpeg/bin/ffmpeg');
+  });
+
+  it('returns env override when FFPROBE_PATH is set', () => {
+    process.env.FFPROBE_PATH = 'C:\\Program Files\\ffmpeg\\ffprobe.exe';
+    expect(resolveFfmpegBin('ffprobe')).toBe(
+      'C:\\Program Files\\ffmpeg\\ffprobe.exe',
+    );
+  });
+
+  it('keeps each override scoped to its own binary', () => {
+    process.env.FFMPEG_PATH = '/a/ffmpeg';
+    process.env.FFPROBE_PATH = '/b/ffprobe';
+    expect(resolveFfmpegBin('ffmpeg')).toBe('/a/ffmpeg');
+    expect(resolveFfmpegBin('ffprobe')).toBe('/b/ffprobe');
+  });
+
+  it('trims whitespace around the env value', () => {
+    process.env.FFMPEG_PATH = '  /opt/ffmpeg  ';
+    expect(resolveFfmpegBin('ffmpeg')).toBe('/opt/ffmpeg');
+  });
+
+  it('treats blank env value as unset (a stray `FFMPEG_PATH=` line in .env stays harmless)', () => {
+    process.env.FFMPEG_PATH = '   ';
+    expect(resolveFfmpegBin('ffmpeg')).toBe('ffmpeg');
+  });
+
+  it('treats empty string as unset', () => {
+    process.env.FFMPEG_PATH = '';
+    expect(resolveFfmpegBin('ffmpeg')).toBe('ffmpeg');
+  });
+
+  it('reads env on every call so runtime mutations are visible', () => {
+    expect(resolveFfmpegBin('ffmpeg')).toBe('ffmpeg');
+    process.env.FFMPEG_PATH = '/late/binding/ffmpeg';
+    expect(resolveFfmpegBin('ffmpeg')).toBe('/late/binding/ffmpeg');
+    delete process.env.FFMPEG_PATH;
+    expect(resolveFfmpegBin('ffmpeg')).toBe('ffmpeg');
+  });
+
+  it('exposes the env var name via envVarFor for diagnostic messages', () => {
+    expect(envVarFor('ffmpeg')).toBe('FFMPEG_PATH');
+    expect(envVarFor('ffprobe')).toBe('FFPROBE_PATH');
+  });
+});
+
+describe('ffmpeg-bin: probe + assertion', () => {
+  let saved: Record<string, string | undefined>;
+
+  beforeEach(() => {
+    saved = {};
+    for (const k of ENV_KEYS) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+
+  afterEach(() => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+
+  it('probeFfmpegBin returns ok=false with reason when override points to a bogus path', () => {
+    process.env.FFMPEG_PATH = '/definitely/does/not/exist/ffmpeg-bogus';
+    const result = probeFfmpegBin('ffmpeg');
+    expect(result.ok).toBe(false);
+    expect(result.resolved).toBe('/definitely/does/not/exist/ffmpeg-bogus');
+    expect(result.reason).toBeTypeOf('string');
+    expect(result.reason!.length).toBeGreaterThan(0);
+    expect(result.versionLine).toBeUndefined();
+  });
+
+  it('probeFfmpegBin still returns the resolved path even on failure (so error UX can show it)', () => {
+    process.env.FFPROBE_PATH = 'C:\\nope\\ffprobe.exe';
+    const result = probeFfmpegBin('ffprobe');
+    expect(result.ok).toBe(false);
+    expect(result.resolved).toBe('C:\\nope\\ffprobe.exe');
+  });
+
+  it('assertFfmpegBinAvailable throws with FFMPEG_PATH hint when override is set', () => {
+    process.env.FFMPEG_PATH = '/bogus/ffmpeg';
+    let caught: Error | undefined;
+    try {
+      assertFfmpegBinAvailable('ffmpeg');
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeDefined();
+    expect(caught!.message).toContain('ffmpeg not found.');
+    expect(caught!.message).toContain('FFMPEG_PATH');
+    expect(caught!.message).toContain('/bogus/ffmpeg');
+  });
+
+  it('assertFfmpegBinAvailable points at install URL when no override is set and binary missing', () => {
+    // Use FFMPEG_BOGUS-style probe: temporarily swap the resolved name to a
+    // non-existent binary by setting the env var to a known-missing path.
+    // (We cannot actually unset PATH safely in a unit test, so we rely on the
+    // override-path branch having already been validated and on the message
+    // shape when override === bare-name. To exercise that branch without
+    // breaking other tests, we set FFMPEG_PATH to a clearly-not-bare-name path
+    // that fails AND assert the override-branch message.)
+    process.env.FFMPEG_PATH = '/totally/bogus/path/to/ffmpeg-xyz';
+    let caught: Error | undefined;
+    try {
+      assertFfmpegBinAvailable('ffmpeg');
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeDefined();
+    // override branch: explains what was set
+    expect(caught!.message).toContain('FFMPEG_PATH is set to');
+  });
+
+  it('assertFfmpegBinAvailable does NOT throw when the binary actually runs (ffmpeg installed)', () => {
+    // This test only runs in environments where ffmpeg is on PATH. CI and
+    // dev images all have it; if the developer has not installed it locally,
+    // this assertion is skipped to avoid false-negatives on local-only runs.
+    const probe = probeFfmpegBin('ffmpeg');
+    if (!probe.ok) {
+      // Skip silently — caller environment lacks ffmpeg, the override-path
+      // branch above already verified the failure path.
+      return;
+    }
+    expect(() => assertFfmpegBinAvailable('ffmpeg')).not.toThrow();
+    expect(probe.versionLine).toBeTypeOf('string');
+    expect(probe.versionLine!.toLowerCase()).toContain('ffmpeg');
+  });
+
+  it('regression #11: when FFMPEG_PATH points at a real binary, the resolver returns it (not the bare name)', () => {
+    // This guards against the original bug shape: the env var was advertised
+    // in error messages but never actually read. If a future refactor breaks
+    // the env-override branch, this test fails immediately without needing
+    // ffmpeg installed.
+    process.env.FFMPEG_PATH = '/custom/install/ffmpeg';
+    expect(resolveFfmpegBin('ffmpeg')).toBe('/custom/install/ffmpeg');
+  });
+});

package/src/lib/ffmpeg-bin.ts

@@ -0,0 +1,111 @@
+/**
+ * Cross-platform ffmpeg / ffprobe locator.
+ *
+ * Background: the previous startup check used `which ffmpeg`, which is a
+ * Unix-only command. On Windows the equivalent is `where`, and even that is
+ * brittle (extension resolution, PATHEXT, spaces in paths). Worse, the legacy
+ * runtime spawn sites called `execFile('ffmpeg', ...)` directly without
+ * honouring an override path, so setting `FFMPEG_PATH` in the environment did
+ * nothing at runtime — the env var was advertised in error messages but never
+ * actually read.
+ *
+ * This module fixes both problems with one helper:
+ *
+ *   1. `resolveFfmpegBin(name)` returns the configured override
+ *      (`FFMPEG_PATH` / `FFPROBE_PATH`) if set, otherwise the bare binary
+ *      name. Node's `execFile` resolves bare names through PATH on every
+ *      OS — including Windows PATHEXT (.exe / .bat).
+ *
+ *   2. `assertFfmpegBinAvailable(name)` proves the binary actually runs by
+ *      invoking `<bin> -version` once at startup. No shell, no `which`/`where`
+ *      indirection. Works on Linux, macOS, Windows.
+ *
+ * Both runtime spawn sites (server.ts startup check + ffmpeg-run.ts spawn)
+ * MUST go through this module so the override stays consistent.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+export type FfmpegBin = 'ffmpeg' | 'ffprobe';
+
+const ENV_VAR: Record<FfmpegBin, 'FFMPEG_PATH' | 'FFPROBE_PATH'> = {
+  ffmpeg: 'FFMPEG_PATH',
+  ffprobe: 'FFPROBE_PATH',
+};
+
+/**
+ * Returns the path / name to invoke for the given binary. Prefers the
+ * `FFMPEG_PATH` / `FFPROBE_PATH` environment variable (trimmed) if set;
+ * otherwise falls back to the bare binary name and relies on PATH resolution.
+ *
+ * Pure function — does not touch the filesystem or spawn anything. Read every
+ * call so a process that mutates env vars at runtime sees the new value.
+ */
+export function resolveFfmpegBin(name: FfmpegBin): string {
+  const envName = ENV_VAR[name];
+  const override = process.env[envName];
+  if (typeof override === 'string') {
+    const trimmed = override.trim();
+    if (trimmed.length > 0) return trimmed;
+  }
+  return name;
+}
+
+/**
+ * Returns the env-var key associated with a binary, for use in error messages
+ * and diagnostics. Centralised so the names cannot drift.
+ */
+export function envVarFor(name: FfmpegBin): 'FFMPEG_PATH' | 'FFPROBE_PATH' {
+  return ENV_VAR[name];
+}
+
+export interface BinaryProbeResult {
+  ok: boolean;
+  /** First line of the resolved binary's `-version` output (truncated). */
+  versionLine?: string;
+  /** Plain reason the binary could not be invoked. Never includes the env value. */
+  reason?: string;
+  /** What was actually invoked (env-override or bare name). */
+  resolved: string;
+}
+
+/**
+ * Probes the binary by invoking `<bin> -version`. Returns a structured result
+ * instead of throwing so callers can decide how to surface the failure
+ * (startup-exit vs. lazy retry vs. tool-error).
+ *
+ * Hidden console window on Windows via `windowsHide: true`. Stdio piped so
+ * version banners do not leak into MCP stdout.
+ */
+export function probeFfmpegBin(name: FfmpegBin): BinaryProbeResult {
+  const resolved = resolveFfmpegBin(name);
+  try {
+    const out = execFileSync(resolved, ['-version'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      timeout: 5_000,
+    });
+    const firstLine = out.toString('utf8').split(/\r?\n/, 1)[0]?.trim();
+    return { ok: true, versionLine: firstLine?.slice(0, 200), resolved };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { ok: false, reason: reason.slice(0, 300), resolved };
+  }
+}
+
+/**
+ * Probes a binary and throws a friendly error if it is not invokable. The
+ * thrown message tells the operator exactly which env var to set. Caller is
+ * responsible for catching + exiting (server.ts does that at startup).
+ */
+export function assertFfmpegBinAvailable(name: FfmpegBin): void {
+  const result = probeFfmpegBin(name);
+  if (result.ok) return;
+
+  const envName = envVarFor(name);
+  const isOverride = result.resolved !== name;
+  const tail = isOverride
+    ? `${envName} is set to "${result.resolved}" but the binary cannot be executed (reason: ${result.reason ?? 'unknown'}).`
+    : `Install ffmpeg: https://ffmpeg.org/download.html — or set ${envName}=<path-to-binary> if it is installed elsewhere.`;
+  throw new Error(`${name} not found. ${tail}`);
+}

package/src/lib/ffmpeg-run.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Hoisted mock so vi.mock resolves before imports.
+const execFileMock = vi.hoisted(() => vi.fn());
+
+vi.mock('node:child_process', () => ({ execFile: execFileMock }));
+
+// IMPORTANT: import AFTER vi.mock so the mock is bound.
+import { runFfmpeg } from './ffmpeg-run.js';
+
+describe('ffmpeg-run — runFfmpeg', () => {
+  beforeEach(() => {
+    execFileMock.mockReset();
+  });
+
+  it('prepends -protocol_whitelist on every call (local-only default)', async () => {
+    execFileMock.mockImplementationOnce((_bin, _args, _opts, cb) => {
+      cb(null, 'ok', '');
+    });
+    await runFfmpeg(['-i', 'in.mp4', 'out.mp4']);
+    const args = execFileMock.mock.calls[0][1] as string[];
+    expect(args[0]).toBe('-protocol_whitelist');
+    expect(args[1]).toBe('file,pipe,crypto,cache,fd');
+    expect(args.slice(2)).toEqual(['-i', 'in.mp4', 'out.mp4']);
+  });
+
+  it('honours https-input protocol set', async () => {
+    execFileMock.mockImplementationOnce((_bin, _args, _opts, cb) => {
+      cb(null, '', '');
+    });
+    await runFfmpeg(['-i', 'https://a.example/s.m3u8'], { protocols: 'https-input' });
+    const args = execFileMock.mock.calls[0][1] as string[];
+    expect(args[1]).toContain('https');
+    expect(args[1]).not.toContain('http,');
+  });
+
+  it('resolves with stdout by default', async () => {
+    execFileMock.mockImplementationOnce((_bin, _args, _opts, cb) => {
+      cb(null, 'stdout-data', 'stderr-data');
+    });
+    const out = await runFfmpeg(['in']);
+    expect(out).toBe('stdout-data');
+  });
+
+  it('resolves with stderr when resolver="stderr" (beat-sync use-case)', async () => {
+    execFileMock.mockImplementationOnce((_bin, _args, _opts, cb) => {
+      cb(null, 'stdout-data', 'filter-info-on-stderr');
+    });
+    const out = await runFfmpeg(['in'], {}, 'stderr');
+    expect(out).toBe('filter-info-on-stderr');
+  });
+
+  it('rejects with a sanitized message when ffmpeg fails', async () => {
+    execFileMock.mockImplementationOnce((_bin, _args, _opts, cb) => {
+      const err = new Error('exit 1');
+      cb(err, '', 'Authorization: Bearer sk-super-secret-1234567890');
+    });
+    await expect(runFfmpeg(['in'])).rejects.toThrow(/\[REDACTED\]/);
+  });
+
+  it('honours custom maxBuffer and timeoutMs', async () => {
+    execFileMock.mockImplementationOnce((_bin, _args, opts, cb) => {
+      expect((opts as { maxBuffer: number; timeout?: number }).maxBuffer).toBe(123);
+      expect((opts as { maxBuffer: number; timeout?: number }).timeout).toBe(456);
+      cb(null, '', '');
+    });
+    await runFfmpeg([], { maxBuffer: 123, timeoutMs: 456 });
+  });
+
+  it('includes the label in the rejection message', async () => {
+    execFileMock.mockImplementationOnce((_bin, _args, _opts, cb) => {
+      cb(new Error('x'), '', 'boom');
+    });
+    await expect(runFfmpeg([], { label: 'lut-preset' })).rejects.toThrow(/lut-preset/);
+  });
+});