Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

13.8 KB
Raw Blame
/**
 * Dedicated Socket.IO namespace for FableLoom QR-hosted play sessions (#5383).
 *
 * Scoped to `/fableloom-hosted`. A guest connection authenticated with a
 * single-use QR token can ONLY access its designated session room and never
 * acquires general PortOS auth privileges or access to other socket events.
 */

import { SOCKET_MEDIA_MAX_BYTES } from '../lib/socketPayloadLimits.js';
import { hostedPlaybackUpdateSchema, hostedSpeechDoneSchema, hostedTextTurnSchema } from '../lib/fableLoomValidation.js';
import {
  _getInternalSession,
  abortHostedTurn,
  acknowledgeHostedSpeech,
  endHostedSession,
  getHostedSession,
  processHostedUtterance,
  releaseHostedSpeechOutput,
  sanitizeHostedSession,
  startHostedListening,
  switchHostedEpisode,
  updateHostedSession,
  verifyHostedHostToken,
  verifyHostedToken,
} from '../services/fableLoom/hostedSession.js';

// Guest mic payload caps. This socket is authenticated by a single-use QR token
// from a guest device, not by the install's one trusted user, so the root trust
// model does not cover it and the numbers mirror the trusted call path in
// `voice.js` (`MAX_CALL_FRAME_BYTES` / `MAX_AUDIO_BYTES`): one 64 KB frame is
// two seconds of headroom over the ~20 ms bursts the audience page ships, and
// 8 MB is ~4 minutes of 16 kHz mono audio for a single turn.
const MAX_MIC_FRAME_BYTES = 64 * 1024;
const MAX_UTTERANCE_BYTES = SOCKET_MEDIA_MAX_BYTES;
const AUDIO_TOO_LARGE = Symbol('audio-too-large');

// Socket payloads are untrusted: never let Buffer.from coerce arbitrary objects
// or allocate from a declared array-like length. Views represent raw audio bytes,
// including their offsets, rather than an array of numeric sample values.
function boundedAudioBuffer(chunk, maxBytes) {
  try {
    if (!(chunk instanceof ArrayBuffer) && !ArrayBuffer.isView(chunk)) return null;
    if (chunk.byteLength > maxBytes) return AUDIO_TOO_LARGE;
    if (Buffer.isBuffer(chunk)) return chunk;
    return chunk instanceof ArrayBuffer
      ? Buffer.from(chunk)
      : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
  } catch {
    // A detached buffer (or otherwise unusable binary view) is a dropped frame,
    // never an exception escaping the Socket.IO event boundary.
    return null;
  }
}

let hostedNsInstance = null;

export function getHostedNamespace() {
  return hostedNsInstance;
}

