@studiomeyer/mcp-video 1.0.0 → 1.0.1

package/src/lib/ffmpeg-run.ts

@@ -0,0 +1,110 @@
+/**
+ * Central ffmpeg runner — every engine should use this instead of calling
+ * `execFile('ffmpeg', args, ...)` directly. Two reasons:
+ *
+ *   1. We inject `-protocol_whitelist` on every call (see ffmpeg-safety.ts).
+ *      Without it, an HLS playlist — or a user-provided "inputPath" that is
+ *      secretly an `https://` URL — lets ffmpeg fetch any protocol it was
+ *      built against, including `file://`, which means SSRF to the local
+ *      filesystem or to AWS/GCP metadata endpoints.
+ *
+ *   2. We sanitize stderr before it lands in logs or thrown messages.
+ *      ffmpeg will happily echo signed URLs, Authorization headers and
+ *      API keys from failed HTTP fetches.
+ *
+ * Callers pass their own `maxBuffer`/`timeout`/`protocols` as needed.
+ */
+
+import { execFile } from 'node:child_process';
+import { logger } from './logger.js';
+import { buildFfmpegArgs, type FfmpegProtocolSet } from './ffmpeg-safety.js';
+import { sanitizeErrorMessage } from './error-sanitizer.js';
+import { resolveFfmpegBin } from './ffmpeg-bin.js';
+
+export interface FfmpegRunOptions {
+  /** Bytes of stdout+stderr buffered before killing the process. Default: 50 MB. */
+  maxBuffer?: number;
+  /** Kill-after timeout in ms. Default: no timeout (ffmpeg exits on its own). */
+  timeoutMs?: number;
+  /** Which ffmpeg protocols to permit. Default: 'local-only' (file + pipe). */
+  protocols?: FfmpegProtocolSet;
+  /** Optional label used in the rejection reason, e.g. "lut-preset" */
+  label?: string;
+}
+
+/**
+ * Some callers (beat-sync, filter pipelines) need stderr because ffmpeg
+ * prints filter-graph info and stream metadata there. Pass `'stderr'` as
+ * the third arg to resolve with stderr instead of stdout. Defaults to stdout.
+ */
+export function runFfmpeg(
+  args: string[],
+  opts: FfmpegRunOptions = {},
+  resolver: 'stdout' | 'stderr' = 'stdout'
+): Promise<string> {
+  const {
+    maxBuffer = 50 * 1024 * 1024,
+    timeoutMs,
+    protocols = 'local-only',
+    label = 'ffmpeg',
+  } = opts;
+  const safeArgs = buildFfmpegArgs(args, protocols);
+
+  return new Promise((resolve, reject) => {
+    execFile(
+      resolveFfmpegBin('ffmpeg'),
+      safeArgs,
+      { maxBuffer, timeout: timeoutMs, windowsHide: true },
+      (error, stdout, stderr) => {
+        if (error) {
+          const safeMsg = sanitizeErrorMessage(stderr || error.message);
+          logger.error(`${label} failed: ${safeMsg}`);
+          reject(new Error(`${label} failed: ${safeMsg}`));
+          return;
+        }
+        resolve(resolver === 'stderr' ? stderr : stdout);
+      }
+    );
+  });
+}
+
+/**
+ * ffprobe runner — same protocol-whitelist + stderr-sanitize discipline as
+ * runFfmpeg. ffprobe silently follows HLS/DASH playlists the same way ffmpeg
+ * does, so every `execFile('ffprobe', args, ...)` must go through here or
+ * the SSRF hardening has a bypass via "just probe the file first".
+ *
+ * Default resolver is stdout because ffprobe's `-show_entries …` + `-of …`
+ * output is what callers need. stderr is error-only.
+ */
+export function runFfprobe(
+  args: string[],
+  opts: FfmpegRunOptions = {},
+  resolver: 'stdout' | 'stderr' = 'stdout'
+): Promise<string> {
+  const {
+    maxBuffer = 10 * 1024 * 1024,
+    timeoutMs,
+    protocols = 'local-only',
+    label = 'ffprobe',
+  } = opts;
+  // ffprobe honours the same -protocol_whitelist flag as ffmpeg.
+  const safeArgs = buildFfmpegArgs(args, protocols);
+
+  return new Promise((resolve, reject) => {
+    execFile(
+      resolveFfmpegBin('ffprobe'),
+      safeArgs,
+      { maxBuffer, timeout: timeoutMs, windowsHide: true },
+      (error, stdout, stderr) => {
+        if (error) {
+          const safeMsg = sanitizeErrorMessage(stderr || error.message);
+          logger.error(`${label} failed: ${safeMsg}`);
+          reject(new Error(`${label} failed: ${safeMsg}`));
+          return;
+        }
+        resolve(resolver === 'stderr' ? stderr : stdout);
+      }
+    );
+  });
+}

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

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import {
+  buildFfmpegArgs,
+  validateFfmpegPath,
+  validateFfmpegPaths,
+} from './ffmpeg-safety.js';
+
+describe('ffmpeg-safety — buildFfmpegArgs', () => {
+  it('prepends -protocol_whitelist local-only by default', () => {
+    const out = buildFfmpegArgs(['-i', 'a.mp4', 'b.mp4']);
+    expect(out[0]).toBe('-protocol_whitelist');
+    expect(out[1]).toBe('file,pipe,crypto,cache,fd');
+    expect(out.slice(2)).toEqual(['-i', 'a.mp4', 'b.mp4']);
+  });
+
+  it('supports https-input protocol set', () => {
+    const out = buildFfmpegArgs(['-i', 'https://example.com/s.m3u8'], 'https-input');
+    expect(out[1]).toBe('file,pipe,crypto,cache,fd,https,tls,tcp');
+  });
+
+  it('supports https-and-hls protocol set', () => {
+    const out = buildFfmpegArgs(['-i', 'a.m3u8'], 'https-and-hls');
+    expect(out[1]).toContain('hls');
+    expect(out[1]).toContain('applehttp');
+  });
+
+  it('never includes http:// (plain-text) in any protocol set', () => {
+    // Explicit check: mixing http would re-open SSRF to 169.254.x.x
+    for (const set of ['local-only', 'https-input', 'https-and-hls'] as const) {
+      const out = buildFfmpegArgs([], set);
+      const protocols = out[1].split(',');
+      expect(protocols).not.toContain('http');
+      expect(protocols).not.toContain('rtmp');
+      expect(protocols).not.toContain('rtsp');
+      expect(protocols).not.toContain('ftp');
+      expect(protocols).not.toContain('sftp');
+    }
+  });
+
+  it('throws if args is not an array', () => {
+    // @ts-expect-error intentional
+    expect(() => buildFfmpegArgs('not-an-array')).toThrow(/array/);
+  });
+});
+
+describe('ffmpeg-safety — validateFfmpegPath', () => {
+  it('accepts normal file paths', () => {
+    expect(validateFfmpegPath('/home/user/x.mp4')).toBe('/home/user/x.mp4');
+    expect(validateFfmpegPath('relative/file.mov')).toBe('relative/file.mov');
+  });
+
+  it('rejects empty strings', () => {
+    expect(() => validateFfmpegPath('')).toThrow(/non-empty/);
+  });
+
+  it('rejects non-string values', () => {
+    expect(() => validateFfmpegPath(null)).toThrow();
+    expect(() => validateFfmpegPath(undefined)).toThrow();
+    expect(() => validateFfmpegPath(42)).toThrow();
+  });
+
+  it('rejects paths starting with "-" (flag injection)', () => {
+    expect(() => validateFfmpegPath('-i')).toThrow(/flag/);
+    expect(() => validateFfmpegPath('-protocol_whitelist')).toThrow(/flag/);
+    expect(() => validateFfmpegPath('-help')).toThrow(/flag/);
+  });
+
+  it('rejects paths containing NUL bytes', () => {
+    expect(() => validateFfmpegPath('safe\0-i /etc/passwd')).toThrow(/null byte/);
+  });
+
+  it('includes the label in error messages', () => {
+    expect(() => validateFfmpegPath('-bad', 'input')).toThrow(/input/);
+  });
+});
+
+describe('ffmpeg-safety — validateFfmpegPaths', () => {
+  it('validates only the indices passed', () => {
+    const args = ['-y', '-i', 'valid.mp4', '-c:v', 'libx264', '-foo'];
+    // Only index 2 is a user-controlled path; -foo at index 5 is a built-in flag
+    validateFfmpegPaths(args, [2]);
+    expect(() => validateFfmpegPaths(args, [5])).toThrow(/flag/);
+  });
+
+  it('throws when any validated arg is empty', () => {
+    expect(() => validateFfmpegPaths(['', 'x'], [0])).toThrow(/non-empty/);
+  });
+});

