@studiomeyer/mcp-video 1.0.0 → 1.0.1

package/dist/lib/ffmpeg-run.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg-run.test.js","sourceRoot":"","sources":["../../src/lib/ffmpeg-run.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/ffmpeg-safety.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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';
+/**
+ * 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 declare function buildFfmpegArgs(userArgs: string[], protocols?: FfmpegProtocolSet): string[];
+/**
+ * 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 declare function validateFfmpegPath(p: unknown, label?: string): string;
+/**
+ * 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 declare function validateFfmpegPaths(args: string[], userControlledIndices: number[], label?: string): void;

package/dist/lib/ffmpeg-safety.js

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+const PROTOCOL_SETS = {
+    // 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, protocols = 'local-only') {
+    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, label = 'path') {
+    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, userControlledIndices, label = 'path') {
+    for (const i of userControlledIndices) {
+        validateFfmpegPath(args[i], `${label}[${i}]`);
+    }
+}
+//# sourceMappingURL=ffmpeg-safety.js.map

package/dist/lib/ffmpeg-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg-safety.js","sourceRoot":"","sources":["../../src/lib/ffmpeg-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,aAAa,GAAsC;IACvD,qEAAqE;IACrE,YAAY,EAAE,2BAA2B;IACzC,2EAA2E;IAC3E,8EAA8E;IAC9E,aAAa,EAAE,yCAAyC;IACxD,6EAA6E;IAC7E,4EAA4E;IAC5E,eAAe,EAAE,uDAAuD;CACzE,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAkB,EAClB,YAA+B,YAAY;IAE3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,yCAAyC,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,CAAC,qBAAqB,EAAE,aAAa,CAAC,SAAS,CAAC,EAAE,GAAG,QAAQ,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAU,EAAE,KAAK,GAAG,MAAM;IAC3D,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,6BAA6B,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,8CAA8C,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,8BAA8B,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAc,EACd,qBAA+B,EAC/B,KAAK,GAAG,MAAM;IAEd,KAAK,MAAM,CAAC,IAAI,qBAAqB,EAAE,CAAC;QACtC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;AACH,CAAC"}

package/dist/lib/ffmpeg-safety.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/ffmpeg-safety.test.js

@@ -0,0 +1,72 @@
+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']) {
+            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/);
+    });
+});
+//# sourceMappingURL=ffmpeg-safety.test.js.map

package/dist/lib/ffmpeg-safety.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffmpeg-safety.test.js","sourceRoot":"","sources":["../../src/lib/ffmpeg-safety.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/temp-dir.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function withTempDir<T>(prefix: string, fn: (dir: string) => Promise<T>): Promise<T>;
+/**
+ * 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 declare function makeTempDir(prefix: string): Promise<string>;

package/dist/lib/temp-dir.js

@@ -0,0 +1,53 @@
+/**
+ * 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(prefix, fn) {
+    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) {
+    const base = join(tmpdir(), sanitizePrefix(prefix));
+    return mkdtemp(base);
+}
+function sanitizePrefix(prefix) {
+    // 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}-`;
+}
+//# sourceMappingURL=temp-dir.js.map

package/dist/lib/temp-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-dir.js","sourceRoot":"","sources":["../../src/lib/temp-dir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAc,EACd,EAA+B;IAE/B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YAC5D,MAAM,CAAC,IAAI,CAAC,+BAA+B,GAAG,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzG,CAAC,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAc;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,cAAc,CAAC,MAAc;IACpC,wEAAwE;IACxE,kEAAkE;IAClE,oEAAoE;IACpE,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvE,kEAAkE;IAClE,6CAA6C;IAC7C,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC;AAChD,CAAC"}

package/dist/lib/temp-dir.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/temp-dir.test.js

@@ -0,0 +1,68 @@
+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 });
+        }
+    });
+});
+//# sourceMappingURL=temp-dir.test.js.map

package/dist/lib/temp-dir.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-dir.test.js","sourceRoot":"","sources":["../../src/lib/temp-dir.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/url-guard.d.ts

@@ -0,0 +1,41 @@
+/**
+ * URL safety guard for any tool that fetches/navigates user-supplied URLs.
+ *
+ * Blocks four classes of SSRF abuse that an AI assistant can stumble into
+ * when the server is asked to open arbitrary URLs:
+ *   1. Non-http(s) schemes (file://, ftp://, gopher://, data: etc.)
+ *   2. Loopback + link-local + RFC1918 + cloud metadata endpoints
+ *   3. IPv6-mapped IPv4 (::ffff:127.0.0.1) that slips past IPv4 regex
+ *   4. DNS-rebinding — hostnames that resolve to internal IPs
+ *
+ * Three entry points:
+ *   • guardUrl(raw)            sync — scheme + literal-host check
+ *   • resolveAndGuardUrl(raw)  async — adds DNS.lookup(family:0) on the host
+ *   • guardFinalUrl(raw)       sync — post-redirect check, reuses guardUrl
+ *
+ * Opt-in escape hatch for local dev: set MCP_VIDEO_ALLOW_INTERNAL=1.
+ */
+export type UrlGuardResult = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function guardUrl(raw: unknown): UrlGuardResult;
+/**
+ * Async variant that also resolves the hostname via DNS and checks every
+ * returned IP against the block list. Catches the simple rebind case where
+ * a public hostname resolves to a loopback or RFC1918 address.
+ *
+ * NOTE: This does not eliminate TOCTOU windows — the browser/ffmpeg will
+ * resolve again at request time. But it blocks the trivial path and forces
+ * an attacker to rely on narrow TTL-based flipping.
+ */
+export declare function resolveAndGuardUrl(raw: unknown): Promise<UrlGuardResult>;
+/**
+ * Post-navigation check: after `page.goto()` the browser may have followed
+ * redirects to an internal host. Pass `page.url()` through this to confirm
+ * the final URL is still guard-clean.
+ */
+export declare function guardFinalUrl(raw: unknown): UrlGuardResult;

