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

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}`.
 
@@ -186,7 +186,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buzz-me-in",
-  "version": "2.1.2-beta.0",
+  "version": "2.2.0-beta.0",
   "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,