@memberjunction/server 5.43.0 → 5.45.0

package/dist/resolvers/meetingRecordingRegistration.js

@@ -0,0 +1,311 @@
+/**
+ * @fileoverview Meeting-Room recording registration — the server-side path that closes the LiveKit
+ * meeting-room recording loop. After a room's composite egress completes, this module:
+ *
+ *  1. Resolves the **Meeting-Room Conversation** for the room (prefer by `EgressID`, fall back to the
+ *     room name → `ExternalID` + `Type='Meeting Room'`, else create one via the sink's pattern).
+ *  2. Resolves the **meeting-recording storage account** — a configured `MJStorage` account that points
+ *     at the same sink LiveKit egress wrote the MP4 to, so MJ can read/stream it.
+ *  3. Creates the `MJ: Files` row for the recording (v1 points DIRECTLY at the egress output — no byte
+ *     copy — so playback streams straight from the sink). An OPTIONAL copy-to-canonical path (OFF by
+ *     default, behind config) reads the bytes and re-uploads into a separate canonical provider.
+ *  4. Stamps `Conversation.RecordingFileID` (+ `EgressID`) and saves.
+ *
+ * Lives in `@memberjunction/server` (the one package that depends on the egress service, MJStorage, and
+ * core-entities). It is invoked from `RealtimeBridgeResolver.StopLiveKitRecording`. Everything is
+ * best-effort: any failure returns a non-throwing failure result and logs — a recording that fails to
+ * register never crashes the stop-recording mutation.
+ *
+ * ## Required configuration
+ *
+ * The egress sink and the MJStorage account must point at the **same** bucket/container so MJ can read the
+ * file LiveKit wrote. Configure the **provider** whose accounts target that sink via either:
+ *
+ *   - env: `MJ_MEETING_RECORDING_STORAGE_PROVIDER=<MJ: File Storage Providers ID>`
+ *   - config (`mj.config.cjs`): `meetingRecordingStorageProviderID: '<provider id>'`
+ *
+ * When unset, registration returns a clear, non-throwing failure explaining the config is required (the
+ * recording still stopped; it just isn't registered as a `MJ: Files` row).
+ *
+ * ### Optional copy-to-canonical ("copy into Box")
+ *
+ * To copy the MP4 OUT of the egress sink into a separate canonical provider (e.g. Box) instead of pointing
+ * the Files row at the sink, set a DIFFERENT provider via:
+ *
+ *   - env: `MJ_MEETING_RECORDING_CANONICAL_STORAGE_PROVIDER=<provider id>`
+ *   - config: `meetingRecordingCanonicalStorageProviderID: '<provider id>'`
+ *
+ * When set and different from the sink provider, the bytes are read from the sink and uploaded into the
+ * canonical provider, and the Files row points there. OFF by default.
+ *
+ * @module @memberjunction/server
+ * @author MemberJunction.com
+ */
+import { RunView, LogError, LogStatus } from '@memberjunction/core';
+import { FileStorageEngine } from '@memberjunction/storage';
+const CONVERSATION_ENTITY = 'MJ: Conversations';
+const FILES_ENTITY = 'MJ: Files';
+const MEETING_ROOM_CONVERSATION_TYPE = 'Meeting Room';
+/**
+ * Registers a completed meeting recording: resolves the Meeting-Room Conversation, creates the `MJ: Files`
+ * row for the egress MP4, and stamps `Conversation.RecordingFileID` (+ `EgressID`). Best-effort — never
+ * throws; returns a failure result with a clear message instead.
+ *
+ * @param egress The completed egress result (must carry an `OutputLocation`).
+ * @param contextUser The authenticated user (for DB writes + credential access).
+ * @param provider The metadata provider servicing this request.
+ * @param config Optional config overrides (otherwise read from env).
+ */
+export async function registerMeetingRecordingFile(egress, contextUser, provider, config) {
+    try {
+        if (!egress.OutputLocation) {
+            return {
+                Success: false,
+                ErrorMessage: 'The recording has no output yet (egress still in progress) — nothing to register. ' + 'Register only after the egress has stopped/completed.',
+            };
+        }
+        const sinkProviderID = config?.sinkStorageProviderID ?? process.env.MJ_MEETING_RECORDING_STORAGE_PROVIDER;
+        if (!sinkProviderID) {
+            return {
+                Success: false,
+                ErrorMessage: 'No meeting-recording storage provider is configured. Set MJ_MEETING_RECORDING_STORAGE_PROVIDER ' +
+                    '(or meetingRecordingStorageProviderID in mj.config.cjs) to the MJ: File Storage Providers id ' +
+                    'whose accounts target the same sink LiveKit egress writes to.',
+            };
+        }
+        await FileStorageEngine.Instance.Config(false, contextUser, provider);
+        const sinkAccountID = resolveStorageAccountForProvider(sinkProviderID);
+        if (!sinkAccountID) {
+            return {
+                Success: false,
+                ErrorMessage: `No active MJStorage account is linked to the configured meeting-recording provider '${sinkProviderID}'. ` +
+                    'Create a File Storage Account for that provider pointing at the egress sink bucket/container.',
+            };
+        }
+        const conversationID = await resolveMeetingConversation(egress, contextUser, provider);
+        if (!conversationID) {
+            return { Success: false, ErrorMessage: 'Could not resolve or create the Meeting-Room Conversation for the recording.' };
+        }
+        // v1: point the Files row directly at the egress output in the sink account (no byte copy). The
+        // OPTIONAL copy-to-canonical path overrides both the provider+key when a differing canonical
+        // provider is configured.
+        const fileLocation = await resolveFileLocation(egress, sinkProviderID, sinkAccountID, contextUser, config);
+        if (!fileLocation.Success) {
+            return { Success: false, ErrorMessage: fileLocation.ErrorMessage, ConversationID: conversationID };
+        }
+        const fileID = await createRecordingFileRow(egress, fileLocation.ProviderID, fileLocation.ProviderKey, contextUser, provider);
+        if (!fileID) {
+            return { Success: false, ErrorMessage: 'Failed to create the MJ: Files row for the recording.', ConversationID: conversationID };
+        }
+        const stamped = await stampConversationRecording(conversationID, fileID, egress.EgressID, contextUser, provider);
+        if (!stamped) {
+            return {
+                Success: false,
+                ErrorMessage: 'Created the recording file but failed to stamp it onto the Conversation.',
+                ConversationID: conversationID,
+                RecordingFileID: fileID,
+            };
+        }
+        LogStatus(`registerMeetingRecordingFile: registered recording ${fileID} for room '${egress.RoomName}' on conversation ${conversationID}.`);
+        return { Success: true, RecordingFileID: fileID, ConversationID: conversationID };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        LogError(`registerMeetingRecordingFile failed: ${msg}`);
+        return { Success: false, ErrorMessage: msg };
+    }
+}
+/**
+ * Best-effort correlation when a recording STARTS: stamps `Conversation.EgressID` onto the room's
+ * Meeting-Room Conversation (if it already exists) so a live recording is tracked against the room. If the
+ * conversation doesn't exist yet, this resolves to `false` silently — the stop-flow will resolve/create it.
+ * Never throws.
+ *
+ * @param roomName The LiveKit room name (= the Conversation's `ExternalID`).
+ * @param egressID The egress id that just started.
+ * @param contextUser The authenticated user.
+ * @param provider The metadata provider.
+ * @returns `true` when an existing conversation was stamped, else `false`.
+ */
+export async function correlateRecordingStart(roomName, egressID, contextUser, provider) {
+    try {
+        const conversationID = await findConversationByRoomName(roomName, contextUser, provider);
+        if (!conversationID) {
+            return false; // not created yet — stop-flow resolves/creates it
+        }
+        const conversation = await provider.GetEntityObject(CONVERSATION_ENTITY, contextUser);
+        if (!(await conversation.Load(conversationID))) {
+            return false;
+        }
+        conversation.EgressID = egressID;
+        if (await conversation.Save()) {
+            return true;
+        }
+        LogError(`correlateRecordingStart: failed to stamp EgressID: ${conversation.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        return false;
+    }
+    catch (error) {
+        // Never fail the recording start on correlation.
+        LogError(`correlateRecordingStart (best-effort) failed: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+/**
+ * Resolves the Meeting-Room Conversation for a completed recording: prefer matching by `EgressID` (set on
+ * start), fall back to the room name (`ExternalID` + `Type`), else create one following the transcript
+ * sink's pattern (scoped `Application` so it stays out of the normal chat list).
+ */
+export async function resolveMeetingConversation(egress, contextUser, provider) {
+    const byEgress = await findConversationByEgressID(egress.EgressID, contextUser, provider);
+    if (byEgress) {
+        return byEgress;
+    }
+    const byRoom = await findConversationByRoomName(egress.RoomName, contextUser, provider);
+    if (byRoom) {
+        return byRoom;
+    }
+    return createMeetingConversation(egress.RoomName, contextUser, provider);
+}
+/** Finds a non-archived Meeting-Room Conversation by its `EgressID`. */
+async function findConversationByEgressID(egressID, contextUser, provider) {
+    if (!egressID) {
+        return null;
+    }
+    const rv = RunView.FromMetadataProvider(provider);
+    const found = await rv.RunView({
+        EntityName: CONVERSATION_ENTITY,
+        ExtraFilter: `EgressID='${escapeSql(egressID)}' AND Type='${escapeSql(MEETING_ROOM_CONVERSATION_TYPE)}' AND (IsArchived IS NULL OR IsArchived=0)`,
+        Fields: ['ID'],
+        OrderBy: '__mj_CreatedAt DESC',
+        MaxRows: 1,
+        ResultType: 'simple',
+    }, contextUser);
+    return found.Success && found.Results.length > 0 ? found.Results[0].ID : null;
+}
+/** Finds a non-archived Meeting-Room Conversation by room name (`ExternalID` + `Type`). */
+async function findConversationByRoomName(roomName, contextUser, provider) {
+    if (!roomName) {
+        return null;
+    }
+    const rv = RunView.FromMetadataProvider(provider);
+    const found = await rv.RunView({
+        EntityName: CONVERSATION_ENTITY,
+        ExtraFilter: `ExternalID='${escapeSql(roomName)}' AND Type='${escapeSql(MEETING_ROOM_CONVERSATION_TYPE)}' AND (IsArchived IS NULL OR IsArchived=0)`,
+        Fields: ['ID'],
+        OrderBy: '__mj_CreatedAt DESC',
+        MaxRows: 1,
+        ResultType: 'simple',
+    }, contextUser);
+    return found.Success && found.Results.length > 0 ? found.Results[0].ID : null;
+}
+/** Creates a Meeting-Room Conversation for a room (scoped `Application`, keyed by room name) — mirrors the transcript sink. */
+async function createMeetingConversation(roomName, contextUser, provider) {
+    const conversation = await provider.GetEntityObject(CONVERSATION_ENTITY, contextUser);
+    conversation.NewRecord();
+    conversation.UserID = contextUser.ID;
+    conversation.Name = `Meeting Room ${roomName}`;
+    conversation.Type = MEETING_ROOM_CONVERSATION_TYPE;
+    conversation.ExternalID = roomName;
+    conversation.ApplicationScope = 'Application';
+    if (await conversation.Save()) {
+        return conversation.ID;
+    }
+    LogError(`registerMeetingRecordingFile: failed to create Meeting-Room conversation for room '${roomName}': ${conversation.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    return null;
+}
+/**
+ * Resolves the `(ProviderID, ProviderKey)` the Files row should point at. v1 default: the egress output in
+ * the sink provider (no copy). When a DIFFERING canonical provider is configured, copies the bytes into it
+ * and points there instead.
+ */
+async function resolveFileLocation(egress, sinkProviderID, sinkAccountID, contextUser, config) {
+    const outputLocation = egress.OutputLocation;
+    const canonicalProviderID = config?.canonicalStorageProviderID ?? process.env.MJ_MEETING_RECORDING_CANONICAL_STORAGE_PROVIDER;
+    // Default (v1): point directly at the sink output — playback streams straight from it, no byte copy.
+    if (!canonicalProviderID || canonicalProviderID === sinkProviderID) {
+        return { Success: true, ProviderID: sinkProviderID, ProviderKey: outputLocation };
+    }
+    // OPTIONAL "copy into Box": a separate canonical provider IS configured and differs from the sink —
+    // read the bytes from the sink and upload them into the canonical provider, then point there.
+    const canonicalKey = await copyEgressOutputToCanonical(outputLocation, sinkAccountID, canonicalProviderID, contextUser);
+    if (!canonicalKey.Success) {
+        return { Success: false, ErrorMessage: canonicalKey.ErrorMessage, ProviderID: '', ProviderKey: '' };
+    }
+    return { Success: true, ProviderID: canonicalProviderID, ProviderKey: canonicalKey.ProviderKey };
+}
+/**
+ * OPTIONAL — copies the egress MP4 OUT of the sink account into a configured canonical provider (the "copy
+ * into Box" option). Reads the bytes via the sink driver's `GetObject({ fullPath })` and re-uploads them
+ * into the canonical provider via `FileStorageEngine.UploadFile`. Returns the canonical `ProviderKey`.
+ */
+export async function copyEgressOutputToCanonical(outputLocation, sinkAccountID, canonicalProviderID, contextUser) {
+    const engine = FileStorageEngine.Instance;
+    const canonicalAccountID = resolveStorageAccountForProvider(canonicalProviderID);
+    if (!canonicalAccountID) {
+        return {
+            Success: false,
+            ErrorMessage: `No active MJStorage account is linked to the configured canonical provider '${canonicalProviderID}'.`,
+            ProviderKey: '',
+        };
+    }
+    const sinkDriver = await engine.GetDriver(sinkAccountID, contextUser);
+    const bytes = await sinkDriver.GetObject({ fullPath: outputLocation });
+    const fileName = outputLocation.split('/').pop() || `recording-${Date.now()}.mp4`;
+    const uploaded = await engine.UploadFile({
+        content: bytes,
+        fileName,
+        mimeType: 'video/mp4',
+        contextUser,
+        storageAccountId: canonicalAccountID,
+        pathPrefix: `meeting-recordings/${new Date().toISOString().slice(0, 10)}`,
+    });
+    return { Success: true, ProviderKey: uploaded.StoragePath };
+}
+/** Creates the `MJ: Files` row pointing at the recording (no byte copy in the default v1 path). */
+async function createRecordingFileRow(egress, providerID, providerKey, contextUser, provider) {
+    const file = await provider.GetEntityObject(FILES_ENTITY, contextUser);
+    file.NewRecord();
+    file.Name = `Meeting Recording — ${egress.RoomName} — ${new Date().toISOString().slice(0, 10)}`;
+    file.ContentType = 'video/mp4';
+    file.ProviderID = providerID;
+    file.ProviderKey = providerKey;
+    file.Status = 'Uploaded';
+    // NOTE: `MJ: Files` has no size column, so `egress.OutputSizeBytes` is not persisted here (it is logged
+    // and used by the player's range-streaming on demand). If a size column is added, set it here.
+    if (await file.Save()) {
+        return file.ID;
+    }
+    LogError(`registerMeetingRecordingFile: failed to save MJ: Files row: ${file.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    return null;
+}
+/** Loads the Conversation and stamps `RecordingFileID` (+ `EgressID` if unset), then saves. */
+async function stampConversationRecording(conversationID, fileID, egressID, contextUser, provider) {
+    const conversation = await provider.GetEntityObject(CONVERSATION_ENTITY, contextUser);
+    if (!(await conversation.Load(conversationID))) {
+        LogError(`registerMeetingRecordingFile: could not load conversation ${conversationID} to stamp the recording.`);
+        return false;
+    }
+    conversation.RecordingFileID = fileID;
+    if (!conversation.EgressID) {
+        conversation.EgressID = egressID;
+    }
+    if (await conversation.Save()) {
+        return true;
+    }
+    LogError(`registerMeetingRecordingFile: failed to stamp the Conversation: ${conversation.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    return false;
+}
+/**
+ * Resolves an MJStorage account linked to a provider id (the first one). `IsActive` lives on the
+ * *provider*, not the account, so provider-level inactivity is handled upstream by the engine's driver
+ * cache; here we just pick the provider's account.
+ */
+function resolveStorageAccountForProvider(providerID) {
+    const accounts = FileStorageEngine.Instance.GetAccountsByProviderID(providerID);
+    return accounts.length > 0 ? accounts[0].ID : null;
+}
+/** Escapes single quotes for safe embedding in an `ExtraFilter` literal. */
+function escapeSql(value) {
+    return value.replace(/'/g, "''");
+}
+//# sourceMappingURL=meetingRecordingRegistration.js.map

package/dist/resolvers/meetingRecordingRegistration.js.map

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

package/dist/resolvers/peaksSidecar.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Pure helpers for the `peaks.json` waveform sidecar that rides alongside a stored
+ * recording. Kept free of type-graphql / resolver / DB dependencies so they can be unit-tested in
+ * isolation (the resolver class itself can't be imported under vitest without standing up the full
+ * decorated schema). {@link FileResolver.tryReadPeaksSidecar} composes these with a storage driver.
+ *
+ * @module @memberjunction/server/resolvers/peaksSidecar
+ */
+/**
+ * Derives the `peaks.json` sidecar path that sits in the SAME folder as a file's `ProviderKey`:
+ * the final path segment of `providerKey` is replaced with `peaks.json`. Returns `null` when
+ * `providerKey` is empty (no folder to derive from).
+ *
+ * @example deriveSidecarPath('realtime-recordings/sess-1/recording.wav') === 'realtime-recordings/sess-1/peaks.json'
+ * @example deriveSidecarPath('recording.wav') === 'peaks.json'
+ */
+export declare function deriveSidecarPath(providerKey: string | null | undefined): string | null;
+/** Generous ceiling on the number of peaks returned — matches the capture-side cap. */
+export declare const MAX_PEAKS = 4096;
+/**
+ * Parses + sanitizes a `peaks.json` payload (UTF-8 bytes). The content must be a JSON array of
+ * finite numbers; each value is clamped to `[0, 1]` and the array is capped at {@link MAX_PEAKS}
+ * entries so a malformed/hostile sidecar can't bloat the response. Returns `undefined` for anything
+ * that isn't a non-empty array of finite numbers, and NEVER throws (a parse error → `undefined`).
+ *
+ * @param bytes The raw sidecar bytes (e.g. from a storage `GetObject`).
+ * @returns Sanitized `0..1` peaks, or `undefined`.
+ */
+export declare function parsePeaksSidecar(bytes: Buffer): number[] | undefined;
+//# sourceMappingURL=peaksSidecar.d.ts.map

package/dist/resolvers/peaksSidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peaksSidecar.d.ts","sourceRoot":"","sources":["../../src/resolvers/peaksSidecar.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMvF;AAED,uFAAuF;AACvF,eAAO,MAAM,SAAS,OAAO,CAAC;AAE9B;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAcrE"}

package/dist/resolvers/peaksSidecar.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Pure helpers for the `peaks.json` waveform sidecar that rides alongside a stored
+ * recording. Kept free of type-graphql / resolver / DB dependencies so they can be unit-tested in
+ * isolation (the resolver class itself can't be imported under vitest without standing up the full
+ * decorated schema). {@link FileResolver.tryReadPeaksSidecar} composes these with a storage driver.
+ *
+ * @module @memberjunction/server/resolvers/peaksSidecar
+ */
+/**
+ * Derives the `peaks.json` sidecar path that sits in the SAME folder as a file's `ProviderKey`:
+ * the final path segment of `providerKey` is replaced with `peaks.json`. Returns `null` when
+ * `providerKey` is empty (no folder to derive from).
+ *
+ * @example deriveSidecarPath('realtime-recordings/sess-1/recording.wav') === 'realtime-recordings/sess-1/peaks.json'
+ * @example deriveSidecarPath('recording.wav') === 'peaks.json'
+ */
+export function deriveSidecarPath(providerKey) {
+    if (!providerKey) {
+        return null;
+    }
+    const lastSlash = providerKey.lastIndexOf('/');
+    return lastSlash >= 0 ? `${providerKey.slice(0, lastSlash)}/peaks.json` : 'peaks.json';
+}
+/** Generous ceiling on the number of peaks returned — matches the capture-side cap. */
+export const MAX_PEAKS = 4096;
+/**
+ * Parses + sanitizes a `peaks.json` payload (UTF-8 bytes). The content must be a JSON array of
+ * finite numbers; each value is clamped to `[0, 1]` and the array is capped at {@link MAX_PEAKS}
+ * entries so a malformed/hostile sidecar can't bloat the response. Returns `undefined` for anything
+ * that isn't a non-empty array of finite numbers, and NEVER throws (a parse error → `undefined`).
+ *
+ * @param bytes The raw sidecar bytes (e.g. from a storage `GetObject`).
+ * @returns Sanitized `0..1` peaks, or `undefined`.
+ */
+export function parsePeaksSidecar(bytes) {
+    try {
+        const parsed = JSON.parse(bytes.toString('utf8'));
+        if (!Array.isArray(parsed) || parsed.length === 0) {
+            return undefined;
+        }
+        const cleaned = parsed
+            .slice(0, MAX_PEAKS)
+            .filter((v) => typeof v === 'number' && Number.isFinite(v))
+            .map((v) => (v < 0 ? 0 : v > 1 ? 1 : v));
+        return cleaned.length > 0 ? cleaned : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=peaksSidecar.js.map

package/dist/resolvers/peaksSidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peaksSidecar.js","sourceRoot":"","sources":["../../src/resolvers/peaksSidecar.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAsC;IACpE,IAAI,CAAC,WAAW,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/C,OAAO,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC;AAC3F,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAC;AAE9B;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC3C,IAAI,CAAC;QACD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,MAAM,OAAO,GAAG,MAAM;aACjB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC;aACnB,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;aACvE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,SAAS,CAAC;IACrB,CAAC;AACL,CAAC"}

package/dist/rest/MediaAccessKeys.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Short-lived HS256 token manager for authenticated media streaming.
+ *
+ * Media-access tokens are minted by the `CreateMediaAccessToken` GraphQL mutation
+ * (after a per-user permission check on the `MJ: Files` row) and verified by the
+ * `/media/:fileId` streaming route. The token IS the capability: access is checked
+ * once at mint time, and the route trusts a valid, unexpired, file-matching token.
+ *
+ * This is intentionally a SEPARATE, self-contained mechanism from the magic-link
+ * RS256 manager: media streaming must work on EVERY deployment, whereas the
+ * magic-link keypair is only initialized when `magicLink.enabled` is configured.
+ * We sign HS256 with the deployment's symmetric secret (`MJ_BASE_ENCRYPTION_KEY`),
+ * falling back to an ephemeral per-process secret (with a warning) when unset —
+ * the same degradation MagicLinkKeyManager uses for its ephemeral keypair.
+ *
+ * @module @memberjunction/server/rest/MediaAccessKeys
+ */
+import { BaseSingleton } from '@memberjunction/global';
+/** The token's `typ` claim — the route rejects any token whose `typ` differs. */
+export declare const MEDIA_ACCESS_TOKEN_TYPE = "media-access";
+/** Default media-access token lifetime (hours). Long enough to cover a full playback session. */
+export declare const MEDIA_ACCESS_DEFAULT_TTL_HOURS = 4;
+/** The claims carried by a media-access token. */
+export interface MediaAccessTokenClaims {
+    /** The `MJ: Files` id this token grants streaming access to. */
+    fileId: string;
+    /** The id of the user the token was minted for (audit/forensics only — access was already checked). */
+    userId: string;
+    /** Discriminator — always {@link MEDIA_ACCESS_TOKEN_TYPE}. */
+    typ: typeof MEDIA_ACCESS_TOKEN_TYPE;
+}
+/** Outcome of verifying a media-access token. */
+export type MediaTokenVerifyResult = {
+    Valid: true;
+    Claims: MediaAccessTokenClaims;
+} | {
+    Valid: false;
+};
+/**
+ * Signs and verifies short-lived HS256 media-access tokens. Singleton so the
+ * signing secret is stable for the process lifetime. The secret is resolved
+ * lazily on first use from `MJ_BASE_ENCRYPTION_KEY`; if unset, an ephemeral
+ * 32-byte secret is generated (outstanding tokens die on restart — acceptable
+ * for a 4h-TTL streaming credential).
+ */
+export declare class MediaAccessKeyManager extends BaseSingleton<MediaAccessKeyManager> {
+    private secret;
+    private _initialized;
+    constructor();
+    static get Instance(): MediaAccessKeyManager;
+    /** Resolves the signing secret once, preferring the deployment's symmetric key. */
+    private ensureSecret;
+    /**
+     * Mints a signed media-access token for a file + user, expiring after `ttlHours`.
+     *
+     * @returns `{ Token, ExpiresAt }` — the compact JWT and its absolute expiry.
+     */
+    Sign(fileId: string, userId: string, ttlHours?: number): {
+        Token: string;
+        ExpiresAt: Date;
+    };
+    /**
+     * Verifies a token's signature, expiry, and `typ`. Returns the typed claims on
+     * success. Never throws — an invalid/expired/malformed token returns `{ Valid: false }`.
+     */
+    Verify(token: string): MediaTokenVerifyResult;
+}
+//# sourceMappingURL=MediaAccessKeys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MediaAccessKeys.d.ts","sourceRoot":"","sources":["../../src/rest/MediaAccessKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAKvD,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD,iGAAiG;AACjG,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,kDAAkD;AAClD,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,uGAAuG;IACvG,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,GAAG,EAAE,OAAO,uBAAuB,CAAC;CACrC;AAED,iDAAiD;AACjD,MAAM,MAAM,sBAAsB,GAC9B;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAA;CAAE,GAC/C;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAErB;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,aAAa,CAAC,qBAAqB,CAAC;IAC7E,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,YAAY,CAAS;;IAO7B,WAAkB,QAAQ,IAAI,qBAAqB,CAElD;IAED,mFAAmF;IACnF,OAAO,CAAC,YAAY;IAkBpB;;;;OAIG;IACI,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAuC,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,IAAI,CAAA;KAAE;IASlI;;;OAGG;IACI,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,sBAAsB;CAmBrD"}

package/dist/rest/MediaAccessKeys.js

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Short-lived HS256 token manager for authenticated media streaming.
+ *
+ * Media-access tokens are minted by the `CreateMediaAccessToken` GraphQL mutation
+ * (after a per-user permission check on the `MJ: Files` row) and verified by the
+ * `/media/:fileId` streaming route. The token IS the capability: access is checked
+ * once at mint time, and the route trusts a valid, unexpired, file-matching token.
+ *
+ * This is intentionally a SEPARATE, self-contained mechanism from the magic-link
+ * RS256 manager: media streaming must work on EVERY deployment, whereas the
+ * magic-link keypair is only initialized when `magicLink.enabled` is configured.
+ * We sign HS256 with the deployment's symmetric secret (`MJ_BASE_ENCRYPTION_KEY`),
+ * falling back to an ephemeral per-process secret (with a warning) when unset —
+ * the same degradation MagicLinkKeyManager uses for its ephemeral keypair.
+ *
+ * @module @memberjunction/server/rest/MediaAccessKeys
+ */
+import { BaseSingleton } from '@memberjunction/global';
+import { LogStatus } from '@memberjunction/core';
+import { randomBytes } from 'node:crypto';
+import jwt from 'jsonwebtoken';
+/** The token's `typ` claim — the route rejects any token whose `typ` differs. */
+export const MEDIA_ACCESS_TOKEN_TYPE = 'media-access';
+/** Default media-access token lifetime (hours). Long enough to cover a full playback session. */
+export const MEDIA_ACCESS_DEFAULT_TTL_HOURS = 4;
+/**
+ * Signs and verifies short-lived HS256 media-access tokens. Singleton so the
+ * signing secret is stable for the process lifetime. The secret is resolved
+ * lazily on first use from `MJ_BASE_ENCRYPTION_KEY`; if unset, an ephemeral
+ * 32-byte secret is generated (outstanding tokens die on restart — acceptable
+ * for a 4h-TTL streaming credential).
+ */
+export class MediaAccessKeyManager extends BaseSingleton {
+    // Public to satisfy BaseSingleton.getInstance's `this: new () => T` constraint.
+    constructor() {
+        super();
+        this.secret = '';
+        this._initialized = false;
+    }
+    static get Instance() {
+        return MediaAccessKeyManager.getInstance();
+    }
+    /** Resolves the signing secret once, preferring the deployment's symmetric key. */
+    ensureSecret() {
+        if (this._initialized) {
+            return;
+        }
+        const configured = process.env.MJ_BASE_ENCRYPTION_KEY?.trim();
+        if (configured) {
+            this.secret = configured;
+        }
+        else {
+            this.secret = randomBytes(32).toString('base64');
+            LogStatus('[MediaAccess] No MJ_BASE_ENCRYPTION_KEY configured — generated an EPHEMERAL HS256 secret for ' +
+                'media-access tokens. Outstanding media URLs will be invalidated on restart. Set ' +
+                'MJ_BASE_ENCRYPTION_KEY for stable signing.');
+        }
+        this._initialized = true;
+    }
+    /**
+     * Mints a signed media-access token for a file + user, expiring after `ttlHours`.
+     *
+     * @returns `{ Token, ExpiresAt }` — the compact JWT and its absolute expiry.
+     */
+    Sign(fileId, userId, ttlHours = MEDIA_ACCESS_DEFAULT_TTL_HOURS) {
+        this.ensureSecret();
+        const claims = { fileId, userId, typ: MEDIA_ACCESS_TOKEN_TYPE };
+        const expiresInSeconds = Math.floor(ttlHours * 3600);
+        const token = jwt.sign(claims, this.secret, { algorithm: 'HS256', expiresIn: expiresInSeconds });
+        const expiresAt = new Date(Date.now() + expiresInSeconds * 1000);
+        return { Token: token, ExpiresAt: expiresAt };
+    }
+    /**
+     * Verifies a token's signature, expiry, and `typ`. Returns the typed claims on
+     * success. Never throws — an invalid/expired/malformed token returns `{ Valid: false }`.
+     */
+    Verify(token) {
+        this.ensureSecret();
+        try {
+            const decoded = jwt.verify(token, this.secret, { algorithms: ['HS256'] });
+            if (typeof decoded === 'object' && decoded !== null &&
+                decoded.typ === MEDIA_ACCESS_TOKEN_TYPE &&
+                typeof decoded.fileId === 'string' &&
+                typeof decoded.userId === 'string') {
+                const d = decoded;
+                return { Valid: true, Claims: { fileId: d.fileId, userId: d.userId, typ: MEDIA_ACCESS_TOKEN_TYPE } };
+            }
+            return { Valid: false };
+        }
+        catch {
+            // Signature mismatch, expiry, or malformed token — all map to "not valid".
+            return { Valid: false };
+        }
+    }
+}
+//# sourceMappingURL=MediaAccessKeys.js.map

package/dist/rest/MediaAccessKeys.js.map

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

package/dist/rest/MediaStreamHandler.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @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 { type Router } from 'express';
+/**
+ * Builds the Express router exposing `GET /media/:fileId`. Stateless — verification
+ * and byte-source resolution happen per request.
+ */
+export declare function createMediaStreamRouter(): Router;
+//# sourceMappingURL=MediaStreamHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MediaStreamHandler.d.ts","sourceRoot":"","sources":["../../src/rest/MediaStreamHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAgB,EAAE,KAAK,MAAM,EAA+B,MAAM,SAAS,CAAC;AAiB5E;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAMhD"}