package/src/lib/ffmpeg-safety.ts

@@ -0,0 +1,79 @@
+/**
+ * ffmpeg hardening — protocol whitelist + argument validation.
+ *
+ * Two distinct threats:
+ *   1. ffmpeg can follow URLs inside HLS/DASH playlists and fetch any
+ *      protocol ffmpeg was built with (file://, http, rtsp, tcp, udp...).
+ *      A playlist from an attacker-controlled HTTPS host can reference
+ *      `http://169.254.169.254/latest/meta-data/` and exfiltrate cloud
+ *      credentials. We counter by passing -protocol_whitelist on every
+ *      invocation, restricting ffmpeg to the smallest set of protocols
+ *      the caller actually needs.
+ *   2. Any user-controlled path string that starts with `-` is treated
+ *      by ffmpeg as a flag, not a filename. A caller passing
+ *      `-i /etc/passwd -frames:v 1 -f image2` as "filename" can hijack
+ *      the command. We forbid leading `-` on any input/output path.
+ */
+
+export type FfmpegProtocolSet = 'local-only' | 'https-input' | 'https-and-hls';
+
+const PROTOCOL_SETS: Record<FfmpegProtocolSet, string> = {
+  // Pure file-to-file work: editing, color, concat, audio mix, chroma.
+  'local-only': 'file,pipe,crypto,cache,fd',
+  // ffmpeg can fetch the top-level https input but cannot follow HLS segment
+  // lists or reference any other protocol. Use when ONE https URL is the input.
+  'https-input': 'file,pipe,crypto,cache,fd,https,tls,tcp',
+  // HLS master+segment playback. Still refuses http (only https), file schemes
+  // and 169.254.x.x metadata (those need to be caught upstream by url-guard).
+  'https-and-hls': 'file,pipe,crypto,cache,fd,https,tls,tcp,hls,applehttp',
+};
+
+/**
+ * Prepend `-protocol_whitelist <set>` to ffmpeg args.
+ *
+ * Callers should use 'local-only' unless they genuinely need network.
+ * Position matters: ffmpeg only honours -protocol_whitelist when it appears
+ * before any `-i` input that would use it, so we always prepend.
+ */
+export function buildFfmpegArgs(
+  userArgs: string[],
+  protocols: FfmpegProtocolSet = 'local-only'
+): string[] {
+  if (!Array.isArray(userArgs)) {
+    throw new TypeError('ffmpeg args must be an array of strings');
+  }
+  return ['-protocol_whitelist', PROTOCOL_SETS[protocols], ...userArgs];
+}
+
+/**
+ * Validate a user-supplied path that will be passed to ffmpeg as -i or output.
+ * Returns the sanitized path or throws. Rejects leading `-` (flag injection),
+ * empty strings, and values containing NUL bytes.
+ */
+export function validateFfmpegPath(p: unknown, label = 'path'): string {
+  if (typeof p !== 'string' || p.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string`);
+  }
+  if (p.startsWith('-')) {
+    throw new Error(`${label} must not start with "-" (looks like a flag)`);
+  }
+  if (p.includes('\0')) {
+    throw new Error(`${label} must not contain null bytes`);
+  }
+  return p;
+}
+
+/**
+ * Validate every entry in an args array used as ffmpeg filename-like tokens.
+ * Pass the list of indices that are user-controlled paths; other args
+ * (built by the caller with known flags) are not touched.
+ */
+export function validateFfmpegPaths(
+  args: string[],
+  userControlledIndices: number[],
+  label = 'path'
+): void {
+  for (const i of userControlledIndices) {
+    validateFfmpegPath(args[i], `${label}[${i}]`);
+  }
+}

package/src/lib/temp-dir.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { withTempDir, makeTempDir } from './temp-dir.js';
+
+describe('temp-dir — withTempDir', () => {
+  it('creates a unique directory per call', async () => {
+    const dirs = await Promise.all([
+      withTempDir('parallel-', async (d) => d),
+      withTempDir('parallel-', async (d) => d),
+      withTempDir('parallel-', async (d) => d),
+    ]);
+    expect(new Set(dirs).size).toBe(3);
+    for (const d of dirs) {
+      expect(fsSync.existsSync(d)).toBe(false); // already cleaned
+    }
+  });
+
+  it('cleans up after the callback resolves', async () => {
+    let captured = '';
+    await withTempDir('cleanup-ok-', async (dir) => {
+      captured = dir;
+      expect(fsSync.existsSync(dir)).toBe(true);
+      await fs.writeFile(join(dir, 'x.txt'), 'hi');
+    });
+    expect(fsSync.existsSync(captured)).toBe(false);
+  });
+
+  it('cleans up even when the callback throws', async () => {
+    let captured = '';
+    await expect(
+      withTempDir('cleanup-fail-', async (dir) => {
+        captured = dir;
+        await fs.writeFile(join(dir, 'y.txt'), 'bye');
+        throw new Error('simulated');
+      })
+    ).rejects.toThrow('simulated');
+    expect(fsSync.existsSync(captured)).toBe(false);
+  });
+
+  it('creates a subdirectory under os.tmpdir()', async () => {
+    await withTempDir('under-tmpdir-', async (dir) => {
+      expect(dir.startsWith(tmpdir())).toBe(true);
+    });
+  });
+
+  it('sanitizes unsafe characters in the prefix (no traversal literal)', async () => {
+    await withTempDir('../../etc/passwd', async (dir) => {
+      // mkdtemp + join(tmpdir(), ...) already prevent real traversal; we
+      // additionally scrub `..` out of the literal segment for tidy
+      // audit logs.
+      expect(dir.startsWith(tmpdir())).toBe(true);
+      expect(dir.includes('..')).toBe(false);
+      expect(dir).toMatch(/etc-passwd-/);
+    });
+  });
+
+  it('returns the value from the callback', async () => {
+    const result = await withTempDir('value-', async () => 'ok');
+    expect(result).toBe('ok');
+  });
+});
+
+describe('temp-dir — makeTempDir', () => {
+  it('returns a path that exists and can be manually cleaned', async () => {
+    const dir = await makeTempDir('manual-');
+    try {
+      expect(fsSync.existsSync(dir)).toBe(true);
+    } finally {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/lib/temp-dir.ts

@@ -0,0 +1,58 @@
+/**
+ * Safe temp directory helper.
+ *
+ * Motivation: many engines create predictable paths like
+ * `/tmp/narrated-video-${Date.now()}` which (a) race when two invocations
+ * hit the same millisecond, (b) leak state when the process crashes before
+ * the manual cleanup runs, and (c) are trivially overwritable by a local
+ * attacker who can guess the pattern.
+ *
+ * `withTempDir` uses `fs.mkdtemp` (unique suffix from the kernel) and
+ * always cleans up via try/finally.
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { logger } from './logger.js';
+
+/**
+ * Create a unique temp directory, pass it to `fn`, then clean up.
+ * Cleanup runs even if `fn` throws. Cleanup errors are logged but never
+ * re-thrown — the original error from `fn` always wins.
+ */
+export async function withTempDir<T>(
+  prefix: string,
+  fn: (dir: string) => Promise<T>
+): Promise<T> {
+  const base = join(tmpdir(), sanitizePrefix(prefix));
+  const dir = await mkdtemp(base);
+  try {
+    return await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch((err) => {
+      logger.warn(`temp-dir cleanup failed for ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+    });
+  }
+}
+
+/**
+ * Low-level: just create a unique temp directory, return the path.
+ * The caller is responsible for cleanup — prefer `withTempDir` when
+ * the lifetime is scoped to one function.
+ */
+export async function makeTempDir(prefix: string): Promise<string> {
+  const base = join(tmpdir(), sanitizePrefix(prefix));
+  return mkdtemp(base);
+}
+
+function sanitizePrefix(prefix: string): string {
+  // Kill `..` sequences first so a caller can't build a traversal-looking
+  // literal segment (the join() to tmpdir() already makes traversal
+  // impossible, but we still prefer tidy paths for ops + audit logs).
+  const noTraversal = prefix.replace(/\.{2,}/g, '-');
+  const safe = noTraversal.replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 32);
+  // mkdtemp appends 6 random chars; ensure we end with a `-` so the
+  // generated suffix stays visually separated.
+  return safe.endsWith('-') ? safe : `${safe}-`;
+}

