@memberjunction/server 5.44.0 → 5.45.1

package/src/telephony/TeamsMeetingsRouter.ts

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Express wiring for the Teams meetings ingress — the Microsoft Graph change-notification webhook.
+ *
+ * One public surface (Graph cannot present an MJ JWT — the subscription validation-token handshake + the
+ * per-notification `clientState` shared secret are the gate):
+ *   - `POST /meetings/teams/notifications` — the Graph change-notification endpoint. Handles BOTH:
+ *       1. The **subscription-validation handshake**: when Graph creates/renews a subscription it calls this
+ *          URL with `?validationToken=…` and expects the exact token echoed back as `text/plain` 200.
+ *       2. **Real call/participant notifications**: each carries a `clientState` verified (constant-time)
+ *          against the secret set on subscription creation, then mapped to the meetings service's roster /
+ *          call-ended drive helpers.
+ *
+ * Mirrors the Twilio telephony public-router pattern: mount the router BEFORE the unified auth middleware. The
+ * validation + notification parsing use the offline-complete, unit-tested helpers from the Teams provider
+ * package (`validateGraphNotification` / `parseCallNotification`); this module is thin HTTP plumbing over them
+ * and the {@link TeamsMeetingsService}.
+ *
+ * The ACS application-hosted-media socket(s) (the audio plane) are owned by the server's native ACS media
+ * adapter, which attaches transports to the shared {@link TeamsAcsMediaRegistry} — there is no media WSS here
+ * (unlike Twilio Media Streams), because ACS app-hosted media is negotiated out-of-band by that adapter.
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import { Router, json, type Request, type Response } from 'express';
+import { LogError, LogStatus } from '@memberjunction/core';
+import {
+    validateGraphNotification,
+    parseCallNotification,
+    type GraphChangeNotification,
+} from '@memberjunction/ai-bridge-teams';
+import type { TeamsMeetingsConfig } from '../config.js';
+import { TeamsAcsMediaRegistry } from './teamsAcsMediaRegistry.js';
+import { TeamsMeetingsService } from './TeamsMeetingsService.js';
+
+/** The mount path for the Teams meetings public router. */
+export const TEAMS_MEETINGS_MOUNT_PATH = '/meetings/teams';
+
+/** The minimal shape of a Graph change-notification POST body (the `value[]` batch). */
+interface GraphNotificationBatch {
+    value?: GraphChangeNotification[];
+}
+
+/**
+ * Builds the Teams meetings handler: the public Graph change-notification router + the shared ACS media
+ * registry + the meetings service (returned for observability/tests + so server boot can bind the service to
+ * the runtime holder and hand the registry to the native ACS media adapter).
+ */
+export function createTeamsMeetingsHandler(
+    config: TeamsMeetingsConfig,
+): {
+    publicRouter: Router;
+    registry: TeamsAcsMediaRegistry;
+    service: TeamsMeetingsService;
+} {
+    const registry = new TeamsAcsMediaRegistry(config.acsSampleRate);
+    const service = new TeamsMeetingsService(config, registry);
+    const publicRouter = Router();
+
+    // Graph posts JSON; it also issues the validation handshake as a query-param GET-like POST. Parse JSON but
+    // tolerate an empty body on the handshake.
+    publicRouter.post('/notifications', json({ type: () => true }), (req: Request, res: Response) => {
+        handleGraphNotification(service, config, req, res);
+    });
+
+    return { publicRouter, registry, service };
+}
+
+/** Handles the Graph webhook: echo the validation token, else verify clientState + drive the service. */
+function handleGraphNotification(
+    service: TeamsMeetingsService,
+    config: TeamsMeetingsConfig,
+    req: Request,
+    res: Response,
+): void {
+    const validationToken = readValidationToken(req);
+    const batch = (req.body ?? {}) as GraphNotificationBatch;
+    const notifications = Array.isArray(batch.value) ? batch.value : [];
+    const clientStates = notifications.map((n) => n.clientState);
+
+    const verdict = validateGraphNotification(validationToken, config.notificationClientState ?? '', clientStates);
+    if (verdict.Kind === 'validation') {
+        // The subscription-validation handshake: echo the token verbatim as text/plain 200.
+        res.status(200).type('text/plain').send(verdict.ValidationToken);
+        return;
+    }
+    if (verdict.Kind === 'reject') {
+        LogStatus(`[Meetings][Teams] notification rejected: ${verdict.Reason}`);
+        res.status(verdict.Reason === 'empty-validation-token' ? 400 : 403).type('text/plain').send('Rejected.');
+        return;
+    }
+
+    dispatchNotifications(service, notifications);
+    // Graph requires a fast 202 to acknowledge receipt; processing is fire-and-forget.
+    res.status(202).end();
+}
+
+/** Maps each Graph call/participant notification to the meetings service's roster / call-ended drive helpers. */
+function dispatchNotifications(service: TeamsMeetingsService, notifications: GraphChangeNotification[]): void {
+    for (const notification of notifications) {
+        try {
+            const normalized = parseCallNotification(notification);
+            if (normalized.state === 'terminated') {
+                service.DriveCallEnded(normalized.callId);
+            } else if (normalized.participants.length > 0) {
+                service.DriveParticipantsUpdated(normalized.callId, normalized.participants);
+            }
+        } catch (e) {
+            LogError(`[Meetings][Teams] failed to process notification: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+}
+
+/** Reads the `?validationToken=…` query param (Graph URL-encodes it), when present. */
+function readValidationToken(req: Request): string | undefined {
+    const raw = req.query?.validationToken;
+    if (typeof raw === 'string') {
+        return raw;
+    }
+    if (Array.isArray(raw) && typeof raw[0] === 'string') {
+        return raw[0];
+    }
+    return undefined;
+}

package/src/telephony/TeamsMeetingsService.ts

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview Orchestrates Teams meeting bridge sessions (join-by-URL) for MJAPI.
+ *
+ * This is the composition layer between the Teams meetings ingress (the public Graph change-notification
+ * webhook + the server-owned ACS media plane) and the ONE unified realtime-agent pathway. It does NOT
+ * re-implement any bridge logic: it resolves the Teams provider + the agent identity, opens a server-side
+ * realtime session via the agent layer's `CreateBridgeRealtimeSession` factory, binds the REAL Teams binding
+ * (`RealTeamsBindings` over the Graph control plane + the per-call ACS media registry) onto the driver, and
+ * hands everything to `AIBridgeEngine.StartBridgeSession` — exactly the seam the Twilio telephony service +
+ * the LiveKit room coordinator use.
+ *
+ * Collaborators are injected (engine, session factory, session manager) so the resolution/branching logic is
+ * unit-testable with fakes; the actual Graph call placement + ACS media flow are live-only (real Teams/Azure
+ * credentials + a publicly reachable Graph webhook URL — see meeting-vendor-bindings-teams-slack.md M1).
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import { RunView, UserInfo, IMetadataProvider, LogError } from '@memberjunction/core';
+import type { MJAIBridgeAgentIdentityEntity, MJAIBridgeProviderEntity } from '@memberjunction/core-entities';
+import { AIBridgeEngine, type StartBridgeSessionParams } from '@memberjunction/ai-bridge-server';
+import { CreateBridgeRealtimeSession } from '@memberjunction/ai-agents';
+import { BaseRealtimeBridge, type BridgeNativeSdkBinding } from '@memberjunction/ai-bridge-base';
+import { RealTeamsBindings, RealGraphCallsClient, PumpBackedAcsMedia, type TeamsBridge } from '@memberjunction/ai-bridge-teams';
+import type { TeamsMeetingsConfig } from '../config.js';
+import { SessionManager } from '../agentSessions/SessionManager.js';
+import { TeamsAcsMediaRegistry } from './teamsAcsMediaRegistry.js';
+
+const TEAMS_PROVIDER_DRIVER = 'TeamsBridge';
+const AGENT_IDENTITY_ENTITY = 'MJ: AI Bridge Agent Identities';
+
+/** Result of starting a Teams meeting bridge session. */
+export interface JoinMeetingResult {
+    /** Whether a bridge session was started for the meeting. */
+    accepted: boolean;
+    /** The Graph call id the bot joined (the bridge's external connection id), when accepted. */
+    callId?: string;
+    /** Why it was rejected (no agent identity, provider missing, unparseable join URL, etc.). */
+    reason?: string;
+}
+
+/** Injectable collaborators (production defaults wired in the constructor; fakes in tests). */
+export interface TeamsMeetingsServiceDeps {
+    engine?: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    sessionFactory?: typeof CreateBridgeRealtimeSession;
+    sessionManager?: Pick<SessionManager, 'CreateSession'>;
+    /** Constructs the Graph control-plane client for a session (default: the real lazy-SDK client). */
+    graphClientFactory?: (accessToken: string, tenantId?: string) => RealGraphCallsClient;
+}
+
+/**
+ * Starts Teams meeting bridge sessions. One instance per server, constructed alongside the meetings router and
+ * sharing the {@link TeamsAcsMediaRegistry} with the server's ACS media adapter.
+ */
+export class TeamsMeetingsService {
+    private readonly engine: Pick<AIBridgeEngine, 'ProviderByName' | 'ProviderByDriverClass' | 'StartBridgeSession' | 'Config'>;
+    private readonly sessionFactory: typeof CreateBridgeRealtimeSession;
+    private readonly sessionManager: Pick<SessionManager, 'CreateSession'>;
+    private readonly graphClientFactory: (accessToken: string, tenantId?: string) => RealGraphCallsClient;
+    /** Live Graph clients keyed by call id, so the webhook ingress can drive their roster/ended handlers. */
+    private readonly graphClientsByCall = new Map<string, RealGraphCallsClient>();
+
+    constructor(
+        private readonly config: TeamsMeetingsConfig,
+        private readonly registry: TeamsAcsMediaRegistry,
+        deps: TeamsMeetingsServiceDeps = {},
+    ) {
+        this.engine = deps.engine ?? AIBridgeEngine.Instance;
+        this.sessionFactory = deps.sessionFactory ?? CreateBridgeRealtimeSession;
+        this.sessionManager = deps.sessionManager ?? new SessionManager();
+        this.graphClientFactory =
+            deps.graphClientFactory ?? ((accessToken, tenantId) => new RealGraphCallsClient({ AccessToken: accessToken, TenantId: tenantId }));
+    }
+
+    /**
+     * Joins a Teams meeting by URL for a given agent identity and starts the bridge session. The bound
+     * `RealTeamsBindings` issues the Graph `POST /communications/calls` and accepts the ACS media transport
+     * (attached by the server's media adapter) for the joined call. Returns `{ accepted:false }` (never
+     * throws) when the agent identity is missing/inactive, so the caller can answer cleanly.
+     *
+     * @param agentIdentityId The agent identity to join as (its Teams account/email is the bot's identity).
+     * @param joinUrl The Teams meeting join URL.
+     * @param contextUser The request-scoped principal.
+     * @param provider The request-scoped metadata provider (multi-provider safe — never the global Metadata).
+     */
+    public async JoinMeetingByUrl(
+        agentIdentityId: string,
+        joinUrl: string,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<JoinMeetingResult> {
+        try {
+            const identity = await this.loadAgentIdentity(agentIdentityId, contextUser, provider);
+            if (!identity) {
+                return { accepted: false, reason: `Agent identity '${agentIdentityId}' not found or inactive.` };
+            }
+            const session = await this.startBridge({ agentID: identity.AgentID, joinUrl, contextUser, provider });
+            return { accepted: true, callId: session.CallId };
+        } catch (e) {
+            LogError(`[Meetings][Teams] join meeting failed: ${e instanceof Error ? e.message : String(e)}`);
+            return { accepted: false, reason: e instanceof Error ? e.message : 'Internal error starting the agent.' };
+        }
+    }
+
+    /**
+     * Drives the retained Graph roster handler for a call from a Graph change notification (called by the
+     * webhook ingress — Graph delivers roster changes over the webhook, not a client subscription).
+     */
+    public DriveParticipantsUpdated(callId: string, participants: { id: string; displayName?: string; role?: string }[]): void {
+        this.graphClientsByCall.get(callId)?.DriveParticipantsUpdated(callId, participants);
+    }
+
+    /** Drives the call-ended handler for a call from a Graph change notification, then tears the call down. */
+    public DriveCallEnded(callId: string): void {
+        this.graphClientsByCall.get(callId)?.DriveCallEnded(callId);
+        this.graphClientsByCall.delete(callId);
+        this.registry.EndCall(callId);
+    }
+
+    /**
+     * Builds the {@link StartBridgeSessionParams} for a SCHEDULED Teams join — a bridge the
+     * {@link ScheduledBridgeRunner} owns (it created the `MJ: AI Agent Sessions` row and owns the
+     * `StartBridgeSession` call). Reuses the same provider resolution, realtime-session factory, Graph
+     * client, and bind-sdk as an on-demand join, so a scheduled Teams join is identical to a live one
+     * for audio (the ACS media registry is wired via {@link buildBindSdk}).
+     *
+     * NOTE: an on-demand join also registers the live Graph client by call id for webhook-driven
+     * roster/ended routing; the runner abstracts the post-start call id away, so for a SCHEDULED join
+     * that notification routing is a documented follow-on. Audio is fully wired here.
+     */
+    public async BuildScheduledStartParams(args: {
+        agentID: string;
+        joinUrl: string;
+        agentSessionID: string;
+        contextUser: UserInfo;
+        provider: IMetadataProvider;
+    }): Promise<StartBridgeSessionParams> {
+        await this.engine.Config(false, args.contextUser, args.provider);
+        const teamsProvider = this.resolveProvider();
+        const realtimeSession = await this.sessionFactory({
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+            AgentSessionID: args.agentSessionID,
+            RoomName: args.joinUrl,
+        });
+        const graphClient = this.graphClientFactory(this.config.botAccessToken ?? '', this.config.tenantId);
+        return {
+            AgentSessionID: args.agentSessionID,
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            Provider: teamsProvider,
+            RealtimeSession: realtimeSession,
+            Address: args.joinUrl,
+            Direction: 'Outbound',
+            Configuration: this.buildSessionConfiguration(),
+            BindSdk: this.buildBindSdk(graphClient),
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+        };
+    }
+
+    // ── internals ────────────────────────────────────────────────────────────────
+
+    /** Resolves provider, opens the realtime session, binds the real Teams SDK, and starts the bridge. */
+    private async startBridge(args: {
+        agentID: string;
+        joinUrl: string;
+        contextUser: UserInfo;
+        provider: IMetadataProvider;
+    }): Promise<{ CallId?: string }> {
+        await this.engine.Config(false, args.contextUser, args.provider);
+        const teamsProvider = this.resolveProvider();
+
+        const agentSession = await this.sessionManager.CreateSession(
+            { agentID: args.agentID, userID: args.contextUser.ID },
+            args.contextUser,
+            args.provider,
+        );
+        const realtimeSession = await this.sessionFactory({
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+            AgentSessionID: agentSession.ID,
+            RoomName: args.joinUrl,
+        });
+
+        // The Graph client is created per session; its retained webhook handlers are driven by the ingress.
+        const graphClient = this.graphClientFactory(this.config.botAccessToken ?? '', this.config.tenantId);
+
+        const active = await this.engine.StartBridgeSession({
+            AgentSessionID: agentSession.ID,
+            AgentID: args.agentID,
+            TargetAgentID: args.agentID,
+            Provider: teamsProvider,
+            RealtimeSession: realtimeSession,
+            Address: args.joinUrl,
+            Direction: 'Outbound',
+            Configuration: this.buildSessionConfiguration(),
+            BindSdk: this.buildBindSdk(graphClient),
+            ContextUser: args.contextUser,
+            MetadataProvider: args.provider,
+        });
+
+        const callId = active.RoomKey;
+        if (callId) {
+            this.registry.RegisterCall(callId);
+            this.graphClientsByCall.set(callId, graphClient);
+        }
+        return { CallId: callId };
+    }
+
+    /** Resolves the seeded Teams provider row (by driver class, falling back to display name). */
+    private resolveProvider(): MJAIBridgeProviderEntity {
+        const provider = this.engine.ProviderByDriverClass(TEAMS_PROVIDER_DRIVER) ?? this.engine.ProviderByName('Microsoft Teams');
+        if (!provider) {
+            throw new Error(`No active 'MJ: AI Bridge Providers' row for the Teams bridge (DriverClass '${TEAMS_PROVIDER_DRIVER}').`);
+        }
+        return provider;
+    }
+
+    /**
+     * Builds the per-session SDK binding that wires the REAL Teams binding (`RealTeamsBindings` over the Graph
+     * control plane + the per-call ACS media registry) onto the Teams driver — overriding the package's default
+     * native loader. This is where the offline-complete seams meet the live Graph + ACS plumbing.
+     */
+    public buildBindSdk(graphClient: RealGraphCallsClient): BridgeNativeSdkBinding {
+        return (driver: BaseRealtimeBridge) => {
+            const teams = driver as TeamsBridge;
+            // RealTeamsBindings threads the Graph call id through every media call, so PumpBackedAcsMedia
+            // routes onto the shared registry keyed by that id — no call id needed at construction.
+            teams.SetSdkFactory(
+                () =>
+                    new RealTeamsBindings({
+                        Graph: graphClient,
+                        Media: new PumpBackedAcsMedia(this.registry),
+                        ModelSampleRate: this.config.modelSampleRate,
+                    }),
+            );
+        };
+    }
+
+    /** Assembles the per-session bridge configuration (carries the resolved tenant for diagnostics). */
+    private buildSessionConfiguration(): Record<string, unknown> {
+        const config: Record<string, unknown> = {};
+        if (this.config.tenantId) {
+            config.TenantId = this.config.tenantId;
+        }
+        return config;
+    }
+
+    /** Loads a specific agent identity by id (used by join-by-URL), requiring it be active. */
+    private async loadAgentIdentity(
+        agentIdentityId: string,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<MJAIBridgeAgentIdentityEntity | null> {
+        // Use the request-scoped provider (multi-provider safe), not the global Metadata.
+        const entity = await provider.GetEntityObject<MJAIBridgeAgentIdentityEntity>(AGENT_IDENTITY_ENTITY, contextUser);
+        const loaded = await entity.Load(agentIdentityId);
+        if (!loaded || !entity.IsActive) {
+            return null;
+        }
+        return entity;
+    }
+}

package/src/telephony/TwilioTelephonyRouter.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Express + WSS wiring for the Twilio telephony ingress.
+ *
+ * Two public surfaces (carriers cannot present an MJ JWT — the X-Twilio-Signature HMAC is the gate):
+ *   - `POST /telephony/twilio/voice`  — inbound voice webhook. Verifies the signature, resolves the
+ *     dialed DID to a pinned agent, starts an inbound bridge session, and answers with the
+ *     `<Connect><Stream>` TwiML that opens the Media-Streams socket.
+ *   - `WSS /telephony/twilio/media`   — the bidirectional Media-Streams socket. Frames are routed to the
+ *     active call's `RealTwilioBindings` via the shared {@link TwilioCallMediaRegistry}.
+ *
+ * Mirrors the magic-link / widget public-router pattern: mount the router BEFORE the unified auth
+ * middleware and attach the WSS to the shared HTTP server at startup. The signature-verification gate +
+ * inbound resolution use the offline-complete, unit-tested helpers from the Twilio provider package; this
+ * module is thin HTTP/WS plumbing over them and the {@link TwilioTelephonyService}.
+ *
+ * @module @memberjunction/server/telephony
+ */
+
+import { Router, urlencoded, type Request, type Response } from 'express';
+import { WebSocketServer, type WebSocket } from 'ws';
+import { RegisterMediaUpgradeRoute } from './media-upgrade-router.js';
+import { LogError, LogStatus, UserInfo, IMetadataProvider, Metadata } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+import {
+    verifyTwilioSignature,
+    resolveInboundCall,
+    buildInboundVoiceTwiML,
+    type TwilioMediaFrame,
+} from '@memberjunction/ai-bridge-twilio';
+import type { TwilioTelephonyConfig } from '../config.js';
+import { TwilioCallMediaRegistry } from './twilioMediaRegistry.js';
+import { TwilioTelephonyService } from './TwilioTelephonyService.js';
+
+/** The mount path for the Twilio telephony public router. */
+export const TWILIO_TELEPHONY_MOUNT_PATH = '/telephony/twilio';
+
+/** The Media-Streams websocket path Twilio's `<Connect><Stream>` connects to. */
+export const TWILIO_MEDIA_WSS_PATH = '/telephony/twilio/media';
+
+/** A polite TwiML response played when no agent is available for the dialed number. */
+const NO_AGENT_TWIML =
+    '<?xml version="1.0" encoding="UTF-8"?><Response><Say>Sorry, no agent is available to take this call.</Say><Hangup/></Response>';
+
+/** The minimal shape of a Twilio Media-Streams websocket message (a superset of TwilioMediaFrame). */
+interface TwilioWsMessage extends TwilioMediaFrame {
+    /** Present on the `start` frame: carries the Call SID + stream SID that key the call's media channel. */
+    start?: { callSid?: string; streamSid?: string };
+}
+
+/**
+ * Builds the Twilio telephony handler: the public webhook router + a function to attach the
+ * Media-Streams WSS to the shared HTTP server. Returns the registry + service for observability/tests.
+ */
+export function createTwilioTelephonyHandler(
+    publicUrl: string,
+    config: TwilioTelephonyConfig,
+): {
+    publicRouter: Router;
+    attachMediaStreamServer: () => void;
+    registry: TwilioCallMediaRegistry;
+    service: TwilioTelephonyService;
+} {
+    const registry = new TwilioCallMediaRegistry();
+    const service = new TwilioTelephonyService(config, registry);
+    const publicRouter = Router();
+
+    // Twilio signs the form-urlencoded webhook body; parse it so we can both verify + resolve.
+    publicRouter.post('/voice', urlencoded({ extended: false }), async (req: Request, res: Response) => {
+        await handleInboundVoice(service, config, publicUrl, req, res);
+    });
+
+    return {
+        publicRouter,
+        attachMediaStreamServer: () => attachMediaStreamServer(registry),
+        registry,
+        service,
+    };
+}
+
+/** Handles the inbound voice webhook: verify signature → resolve → start bridge → answer with stream TwiML. */
+async function handleInboundVoice(
+    service: TwilioTelephonyService,
+    config: TwilioTelephonyConfig,
+    publicUrl: string,
+    req: Request,
+    res: Response,
+): Promise<void> {
+    const params = coerceParams(req.body);
+    const fullUrl = `${publicUrl.replace(/\/+$/, '')}${req.originalUrl}`;
+    if (!config.authToken || !verifyTwilioSignature(config.authToken, req.get('X-Twilio-Signature'), fullUrl, params)) {
+        res.status(403).type('text/plain').send('Invalid Twilio signature.');
+        return;
+    }
+
+    const { callSid, from, to } = resolveInboundCall(params);
+    const context = resolveServerContext();
+    if (!context) {
+        LogError('[Telephony][Twilio] no server context user available; cannot start inbound call.');
+        res.status(200).type('text/xml').send(NO_AGENT_TWIML);
+        return;
+    }
+
+    const result = await service.HandleInboundCall({ callSid, from, to }, context.user, context.provider);
+    if (!result.accepted) {
+        LogStatus(`[Telephony][Twilio] inbound ${callSid} not accepted: ${result.reason ?? 'unknown'}`);
+        res.status(200).type('text/xml').send(NO_AGENT_TWIML);
+        return;
+    }
+    res.status(200).type('text/xml').send(buildInboundVoiceTwiML(config.streamPublicUrl));
+}
+
+/**
+ * Attaches the Media-Streams WSS to the shared HTTP server on {@link TWILIO_MEDIA_WSS_PATH}. Each socket
+ * is mapped to its Call SID on the first `start` frame, then inbound frames are dispatched to the call's
+ * bindings via the registry; the socket is also the registry's outbound pump for that call.
+ */
+function attachMediaStreamServer(registry: TwilioCallMediaRegistry): void {
+    // noServer: the shared path-routing upgrade dispatcher (media-upgrade-router) owns the HTTP
+    // 'upgrade' event — a second {server}-bound WS server would fight GraphQL's socket and 400 the
+    // handshake (Twilio error 31920). We register our path and the dispatcher routes to it.
+    const wss = new WebSocketServer({ noServer: true });
+    wss.on('connection', (socket: WebSocket) => wireMediaSocket(socket, registry));
+    RegisterMediaUpgradeRoute(TWILIO_MEDIA_WSS_PATH, wss);
+    LogStatus(`[Telephony][Twilio] Media-Streams WSS route registered at ${TWILIO_MEDIA_WSS_PATH}`);
+}
+
+/** Wires one Media-Streams socket: bind on `start`, dispatch inbound frames, tear down on close. */
+function wireMediaSocket(socket: WebSocket, registry: TwilioCallMediaRegistry): void {
+    let callSid: string | null = null;
+    const adapter = { send: (data: string) => socket.send(data), close: () => socket.close() };
+
+    socket.on('message', (raw: unknown) => {
+        const message = parseWsMessage(raw);
+        if (!message) {
+            return;
+        }
+        if (message.event === 'start' && message.start?.callSid) {
+            callSid = message.start.callSid;
+            registry.AttachSocket(callSid, adapter, message.start.streamSid ?? '');
+            return;
+        }
+        if (callSid) {
+            registry.DispatchInbound(callSid, message);
+        }
+    });
+    socket.on('close', () => {
+        if (callSid) {
+            registry.EndCall(callSid);
+        }
+    });
+}
+
+/** Parses a raw WS payload (Buffer/string) into a Twilio message, or null when unparseable. */
+function parseWsMessage(raw: unknown): TwilioWsMessage | null {
+    try {
+        const text = typeof raw === 'string' ? raw : raw instanceof Buffer ? raw.toString('utf8') : String(raw);
+        return JSON.parse(text) as TwilioWsMessage;
+    } catch {
+        return null;
+    }
+}
+
+/** Coerces an Express urlencoded body to the `Record<string,string>` the signature verifier expects. */
+function coerceParams(body: unknown): Record<string, string> {
+    const out: Record<string, string> = {};
+    if (body && typeof body === 'object') {
+        for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
+            if (typeof value === 'string') {
+                out[key] = value;
+            }
+        }
+    }
+    return out;
+}
+
+/** Resolves the server-side principal + provider for the public webhook (no MJ JWT on a carrier request). */
+function resolveServerContext(): { user: UserInfo; provider: IMetadataProvider } | null {
+    const user = UserCache.Instance.GetSystemUser() ?? UserCache.Users.find((u) => u.IsActive && u.Type?.trim().toLowerCase() === 'owner') ?? null;
+    const provider = Metadata.Provider as unknown as IMetadataProvider | undefined; // global-provider-ok: public carrier webhook has no MJ JWT / per-request provider; the server's single default provider is correct
+    if (!user || !provider) {
+        return null;
+    }
+    return { user, provider };
+}