buzz-me-in 2.1.2-beta.0 → 2.2.0-beta.1

package/.env.example

@@ -18,6 +18,15 @@ TUNNEL_HOSTNAME=intercom.yourdomain.com
 # Set this if your externally visible webhook URL differs.
 #TWILIO_WEBHOOK_BASE_URL=https://intercom.yourdomain.com
 
+# Twilio also signs the /media WebSocket handshake, so it can be verified before
+# the socket is accepted. Defence in depth only: the signature is an HMAC over a
+# constant URL, so it never varies between calls and cannot replace the one-time
+# stream token. Modes: off | log | enforce.
+# Start on `log`, confirm real calls emit media-ws-handshake-verified, then
+# switch to `enforce`. A mismatch usually means Twilio signed a different URL
+# variant than expected (see signedUrl in the log line).
+TWILIO_MEDIA_SIGNATURE_MODE=log
+
 # HMAC secret used to sign one-time WebSocket stream tokens embedded in TwiML.
 # Must be at least 32 chars.
 STREAM_AUTH_SECRET=replace_with_a_long_random_secret_min_32_chars

package/README.md

@@ -58,14 +58,14 @@ RPi: server.js (HTTP + WebSocket on one port)
 
 All endpoints are reachable from the public internet through the tunnel; each enforces its own auth:
 
-| Endpoint    | Method    | Auth                                         | Purpose                                |
-| ----------- | --------- | -------------------------------------------- | -------------------------------------- |
-| `/twiml`    | POST      | Twilio signature (`X-Twilio-Signature`)      | Returns TwiML for incoming calls       |
-| `/media`    | WebSocket | One-time HMAC stream token (issued in TwiML) | Bidirectional call audio               |
-| `/status`   | GET       | Bearer token (`STATUS_API_TOKEN`)            | Active call info                       |
-| `/healthz`  | GET       | None (by design)                             | Liveness probe, returns `{"ok":true}`  |
-| `/readyz`   | GET       | None (by design)                             | Readiness probe, returns `{"ok":true}` |
-| `/ringtone` | GET       | None                                         | Ring tone WAV for debug/manual checks  |
+| Endpoint    | Method    | Auth                                                                                   | Purpose                                |
+| ----------- | --------- | -------------------------------------------------------------------------------------- | -------------------------------------- |
+| `/twiml`    | POST      | Twilio signature (`X-Twilio-Signature`)                                                | Returns TwiML for incoming calls       |
+| `/media`    | WebSocket | Twilio signature on the handshake, then a one-time HMAC stream token (issued in TwiML) | Bidirectional call audio               |
+| `/status`   | GET       | Bearer token (`STATUS_API_TOKEN`)                                                      | Active call info                       |
+| `/healthz`  | GET       | None (by design)                                                                       | Liveness probe, returns `{"ok":true}`  |
+| `/readyz`   | GET       | None (by design)                                                                       | Readiness probe, returns `{"ok":true}` |
+| `/ringtone` | GET       | None                                                                                   | Ring tone WAV for debug/manual checks  |
 
 The health endpoints are deliberately unauthenticated so systemd checks, uptime monitors, and the test sequence below can probe them; they expose nothing beyond `{"ok":true}`.
 
@@ -86,7 +86,8 @@ The health endpoints are deliberately unauthenticated so systemd checks, uptime
 - Node.js >= 20
   - Runtime is tested on Node 20+.
   - Repo tooling/CI currently runs on Node 20, 22, and 24.
-- ffmpeg with libx264 and libopus: `sudo apt install ffmpeg`
+- ffmpeg >= 5.1 with libx264 and libopus: `sudo apt install ffmpeg`
+  - The 5.1 floor is the `-ch_layout` option used on the inbound audio pipeline. Debian 12 (bookworm) ships 5.1 and Raspberry Pi OS based on Debian 13 ships 7.1, so apt satisfies this on any currently supported release.
 
 ### Accounts and services
 