package/src/lib/url-guard.test.ts

@@ -0,0 +1,261 @@
+/**
+ * Tests for the URL safety guard.
+ *
+ * The guard is the single chokepoint for any tool that navigates a
+ * user-supplied URL (Playwright page.goto, ffmpeg -i http://…). A bug here
+ * lets an AI assistant coerce the server to probe localhost, cloud metadata
+ * endpoints, or internal RFC1918 addresses, so this file exercises every
+ * branch of the reject rules and the MCP_VIDEO_ALLOW_INTERNAL escape hatch.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { guardUrl } from './url-guard.js';
+
+const ORIGINAL_ALLOW_INTERNAL = process.env.MCP_VIDEO_ALLOW_INTERNAL;
+
+beforeEach(() => {
+  delete process.env.MCP_VIDEO_ALLOW_INTERNAL;
+});
+afterEach(() => {
+  if (ORIGINAL_ALLOW_INTERNAL === undefined) {
+    delete process.env.MCP_VIDEO_ALLOW_INTERNAL;
+  } else {
+    process.env.MCP_VIDEO_ALLOW_INTERNAL = ORIGINAL_ALLOW_INTERNAL;
+  }
+});
+
+describe('guardUrl — input validation', () => {
+  it('rejects a non-string input (number)', () => {
+    const result = guardUrl(42 as unknown);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/non-empty string/);
+  });
+
+  it('rejects null and undefined', () => {
+    expect(guardUrl(null).ok).toBe(false);
+    expect(guardUrl(undefined).ok).toBe(false);
+  });
+
+  it('rejects an empty string', () => {
+    const result = guardUrl('');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/non-empty string/);
+  });
+
+  it('rejects a malformed URL', () => {
+    const result = guardUrl('not a url at all');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/not a valid URL/);
+  });
+});
+
+describe('guardUrl — scheme rules', () => {
+  it('allows https:// to a public host', () => {
+    const result = guardUrl('https://example.com/path');
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.url).toBe('https://example.com/path');
+  });
+
+  it('allows http:// to a public host', () => {
+    const result = guardUrl('http://example.com');
+    expect(result.ok).toBe(true);
+  });
+
+  it('rejects file://', () => {
+    const result = guardUrl('file:///etc/passwd');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/scheme .* not allowed/);
+  });
+
+  it('rejects ftp://', () => {
+    const result = guardUrl('ftp://example.com/file.txt');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/scheme ftp/);
+  });
+
+  it('rejects gopher:// (Redis-SSRF vector)', () => {
+    const result = guardUrl('gopher://evil.example/_redis');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/scheme gopher/);
+  });
+
+  it('rejects data: URLs', () => {
+    const result = guardUrl('data:text/html,<script>alert(1)</script>');
+    expect(result.ok).toBe(false);
+  });
+
+  it('rejects javascript: URLs', () => {
+    const result = guardUrl('javascript:alert(1)');
+    expect(result.ok).toBe(false);
+  });
+});
+
+describe('guardUrl — private-network blocks', () => {
+  it('blocks localhost by name', () => {
+    const result = guardUrl('http://localhost:8080/admin');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/private or loopback/);
+  });
+
+  it('blocks 127.0.0.1 (IPv4 loopback)', () => {
+    expect(guardUrl('http://127.0.0.1/').ok).toBe(false);
+    expect(guardUrl('http://127.5.6.7/').ok).toBe(false);
+  });
+
+  it('blocks IPv6 loopback ::1', () => {
+    // URL spec writes [::1] for IPv6 literals; parser normalises to [::1].
+    const result = guardUrl('http://[::1]/');
+    expect(result.ok).toBe(false);
+  });
+
+  it('blocks the 10/8 private range', () => {
+    expect(guardUrl('http://10.0.0.1/').ok).toBe(false);
+    expect(guardUrl('http://10.255.255.255/').ok).toBe(false);
+  });
+
+  it('blocks the 192.168/16 private range', () => {
+    expect(guardUrl('http://192.168.1.1/').ok).toBe(false);
+    expect(guardUrl('http://192.168.255.255/').ok).toBe(false);
+  });
+
+  it('blocks the 172.16/12 private range (CIDR edge cases)', () => {
+    expect(guardUrl('http://172.16.0.1/').ok).toBe(false);
+    expect(guardUrl('http://172.20.1.1/').ok).toBe(false);
+    expect(guardUrl('http://172.31.255.255/').ok).toBe(false);
+  });
+
+  it('does NOT block addresses just outside 172.16/12', () => {
+    // 172.15.x.x and 172.32.x.x are public.
+    expect(guardUrl('http://172.15.0.1/').ok).toBe(true);
+    expect(guardUrl('http://172.32.0.1/').ok).toBe(true);
+  });
+
+  it('blocks 169.254/16 link-local (covers AWS/GCP/Azure metadata at 169.254.169.254)', () => {
+    const aws = guardUrl('http://169.254.169.254/latest/meta-data/');
+    expect(aws.ok).toBe(false);
+    if (!aws.ok) expect(aws.reason).toMatch(/private or loopback/);
+    expect(guardUrl('http://169.254.0.1/').ok).toBe(false);
+  });
+
+  it('blocks 0.0.0.0 / 0.x.x.x', () => {
+    expect(guardUrl('http://0.0.0.0/').ok).toBe(false);
+    expect(guardUrl('http://0.1.2.3/').ok).toBe(false);
+  });
+
+  it('blocks IPv6 unique-local (fcXX::)', () => {
+    expect(guardUrl('http://[fc00::1]/').ok).toBe(false);
+    expect(guardUrl('http://[fd12::1]/').ok).toBe(false);
+  });
+
+  it('blocks IPv6 link-local (fe80::)', () => {
+    expect(guardUrl('http://[fe80::1]/').ok).toBe(false);
+  });
+
+  // ── Bypass-vector coverage (Critic round 2, Session 839) ──
+  // These encodings are classic SSRF-filter evasion. They work against
+  // regex-only guards that look for the literal string "127.0.0.1".
+  // Node's WHATWG URL parser normalises all of them, so our dotted-decimal
+  // + bracketed-IPv6 patterns catch every form — we test here to lock it in.
+
+  it('blocks IPv6-mapped-IPv4 literals ([::ffff:127.0.0.1])', () => {
+    // URL parser normalises ::ffff:127.0.0.1 → ::ffff:7f00:1 (compact form).
+    // Our /^\[/ generic-IPv6-literal pattern catches both, regardless of
+    // whether anyone embedded a v4 address in it.
+    expect(guardUrl('http://[::ffff:127.0.0.1]/').ok).toBe(false);
+    expect(guardUrl('http://[::ffff:7f00:1]/').ok).toBe(false);
+    expect(guardUrl('http://[0:0:0:0:0:ffff:7f00:1]/').ok).toBe(false);
+  });
+
+  it('blocks decimal-encoded IPv4 (URL parser normalises to dotted)', () => {
+    // 2130706433 == 0x7F000001 == 127.0.0.1.
+    expect(guardUrl('http://2130706433/').ok).toBe(false);
+  });
+
+  it('blocks hex-encoded IPv4 (URL parser normalises to dotted)', () => {
+    expect(guardUrl('http://0x7f000001/').ok).toBe(false);
+  });
+
+  it('blocks octal-encoded IPv4 (URL parser normalises to dotted)', () => {
+    // 0177.0.0.1 (octal for 127) → 127.0.0.1 after parsing.
+    expect(guardUrl('http://0177.0.0.1/').ok).toBe(false);
+  });
+
+  it('blocks short-form IPv4 (http://127.1/ → 127.0.0.1)', () => {
+    expect(guardUrl('http://127.1/').ok).toBe(false);
+  });
+
+  it('blocks bare "http://0/" (URL parser expands to 0.0.0.0)', () => {
+    expect(guardUrl('http://0/').ok).toBe(false);
+  });
+});
+
+describe('guardUrl — public hosts pass through', () => {
+  it('allows a typical public domain', () => {
+    expect(guardUrl('https://www.example.com/').ok).toBe(true);
+  });
+
+  it('allows a public IPv4 (8.8.8.8)', () => {
+    expect(guardUrl('http://8.8.8.8/').ok).toBe(true);
+  });
+
+  it('allows URLs with query strings and ports', () => {
+    const result = guardUrl('https://api.example.com:8443/v1/data?x=1&y=2');
+    expect(result.ok).toBe(true);
+  });
+
+  it('normalises URL formatting via WHATWG URL', () => {
+    // URL parser lowercases the scheme + host, appends default path.
+    const result = guardUrl('HTTPS://Example.COM');
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.url).toBe('https://example.com/');
+  });
+});
+
+describe('guardUrl — MCP_VIDEO_ALLOW_INTERNAL escape hatch', () => {
+  it('allows localhost when MCP_VIDEO_ALLOW_INTERNAL=1', () => {
+    process.env.MCP_VIDEO_ALLOW_INTERNAL = '1';
+    expect(guardUrl('http://localhost:3000/').ok).toBe(true);
+  });
+
+  it('allows RFC1918 addresses when the flag is on', () => {
+    process.env.MCP_VIDEO_ALLOW_INTERNAL = '1';
+    expect(guardUrl('http://192.168.1.1/').ok).toBe(true);
+    expect(guardUrl('http://10.0.0.1/').ok).toBe(true);
+  });
+
+  it('still rejects non-http(s) schemes even with the flag on', () => {
+    // Flag opens the private-network door, NOT the scheme door.
+    process.env.MCP_VIDEO_ALLOW_INTERNAL = '1';
+    expect(guardUrl('file:///etc/passwd').ok).toBe(false);
+  });
+
+  it('does NOT treat arbitrary truthy values as "on" — only the string "1"', () => {
+    process.env.MCP_VIDEO_ALLOW_INTERNAL = 'true';
+    expect(guardUrl('http://localhost/').ok).toBe(false);
+    process.env.MCP_VIDEO_ALLOW_INTERNAL = 'yes';
+    expect(guardUrl('http://localhost/').ok).toBe(false);
+    process.env.MCP_VIDEO_ALLOW_INTERNAL = '0';
+    expect(guardUrl('http://localhost/').ok).toBe(false);
+  });
+});
+
+describe('guardUrl — return-type narrowing', () => {
+  it('on success, result.url is the normalised absolute URL', () => {
+    const result = guardUrl('https://example.com');
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      // Type narrowing: result.url exists, result.reason does not.
+      expect(typeof result.url).toBe('string');
+      expect(result.url.startsWith('https://')).toBe(true);
+    }
+  });
+
+  it('on failure, result.reason is a non-empty string', () => {
+    const result = guardUrl('ftp://example.com');
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(typeof result.reason).toBe('string');
+      expect(result.reason.length).toBeGreaterThan(0);
+    }
+  });
+});