package/dist/lib/url-guard.js

@@ -0,0 +1,134 @@
+/**
+ * URL safety guard for any tool that fetches/navigates user-supplied URLs.
+ *
+ * Blocks four classes of SSRF abuse that an AI assistant can stumble into
+ * when the server is asked to open arbitrary URLs:
+ *   1. Non-http(s) schemes (file://, ftp://, gopher://, data: etc.)
+ *   2. Loopback + link-local + RFC1918 + cloud metadata endpoints
+ *   3. IPv6-mapped IPv4 (::ffff:127.0.0.1) that slips past IPv4 regex
+ *   4. DNS-rebinding — hostnames that resolve to internal IPs
+ *
+ * Three entry points:
+ *   • guardUrl(raw)            sync — scheme + literal-host check
+ *   • resolveAndGuardUrl(raw)  async — adds DNS.lookup(family:0) on the host
+ *   • guardFinalUrl(raw)       sync — post-redirect check, reuses guardUrl
+ *
+ * Opt-in escape hatch for local dev: set MCP_VIDEO_ALLOW_INTERNAL=1.
+ */
+import { lookup } from 'node:dns/promises';
+const ALLOWED_SCHEMES = new Set(['https:', 'http:']);
+const BLOCKED_HOST_PATTERNS = [
+    /^localhost$/i,
+    /^(?:127|10)\./,
+    /^192\.168\./,
+    /^172\.(?:1[6-9]|2\d|3[0-1])\./,
+    /^169\.254\./, // link-local + AWS/GCP/Azure metadata (169.254.169.254)
+    /^0\./,
+    /^::1$/,
+    // IPv6 unique-local is fc00::/7 — that covers fc00..fdff.
+    /^f[cd][0-9a-f]{2}:/i,
+    /^fe80:/i, // IPv6 link-local
+];
+// IPv4 dotted-quad literal (captures the form the OS + URL parser canonicalize to).
+const IPV4_LITERAL = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+// IPv6-mapped IPv4 in dotted form: ::ffff:127.0.0.1
+const IPV6_MAPPED_IPV4_DOTTED = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i;
+// IPv6-mapped IPv4 in compact hex form: ::ffff:7f00:1
+const IPV6_MAPPED_IPV4_HEX = /^::ffff:[0-9a-f]{1,4}:[0-9a-f]{1,4}$/i;
+// IPv6-mapped IPv4 in fully uncompressed form: 0:0:0:0:0:ffff:7f00:1
+const IPV6_MAPPED_IPV4_FULL = /^0:0:0:0:0:ffff:[0-9a-f]{1,4}:[0-9a-f]{1,4}$/i;
+function normalizeHost(hostname) {
+    // URL parser strips brackets from IPv6 hostnames already; be defensive
+    // in case a caller passes the raw host string.
+    const unbracketed = hostname.replace(/^\[/, '').replace(/\]$/, '');
+    const mapped = unbracketed.match(IPV6_MAPPED_IPV4_DOTTED);
+    if (mapped)
+        return mapped[1]; // re-check dotted form against IPv4 patterns
+    return unbracketed;
+}
+function isMappedIpv4(host) {
+    return (IPV6_MAPPED_IPV4_DOTTED.test(host) ||
+        IPV6_MAPPED_IPV4_HEX.test(host) ||
+        IPV6_MAPPED_IPV4_FULL.test(host));
+}
+function isBlockedHost(hostname) {
+    const normalized = normalizeHost(hostname);
+    if (isMappedIpv4(normalized)) {
+        return `host ${hostname} is IPv6-mapped IPv4 — blocked`;
+    }
+    for (const pat of BLOCKED_HOST_PATTERNS) {
+        if (pat.test(normalized)) {
+            return `host ${hostname} is private or loopback — set MCP_VIDEO_ALLOW_INTERNAL=1 to override`;
+        }
+    }
+    return null;
+}
+export function guardUrl(raw) {
+    if (typeof raw !== 'string' || raw.length === 0) {
+        return { ok: false, reason: 'url must be a non-empty string' };
+    }
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return { ok: false, reason: 'url is not a valid URL' };
+    }
+    if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+        return { ok: false, reason: `scheme ${parsed.protocol} is not allowed — use http(s)` };
+    }
+    if (process.env.MCP_VIDEO_ALLOW_INTERNAL === '1') {
+        return { ok: true, url: parsed.toString() };
+    }
+    const blocked = isBlockedHost(parsed.hostname);
+    if (blocked)
+        return { ok: false, reason: blocked };
+    return { ok: true, url: parsed.toString() };
+}
+/**
+ * Async variant that also resolves the hostname via DNS and checks every
+ * returned IP against the block list. Catches the simple rebind case where
+ * a public hostname resolves to a loopback or RFC1918 address.
+ *
+ * NOTE: This does not eliminate TOCTOU windows — the browser/ffmpeg will
+ * resolve again at request time. But it blocks the trivial path and forces
+ * an attacker to rely on narrow TTL-based flipping.
+ */
+export async function resolveAndGuardUrl(raw) {
+    const first = guardUrl(raw);
+    if (!first.ok)
+        return first;
+    if (process.env.MCP_VIDEO_ALLOW_INTERNAL === '1')
+        return first;
+    const parsed = new URL(first.url);
+    const host = parsed.hostname.replace(/^\[/, '').replace(/\]$/, '');
+    // Literal IPv4/IPv6 — guardUrl already checked, nothing to resolve.
+    if (IPV4_LITERAL.test(host) || host.includes(':'))
+        return first;
+    try {
+        const addresses = await lookup(host, { all: true, family: 0 });
+        for (const addr of addresses) {
+            const blocked = isBlockedHost(addr.address);
+            if (blocked) {
+                return {
+                    ok: false,
+                    reason: `host ${host} resolves to private address ${addr.address} — blocked`,
+                };
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `DNS lookup failed for ${host}: ${msg}` };
+    }
+    return first;
+}
+/**
+ * Post-navigation check: after `page.goto()` the browser may have followed
+ * redirects to an internal host. Pass `page.url()` through this to confirm
+ * the final URL is still guard-clean.
+ */
+export function guardFinalUrl(raw) {
+    return guardUrl(raw);
+}
+//# sourceMappingURL=url-guard.js.map

package/dist/lib/url-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-guard.js","sourceRoot":"","sources":["../../src/lib/url-guard.ts"],"names":[],"mappings":"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"}

package/dist/lib/url-guard.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+export {};