@memberjunction/server 5.43.0 → 5.45.0

package/dist/rest/MediaStreamHandler.js

@@ -0,0 +1,195 @@
+/**
+ * @fileoverview Authenticated HTTP-Range media streaming route (`GET /media/:fileId`).
+ *
+ * Streams an `MJ: Files` object's bytes (optionally a byte range) to the browser so
+ * `<audio>`/`<video>` elements get native progressive playback + seek-before-download
+ * for large media — instead of the whole file being base64'd over GraphQL.
+ *
+ * Auth model: the request carries a short-lived signed token (`?token=`) minted by
+ * `CreateMediaAccessToken` AFTER a per-user permission check. The token IS the
+ * capability: this route re-verifies its signature/expiry/`typ` and that it matches
+ * the `:fileId`, then loads the file under a SYSTEM context (it only needs
+ * `ProviderKey`/`ProviderID` to locate the bytes — no row-level re-check, since
+ * access was already authorized at mint).
+ *
+ * Mount unauthenticated, BEFORE the unified auth middleware:
+ *   `app.use('/media', cors<cors.CorsRequest>(), createMediaStreamRouter())`
+ *
+ * @module @memberjunction/server/rest/MediaStreamHandler
+ */
+import express from 'express';
+import { LogError, Metadata } from '@memberjunction/core';
+import { FileStorageEngine } from '@memberjunction/storage';
+import { getSystemUser } from '../auth/index.js';
+import { MediaAccessKeyManager } from './MediaAccessKeys.js';
+import { parseRange, parseRangeHeaderLoose } from './mediaRange.js';
+/**
+ * Builds the Express router exposing `GET /media/:fileId`. Stateless — verification
+ * and byte-source resolution happen per request.
+ */
+export function createMediaStreamRouter() {
+    const router = express.Router();
+    router.get('/:fileId', async (req, res) => {
+        await handleMediaRequest(req, res);
+    });
+    return router;
+}
+/** Top-level request handler: verify token → resolve bytes → stream/buffer with Range support. */
+async function handleMediaRequest(req, res) {
+    // Express type defs allow req.params values to be string | string[]; normalize to string
+    // so downstream consumers with moduleResolution:"node" type-check cleanly (see SignatureWebhookHandler).
+    const rawFileId = req.params.fileId;
+    const fileId = Array.isArray(rawFileId) ? rawFileId[0] : rawFileId;
+    const token = typeof req.query.token === 'string' ? req.query.token : '';
+    const claims = verifyMediaToken(token, fileId);
+    if (!claims) {
+        // No body leak — a bad/expired/mismatched token is indistinguishable from "forbidden".
+        res.status(403).end();
+        return;
+    }
+    // Never let CDNs or shared caches retain authorized media bytes.
+    res.setHeader('Cache-Control', 'private, no-store');
+    try {
+        const source = await resolveFileBytesSource(fileId);
+        if (!source) {
+            res.status(404).end();
+            return;
+        }
+        await streamOrBuffer(req, res, source);
+    }
+    catch (error) {
+        LogError(`[MediaStream] Failed to serve file ${fileId}: ${error instanceof Error ? error.message : String(error)}`);
+        if (!res.headersSent) {
+            res.status(500).end();
+        }
+        else {
+            res.destroy();
+        }
+    }
+}
+/**
+ * Verifies the token and that it grants access to THIS file. Returns null on any failure
+ * (signature, expiry, `typ`, or fileId mismatch) so the caller can 403 uniformly.
+ */
+function verifyMediaToken(token, fileId) {
+    if (!token) {
+        return null;
+    }
+    const result = MediaAccessKeyManager.Instance.Verify(token);
+    if (!result.Valid) {
+        return null;
+    }
+    // The token's fileId must match the path — a token minted for file A cannot stream file B.
+    if (result.Claims.fileId !== fileId) {
+        return null;
+    }
+    return { fileId: result.Claims.fileId, userId: result.Claims.userId };
+}
+/**
+ * Loads the file under a SYSTEM context and resolves its storage driver + provider key.
+ * Returns null when the file row, its account, or its provider key can't be resolved
+ * (→ 404). Mirrors `readRealtimeRecordingFile`'s account-resolution (engine config with
+ * force-refresh fallback for newly-provisioned accounts).
+ */
+async function resolveFileBytesSource(fileId) {
+    const systemUser = await getSystemUser();
+    // The /media route runs pre-auth on the server's own provider; access was already authorized
+    // at token-mint time, so this load only locates the bytes.
+    const md = new Metadata(); // global-provider-ok: pre-auth system-context route, no per-request provider
+    const file = await md.GetEntityObject('MJ: Files', systemUser);
+    if (!await file.Load(fileId) || !file.ProviderKey) {
+        return null;
+    }
+    // Resolve the storage account for the file's provider; force-refresh once if a
+    // newly-provisioned account isn't in the cache yet.
+    await FileStorageEngine.Instance.Config(false, systemUser);
+    let accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+    if (accounts.length === 0) {
+        await FileStorageEngine.Instance.Config(true, systemUser);
+        accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+    }
+    const account = accounts[0];
+    if (!account) {
+        return null;
+    }
+    const driver = await FileStorageEngine.Instance.GetDriver(account.ID, systemUser);
+    return {
+        driver,
+        providerKey: file.ProviderKey,
+        contentType: file.ContentType ?? 'application/octet-stream',
+    };
+}
+/**
+ * Streams the object honoring an HTTP `Range` request. Prefers true streaming
+ * (`GetObjectStream`) for streaming-capable drivers; gracefully falls back to a
+ * full buffered `GetObject` (slicing for Range) for drivers that don't.
+ */
+async function streamOrBuffer(req, res, source) {
+    const rangeHeader = typeof req.headers.range === 'string' ? req.headers.range : undefined;
+    if (source.driver.SupportsStreaming) {
+        await serveViaStream(res, source, rangeHeader);
+    }
+    else {
+        await serveViaBuffer(res, source, rangeHeader);
+    }
+}
+/** True-streaming path: `GetObjectStream` + pipe, with 206 when a Range was honored. */
+async function serveViaStream(res, source, rangeHeader) {
+    const range = rangeHeader ? parseRangeHeaderLoose(rangeHeader) : undefined;
+    // Omit End for an open-ended range so the driver streams to EOF (per ByteRange semantics).
+    const streamRange = range
+        ? (range.end == null ? { Start: range.start } : { Start: range.start, End: range.end })
+        : undefined;
+    const result = await source.driver.GetObjectStream({ fullPath: source.providerKey, Range: streamRange });
+    res.setHeader('Accept-Ranges', 'bytes');
+    res.setHeader('Content-Type', result.ContentType ?? source.contentType);
+    if (result.ContentLength != null) {
+        res.setHeader('Content-Length', String(result.ContentLength));
+    }
+    if (result.ContentRange) {
+        const { Start, End, Total } = result.ContentRange;
+        res.setHeader('Content-Range', `bytes ${Start}-${End}/${Total}`);
+        res.status(206);
+    }
+    else {
+        res.status(200);
+    }
+    // Tear down the source stream if the client aborts (closed tab, seek, etc.).
+    res.on('close', () => result.Stream.destroy());
+    result.Stream.on('error', (err) => {
+        LogError(`[MediaStream] Source stream error: ${err instanceof Error ? err.message : String(err)}`);
+        if (!res.headersSent) {
+            res.status(500).end();
+        }
+        else {
+            res.destroy();
+        }
+    });
+    result.Stream.pipe(res);
+}
+/** Fallback path: full buffered `GetObject`, slicing the buffer for Range (206) or sending whole (200). */
+async function serveViaBuffer(res, source, rangeHeader) {
+    const buffer = await source.driver.GetObject({ fullPath: source.providerKey });
+    const total = buffer.length;
+    res.setHeader('Accept-Ranges', 'bytes');
+    res.setHeader('Content-Type', source.contentType);
+    if (!rangeHeader) {
+        res.status(200);
+        res.setHeader('Content-Length', String(total));
+        res.end(buffer);
+        return;
+    }
+    const range = parseRange(rangeHeader, total);
+    if (!range) {
+        // Unsatisfiable range — per RFC 7233, 416 + Content-Range with the total size.
+        res.setHeader('Content-Range', `bytes */${total}`);
+        res.status(416).end();
+        return;
+    }
+    const slice = buffer.subarray(range.start, range.end + 1);
+    res.status(206);
+    res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${total}`);
+    res.setHeader('Content-Length', String(slice.length));
+    res.end(slice);
+}
+//# sourceMappingURL=MediaStreamHandler.js.map

package/dist/rest/MediaStreamHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MediaStreamHandler.js","sourceRoot":"","sources":["../../src/rest/MediaStreamHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,OAAqD,MAAM,SAAS,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAEpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAUpE;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAChC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;QAC3D,MAAM,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,kGAAkG;AAClG,KAAK,UAAU,kBAAkB,CAAC,GAAY,EAAE,GAAa;IAC3D,yFAAyF;IACzF,yGAAyG;IACzG,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,MAAM,MAAM,GAAW,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3E,MAAM,KAAK,GAAG,OAAO,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAEzE,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,uFAAuF;QACvF,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACtB,OAAO;IACT,CAAC;IAED,iEAAiE;IACjE,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC;IAEpD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,sBAAsB,CAAC,MAAM,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QACD,MAAM,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,QAAQ,CAAC,sCAAsC,MAAM,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpH,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;YACrB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,OAAO,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,KAAa,EAAE,MAAc;IACrD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,2FAA2F;IAC3F,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,sBAAsB,CAAC,MAAc;IAClD,MAAM,UAAU,GAAa,MAAM,aAAa,EAAE,CAAC;IAEnD,6FAA6F;IAC7F,2DAA2D;IAC3D,MAAM,EAAE,GAAG,IAAI,QAAQ,EAAE,CAAC,CAAC,6EAA6E;IACxG,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,eAAe,CAAe,WAAW,EAAE,UAAU,CAAC,CAAC;IAC7E,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,+EAA+E;IAC/E,oDAAoD;IACpD,MAAM,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC3D,IAAI,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,CAAC,uBAAuB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACnF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC1D,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,CAAC,uBAAuB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjF,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAClF,OAAO;QACL,MAAM;QACN,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,0BAA0B;KAC5D,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,cAAc,CAAC,GAAY,EAAE,GAAa,EAAE,MAAuB;IAChF,MAAM,WAAW,GAAG,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAE1F,IAAI,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;QACpC,MAAM,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACjD,CAAC;SAAM,CAAC;QACN,MAAM,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACjD,CAAC;AACH,CAAC;AAED,wFAAwF;AACxF,KAAK,UAAU,cAAc,CAAC,GAAa,EAAE,MAAuB,EAAE,WAA+B;IACnG,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3E,2FAA2F;IAC3F,MAAM,WAAW,GAA0B,KAAK;QAC9C,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;QACvF,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAEzG,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;IACxC,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC;IACxE,IAAI,MAAM,CAAC,aAAa,IAAI,IAAI,EAAE,CAAC;QACjC,GAAG,CAAC,SAAS,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,YAAY,CAAC;QAClD,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC;QACjE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC;IAED,6EAA6E;IAC7E,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/C,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;QAChC,QAAQ,CAAC,sCAAsC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;YACrB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,OAAO,EAAE,CAAC;QAChB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED,2GAA2G;AAC3G,KAAK,UAAU,cAAc,CAAC,GAAa,EAAE,MAAuB,EAAE,WAA+B;IACnG,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;IAE5B,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;IACxC,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAElD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChB,GAAG,CAAC,SAAS,CAAC,gBAAgB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/C,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChB,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,+EAA+E;QAC/E,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,WAAW,KAAK,EAAE,CAAC,CAAC;QACnD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACtB,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAC1D,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChB,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,SAAS,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC;IAC7E,GAAG,CAAC,SAAS,CAAC,gBAAgB,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACtD,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC"}

package/dist/rest/mediaRange.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Pure HTTP `Range` header parsing for the `/media/:fileId` stream route.
+ *
+ * Split out of {@link module:@memberjunction/server/rest/MediaStreamHandler} (which pulls in
+ * auth/config/storage at module load) so this load-bearing parsing logic is unit-testable in
+ * isolation — same pattern as `peaksSidecar.ts`. These functions decide whether a request gets
+ * a 206 partial body (and over which byte window) vs. a full 200 / a 416.
+ *
+ * Both helpers are deliberately strict single-range parsers: anything malformed, multi-range,
+ * or suffix-only (`bytes=-N`) yields `undefined`, letting the caller fall back to a full read
+ * (streaming path) or a 416 (buffer path).
+ *
+ * @module @memberjunction/server/rest/mediaRange
+ */
+/** A parsed, validated `Range` request against a known total size. */
+export interface ParsedRange {
+    start: number;
+    end: number;
+}
+/**
+ * A parsed `Range` request WITHOUT a known total (streaming path). `end` is undefined
+ * for an open-ended `bytes=start-` request, matching `ByteRange`'s "omit End = EOF".
+ */
+export interface ParsedOpenRange {
+    start: number;
+    end?: number;
+}
+/**
+ * Parses a single-range `bytes=start-end` header WITHOUT a known total (streaming path).
+ * Returns the inclusive offsets, or undefined when the header is malformed/multi-range/
+ * suffix-only (those we leave to the driver as a full read). `end` is left undefined when
+ * open-ended (`bytes=start-`) so the driver streams to EOF.
+ */
+export declare function parseRangeHeaderLoose(rangeHeader: string): ParsedOpenRange | undefined;
+/**
+ * Parses a single-range `bytes=start-end` header against a known total (buffer path),
+ * clamping `end` to the last byte. Returns undefined when unsatisfiable (→ 416) or
+ * malformed/multi-range.
+ */
+export declare function parseRange(rangeHeader: string, total: number): ParsedRange | undefined;
+//# sourceMappingURL=mediaRange.d.ts.map

package/dist/rest/mediaRange.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaRange.d.ts","sourceRoot":"","sources":["../../src/rest/mediaRange.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAiBtF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAetF"}

package/dist/rest/mediaRange.js

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Pure HTTP `Range` header parsing for the `/media/:fileId` stream route.
+ *
+ * Split out of {@link module:@memberjunction/server/rest/MediaStreamHandler} (which pulls in
+ * auth/config/storage at module load) so this load-bearing parsing logic is unit-testable in
+ * isolation — same pattern as `peaksSidecar.ts`. These functions decide whether a request gets
+ * a 206 partial body (and over which byte window) vs. a full 200 / a 416.
+ *
+ * Both helpers are deliberately strict single-range parsers: anything malformed, multi-range,
+ * or suffix-only (`bytes=-N`) yields `undefined`, letting the caller fall back to a full read
+ * (streaming path) or a 416 (buffer path).
+ *
+ * @module @memberjunction/server/rest/mediaRange
+ */
+/**
+ * Parses a single-range `bytes=start-end` header WITHOUT a known total (streaming path).
+ * Returns the inclusive offsets, or undefined when the header is malformed/multi-range/
+ * suffix-only (those we leave to the driver as a full read). `end` is left undefined when
+ * open-ended (`bytes=start-`) so the driver streams to EOF.
+ */
+export function parseRangeHeaderLoose(rangeHeader) {
+    const match = /^bytes=(\d+)-(\d*)$/.exec(rangeHeader.trim());
+    if (!match) {
+        return undefined;
+    }
+    const start = Number(match[1]);
+    if (!Number.isFinite(start)) {
+        return undefined;
+    }
+    if (match[2] === '') {
+        return { start };
+    }
+    const end = Number(match[2]);
+    if (!Number.isFinite(end) || end < start) {
+        return undefined;
+    }
+    return { start, end };
+}
+/**
+ * Parses a single-range `bytes=start-end` header against a known total (buffer path),
+ * clamping `end` to the last byte. Returns undefined when unsatisfiable (→ 416) or
+ * malformed/multi-range.
+ */
+export function parseRange(rangeHeader, total) {
+    const match = /^bytes=(\d+)-(\d*)$/.exec(rangeHeader.trim());
+    if (!match) {
+        return undefined;
+    }
+    const start = Number(match[1]);
+    if (!Number.isFinite(start) || start >= total) {
+        return undefined; // start past EOF → unsatisfiable
+    }
+    const requestedEnd = match[2] === '' ? total - 1 : Number(match[2]);
+    const end = Math.min(requestedEnd, total - 1);
+    if (end < start) {
+        return undefined;
+    }
+    return { start, end };
+}
+//# sourceMappingURL=mediaRange.js.map

package/dist/rest/mediaRange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaRange.js","sourceRoot":"","sources":["../../src/rest/mediaRange.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiBH;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;QACzC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,WAAmB,EAAE,KAAa;IAC3D,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;QAC9C,OAAO,SAAS,CAAC,CAAC,iCAAiC;IACrD,CAAC;IACD,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC9C,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;QAChB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACxB,CAAC"}

package/dist/telephony/RingCentralTelephonyService.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Orchestrates RingCentral telephony bridge sessions (inbound + outbound) for MJAPI over the
+ * **SIP softphone** transport.
+ *
+ * RingCentral's only product that carries bidirectional call audio is a registered SIP softphone (the
+ * `ringcentral-softphone` SDK over SIP/TLS + RTP/SRTP) — its WebSocket "Call Streaming" product is
+ * receive-only and cannot inject the agent's voice. So unlike the Twilio/Vonage ingresses (public webhook
+ * + media WSS), this service owns a **long-lived SIP registration**: one
+ * {@link RingCentralSoftphoneHandle} created + registered at boot, shared across all calls. Inbound calls
+ * arrive as SIP INVITEs on that registration (no HTTP webhook); outbound calls place SIP calls through it.
+ *
+ * It does NOT re-implement bridge logic: it resolves the RingCentral provider + the agent identity, opens a
+ * server-side realtime session via the agent layer's `CreateBridgeRealtimeSession` factory, binds a
+ * {@link RingCentralSoftphoneCallSdk} (drawing its session from the shared handle) onto the driver, and
+ * hands everything to `AIBridgeEngine.StartBridgeSession` — the same seam the Twilio/Vonage services use.
+ *
+ * @module @memberjunction/server/telephony
+ */
+import { UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
+import { CreateBridgeRealtimeSession } from '@memberjunction/ai-agents';
+import { type BridgeNativeSdkBinding } from '@memberjunction/ai-bridge-base';
+import { createRingCentralSoftphone } from '@memberjunction/ai-bridge-ringcentral';
+import type { RingCentralTelephonyConfig } from '../config.js';
+import { SessionManager } from '../agentSessions/SessionManager.js';
+/** A resolved inbound call's identifying fields (mapped from a RingCentral SIP INVITE). */
+export interface InboundCallInput {
+    /** The SIP `Call-ID` (the per-call id the handle parked the INVITE under + the bridge's inbound id). */
+    sessionId: string;
+    /** The caller's number (the INVITE's `From`). */
+    from: string;
+    /** The dialed DID (the INVITE's `To`) — resolved to an agent identity. */
+    to: string;
+}
+/** Result of starting an inbound bridge session. */
+export interface InboundCallResult {
+    /** Whether a pinned agent was resolved + a bridge session started. */
+    accepted: boolean;
+    /** Why it was rejected (no agent identity for the DID, provider missing, etc.). */
+    reason?: string;
+}
+/** Injectable collaborators (production defaults wired in the constructor; fakes in tests). */
+export interface RingCentralTelephonyServiceDeps {
+    engine?: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    sessionFactory?: typeof CreateBridgeRealtimeSession;
+    sessionManager?: Pick<SessionManager, 'CreateSession'>;
+    /** Test seam: a factory that builds the softphone handle (inject a fake to avoid the real SIP SDK). */
+    createHandle?: typeof createRingCentralSoftphone;
+}
+/**
+ * Starts RingCentral bridge sessions over a shared SIP-softphone registration. One instance per server,
+ * constructed at boot and held by the runtime holder so the outbound `PlaceRingCentralCall` resolver and the
+ * inbound INVITE coordinator share the same registration.
+ */
+export declare class RingCentralTelephonyService {
+    private readonly config;
+    private readonly engine;
+    private readonly sessionFactory;
+    private readonly sessionManager;
+    private readonly createHandle;
+    /** The shared SIP registration — created + registered by {@link start}; null until then. */
+    private handle;
+    /** The carrier PCM16 rate for the negotiated codec (set in {@link start}). */
+    private carrierSampleRate;
+    constructor(config: RingCentralTelephonyConfig, deps?: RingCentralTelephonyServiceDeps);
+    /**
+     * Creates + registers the shared SIP softphone and wires inbound INVITE handling. Called once at boot
+     * (fire-and-forget so SIP registration never blocks server startup); logs success/failure. Inbound calls
+     * only flow once this resolves.
+     */
+    start(): Promise<void>;
+    /** Best-effort teardown of the SIP registration (server shutdown). */
+    dispose(): void;
+    /**
+     * Resolves the dialed DID to a pinned agent and starts an INBOUND bridge session. The bound
+     * {@link RingCentralSoftphoneCallSdk} answers the parked INVITE for `sessionId`. Returns
+     * `{ accepted:false }` (never throws) when no agent identity matches the DID, so the coordinator can
+     * decline the INVITE cleanly.
+     */
+    HandleInboundCall(input: InboundCallInput, contextUser: UserInfo, provider: IMetadataProvider): Promise<InboundCallResult>;
+    /**
+     * Places an OUTBOUND call from a given agent identity to a destination number. The bound
+     * {@link RingCentralSoftphoneCallSdk} places the SIP call through the shared registration; the returned
+     * SIP `Call-ID` is the bridge's external connection id.
+     *
+     * @returns The placed call's SIP `Call-ID`.
+     */
+    PlaceOutboundCall(agentIdentityId: string, toNumber: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<string>;
+    /** Inbound INVITE coordinator: resolve the server principal, start a bridge, decline if no agent matched. */
+    private onInboundInvite;
+    /** Shared inbound/outbound bridge-start: resolve provider, open the realtime session, bind the SDK, start. */
+    private startBridge;
+    /** Resolves the seeded RingCentral provider row (by driver class, falling back to display name). */
+    private resolveProvider;
+    /**
+     * Builds the per-session SDK binding that wires a {@link RingCentralSoftphoneCallSdk} (drawing its
+     * session from the shared SIP registration handle) onto the telephony driver — overriding the package's
+     * default unbound SDK. Reads the handle lazily at call time so a call placed during the brief boot window
+     * before registration fails loudly rather than binding a null handle.
+     */
+    buildBindSdk(): BridgeNativeSdkBinding;
+    /** Returns the live registration handle, or throws if the softphone hasn't registered yet. */
+    private requireHandle;
+    /** Assembles the per-session bridge configuration (direction / from-number / inbound-call-id / carrier rate). */
+    private buildSessionConfiguration;
+    /** Maps the server config block to the softphone SDK's SIP-device config (credentials resolved upstream). */
+    private toSoftphoneConfig;
+    /** Resolves the server-side principal + provider for an inbound call (no MJ JWT on a SIP INVITE). */
+    private resolveServerContext;
+    /** Finds the active agent identity whose phone number matches the dialed DID. */
+    private resolveAgentIdentityByPhone;
+    /** Loads a specific agent identity by id (used by outbound PlaceCall), requiring it be active. */
+    private loadAgentIdentity;
+}
+//# sourceMappingURL=RingCentralTelephonyService.d.ts.map

package/dist/telephony/RingCentralTelephonyService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RingCentralTelephonyService.d.ts","sourceRoot":"","sources":["../../src/telephony/RingCentralTelephonyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAW,QAAQ,EAAE,iBAAiB,EAAiC,MAAM,sBAAsB,CAAC;AAG3G,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,OAAO,EAEH,KAAK,sBAAsB,EAK9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACH,0BAA0B,EAK7B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAapE,2FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAC7B,wGAAwG;IACxG,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAC9B,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAC;IAClB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,+FAA+F;AAC/F,MAAM,WAAW,+BAA+B;IAC5C,MAAM,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,gBAAgB,GAAG,uBAAuB,GAAG,oBAAoB,GAAG,QAAQ,CAAC,CAAC;IAC5G,cAAc,CAAC,EAAE,OAAO,2BAA2B,CAAC;IACpD,cAAc,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;IACvD,uGAAuG;IACvG,YAAY,CAAC,EAAE,OAAO,0BAA0B,CAAC;CACpD;AAED;;;;GAIG;AACH,qBAAa,2BAA2B;IAahC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZ3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqG;IAC5H,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqC;IACpE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwC;IACvE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoC;IAEjE,4FAA4F;IAC5F,OAAO,CAAC,MAAM,CAA2C;IAEzD,8EAA8E;IAC9E,OAAO,CAAC,iBAAiB,CAA4C;gBAGhD,MAAM,EAAE,0BAA0B,EACnD,IAAI,GAAE,+BAAoC;IAQ9C;;;;OAIG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAanC,sEAAsE;IAC/D,OAAO,IAAI,IAAI;IAKtB;;;;;OAKG;IACU,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAqBvI;;;;;;OAMG;IACU,iBAAiB,CAAC,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB9I,6GAA6G;YAC/F,eAAe;IAc7B,8GAA8G;YAChG,WAAW;IAsCzB,oGAAoG;IACpG,OAAO,CAAC,eAAe;IAQvB;;;;;OAKG;IACI,YAAY,IAAI,sBAAsB;IAO7C,8FAA8F;IAC9F,OAAO,CAAC,aAAa;IAOrB,iHAAiH;IACjH,OAAO,CAAC,yBAAyB;IAiBjC,6GAA6G;IAC7G,OAAO,CAAC,iBAAiB;IAYzB,qGAAqG;IACrG,OAAO,CAAC,oBAAoB;IAS5B,iFAAiF;YACnE,2BAA2B;IAsBzC,kGAAkG;YACpF,iBAAiB;CASlC"}