@molecule/api-media-streaming-hls 1.0.1 → 1.1.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-08-04T01:48:38.551Z
+Generated: 2026-09-18T06:08:25.367Z
 -->
 
 # @molecule/api-media-streaming-hls
@@ -218,6 +218,16 @@ Peer dependencies:
 
 - `@molecule/api-media-streaming`
 
+- **String inputs must be local absolute file paths.** `createStream()` and
+  `transcode()` accept `Buffer | string`; a string is passed straight to
+  ffmpeg's `-i`, and ffmpeg natively fetches `http(s)`, `tcp`, `tls`, and
+  more — so an unvalidated string would make the bond an SSRF / file-read
+  primitive acting with your server's network position. Strings that
+  contain `://`, carry a `scheme:` prefix, or are not absolute paths are
+  rejected with a thrown error. For remote media, fetch the bytes yourself
+  (with your own SSRF guard) and pass a `Buffer`. As defense-in-depth the
+  ffmpeg protocol whitelist is trimmed to local protocols (`file,crypto`) —
+  network protocols are never enabled.
 - **Requires the `ffmpeg` binary on the host** (resolved via PATH, or set
   `createProvider({ ffmpegPath })`). A missing binary fails at first
   `createStream()`/`transcode()` call with `spawn ffmpeg ENOENT` — verify

package/dist/index.d.ts

@@ -20,6 +20,16 @@
  * ```
  *
  * @remarks
+ * - **String inputs must be local absolute file paths.** `createStream()` and
+ *   `transcode()` accept `Buffer | string`; a string is passed straight to
+ *   ffmpeg's `-i`, and ffmpeg natively fetches `http(s)`, `tcp`, `tls`, and
+ *   more — so an unvalidated string would make the bond an SSRF / file-read
+ *   primitive acting with your server's network position. Strings that
+ *   contain `://`, carry a `scheme:` prefix, or are not absolute paths are
+ *   rejected with a thrown error. For remote media, fetch the bytes yourself
+ *   (with your own SSRF guard) and pass a `Buffer`. As defense-in-depth the
+ *   ffmpeg protocol whitelist is trimmed to local protocols (`file,crypto`) —
+ *   network protocols are never enabled.
  * - **Requires the `ffmpeg` binary on the host** (resolved via PATH, or set
  *   `createProvider({ ffmpegPath })`). A missing binary fails at first
  *   `createStream()`/`transcode()` call with `spawn ffmpeg ENOENT` — verify

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -20,6 +20,16 @@
  * ```
  *
  * @remarks
+ * - **String inputs must be local absolute file paths.** `createStream()` and
+ *   `transcode()` accept `Buffer | string`; a string is passed straight to
+ *   ffmpeg's `-i`, and ffmpeg natively fetches `http(s)`, `tcp`, `tls`, and
+ *   more — so an unvalidated string would make the bond an SSRF / file-read
+ *   primitive acting with your server's network position. Strings that
+ *   contain `://`, carry a `scheme:` prefix, or are not absolute paths are
+ *   rejected with a thrown error. For remote media, fetch the bytes yourself
+ *   (with your own SSRF guard) and pass a `Buffer`. As defense-in-depth the
+ *   ffmpeg protocol whitelist is trimmed to local protocols (`file,crypto`) —
+ *   network protocols are never enabled.
  * - **Requires the `ffmpeg` binary on the host** (resolved via PATH, or set
  *   `createProvider({ ffmpegPath })`). A missing binary fails at first
  *   `createStream()`/`transcode()` call with `spawn ffmpeg ENOENT` — verify

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,KAAK,EACV,iBAAiB,EAOlB,MAAM,+BAA+B,CAAA;AAGtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAwD3C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,SAAQ,SAAc,KAAG,iBA8JvD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,iBAAoC,CAAA"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,KAAK,EACV,iBAAiB,EAOlB,MAAM,+BAA+B,CAAA;AAGtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAoG3C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,SAAQ,SAAc,KAAG,iBAmKvD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,iBAAoC,CAAA"}

package/dist/provider.js

@@ -10,11 +10,48 @@
 import { execFile } from 'node:child_process';
 import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { isAbsolute, join } from 'node:path';
 import { promisify } from 'node:util';
 import { generateMasterPlaylist, generateMediaPlaylist } from './m3u8.js';
 import { assertSafePathComponent, assertSegmentIndex, resolveWithinBase } from './validate.js';
 const execFileAsync = promisify(execFile);
