buzz-me-in 2.0.0

package/src/core/return-audio-sdp.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Return-audio SDP file handling for the outbound (HomeKit → Twilio) ffmpeg
+ * pipeline. The SDP embeds the SRTP master key/salt, so files are written
+ * into a process-private 0700 temp directory with mode 0600 instead of
+ * world-readable predictable paths directly under /tmp.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Created lazily (not eagerly at module load) so that merely importing this
+// module — e.g. in tests that never write an SDP — has no filesystem side
+// effect, and so removeSdpDir() can reset it for recreation.
+let sdpDir = null;
+
+/** Lazily create the private per-process SDP directory (mkdtemp → 0700). */
+function ensureSdpDir() {
+  if (!sdpDir) {
+    sdpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'intercom-'));
+  }
+  return sdpDir;
+}
+
+/**
+ * @param {{ port: number, payloadType: number, srtpParams: string }} input
+ * @returns {string}
+ */
+function buildReturnAudioSdp({ port, payloadType, srtpParams }) {
+  return [
+    'v=0',
+    'o=- 0 0 IN IP4 127.0.0.1',
+    's=Return Audio',
+    'c=IN IP4 127.0.0.1',
+    't=0 0',
+    `m=audio ${port} RTP/SAVP ${payloadType}`,
+    `a=rtpmap:${payloadType} opus/48000/2`,
+    `a=fmtp:${payloadType} minptime=10;useinbandfec=1`,
+    `a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:${srtpParams}`,
+    'a=recvonly',
+    '',
+  ].join('\r\n');
+}
+
+/**
+ * Write the SDP for a HAP session into the private directory.
+ *
+ * The 0700 directory (owned by this process) is what prevents another local
+ * user from reading the SRTP key or planting a symlink at the target path, so
+ * an overwrite (`w`) is safe: a re-issued START for the same session simply
+ * refreshes the file rather than throwing, keeping _startSession idempotent.
+ *
+ * @param {{ sessionID: string, port: number, payloadType: number, srtpParams: string }} input
+ * @returns {string} absolute path of the written SDP file
+ */
+function writeReturnAudioSdp({ sessionID, port, payloadType, srtpParams }) {
+  const safeName = String(sessionID).replace(/[^A-Za-z0-9_-]/g, '_');
+  const sdpPath = path.join(ensureSdpDir(), `return_${safeName}.sdp`);
+  fs.writeFileSync(sdpPath, buildReturnAudioSdp({ port, payloadType, srtpParams }), {
+    mode: 0o600,
+    flag: 'w',
+  });
+  return sdpPath;
+}
+
+/**
+ * Best-effort removal of a previously written SDP file.
+ * @param {string} sdpPath
+ */
+function removeReturnAudioSdp(sdpPath) {
+  try {
+    fs.unlinkSync(sdpPath);
+  } catch {}
+}
+
+/**
+ * Best-effort removal of the private SDP directory itself, called on graceful
+ * shutdown so the intercom-* dir does not linger. Resets the cached path so a
+ * later write (should one occur) recreates a fresh private directory.
+ */
+function removeSdpDir() {
+  if (!sdpDir) return;
+  try {
+    fs.rmSync(sdpDir, { recursive: true, force: true });
+  } catch {}
+  sdpDir = null;
+}
+
+module.exports = {
+  removeReturnAudioSdp,
+  removeSdpDir,
+  writeReturnAudioSdp,
+};

package/src/core/safe-equal.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Constant-time string comparison. Inputs are padded to a common length so
+ * unequal lengths do not short-circuit the comparison.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function safeEqualString(a, b) {
+  const left = Buffer.from(a, 'utf8');
+  const right = Buffer.from(b, 'utf8');
+  const len = Math.max(left.length, right.length);
+  const paddedLeft = Buffer.concat([left, Buffer.alloc(len - left.length)]);
+  const paddedRight = Buffer.concat([right, Buffer.alloc(len - right.length)]);
+  return crypto.timingSafeEqual(paddedLeft, paddedRight);
+}
+
+module.exports = { safeEqualString };