export function registerFableLoomHostedNamespace(io) {
  if (!io || typeof io.of !== 'function') return null;

  const ns = io.of('/fableloom-hosted');
  hostedNsInstance = ns;

  // `io.use(socketAuthGate)` only covers the default namespace, so every role
  // here must authenticate with this session's join token.
  ns.use(async (socket, next) => {
    try {
      const auth = socket.handshake.auth || {};
      const query = socket.handshake.query || {};
      const sessionId = auth.sessionId || query.sessionId;
      const token = auth.token || query.token;
      const role = auth.role || query.role || 'audience';

      if (!sessionId || typeof sessionId !== 'string') {
        return next(new Error('SESSION_ID_REQUIRED'));
      }

      const session = _getInternalSession(sessionId);
      if (!session || session.status !== 'active') {
        return next(new Error('HOSTED_SESSION_NOT_FOUND_OR_EXPIRED'));
      }

      if (role !== 'audience' && role !== 'host') {
        return next(new Error('HOSTED_SESSION_ROLE_INVALID'));
      }

      // The audience (QR/join link) token and the host token are distinct
      // secrets (#8357) — each role verifies against its own token so the
      // audience token can never authenticate a `role: 'host'` connection.
      const tokenValid = role === 'host'
        ? verifyHostedHostToken(sessionId, token)
        : verifyHostedToken(sessionId, token);
      if (!token || !tokenValid) {
        return next(new Error('HOSTED_SESSION_UNAUTHORIZED'));
      }

      socket.hostedRole = role;
      socket.hostedSessionId = sessionId;
      return next();
    } catch (err) {
      return next(new Error(`AUTH_ERROR: ${err?.message || err}`));
    }
  });

  ns.on('connection', (socket) => {
    const { hostedSessionId: sessionId, hostedRole: role } = socket;
    const room = `session:${sessionId}`;
    socket.join(room);

    const session = _getInternalSession(sessionId);
    if (!session) {
      socket.disconnect(true);
      return;
    }

    if (role === 'host') {
      session.hostSocketId = socket.id;
    } else if (role === 'audience') {
      // Single audience device policy: if an existing audience socket was connected, notify/replace
      if (session.audienceSocketId && session.audienceSocketId !== socket.id) {
        const oldSocket = ns.sockets.get(session.audienceSocketId);
        if (oldSocket) {
          oldSocket.emit('hosted:session:replaced', { reason: 'Another audience device joined this session.' });
          oldSocket.disconnect(true);
        }
      }
      session.audienceSocketId = socket.id;
    }

    // Emit initial sync snapshot to newly connected client
    socket.emit('hosted:session:sync', sanitizeHostedSession(session));

    // Broadcast peer connection status to the room
    ns.to(room).emit('hosted:peer:status', {
      hasHostConnected: !!session.hostSocketId,
      hasAudienceConnected: !!session.audienceSocketId,
      role,
    });

    // Inbound frame buffer for streaming mic chunks. `micBytes` is a running
    // counter rather than a re-sum of the array, and `micOverflow` latches the
    // refusal so an over-cap turn is reported once and never processed as if it
    // were a complete utterance.
    let micChunks = [];
    let micBytes = 0;
    let micOverflow = false;

    const resetMicBuffer = () => {
      micChunks = [];
      micBytes = 0;
      micOverflow = false;
    };

    // The record captured at connect goes stale: TTL expiry marks a session
    // `ended` without touching `turnPhase`, so a closure gated on that snapshot
    // reads `listening` forever. `_getInternalSession` re-evaluates the TTL and
    // returns null for a dead session.
    const liveSession = () => _getInternalSession(sessionId);

    // --- Host actions ---
    socket.on('hosted:playback:update', async (data) => {
      if (socket.hostedRole !== 'host') return;
      try {
        const parsed = hostedPlaybackUpdateSchema.safeParse(data);
        if (!parsed.success) {
          socket.emit('hosted:error', {
            code: 'VALIDATION_ERROR',
            message: parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '),
          });
          return;
        }
        const updated = await updateHostedSession(sessionId, {
          playbackPhase: parsed.data.phase,
          activeHoldIndex: parsed.data.activeHoldIndex,
          currentNodeId: parsed.data.nodeId,
        }, { io });
        ns.to(room).emit('hosted:playback:sync', {
          phase: updated.playbackPhase,
          activeHoldIndex: updated.activeHoldIndex,
          nodeId: updated.currentNodeId,
        });
      } catch (err) {
        socket.emit('hosted:error', { code: err.code || 'UPDATE_FAILED', message: err.message });
      }
    });

    socket.on('hosted:audio:target', async (data) => {
      if (socket.hostedRole !== 'host') return;
      try {
        const updated = await updateHostedSession(sessionId, { audioTarget: data?.target }, { io });
        ns.to(room).emit('hosted:audio:target:updated', { audioTarget: updated.audioTarget });
      } catch (err) {
        socket.emit('hosted:error', { code: 'TARGET_UPDATE_FAILED', message: err.message });
      }
    });

    // Host advanced to a different episode ("Next: Episode N") — re-bind THIS
    // hosted session to it rather than letting the server keep resolving
    // audience turns against the old episode's graph (#8112). On preflight
    // failure `switchHostedEpisode` already ends the session and broadcasts
    // `hosted:session:ended` with reason `episode_not_ready`; there is no live
    // room left to answer with a second error frame.
    socket.on('hosted:episode:switch', async (data) => {
      if (socket.hostedRole !== 'host') return;
      const episodeId = typeof data?.episodeId === 'string' ? data.episodeId : null;
      if (!episodeId) {
        socket.emit('hosted:error', { code: 'EPISODE_ID_REQUIRED', message: 'episodeId is required' });
        return;
      }
      try {
        await switchHostedEpisode(sessionId, episodeId, { io });
      } catch (err) {
        socket.emit('hosted:error', { code: err.code || 'EPISODE_SWITCH_FAILED', message: err.message });
      }
    });

    socket.on('hosted:session:end', () => {
      if (socket.hostedRole !== 'host') return;
      endHostedSession(sessionId, { reason: 'host_ended', io });
    });

    // --- Audience actions ---
    socket.on('hosted:mic:start', async () => {
      if (socket.hostedRole !== 'audience') return;
      resetMicBuffer();
      try {
        await startHostedListening(sessionId, { io });
      } catch (err) {
        socket.emit('hosted:error', { code: err.code || 'MIC_START_FAILED', message: err.message });
      }
    });

    socket.on('hosted:mic:frame', (chunk) => {
      if (socket.hostedRole !== 'audience') return;
      const live = liveSession();
      if (!live || live.turnPhase !== 'listening') return;
      // Already refused this turn — keep dropping until the next mic:start.
      if (micOverflow || !chunk) return;

      const frame = boundedAudioBuffer(chunk, MAX_MIC_FRAME_BYTES);
      if (!Buffer.isBuffer(frame)) return;

      if (micBytes + frame.length > MAX_UTTERANCE_BYTES) {
        micOverflow = true;
        micChunks = [];
        micBytes = 0;
        socket.emit('hosted:error', {
          code: 'UTTERANCE_TOO_LARGE',
          message: `audio too large (over ${MAX_UTTERANCE_BYTES} bytes)`,
        });
        return;
      }

      micChunks.push(frame);
      micBytes += frame.length;
    });

    socket.on('hosted:mic:stop', async (completeBuffer) => {
      if (socket.hostedRole !== 'audience') return;
      const live = liveSession();
      if (!live || live.turnPhase !== 'listening') return;

      const overflowed = micOverflow;
      let finalAudio = null;
      if (!overflowed && completeBuffer != null) {
        const complete = boundedAudioBuffer(completeBuffer, MAX_UTTERANCE_BYTES);
        if (!Buffer.isBuffer(complete)) {
          resetMicBuffer();
          socket.emit('hosted:error', {
            code: complete === AUDIO_TOO_LARGE ? 'UTTERANCE_TOO_LARGE' : 'INVALID_AUDIO_FRAME',
            message: 'audio must be a binary buffer within the utterance limit',
          });
          return;
        }
        finalAudio = complete;
      } else if (!overflowed && micChunks.length > 0) {
        finalAudio = Buffer.concat(micChunks);
      }
      resetMicBuffer();

      // A truncated buffer would hand the LLM half a sentence with no signal,
      // so an overflowed turn is refused outright; the error already went out.
      if (overflowed) return;

      try {
        await processHostedUtterance(sessionId, { audioBuffer: finalAudio, io });
      } catch (err) {
        if (!err?.hostedReported) socket.emit('hosted:error', { code: err.code || 'UTTERANCE_FAILED', message: err.message });
      }
    });

    socket.on('hosted:turn:text', async (data) => {
      if (socket.hostedRole !== 'audience') return;
      const live = liveSession();
      if (!live) return;
      try {
        const parsed = hostedTextTurnSchema.safeParse(data);
        if (!parsed.success) {
          const count = typeof data?.text === 'string' ? data.text.length : null;
          const maxLength = hostedTextTurnSchema.shape.text.maxLength;
          socket.emit('hosted:error', {
            code: 'VALIDATION_ERROR',
            message: count === null
              ? 'Text must be a string.'
              : `Text has ${count} characters; send between 1 and ${maxLength} characters.`,
            count,
            maxLength,
          });
          return;
        }
        if (live.turnPhase === 'thinking' || live.turnPhase === 'speaking') {
          socket.emit('hosted:error', { code: 'TURN_IN_PROGRESS', message: 'A turn is already in progress' });
          return;
        }
        if (live.turnPhase === 'idle') await startHostedListening(sessionId, { io });
        await processHostedUtterance(sessionId, { textMessage: parsed.data.text, io });
      } catch (err) {
        if (!err?.hostedReported) socket.emit('hosted:error', { code: err.code || 'TEXT_FAILED', message: err.message });
      }
    });

    socket.on('hosted:speech:done', (data) => {
      const parsed = hostedSpeechDoneSchema.safeParse(data);
      if (!parsed.success) return undefined;
      // Role and socket id come from the authenticated connection, never from
      // the payload, so the other device cannot finish this turn's playback.
      return acknowledgeHostedSpeech(sessionId, {
        turnId: parsed.data.turnId,
        status: parsed.data.status,
        role: socket.hostedRole,
        socketId: socket.id,
        io,
      }).catch((err) => {
        console.error(`❌ Hosted speech acknowledgement failed: ${err?.message || err}`);
      });
    });

    socket.on('hosted:turn:abort', () => {
      abortHostedTurn(sessionId, { reason: 'client_aborted', io });
    });

    // --- Disconnect lifecycle ---
    socket.on('disconnect', () => {
      releaseHostedSpeechOutput(sessionId, socket.id, { io });
      if (socket.hostedRole === 'host' && session.hostSocketId === socket.id) {
        session.hostSocketId = null;
      } else if (socket.hostedRole === 'audience' && session.audienceSocketId === socket.id) {
        session.audienceSocketId = null;
      }
      ns.to(room).emit('hosted:peer:status', {
        hasHostConnected: !!session.hostSocketId,
        hasAudienceConnected: !!session.audienceSocketId,
        disconnectedRole: socket.hostedRole,
      });
      socket.removeAllListeners();
    });
  });

  return ns;
}

export { MAX_MIC_FRAME_BYTES, MAX_UTTERANCE_BYTES };