+/**
+ * Matches a URL scheme prefix (`scheme:`) the way ffmpeg's own protocol
+ * handler resolution does — including scheme-only forms like `http:host/x`
+ * that carry no `//`.
+ */
+const URL_SCHEME_PREFIX = /^[a-z][a-z0-9+.-]*:/i;
+/**
+ * Asserts that a caller-supplied string input is a LOCAL ABSOLUTE FILE PATH.
+ *
+ * String inputs are passed verbatim as ffmpeg's `-i` argument, and ffmpeg
+ * natively speaks `http`, `https`, `tcp`, `tls`, `concat`, `gopher`, and
+ * more. Forwarding an unvalidated string therefore turns this bond into an
+ * SSRF / file-read primitive: `http://169.254.169.254/…` (cloud metadata),
+ * `http://intra-host/…`, or any other URL the host can reach, executed by
+ * ffmpeg with the server's network position. We reject:
+ *
+ * - anything containing `://` (absolute URLs),
+ * - anything with a `scheme:` prefix (ffmpeg accepts `http:host/x` too),
+ * - anything that is not an absolute path (`/…`) — a relative path would
+ *   resolve against ffmpeg's CWD, not the caller's.
+ *
+ * Applications that need remote media must fetch the bytes themselves (with
+ * their own SSRF guard) and pass a `Buffer`.
+ *
+ * Module-private: not part of the package's public export surface.
+ *
+ * @param inputPath - The caller-supplied string input.
+ * @returns The validated path, unchanged.
+ * @throws {Error} When the string is not a local absolute file path.
+ */
+const assertLocalInputPath = (inputPath) => {
+    if (inputPath.includes('://') || URL_SCHEME_PREFIX.test(inputPath) || !isAbsolute(inputPath)) {
+        throw new Error(`Invalid media input: string inputs must be local absolute file paths (got ${JSON.stringify(inputPath)}). ` +
+            'Fetch remote media yourself (with an SSRF guard) and pass a Buffer instead — ffmpeg URLs are rejected to prevent server-side request forgery.');
+    }
+    return inputPath;
+};
 let streamCounter = 0;
 /**
  * Generates a unique stream identifier.
@@ -34,7 +71,10 @@ const generateStreamId = () => {
  */
 const prepareInput = async (input, dir) => {
     if (typeof input === 'string') {
-        return input;
+        // SSRF guard: a string is treated as a local absolute FILE path only —
+        // ffmpeg speaks http/tcp/… natively, so an unvalidated string is a
+        // fetch-anything primitive. Remote media must arrive as a Buffer.
+        return assertLocalInputPath(input);
     }
     const inputPath = join(dir, 'input.tmp');
     await writeFile(inputPath, input);
@@ -78,10 +118,13 @@ export const createProvider = (config = {}) => {
             await mkdir(outputDir, { recursive: true });
             const inputPath = await prepareInput(input, outputDir);
             await execFileAsync(ffmpegPath, [
-                // Restrict ffmpeg to safe protocols so a string input can't abuse dangerous
-                // ones (concat/gopher/ftp/subfile/unix) for LFI/SSRF escalation. [P5BONDS DiD]
+                // Defense-in-depth behind the string-input SSRF guard: restrict ffmpeg
+                // to LOCAL protocols only (file, crypto). Network protocols (http,
+                // https, tcp, tls) are deliberately NOT whitelisted — a string input
+                // must be a local absolute file path (see assertLocalInputPath), so
+                // nothing legitimate ever needs network access here. [P5BONDS DiD]
                 '-protocol_whitelist',
-                'file,crypto,data,http,https,tcp,tls',
+                'file,crypto',
                 '-i',
                 inputPath,
                 '-codec',
@@ -128,9 +171,11 @@ export const createProvider = (config = {}) => {
                 await mkdir(profileDir, { recursive: true });
                 const codec = profile.codec ?? 'h264';
                 const args = [
-                    // Restrict ffmpeg to safe protocols (no concat/gopher/ftp/subfile). [P5BONDS DiD]
+                    // Defense-in-depth behind the string-input SSRF guard: local
+                    // protocols only — see the createStream whitelist comment.
+                    // [P5BONDS DiD]
                     '-protocol_whitelist',
-                    'file,crypto,data,http,https,tcp,tls',
+                    'file,crypto',
                     '-i',
                     inputPath,
                     '-c:v',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-media-streaming-hls",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "HLS media streaming provider for molecule.dev — ffmpeg-based segmentation, transcoding, and M3U8 playlist generation",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,7 @@
     "@molecule/api-media-streaming": "1.0.1",
     "@types/node": "26.1.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "repository": {
     "type": "git",