package/src/core/state.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const config = require('./config');
+const { createLogger } = require('./log');
+const logger = createLogger({ component: 'state' });
+
+/** @import { connection as WebSocketConnection } from 'websocket' */
+/** @import { CallSession, CallStatus, StartCallResult, ClearCallResult, ClearedCallSession } from './types.js' */
+
+class CallSessionManager {
+  /**
+   * @param {number} staleSec
+   */
+  constructor(staleSec) {
+    /** @type {Map<string, CallSession>} */
+    this._sessions = new Map();
+    /** @type {string | null} */
+    this._activeCallSid = null;
+    this._staleMs = staleSec * 1000;
+    /** @type {((session: ClearedCallSession) => void) | null} */
+    this._onSessionStale = null;
+
+    const tickMs = Math.max(5000, Math.min(30000, Math.floor(this._staleMs / 3)));
+    this._reaper = setInterval(() => this._reapStaleSession(), tickMs);
+    if (typeof this._reaper.unref === 'function') this._reaper.unref();
+  }
+
+  /**
+   * @param {((session: ClearedCallSession) => void) | null | undefined} handler
+   */
+  setOnSessionStale(handler) {
+    this._onSessionStale = typeof handler === 'function' ? handler : null;
+  }
+
+  /**
+   * @param {{ callSid: string, streamSid: string, wsConnection: WebSocketConnection }} input
+   * @returns {StartCallResult}
+   */
+  startCall({ callSid, streamSid, wsConnection }) {
+    if (!callSid || !streamSid || !wsConnection) {
+      return { ok: false, reason: 'invalid session payload' };
+    }
+    const active = this.getActiveCall();
+    if (active && active.callSid !== callSid) {
+      return { ok: false, reason: 'another call is already active' };
+    }
+
+    const now = Date.now();
+    /** @type {CallSession} */
+    const session = {
+      callSid,
+      streamSid,
+      wsConnection,
+      createdAtMs: now,
+      lastEventAtMs: now,
+      lastEvent: 'start',
+    };
+
+    this._sessions.set(callSid, session);
+    this._activeCallSid = callSid;
+    return { ok: true, session };
+  }
+
+  /**
+   * @returns {CallSession | null}
+   */
+  getActiveCall() {
+    if (!this._activeCallSid) return null;
+    return this._sessions.get(this._activeCallSid) || null;
+  }
+
+  /**
+   * @returns {CallStatus}
+   */
+  getStatus() {
+    const active = this.getActiveCall();
+    if (!active) return { active: false };
+    return { active: true, callSid: active.callSid };
+  }
+
+  /**
+   * @param {string | null | undefined} callSid
+   * @param {string | null | undefined} eventName
+   * @returns {boolean}
+   */
+  markActivity(callSid, eventName) {
+    const session = callSid ? this._sessions.get(callSid) : this.getActiveCall();
+    if (!session) return false;
+    session.lastEventAtMs = Date.now();
+    if (eventName) session.lastEvent = eventName;
+    return true;
+  }
+
+  /**
+   * @param {string | null | undefined} reason
+   * @returns {ClearCallResult}
+   */
+  clearActiveCall(reason) {
+    const active = this.getActiveCall();
+    if (!active) return { cleared: false, session: null };
+    this._sessions.delete(active.callSid);
+    this._activeCallSid = null;
+    return { cleared: true, session: { ...active, clearedReason: reason || 'cleared' } };
+  }
+
+  /**
+   * @param {WebSocketConnection} wsConnection
+   * @param {string | null | undefined} reason
+   * @returns {ClearCallResult}
+   */
+  clearIfConnection(wsConnection, reason) {
+    const active = this.getActiveCall();
+    if (!active || active.wsConnection !== wsConnection) {
+      return { cleared: false, session: null };
+    }
+    return this.clearActiveCall(reason || 'connection-closed');
+  }
+
+  stop() {
+    if (this._reaper) {
+      clearInterval(this._reaper);
+      this._reaper = null;
+    }
+    this._sessions.clear();
+    this._activeCallSid = null;
+  }
+
+  _reapStaleSession() {
+    const active = this.getActiveCall();
+    if (!active) return;
+    if (Date.now() - active.lastEventAtMs <= this._staleMs) return;
+
+    const { cleared, session } = this.clearActiveCall('stale-timeout');
+    if (!cleared || !this._onSessionStale) return;
+
+    try {
+      this._onSessionStale(session);
+    } catch (err) {
+      logger.error('stale session handler failed', {
+        event: 'stale-handler-failed',
+        reason: 'handler-throw',
+        callSid: session.callSid,
+        error: err,
+      });
+    }
+  }
+}
+
+module.exports = new CallSessionManager(config.callSessionStaleSec);