@@ -186,7 +187,8 @@ In the [Twilio Console](https://console.twilio.com/us1/develop/phone-numbers/man
 Security hardening notes:
 
 - `/twiml` enforces `X-Twilio-Signature` verification with your `TWILIO_AUTH_TOKEN`.
-- TwiML embeds a short-lived, one-time signed token in the media stream URL. WebSocket connections are rejected unless this token validates.
+- TwiML embeds a short-lived, one-time signed token as a `<Parameter>`, which Twilio sends in the WebSocket `start` event. Connections are rejected unless this token validates.
+- `/media` additionally verifies `X-Twilio-Signature` on the WebSocket handshake, before the socket is accepted, so unauthenticated connections cost the Pi nothing. This is defence in depth: the handshake carries no body or query string, so its signature is an HMAC over a constant URL and is the same on every call. Only the one-time token is single-use. Controlled by `TWILIO_MEDIA_SIGNATURE_MODE` (`off` | `log` | `enforce`, default `log`); see `.env.example`.
 - If your externally visible webhook base URL differs from `https://{TUNNEL_HOSTNAME}`, set `TWILIO_WEBHOOK_BASE_URL` explicitly in `.env`.
 
 ### 5. Pair with HomeKit

package/homekit.js

@@ -291,6 +291,10 @@ function _startSession(sessionID, s, request, callback) {
   // Input 0  – raw mulaw/8kHz from Twilio via stdin
   //   Let the raw audio demuxer derive PTS from sample count. Using wall-clock
   //   timestamps breaks when ffmpeg drains the buffered startup audio burst.
+  //   -ch_layout declares mono rather than -ac counting one channel: a count
+  //   leaves the layout unset, so the decoder guesses it and logs "Guessed
+  //   Channel Layout: mono" on every call. Our stderr handler is a warn, so
+  //   that guess looked like a fault in the journal. Needs ffmpeg >= 5.1.
   //
   // Input 1  – synthetic black video (lavfi color source)
   //   Generates H.264 Baseline/3.1 frames at 15 fps.
@@ -313,8 +317,8 @@ function _startSession(sessionID, s, request, callback) {
     'mulaw',
     '-ar',
     '8000',
-    '-ac',
-    '1',
+    '-ch_layout',
+    'mono',
     '-i',
     'pipe:0',
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buzz-me-in",
-  "version": "2.1.2-beta.0",
+  "version": "2.2.0-beta.1",
   "description": "HomeKit-compatible apartment intercom via Twilio media streams",
   "main": "server.js",
   "bin": {

package/server.js

@@ -38,6 +38,7 @@ const {
   buildConnectStreamTwiml,
   STREAM_TOKEN_PARAMETER_NAME,
   verifyAndConsumeStreamToken,
+  verifyStreamHandshakeSignature,
 } = require('./src/core/stream-auth');
 const { normalizeCallSid } = require('./src/core/twilio-ids');
 const homekit = require('./homekit');
@@ -45,12 +46,14 @@ const { createLogger } = require('./src/core/log');
 const { safeEqualString } = require('./src/core/safe-equal');
 const { MediaStream } = require('./src/core/media-stream');
 /** @import { request as WebSocketRequest } from 'websocket' */
+/** @import { HandshakeVerificationError } from './src/core/types' */
 
 const HTTP_SERVER_PORT = config.port;
 const STREAM_PATH = '/media';
 const STREAM_START_TIMEOUT_MS = config.streamStartTimeoutMs;
 const STATUS_BEARER_PREFIX = 'Bearer ';
 const MAX_WS_UTF8_BYTES = config.wsMaxMessageBytes;
+const MEDIA_SIGNATURE_MODE = config.twilioMediaSignatureMode;
 const SHUTDOWN_GRACE_MS = config.shutdownGraceMs;
 let shuttingDown = false;
 const activeWsConnections = new Set();
@@ -262,6 +265,36 @@ mediaws.on('request', function (request) {
     wsRequest.reject(404, 'Not found');
     return;
   }
+  // Twilio signs the Media Streams handshake, so an unauthenticated socket can
+  // be refused here rather than after accept(). Without this the server accepts
+  // the connection and allocates a MediaStream before any auth runs, because
+  // the stream token only arrives later in the `start` frame. Defence in depth:
+  // the one-time token below remains the authority, since this signature is an
+  // HMAC over a constant URL and so never varies between calls.
+  if (MEDIA_SIGNATURE_MODE !== 'off') {
+    const handshake = verifyStreamHandshakeSignature(
+      wsRequest.httpRequest.headers['x-twilio-signature']
+    );
+    if (!handshake.ok) {
+      // strict:false disables discriminated-union narrowing; cast as elsewhere.
+      const handshakeError = /** @type {HandshakeVerificationError} */ (handshake);
+      mediaWsLogger.warn('Media websocket handshake signature rejected', {
+        event: 'media-ws-rejected',
+        reason: handshakeError.reason,
+        enforced: MEDIA_SIGNATURE_MODE === 'enforce',
+      });
+      if (MEDIA_SIGNATURE_MODE === 'enforce') {
+        wsRequest.reject(403, 'Forbidden');
+        return;
+      }
+    } else {
+      mediaWsLogger.debug('Media websocket handshake signature verified', {
+        event: 'media-ws-handshake-verified',
+        signedUrl: handshake.signedUrl,
+      });
+    }
+  }
+
   // Memory backstop only: cap total sockets so a connection flood can't grow
   // unbounded. Only one Twilio call is ever authenticated at a time, and each
   // un-started socket is dropped after config.streamStartTimeoutMs, so this is

package/src/core/config.js

@@ -86,6 +86,16 @@ if (!/^[0-9A-Da-d*#wW]+$/.test(twilioUnlockDigits)) {
   fail('TWILIO_UNLOCK_DIGITS may only contain DTMF digits 0-9, A-D, *, #, w, and W');
 }
 
+// Modes for the /media handshake signature check. Defaults to 'log' rather
+// than 'enforce': Twilio's handshake signing has documented quirks (wss://
+// scheme, optional trailing slash), so a deployment must confirm real calls
+// verify before a mismatch is allowed to reject them.
+const MEDIA_SIGNATURE_MODES = ['off', 'log', 'enforce'];
+const twilioMediaSignatureMode = optional('TWILIO_MEDIA_SIGNATURE_MODE') || 'log';
+if (!MEDIA_SIGNATURE_MODES.includes(twilioMediaSignatureMode)) {
+  fail(`TWILIO_MEDIA_SIGNATURE_MODE must be one of: ${MEDIA_SIGNATURE_MODES.join(', ')}`);
+}
+
 const twilioWebhookBaseUrl = sanitizeBaseUrl(
   optional('TWILIO_WEBHOOK_BASE_URL') || `https://${tunnelHostname}`
 );
@@ -101,6 +111,7 @@ module.exports = {
     'AC followed by 32 alphanumeric chars'
   ),
   twilioAuthToken: required('TWILIO_AUTH_TOKEN'),
+  twilioMediaSignatureMode,
   twilioUnlockDigits,
   twilioPhoneNumber: validateRegex(
     'TWILIO_PHONE_NUMBER',

package/src/core/stream-auth.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const crypto = require('crypto');
+const twilio = require('twilio');
 const config = require('./config');
 const { safeEqualString } = require('./safe-equal');
 
@@ -100,6 +101,59 @@ function verifyAndConsumeStreamToken(token) {
   return { ok: true, callSid: payload.callSid || null };
 }
 
+/**
+ * URLs Twilio may have signed for the `/media` WebSocket handshake.
+ *
+ * Twilio signs the URL it was told to connect to, i.e. the `<Stream url>` that
+ * buildConnectStreamTwiml emits. Two documented quirks make the exact string
+ * ambiguous, and both break every call if guessed wrong:
+ *
+ *   - the signature is computed over the `wss://` scheme even though the
+ *     request arrives as an ordinary HTTP upgrade (twilio-aspnet#162);
+ *   - Twilio's own guidance is to try a trailing `/` when validation fails.
+ *
+ * Each candidate is a distinct string that still has to HMAC to the presented
+ * signature under the auth token, so trying all four grants an attacker
+ * nothing: forging any one of them already requires the token.
+ *
+ * @param {string} [tunnelHostname]
+ * @returns {string[]}
+ */
+function streamHandshakeSignedUrls(tunnelHostname = config.tunnelHostname) {
+  return [
+    `wss://${tunnelHostname}${STREAM_PATH}`,
+    `wss://${tunnelHostname}${STREAM_PATH}/`,
+    `https://${tunnelHostname}${STREAM_PATH}`,
+    `https://${tunnelHostname}${STREAM_PATH}/`,
+  ];
+}
+
+/**
+ * Verify the `X-Twilio-Signature` on the `/media` WebSocket handshake.
+ *
+ * This is defence in depth, not a replacement for the one-time stream token.
+ * The handshake carries no body and no query string, so the signature is an
+ * HMAC over a constant URL and is identical on every call for the life of the
+ * auth token. It rejects scanners and anything that has never observed a
+ * genuine handshake; it does not resist replay by anything that has. Only
+ * verifyAndConsumeStreamToken is single-use.
+ *
+ * @param {unknown} signature value of the (lowercase) x-twilio-signature header
+ * @param {string} [tunnelHostname]
+ * @returns {import('./types').StreamHandshakeVerificationResult}
+ */
+function verifyStreamHandshakeSignature(signature, tunnelHostname = config.tunnelHostname) {
+  if (typeof signature !== 'string' || !signature) {
+    return { ok: false, reason: 'missing handshake signature' };
+  }
+  for (const signedUrl of streamHandshakeSignedUrls(tunnelHostname)) {
+    if (twilio.validateRequest(config.twilioAuthToken, signature, signedUrl, {})) {
+      return { ok: true, signedUrl };
+    }
+  }
+  return { ok: false, reason: 'invalid handshake signature' };
+}
+
 /**
  * @param {string | null} callSid
  * @param {string} [tunnelHostname]
@@ -125,6 +179,9 @@ function escapeXmlAttribute(value) {
 module.exports = {
   buildConnectStreamTwiml,
   issueStreamToken,
+  STREAM_PATH,
   STREAM_TOKEN_PARAMETER_NAME,
+  streamHandshakeSignedUrls,
   verifyAndConsumeStreamToken,
+  verifyStreamHandshakeSignature,
 };

package/src/core/types.js

@@ -102,6 +102,18 @@
  * @typedef {TokenVerificationOk | TokenVerificationError} StreamTokenVerificationResult
  */
 
+/**
+ * @typedef {{ ok: true, signedUrl: string }} HandshakeVerificationOk
+ */
+
+/**
+ * @typedef {{ ok: false, reason: string }} HandshakeVerificationError
+ */
+
+/**
+ * @typedef {HandshakeVerificationOk | HandshakeVerificationError} StreamHandshakeVerificationResult
+ */
+
 /**
  * @typedef {{
  *   callSid: string,