@memberjunction/server 5.43.0 → 5.45.0

package/dist/telephony/vonageMediaRegistry.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Per-call WebSocket-media pump registry for the Vonage telephony ingress.
+ *
+ * This is the server half of the Vonage media plane: it implements the provider package's
+ * `IVonageMediaPump` seam (which `RealVonageBindings` drives) on top of the live bidirectional media
+ * websockets MJAPI accepts at `WSS /telephony/vonage/media`. It exists because of the same lifecycle
+ * gap the Twilio ingress has: when an INBOUND call's answer webhook fires, the bridge session starts and
+ * `RealVonageBindings` registers its inbound-audio handler — but Vonage has not yet opened the media
+ * websocket (it does so only AFTER the answer-webhook's `connect`-websocket NCCO response). The registry
+ * bridges that gap by buffering handler registrations + outbound frames per call UUID and binding them to
+ * the socket once it connects (matched on the call UUID Vonage forwards on the websocket handshake).
+ *
+ * Pure + unit-testable: the websocket is injected as the minimal {@link ITelephonyMediaSocket} surface,
+ * so the registry's buffering / dispatch logic is exercised with a fake socket and no `ws` install or
+ * network.
+ *
+ * @module @memberjunction/server/telephony
+ */
+/**
+ * The exact byte size of one outbound audio frame Vonage expects on the `audio/l16;rate=8000` leg: a
+ * 20 ms slice = 8000 Hz × 0.020 s = 160 samples × 2 bytes = **320 bytes**. The realtime model emits audio
+ * in arbitrary-size deltas; the bridge resamples each whole delta to 8 kHz, so the registry MUST re-slice
+ * into these fixed frames before sending. Handing Vonage one oversized blob per delta garbles playback and
+ * (worse) defeats barge-in: `{"action":"clear"}` can drop QUEUED frames but not a giant in-flight one.
+ */
+const OUTBOUND_FRAME_BYTES = 320;
+/**
+ * Coordinates Vonage media websockets with the bridge bindings, keyed by call UUID. One instance per
+ * server, shared between the inbound-webhook service (which binds `RealVonageBindings` over this as the
+ * `IVonageMediaPump`) and the WSS server (which attaches sockets + dispatches inbound audio/events).
+ *
+ * Models Vonage's wire split: outbound audio → binary frames; inbound binary frames → audio handlers;
+ * inbound JSON text frames → parsed {@link VonageControlEvent}s → event handlers. There is no base64
+ * envelope or μ-law transcode — that's the Twilio path, not Vonage's.
+ */
+export class VonageCallMediaRegistry {
+    constructor() {
+        this.channels = new Map();
+    }
+    /** Ensures a channel exists for a call (called when a bridge session for the call starts). */
+    RegisterCall(callUuid) {
+        this.ensureChannel(callUuid);
+    }
+    // ── IVonageMediaPump ─────────────────────────────────────────────────────────
+    /**
+     * @inheritdoc — re-slices the (already-8 kHz) delta into fixed 320-byte / 20 ms frames before sending,
+     * carrying any sub-frame remainder into the next delta so the stream stays continuous (no silence gaps).
+     * Each whole frame is sent immediately if the socket is live, else buffered for {@link AttachSocket}.
+     */
+    SendAudio(callUuid, pcm) {
+        const channel = this.ensureChannel(callUuid);
+        const incoming = new Uint8Array(pcm);
+        const data = channel.partial.length > 0 ? concatBytes(channel.partial, incoming) : incoming;
+        let offset = 0;
+        while (data.length - offset >= OUTBOUND_FRAME_BYTES) {
+            // `.slice` returns a fresh copy, so a buffered frame never retains the larger backing buffer.
+            const frame = data.slice(offset, offset + OUTBOUND_FRAME_BYTES);
+            offset += OUTBOUND_FRAME_BYTES;
+            if (channel.socket) {
+                channel.socket.sendBinary(frame);
+            }
+            else {
+                channel.outboundBuffer.push(frame);
+            }
+        }
+        channel.partial = offset < data.length ? data.slice(offset) : new Uint8Array(0);
+    }
+    /** @inheritdoc — stores the audio handler so frames delivered before AND after socket connect reach it. */
+    OnAudio(callUuid, handler) {
+        this.ensureChannel(callUuid).audioHandlers.push(handler);
+    }
+    /** @inheritdoc — stores the control-event handler (DTMF / connected / close). */
+    OnEvent(callUuid, handler) {
+        this.ensureChannel(callUuid).eventHandlers.push(handler);
+    }
+    /**
+     * @inheritdoc — barge-in flush: drop any outbound audio buffered locally (socket not yet connected) AND,
+     * if the socket is live, send Vonage's `{"action":"clear"}` text command to discard its playback queue.
+     * Safe to call for an unknown/uninitialized call (no-op).
+     */
+    Clear(callUuid) {
+        const channel = this.channels.get(callUuid);
+        if (!channel) {
+            return;
+        }
+        channel.outboundBuffer.length = 0;
+        channel.partial = new Uint8Array(0); // drop the half-built frame too, or it would prepend to the next turn
+        channel.socket?.sendText(JSON.stringify({ action: 'clear' }));
+    }
+    // ── WSS-server side ─────────────────────────────────────────────────────────
+    /**
+     * Binds a connected media socket to a call, flushing any outbound audio produced while the socket
+     * was still connecting. Called by the WSS server once it resolves the call UUID for the socket (from
+     * the `call_uuid` query param the answer NCCO embedded on the media URL).
+     */
+    AttachSocket(callUuid, socket) {
+        const channel = this.ensureChannel(callUuid);
+        channel.socket = socket;
+        const buffered = channel.outboundBuffer.splice(0, channel.outboundBuffer.length);
+        for (const frame of buffered) {
+            socket.sendBinary(frame);
+        }
+    }
+    /** Dispatches one inbound binary audio frame (raw L16 PCM) to all audio handlers for the call. */
+    DispatchInboundAudio(callUuid, pcm) {
+        const channel = this.channels.get(callUuid);
+        if (!channel) {
+            return;
+        }
+        for (const handler of channel.audioHandlers) {
+            handler(pcm);
+        }
+    }
+    /** Dispatches one inbound control event (parsed from a JSON text frame) to all event handlers for the call. */
+    DispatchInboundEvent(callUuid, event) {
+        const channel = this.channels.get(callUuid);
+        if (!channel) {
+            return;
+        }
+        for (const handler of channel.eventHandlers) {
+            handler(event);
+        }
+    }
+    /** Tears down a call's channel and closes its socket (called on socket close / call end). */
+    EndCall(callUuid) {
+        const channel = this.channels.get(callUuid);
+        if (!channel) {
+            return;
+        }
+        try {
+            channel.socket?.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        this.channels.delete(callUuid);
+    }
+    /** Whether a channel is currently tracked for the call (test/observability helper). */
+    HasCall(callUuid) {
+        return this.channels.has(callUuid);
+    }
+    ensureChannel(callUuid) {
+        let channel = this.channels.get(callUuid);
+        if (!channel) {
+            channel = { audioHandlers: [], eventHandlers: [], outboundBuffer: [], partial: new Uint8Array(0) };
+            this.channels.set(callUuid, channel);
+        }
+        return channel;
+    }
+}
+/** Concatenates two byte arrays into a fresh `Uint8Array` (the carry-over remainder + the next delta). */
+function concatBytes(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+//# sourceMappingURL=vonageMediaRegistry.js.map

package/dist/telephony/vonageMediaRegistry.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/server",
-  "version": "5.43.0",
+  "version": "5.45.0",
   "description": "MemberJunction: This project provides API access via GraphQL to the common data store.",
   "main": "./dist/index.js",
   "types": "./src/index.ts",
@@ -27,87 +27,93 @@
     "@as-integrations/express5": "^1.0.0",
     "@graphql-tools/schema": "latest",
     "@graphql-tools/utils": "^11.0.0",
-    "@memberjunction/actions": "5.43.0",
-    "@memberjunction/actions-apollo": "5.43.0",
-    "@memberjunction/actions-base": "5.43.0",
-    "@memberjunction/actions-bizapps-accounting": "5.43.0",
-    "@memberjunction/actions-bizapps-crm": "5.43.0",
-    "@memberjunction/actions-bizapps-formbuilders": "5.43.0",
-    "@memberjunction/actions-bizapps-lms": "5.43.0",
-    "@memberjunction/actions-bizapps-social": "5.43.0",
-    "@memberjunction/ai": "5.43.0",
-    "@memberjunction/ai-agent-manager": "5.43.0",
-    "@memberjunction/ai-agent-manager-actions": "5.43.0",
-    "@memberjunction/ai-agents": "5.43.0",
-    "@memberjunction/ai-bridge-server": "5.43.0",
-    "@memberjunction/ai-core-plus": "5.43.0",
-    "@memberjunction/ai-engine-base": "5.43.0",
-    "@memberjunction/ai-mcp-client": "5.43.0",
-    "@memberjunction/ai-prompts": "5.43.0",
-    "@memberjunction/ai-provider-bundle": "5.43.0",
-    "@memberjunction/ai-vector-sync": "5.43.0",
-    "@memberjunction/ai-vectordb": "5.43.0",
-    "@memberjunction/ai-vectors-pinecone": "5.43.0",
-    "@memberjunction/aiengine": "5.43.0",
-    "@memberjunction/api-keys": "5.43.0",
-    "@memberjunction/auth-providers": "5.43.0",
-    "@memberjunction/clustering-engine": "5.43.0",
-    "@memberjunction/codegen-lib": "5.43.0",
-    "@memberjunction/communication-engine": "5.43.0",
-    "@memberjunction/communication-ms-graph": "5.43.0",
-    "@memberjunction/notifications": "5.43.0",
-    "@memberjunction/communication-sendgrid": "5.43.0",
-    "@memberjunction/communication-types": "5.43.0",
-    "@memberjunction/component-registry-client-sdk": "5.43.0",
-    "@memberjunction/computer-use": "5.43.0",
-    "@memberjunction/computer-use-engine": "5.43.0",
-    "@memberjunction/config": "5.43.0",
-    "@memberjunction/core": "5.43.0",
-    "@memberjunction/core-actions": "5.43.0",
-    "@memberjunction/core-entities": "5.43.0",
-    "@memberjunction/core-entities-server": "5.43.0",
-    "@memberjunction/data-context": "5.43.0",
-    "@memberjunction/data-context-server": "5.43.0",
-    "@memberjunction/doc-utils": "5.43.0",
-    "@memberjunction/encryption": "5.43.0",
-    "@memberjunction/entity-communications-base": "5.43.0",
-    "@memberjunction/entity-communications-server": "5.43.0",
-    "@memberjunction/esignature": "5.43.0",
-    "@memberjunction/external-change-detection": "5.43.0",
-    "@memberjunction/generic-database-provider": "5.43.0",
-    "@memberjunction/global": "5.43.0",
-    "@memberjunction/graphql-dataprovider": "5.43.0",
-    "@memberjunction/integration-engine": "5.43.0",
-    "@memberjunction/integration-progress-artifacts": "5.43.0",
-    "@memberjunction/integration-schema-builder": "5.43.0",
-    "@memberjunction/interactive-component-types": "5.43.0",
-    "@memberjunction/lists": "5.43.0",
-    "@memberjunction/lists-base": "5.43.0",
-    "@memberjunction/livekit-room-server": "5.43.0",
-    "@memberjunction/postgresql-dataprovider": "5.43.0",
-    "@memberjunction/queue": "5.43.0",
-    "@memberjunction/redis-provider": "5.43.0",
-    "@memberjunction/remote-browser-base": "5.43.0",
-    "@memberjunction/remote-browser-cdp": "5.43.0",
-    "@memberjunction/remote-browser-selfhost": "5.43.0",
-    "@memberjunction/remote-browser-server": "5.43.0",
-    "@memberjunction/scheduling-actions": "5.43.0",
-    "@memberjunction/scheduling-base-types": "5.43.0",
-    "@memberjunction/scheduling-engine": "5.43.0",
-    "@memberjunction/scheduling-engine-base": "5.43.0",
-    "@memberjunction/schema-engine": "5.43.0",
-    "@memberjunction/search-engine": "5.43.0",
-    "@memberjunction/server-extensions-core": "5.43.0",
-    "@memberjunction/skip-types": "5.43.0",
-    "@memberjunction/sql-dialect": "5.43.0",
-    "@memberjunction/sqlserver-dataprovider": "5.43.0",
-    "@memberjunction/storage": "5.43.0",
-    "@memberjunction/tag-engine": "5.43.0",
-    "@memberjunction/tag-engine-base": "5.43.0",
-    "@memberjunction/templates": "5.43.0",
-    "@memberjunction/testing-engine": "5.43.0",
-    "@memberjunction/testing-engine-base": "5.43.0",
-    "@memberjunction/version-history": "5.43.0",
+    "@memberjunction/actions": "5.45.0",
+    "@memberjunction/actions-apollo": "5.45.0",
+    "@memberjunction/actions-base": "5.45.0",
+    "@memberjunction/actions-bizapps-accounting": "5.45.0",
+    "@memberjunction/actions-bizapps-crm": "5.45.0",
+    "@memberjunction/actions-bizapps-formbuilders": "5.45.0",
+    "@memberjunction/actions-bizapps-lms": "5.45.0",
+    "@memberjunction/actions-bizapps-social": "5.45.0",
+    "@memberjunction/ai": "5.45.0",
+    "@memberjunction/ai-agent-manager": "5.45.0",
+    "@memberjunction/ai-agent-manager-actions": "5.45.0",
+    "@memberjunction/ai-agents": "5.45.0",
+    "@memberjunction/ai-bridge-base": "5.45.0",
+    "@memberjunction/ai-bridge-ringcentral": "5.45.0",
+    "@memberjunction/ai-bridge-server": "5.45.0",
+    "@memberjunction/ai-bridge-teams": "5.45.0",
+    "@memberjunction/ai-bridge-twilio": "5.45.0",
+    "@memberjunction/ai-bridge-vonage": "5.45.0",
+    "@memberjunction/ai-core-plus": "5.45.0",
+    "@memberjunction/ai-engine-base": "5.45.0",
+    "@memberjunction/ai-mcp-client": "5.45.0",
+    "@memberjunction/ai-prompts": "5.45.0",
+    "@memberjunction/ai-provider-bundle": "5.45.0",
+    "@memberjunction/ai-vector-sync": "5.45.0",
+    "@memberjunction/ai-vectordb": "5.45.0",
+    "@memberjunction/ai-vectors-pinecone": "5.45.0",
+    "@memberjunction/aiengine": "5.45.0",
+    "@memberjunction/api-keys": "5.45.0",
+    "@memberjunction/auth-providers": "5.45.0",
+    "@memberjunction/clustering-engine": "5.45.0",
+    "@memberjunction/codegen-lib": "5.45.0",
+    "@memberjunction/communication-engine": "5.45.0",
+    "@memberjunction/communication-ms-graph": "5.45.0",
+    "@memberjunction/notifications": "5.45.0",
+    "@memberjunction/communication-sendgrid": "5.45.0",
+    "@memberjunction/communication-types": "5.45.0",
+    "@memberjunction/component-registry-client-sdk": "5.45.0",
+    "@memberjunction/computer-use": "5.45.0",
+    "@memberjunction/computer-use-engine": "5.45.0",
+    "@memberjunction/config": "5.45.0",
+    "@memberjunction/core": "5.45.0",
+    "@memberjunction/core-actions": "5.45.0",
+    "@memberjunction/core-entities": "5.45.0",
+    "@memberjunction/core-entities-server": "5.45.0",
+    "@memberjunction/credentials": "5.45.0",
+    "@memberjunction/data-context": "5.45.0",
+    "@memberjunction/data-context-server": "5.45.0",
+    "@memberjunction/doc-utils": "5.45.0",
+    "@memberjunction/encryption": "5.45.0",
+    "@memberjunction/entity-communications-base": "5.45.0",
+    "@memberjunction/entity-communications-server": "5.45.0",
+    "@memberjunction/esignature": "5.45.0",
+    "@memberjunction/external-change-detection": "5.45.0",
+    "@memberjunction/generic-database-provider": "5.45.0",
+    "@memberjunction/global": "5.45.0",
+    "@memberjunction/graphql-dataprovider": "5.45.0",
+    "@memberjunction/integration-engine": "5.45.0",
+    "@memberjunction/integration-progress-artifacts": "5.45.0",
+    "@memberjunction/integration-schema-builder": "5.45.0",
+    "@memberjunction/interactive-component-types": "5.45.0",
+    "@memberjunction/lists": "5.45.0",
+    "@memberjunction/lists-base": "5.45.0",
+    "@memberjunction/livekit-room-server": "5.45.0",
+    "@memberjunction/postgresql-dataprovider": "5.45.0",
+    "@memberjunction/queue": "5.45.0",
+    "@memberjunction/record-comparison": "5.45.0",
+    "@memberjunction/redis-provider": "5.45.0",
+    "@memberjunction/remote-browser-base": "5.45.0",
+    "@memberjunction/remote-browser-cdp": "5.45.0",
+    "@memberjunction/remote-browser-selfhost": "5.45.0",
+    "@memberjunction/remote-browser-server": "5.45.0",
+    "@memberjunction/scheduling-actions": "5.45.0",
+    "@memberjunction/scheduling-base-types": "5.45.0",
+    "@memberjunction/scheduling-engine": "5.45.0",
+    "@memberjunction/scheduling-engine-base": "5.45.0",
+    "@memberjunction/schema-engine": "5.45.0",
+    "@memberjunction/search-engine": "5.45.0",
+    "@memberjunction/server-extensions-core": "5.45.0",
+    "@memberjunction/sql-dialect": "5.45.0",
+    "@memberjunction/sqlserver-dataprovider": "5.45.0",
+    "@memberjunction/storage": "5.45.0",
+    "@memberjunction/tag-engine": "5.45.0",
+    "@memberjunction/tag-engine-base": "5.45.0",
+    "@memberjunction/templates": "5.45.0",
+    "@memberjunction/testing-engine": "5.45.0",
+    "@memberjunction/testing-engine-base": "5.45.0",
+    "@memberjunction/version-history": "5.45.0",
     "@octokit/auth-app": "^7.1.5",
     "@octokit/rest": "^21.1.1",
     "@types/compression": "^1.8.1",

package/src/__tests__/FileResolverPeaks.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { deriveSidecarPath, parsePeaksSidecar, MAX_PEAKS } from '../resolvers/peaksSidecar.js';
+
+/**
+ * Tests for the pure `peaks.json` sidecar helpers that back FileResolver.CreateMediaAccessToken's
+ * peaks pass-through. These cover the load-bearing behavior the mutation depends on:
+ *  - deriving the sidecar path that sits in the SAME folder as the recording, and
+ *  - parsing + sanitizing the sidecar so valid peaks come back and garbage / wrong-shape / missing
+ *    payloads gracefully yield `undefined` (the resolver treats that as "omit Peaks, never fail").
+ *
+ * The resolver wires these to a storage driver behind a try/catch; the helpers themselves never
+ * throw, which is what guarantees a sidecar problem can't block token minting.
+ */
+
+describe('deriveSidecarPath', () => {
+  it('replaces the final path segment with peaks.json (recording in a session folder)', () => {
+    expect(deriveSidecarPath('realtime-recordings/sess-1/recording.wav')).toBe('realtime-recordings/sess-1/peaks.json');
+  });
+
+  it('uses a bare peaks.json when the key has no folder', () => {
+    expect(deriveSidecarPath('recording.wav')).toBe('peaks.json');
+  });
+
+  it('returns null when there is no ProviderKey (cannot derive a folder)', () => {
+    expect(deriveSidecarPath(null)).toBeNull();
+    expect(deriveSidecarPath(undefined)).toBeNull();
+    expect(deriveSidecarPath('')).toBeNull();
+  });
+});
+
+describe('parsePeaksSidecar', () => {
+  it('returns sanitized peaks from a valid JSON array (clamped to 0..1)', () => {
+    const bytes = Buffer.from(JSON.stringify([0, 0.5, 1, 1.7, -0.3]), 'utf8');
+    expect(parsePeaksSidecar(bytes)).toEqual([0, 0.5, 1, 1, 0]);
+  });
+
+  it('returns undefined for non-JSON garbage (never throws)', () => {
+    expect(parsePeaksSidecar(Buffer.from('this is not json', 'utf8'))).toBeUndefined();
+  });
+
+  it('returns undefined when the JSON is not an array', () => {
+    expect(parsePeaksSidecar(Buffer.from(JSON.stringify({ not: 'an array' }), 'utf8'))).toBeUndefined();
+  });
+
+  it('returns undefined for an empty array', () => {
+    expect(parsePeaksSidecar(Buffer.from('[]', 'utf8'))).toBeUndefined();
+  });
+
+  it('drops non-finite / non-number entries, keeping the finite numbers', () => {
+    const bytes = Buffer.from(JSON.stringify([0.2, 'x', null, NaN, 0.8]), 'utf8');
+    // NaN serializes to null in JSON; both 'x' and the nulls are dropped, leaving the two numbers.
+    expect(parsePeaksSidecar(bytes)).toEqual([0.2, 0.8]);
+  });
+
+  it('returns undefined when nothing finite survives sanitization', () => {
+    expect(parsePeaksSidecar(Buffer.from(JSON.stringify(['a', 'b', null]), 'utf8'))).toBeUndefined();
+  });
+
+  it('caps the array length at MAX_PEAKS', () => {
+    const huge = new Array(MAX_PEAKS + 500).fill(0.5);
+    const result = parsePeaksSidecar(Buffer.from(JSON.stringify(huge), 'utf8'));
+    expect(result).toHaveLength(MAX_PEAKS);
+  });
+});

package/src/__tests__/MediaAccessKeys.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import jwt from 'jsonwebtoken';
+import { MediaAccessKeyManager, MEDIA_ACCESS_TOKEN_TYPE } from '../rest/MediaAccessKeys.js';
+
+/**
+ * The manager is a process-wide BaseSingleton whose secret is resolved lazily on first
+ * Sign/Verify. Tests share that single ephemeral secret (no MJ_BASE_ENCRYPTION_KEY in the
+ * test env), which is exactly what production does within one process.
+ */
+describe('MediaAccessKeyManager', () => {
+  it('signs a token that round-trips through Verify with the correct claims', () => {
+    const km = MediaAccessKeyManager.Instance;
+    const { Token, ExpiresAt } = km.Sign('FILE-1', 'USER-1');
+
+    expect(typeof Token).toBe('string');
+    expect(ExpiresAt.getTime()).toBeGreaterThan(Date.now());
+
+    const result = km.Verify(Token);
+    expect(result.Valid).toBe(true);
+    if (result.Valid) {
+      expect(result.Claims.fileId).toBe('FILE-1');
+      expect(result.Claims.userId).toBe('USER-1');
+      expect(result.Claims.typ).toBe(MEDIA_ACCESS_TOKEN_TYPE);
+    }
+  });
+
+  it('honors the requested TTL on ExpiresAt', () => {
+    const km = MediaAccessKeyManager.Instance;
+    const { ExpiresAt } = km.Sign('FILE-2', 'USER-2', 2); // 2 hours
+    const deltaMs = ExpiresAt.getTime() - Date.now();
+    // ~2h, allow a generous window for execution time.
+    expect(deltaMs).toBeGreaterThan(1.9 * 3600 * 1000);
+    expect(deltaMs).toBeLessThan(2.1 * 3600 * 1000);
+  });
+
+  it('rejects a tampered token', () => {
+    const km = MediaAccessKeyManager.Instance;
+    const { Token } = km.Sign('FILE-3', 'USER-3');
+    const tampered = Token.slice(0, -2) + (Token.slice(-2) === 'AA' ? 'BB' : 'AA');
+    expect(km.Verify(tampered).Valid).toBe(false);
+  });
+
+  it('rejects a malformed / empty token', () => {
+    const km = MediaAccessKeyManager.Instance;
+    expect(km.Verify('').Valid).toBe(false);
+    expect(km.Verify('not.a.jwt').Valid).toBe(false);
+  });
+
+  it('rejects an expired token', () => {
+    const km = MediaAccessKeyManager.Instance;
+    // Negative TTL → already expired when minted.
+    const { Token } = km.Sign('FILE-4', 'USER-4', -1);
+    expect(km.Verify(Token).Valid).toBe(false);
+  });
+
+  it('rejects a token with the wrong typ even if validly signed', () => {
+    const km = MediaAccessKeyManager.Instance;
+    // Mint a valid token, then read the real secret out of a known-good token by
+    // re-signing through the manager is not possible; instead assert that a token
+    // whose typ differs is rejected by signing a structurally-valid JWT with a
+    // foreign secret (signature failure also yields false, which is the safe outcome).
+    const foreign = jwt.sign({ fileId: 'FILE-5', userId: 'USER-5', typ: 'something-else' }, 'foreign-secret', {
+      algorithm: 'HS256',
+      expiresIn: 3600,
+    });
+    expect(km.Verify(foreign).Valid).toBe(false);
+  });
+});

package/src/__tests__/MediaStreamHandler.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest';
+import { parseRangeHeaderLoose, parseRange } from '../rest/mediaRange.js';
+
+/**
+ * Tests for the pure HTTP-Range parsing helpers behind the authenticated `/media/:fileId`
+ * stream route. They decide whether a request gets a 206 partial body (and over which byte
+ * window) or a 200/416 — the load-bearing logic for native `<audio>`/`<video>` seeking. Both
+ * helpers are deliberately strict: anything malformed/multi-range yields `undefined` so the
+ * handler falls back to a full read (streaming path) or a 416 (buffer path).
+ *
+ *  - `parseRangeHeaderLoose` — streaming path, NO known total: open-ended `bytes=start-` leaves
+ *    `end` undefined so the driver streams to EOF.
+ *  - `parseRange` — buffer path WITH a known total: clamps `end` to the last byte and rejects
+ *    unsatisfiable ranges (start past EOF) so the caller returns 416.
+ */
+
+describe('parseRangeHeaderLoose (streaming path — no known total)', () => {
+    it('parses a closed range bytes=start-end into inclusive offsets', () => {
+        expect(parseRangeHeaderLoose('bytes=0-499')).toEqual({ start: 0, end: 499 });
+        expect(parseRangeHeaderLoose('bytes=200-1023')).toEqual({ start: 200, end: 1023 });
+    });
+
+    it('leaves end undefined for an open-ended range bytes=start- (stream to EOF)', () => {
+        expect(parseRangeHeaderLoose('bytes=500-')).toEqual({ start: 500 });
+        expect(parseRangeHeaderLoose('bytes=0-')).toEqual({ start: 0 });
+    });
+
+    it('tolerates surrounding whitespace', () => {
+        expect(parseRangeHeaderLoose('  bytes=10-20  ')).toEqual({ start: 10, end: 20 });
+    });
+
+    it('returns undefined when end < start (nonsensical range)', () => {
+        expect(parseRangeHeaderLoose('bytes=500-100')).toBeUndefined();
+    });
+
+    it('returns undefined for malformed / multi-range / suffix-only headers', () => {
+        expect(parseRangeHeaderLoose('bytes=abc-def')).toBeUndefined();
+        expect(parseRangeHeaderLoose('bytes=-500')).toBeUndefined(); // suffix range — left to a full read
+        expect(parseRangeHeaderLoose('bytes=0-100,200-300')).toBeUndefined(); // multi-range
+        expect(parseRangeHeaderLoose('items=0-100')).toBeUndefined(); // wrong unit
+        expect(parseRangeHeaderLoose('bytes=')).toBeUndefined();
+        expect(parseRangeHeaderLoose('')).toBeUndefined();
+    });
+
+    it('accepts a zero-length point range bytes=N-N', () => {
+        expect(parseRangeHeaderLoose('bytes=42-42')).toEqual({ start: 42, end: 42 });
+    });
+});
+
+describe('parseRange (buffer path — known total)', () => {
+    const TOTAL = 1000;
+
+    it('parses a closed range within bounds', () => {
+        expect(parseRange('bytes=0-499', TOTAL)).toEqual({ start: 0, end: 499 });
+    });
+
+    it('clamps end to the last byte when the requested end exceeds total', () => {
+        // bytes=500-99999 against a 1000-byte file → end clamps to 999.
+        expect(parseRange('bytes=500-99999', TOTAL)).toEqual({ start: 500, end: 999 });
+    });
+
+    it('resolves an open-ended range to the last byte', () => {
+        expect(parseRange('bytes=200-', TOTAL)).toEqual({ start: 200, end: 999 });
+    });
+
+    it('returns undefined when start is at or past EOF (unsatisfiable → 416)', () => {
+        expect(parseRange('bytes=1000-1100', TOTAL)).toBeUndefined(); // start === total
+        expect(parseRange('bytes=2000-', TOTAL)).toBeUndefined(); // start > total
+    });
+
+    it('returns undefined when end < start after parsing', () => {
+        expect(parseRange('bytes=600-100', TOTAL)).toBeUndefined();
+    });
+
+    it('returns undefined for malformed / multi-range / suffix-only headers', () => {
+        expect(parseRange('bytes=abc-', TOTAL)).toBeUndefined();
+        expect(parseRange('bytes=-200', TOTAL)).toBeUndefined();
+        expect(parseRange('bytes=0-100,200-300', TOTAL)).toBeUndefined();
+        expect(parseRange('items=0-100', TOTAL)).toBeUndefined();
+        expect(parseRange('', TOTAL)).toBeUndefined();
+    });
+
+    it('handles the very first byte and the very last byte exactly', () => {
+        expect(parseRange('bytes=0-0', TOTAL)).toEqual({ start: 0, end: 0 });
+        expect(parseRange('bytes=999-999', TOTAL)).toEqual({ start: 999, end: 999 });
+    });
+
+    it('tolerates surrounding whitespace', () => {
+        expect(parseRange('  bytes=10-20  ', TOTAL)).toEqual({ start: 10, end: 20 });
+    });
+});

package/src/__tests__/RealtimeBridgeResolver.test.ts

@@ -33,6 +33,13 @@ vi.mock('@memberjunction/ai-agents', () => ({
   CreateBridgeRoomTranscriptSink: vi.fn(),
 }));
 
+// Mock the meeting-recording registration so the thin resolver is tested in isolation (no MJStorage /
+// core-entities graph). Its own behavior is covered by meetingRecordingRegistration.test.ts.
+vi.mock('../resolvers/meetingRecordingRegistration', () => ({
+  registerMeetingRecordingFile: vi.fn(async () => ({ Success: true, RecordingFileID: 'file-1', ConversationID: 'conv-1' })),
+  correlateRecordingStart: vi.fn(async () => true),
+}));
+
 import { RealtimeBridgeResolver, MintLiveKitClientTokenInput, LiveKitRecordingInput } from '../resolvers/RealtimeBridgeResolver';
 import type { AppContext } from '../types.js';
 
@@ -83,10 +90,12 @@ describe('RealtimeBridgeResolver', () => {
       expect(result.Status).toBe('EGRESS_ACTIVE');
     });
 
-    it('stops a recording and maps the result', async () => {
+    it('stops a recording, registers the MP4, and returns the RecordingFileID', async () => {
       const result = await resolver.StopLiveKitRecording('eg-1', ctx);
       expect(result.Success).toBe(true);
       expect(result.Status).toBe('EGRESS_COMPLETE');
+      // The registration mock returns a file id, which the resolver surfaces on the result.
+      expect(result.RecordingFileID).toBe('file-1');
     });
 
     it('requires an authenticated user to record', async () => {