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

package/README.md

@@ -0,0 +1,278 @@
+<!--
+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-09-18T06:08:25.367Z
+-->
+
+# @molecule/api-media-streaming-hls
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+HLS media streaming provider for molecule.dev.
+
+Provides HLS (HTTP Live Streaming) support via ffmpeg for media segmentation
+and transcoding, with pure-TypeScript M3U8 playlist generation. Requires
+ffmpeg to be installed on the host system.
+
+## Quick Start
+
+```typescript
+import { setProvider, createStream } from '@molecule/api-media-streaming'
+import { provider } from '@molecule/api-media-streaming-hls'
+
+setProvider(provider)
+
+const manifest = await createStream('/path/to/video.mp4', {
+  segmentDuration: 6,
+  protocol: 'hls',
+})
+console.log(manifest.manifestUri) // '/hls-…/index.m3u8'
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-media-streaming-hls @molecule/api-media-streaming
+```
+
+## API
+
+### Interfaces
+
+#### `HlsConfig`
+
+Configuration options for the HLS streaming provider.
+
+```typescript
+interface HlsConfig {
+  /** Path to the ffmpeg binary. Defaults to `'ffmpeg'` (resolved via PATH). */
+  ffmpegPath?: string
+
+  /**
+   * Path to the ffprobe binary. RESERVED for future use — the current
+   * provider never invokes ffprobe (segment durations are taken from
+   * `segmentDuration`, not probed). Setting this has no effect today.
+   */
+  ffprobePath?: string
+
+  /** Base directory where stream output files are written. Defaults to `os.tmpdir()`. */
+  outputBasePath?: string
+
+  /** Default segment duration in seconds. Defaults to `6`. */
+  segmentDuration?: number
+
+  /** HLS playlist version. Defaults to `3`. */
+  hlsVersion?: number
+}
+```
+
+#### `M3u8PlaylistOptions`
+
+Options for generating an M3U8 media playlist.
+
+```typescript
+interface M3u8PlaylistOptions {
+  /** HLS playlist version. Defaults to `3`. */
+  version?: number
+
+  /** Target segment duration in seconds. Defaults to the maximum segment duration. */
+  targetDuration?: number
+
+  /** Whether this is a VOD (complete) or live (in-progress) playlist. Defaults to `'vod'`. */
+  playlistType?: 'vod' | 'event'
+
+  /** Media sequence number for the first segment. Defaults to `0`. */
+  mediaSequence?: number
+}
+```
+
+### Functions
+
+#### `assertSafePathComponent(value, label)`
+
+Asserts that a caller-supplied value is a safe single path component.
+
+Rejects empty strings, the relative segments `.` and `..`, anything
+containing a path separator or NUL byte, and anything outside the
+`[A-Za-z0-9._-]` allow-list (which also rejects shell metacharacters).
+
+```typescript
+function assertSafePathComponent(value: string, label: string): string
+```
+
+- `value` — The caller-supplied component (e.g. a stream id or profile name).
+- `label` — Human-readable name of the field, used in the error message.
+
+**Returns:** The validated component, unchanged.
+
+#### `assertSegmentIndex(index)`
+
+Asserts that a caller-supplied segment index is a non-negative integer.
+
+```typescript
+function assertSegmentIndex(index: number): number
+```
+
+- `index` — The caller-supplied segment index.
+
+**Returns:** The validated index, unchanged.
+
+#### `createProvider(config)`
+
+Creates an HLS streaming provider.
+
+```typescript
+function createProvider(config?: HlsConfig): StreamingProvider
+```
+
+- `config` — Optional provider configuration.
+
+**Returns:** A `StreamingProvider` backed by HLS / ffmpeg.
+
+#### `generateMasterPlaylist(variants)`
+
+Generates an M3U8 master playlist for adaptive bitrate streaming.
+
+```typescript
+function generateMasterPlaylist(variants: TranscodeVariant[]): string
+```
+
+- `variants` — The transcoded variant streams.
+
+**Returns:** The master M3U8 playlist content as a string.
+
+#### `generateMediaPlaylist(segments, options)`
+
+Generates an M3U8 media playlist from a list of stream segments.
+
+```typescript
+function generateMediaPlaylist(segments: StreamSegment[], options?: M3u8PlaylistOptions): string
+```
+
+- `segments` — Ordered list of stream segments.
+- `options` — Playlist generation options.
+
+**Returns:** The M3U8 playlist content as a string.
+
+#### `resolveWithinBase(base, parts)`
+
+Resolves `parts` against `base` and asserts the result stays within `base`.
+
+Defense-in-depth on top of {@link assertSafePathComponent}: even if a
+component slipped through, the resolved absolute path is rejected unless it
+is `base` itself or a descendant of it.
+
+```typescript
+function resolveWithinBase(base: string, parts?: string[]): string
+```
+
+- `base` — The intended base directory.
+- `parts` — Path segments to append.
+
+**Returns:** The resolved absolute path, guaranteed to be inside `base`.
+
+### Constants
+
+#### `provider`
+
+The provider implementation with default configuration.
+
+```typescript
+const provider: StreamingProvider
+```
+
+## Core Interface
+
+Implements `@molecule/api-media-streaming` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setProvider } from '@molecule/api-media-streaming'
+import { provider } from '@molecule/api-media-streaming-hls'
+
+export function setupMediaStreamingHls(): void {
+  setProvider(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-media-streaming` ^1.0.1
+
+### Runtime 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
+  with `ffmpeg -version` before shipping.
+- **The default output directory is `os.tmpdir()`** — volatile and served by
+  nothing. Pass `createProvider({ outputBasePath })` pointing at a directory
+  your server exposes (see the core remarks), or serve bytes through
+  `getSegment()` / `generateManifest()` endpoints.
+- `createStream()` also caches every segment `Buffer` in an in-process map
+  (never evicted) so `getSegment()` is fast; memory grows by the full video
+  size per stream. `getSegment()` disk fallback looks ONLY under
+  `outputBasePath/<streamId>/` — a per-call `createStream(..., { outputPath })`
+  override writes segments where the fallback cannot find them after a
+  restart, and `transcode()` ignores `outputPath` entirely (always writes
+  under `outputBasePath`).
+- `ffprobePath` in `HlsConfig` is currently RESERVED — no ffprobe call exists
+  yet; segment durations come from the requested `segmentDuration`.
+
+## E2E Tests
+
+Integration checklist — drive the real UI (live preview, no mocks), adapt
+each item to this app's actual upload/player screens, and check every box
+off one by one. A box you can't check is an integration bug to fix — not a
+skip. You can't judge real transcode QUALITY or a live A/V feed in the
+sandbox; verify the pipeline + playback WIRING you own:
+
+- [ ] Uploading/ingesting a media asset produces a real PLAYABLE stream: the
+      returned `manifestUri` (`.m3u8` for HLS / `.mpd` for DASH) loads in the
+      app's video player and actually plays — frames advance and the player
+      fetches segments (watch the network panel), never a broken/blank player.
+- [ ] The stream is served from/through the APP'S OWN origin — an
+      `outputPath` under a directory the server exposes, or endpoints that return
+      `generateManifest(segments)` and stream `getSegment(streamId, index)` bytes.
+      The player must NOT hotlink a raw expiring provider URL, and no manifest or
+      segment request may 404.
+- [ ] Processing STATE is observable and playback is gated on it: an asset
+      moves pending → processing → ready (StreamStatus), the UI reflects that,
+      and the player mounts only once status is 'ready' — never a dead player on
+      a still-transcoding asset.
+- [ ] If adaptive bitrate is exposed, `transcode()` produced multiple
+      renditions: the master manifest (`masterManifestUri`) lists more than one
+      `variant` and the player can switch quality across them.
+- [ ] If the app exposes a poster/thumbnail for an asset, it generates and
+      renders before playback (no blank tile).
+- [ ] SECURITY — private media is AUTHORIZED on playback: the manifest and
+      segment endpoints check the requester (or hand out a signed/expiring URL),
+      so a user CANNOT fetch another user's stream by guessing its `id`/URL; and
+      provider keys stay server-side (never shipped to the client bundle).

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.0",
+  "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",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -30,13 +31,13 @@
   ],
   "license": "Apache-2.0",
   "peerDependencies": {
-    "@molecule/api-media-streaming": "^1.0.0"
+    "@molecule/api-media-streaming": "^1.0.1"
   },
   "devDependencies": {
-    "@molecule/api-media-streaming": "1.0.0",
+    "@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",