package/src/core/stream-auth.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const crypto = require('crypto');
+const config = require('./config');
+const { safeEqualString } = require('./safe-equal');
+
+const STREAM_TOKEN_PARAMETER_NAME = 'token';
+const STREAM_TOKEN_VERSION = 1;
+const STREAM_PATH = '/media';
+const pendingStreamNonces = new Map();
+
+function toBase64Url(buffer) {
+  return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+
+function fromBase64Url(value) {
+  const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+  return Buffer.from(padded, 'base64');
+}
+
+function pruneExpiredNonces() {
+  const now = Math.floor(Date.now() / 1000);
+  for (const [nonce, data] of pendingStreamNonces.entries()) {
+    if (data.exp <= now) pendingStreamNonces.delete(nonce);
+  }
+}
+
+/**
+ * @param {string | null} callSid
+ * @returns {string}
+ */
+function issueStreamToken(callSid) {
+  pruneExpiredNonces();
+
+  const now = Math.floor(Date.now() / 1000);
+  const exp = now + config.streamAuthTtlSec;
+  const nonce = crypto.randomBytes(16).toString('hex');
+
+  pendingStreamNonces.set(nonce, { exp, callSid });
+
+  const payload = {
+    v: STREAM_TOKEN_VERSION,
+    iat: now,
+    exp,
+    nonce,
+    callSid,
+  };
+
+  const payloadEncoded = toBase64Url(Buffer.from(JSON.stringify(payload), 'utf8'));
+  const signature = toBase64Url(
+    crypto.createHmac('sha256', config.streamAuthSecret).update(payloadEncoded).digest()
+  );
+  return `${payloadEncoded}.${signature}`;
+}
+
+/**
+ * @param {string} token
+ * @returns {import('./types').StreamTokenVerificationResult}
+ */
+function verifyAndConsumeStreamToken(token) {
+  pruneExpiredNonces();
+  if (!token) return { ok: false, reason: 'missing token' };
+
+  const pieces = token.split('.');
+  if (pieces.length !== 2) return { ok: false, reason: 'invalid token format' };
+  const [payloadEncoded, providedSig] = pieces;
+  const expectedSig = toBase64Url(
+    crypto.createHmac('sha256', config.streamAuthSecret).update(payloadEncoded).digest()
+  );
+  if (!safeEqualString(providedSig, expectedSig)) {
+    return { ok: false, reason: 'invalid token signature' };
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(fromBase64Url(payloadEncoded).toString('utf8'));
+  } catch {
+    return { ok: false, reason: 'invalid token payload' };
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  if (
+    payload.v !== STREAM_TOKEN_VERSION ||
+    !payload.nonce ||
+    payload.exp <= now ||
+    payload.iat > now + 30
+  ) {
+    return { ok: false, reason: 'expired or malformed token' };
+  }
+
+  const pending = pendingStreamNonces.get(payload.nonce);
+  if (!pending) return { ok: false, reason: 'nonce not pending' };
+  if (pending.exp !== payload.exp || pending.callSid !== payload.callSid) {
+    pendingStreamNonces.delete(payload.nonce);
+    return { ok: false, reason: 'nonce payload mismatch' };
+  }
+
+  pendingStreamNonces.delete(payload.nonce);
+  return { ok: true, callSid: payload.callSid || null };
+}
+
+/**
+ * @param {string | null} callSid
+ * @param {string} [tunnelHostname]
+ * @returns {string}
+ */
+function buildConnectStreamTwiml(callSid, tunnelHostname = config.tunnelHostname) {
+  return `<Connect><Stream url="wss://${tunnelHostname}${STREAM_PATH}"><Parameter name="${STREAM_TOKEN_PARAMETER_NAME}" value="${escapeXmlAttribute(issueStreamToken(callSid))}"/></Stream></Connect>`;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeXmlAttribute(value) {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+module.exports = {
+  buildConnectStreamTwiml,
+  issueStreamToken,
+  STREAM_TOKEN_PARAMETER_NAME,
+  verifyAndConsumeStreamToken,
+};

package/src/core/twilio-ids.js

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * Twilio identifier formats and normalization.
+ *
+ * Dependency-free on purpose: this module is imported by both the token layer
+ * (stream-auth.js) and the pure protocol schema (ws-events-schema.js), and the
+ * latter must not transitively pull in config.js (which validates env at load).
+ */
+
+const CALL_SID_REGEX = /^CA[0-9a-f]{32}$/;
+
+/**
+ * Normalize an untrusted CallSid value (e.g. from webhook form data or the
+ * Twilio WebSocket start event). Twilio always sends CallSid as "CA" + 32
+ * lowercase hex chars; anything else (wrong shape, duplicate form keys parsed
+ * as arrays, non-strings) is treated as absent so it never reaches logs,
+ * tokens, or REST URLs.
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+function normalizeCallSid(value) {
+  return typeof value === 'string' && CALL_SID_REGEX.test(value) ? value : null;
+}
+
+module.exports = { CALL_SID_REGEX, normalizeCallSid };

package/src/core/types.js

@@ -0,0 +1,145 @@
+'use strict';
+
+/**
+ * Shared JSDoc typedefs for runtime JS type-checking.
+ * This file is intentionally declarations-only; no runtime exports.
+ */
+
+/**
+ * @typedef {'connected' | 'start' | 'media' | 'stop'} SupportedWsEventName
+ */
+
+/**
+ * @typedef {{ event: 'connected' }} ConnectedEvent
+ */
+
+/**
+ * @typedef {{
+ *   event: 'start',
+ *   start: { callSid: string, streamSid: string, customParameters?: Record<string, string> }
+ * }} StartEvent
+ */
+
+/**
+ * @typedef {{
+ *   event: 'media',
+ *   media: { payload: string }
+ * }} MediaEvent
+ */
+
+/**
+ * @typedef {{ event: 'stop' }} StopEvent
+ */
+
+/**
+ * @typedef {ConnectedEvent | StartEvent | MediaEvent | StopEvent} SupportedWsEventData
+ */
+
+/**
+ * @typedef {{
+ *   ok: true,
+ *   unsupported: false,
+ *   event: 'connected',
+ *   data: ConnectedEvent
+ * } | {
+ *   ok: true,
+ *   unsupported: false,
+ *   event: 'start',
+ *   data: StartEvent
+ * } | {
+ *   ok: true,
+ *   unsupported: false,
+ *   event: 'media',
+ *   data: MediaEvent
+ * } | {
+ *   ok: true,
+ *   unsupported: false,
+ *   event: 'stop',
+ *   data: StopEvent
+ * }} WsEventParseOkSupported
+ */
+
+/**
+ * @typedef {{
+ *   ok: true,
+ *   unsupported: true,
+ *   event: string
+ * }} WsEventParseOkUnsupported
+ */
+
+/**
+ * @typedef {{
+ *   ok: false,
+ *   reason: string
+ * }} WsEventParseError
+ */
+
+/**
+ * @typedef {WsEventParseOkSupported | WsEventParseOkUnsupported | WsEventParseError} WsEventParseResult
+ */
+
+/**
+ * @typedef {{ ok: true, decoded: Buffer }} MediaPayloadParseOk
+ */
+
+/**
+ * @typedef {{ ok: false, reason: string }} MediaPayloadParseError
+ */
+
+/**
+ * @typedef {MediaPayloadParseOk | MediaPayloadParseError} MediaPayloadParseResult
+ */
+
+/**
+ * @typedef {{ ok: true, callSid: string | null }} TokenVerificationOk
+ */
+
+/**
+ * @typedef {{ ok: false, reason: string }} TokenVerificationError
+ */
+
+/**
+ * @typedef {TokenVerificationOk | TokenVerificationError} StreamTokenVerificationResult
+ */
+
+/**
+ * @typedef {{
+ *   callSid: string,
+ *   streamSid: string,
+ *   wsConnection: import('websocket').connection,
+ *   createdAtMs: number,
+ *   lastEventAtMs: number,
+ *   lastEvent: string
+ * }} CallSession
+ */
+
+/**
+ * @typedef {CallSession & { clearedReason: string }} ClearedCallSession
+ */
+
+/**
+ * @typedef {{ active: false } | { active: true, callSid: string }} CallStatus
+ */
+
+/**
+ * @typedef {{ ok: true, session: CallSession } | { ok: false, reason: string }} StartCallResult
+ */
+
+/**
+ * @typedef {{ cleared: true, session: ClearedCallSession } | { cleared: false, session: null }} ClearCallResult
+ */
+
+/**
+ * @typedef {{
+ *   ts?: string,
+ *   level?: 'debug' | 'info' | 'warn' | 'error',
+ *   message?: string,
+ *   component?: string,
+ *   callSid?: string,
+ *   event?: string,
+ *   reason?: string,
+ *   durationMs?: number
+ * } & Record<string, unknown>} LogFields
+ */
+
+module.exports = {};

package/src/core/ws-events-schema.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const { z } = require('zod');
+const { CALL_SID_REGEX } = require('./twilio-ids');
+/** @import { WsEventParseResult, MediaPayloadParseResult } from './types.js' */
+
+const connectedEventSchema = z.object({
+  event: z.literal('connected'),
+});
+
+const startEventSchema = z.object({
+  event: z.literal('start'),
+  start: z.object({
+    callSid: z.string().regex(CALL_SID_REGEX),
+    streamSid: z.string().min(1),
+    mediaFormat: z
+      .object({
+        encoding: z.string().optional(),
+        sampleRate: z.number().optional(),
+        channels: z.number().optional(),
+      })
+      .optional(),
+    customParameters: z.record(z.string(), z.string()).optional(),
+  }),
+});
+
+const mediaEventSchema = z.object({
+  event: z.literal('media'),
+  media: z.object({
+    payload: z.string(),
+  }),
+});
+
+const stopEventSchema = z.object({
+  event: z.literal('stop'),
+});
+
+const supportedEventSchema = z.discriminatedUnion('event', [
+  connectedEventSchema,
+  startEventSchema,
+  mediaEventSchema,
+  stopEventSchema,
+]);
+/** @type {Set<string>} */
+const SUPPORTED_EVENTS = new Set(
+  supportedEventSchema.options.map((schema) => schema.shape.event.value)
+);
+
+const BASE64_PAYLOAD_REGEX = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+/**
+ * @param {unknown} raw
+ * @returns {WsEventParseResult}
+ */
+function parseTwilioWsEvent(raw) {
+  const base = z.object({ event: z.string().min(1) }).safeParse(raw);
+  if (!base.success) {
+    return { ok: false, reason: 'missing event field' };
+  }
+
+  if (!SUPPORTED_EVENTS.has(base.data.event)) {
+    return {
+      ok: true,
+      unsupported: true,
+      event: base.data.event,
+    };
+  }
+
+  const parsed = supportedEventSchema.safeParse(raw);
+  if (!parsed.success) {
+    return { ok: false, reason: `invalid ${base.data.event} payload` };
+  }
+
+  switch (parsed.data.event) {
+    case 'connected':
+      return { ok: true, unsupported: false, event: 'connected', data: parsed.data };
+    case 'start':
+      return { ok: true, unsupported: false, event: 'start', data: parsed.data };
+    case 'media':
+      return { ok: true, unsupported: false, event: 'media', data: parsed.data };
+    case 'stop':
+      return { ok: true, unsupported: false, event: 'stop', data: parsed.data };
+  }
+}
+
+/**
+ * @param {unknown} payload
+ * @param {number} maxDecodedBytes
+ * @returns {MediaPayloadParseResult}
+ */
+function parseTwilioMediaPayload(payload, maxDecodedBytes) {
+  if (typeof payload !== 'string') {
+    return { ok: false, reason: 'invalid media payload encoding' };
+  }
+  if (payload.length % 4 !== 0 || !BASE64_PAYLOAD_REGEX.test(payload)) {
+    return { ok: false, reason: 'invalid media payload encoding' };
+  }
+
+  const decoded = Buffer.from(payload, 'base64');
+  if (decoded.length > maxDecodedBytes) {
+    return { ok: false, reason: 'media payload too large' };
+  }
+
+  return { ok: true, decoded };
+}
+
+module.exports = {
+  parseTwilioWsEvent,
+  parseTwilioMediaPayload,
+};