buzz-me-in 2.1.1 → 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

@@ -2,6 +2,9 @@
 
 Apartment intercom to Apple HomeKit, bridged over Twilio.
 
+[![CI](https://img.shields.io/github/actions/workflow/status/atdr/buzz-me-in/ci.yml?style=flat-square&label=CI)](https://github.com/atdr/buzz-me-in/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/atdr/buzz-me-in?style=flat-square&label=coverage)](https://codecov.io/gh/atdr/buzz-me-in)
+
 A Raspberry Pi server that bridges an apartment intercom system into Apple HomeKit. When someone presses the intercom buzzer, your iPhone/HomePod receives a doorbell notification with a live camera tile. You can hear the caller, speak back, and unlock the door — all from the Home app or via Siri.
 
 ## Project docs
@@ -55,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}`.
 
@@ -183,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/homekit.js

@@ -673,37 +673,68 @@ const cameraController = new CameraController({
 
 accessory.configureController(cameraController);
 
-accessory.publish({
-  username: config.hapUsername,
-  pincode: config.hapPincode,
-  port: config.hapPort,
-  category: Categories.VIDEO_DOORBELL,
-  advertiser: hap.MDNSAdvertiser.AVAHI,
-});
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
 
-logger.info('Accessory published', {
-  event: 'accessory-published',
-});
-// The setup QR encodes the pairing pincode, so only print it on an
-// interactive terminal — never into journald/log files.
-if (process.stdout.isTTY) {
-  logger.info('Accessory QR setup URI generated', {
-    event: 'accessory-qr-setup',
+let started = false;
+
+/**
+ * Put the accessory on the network and prepare the snapshot.
+ *
+ * Everything above this is in-memory construction; every side effect that
+ * reaches outside the process lives here. That split is deliberate: it lets
+ * server.js, a test, or the coverage run require this module without binding
+ * `HAP_PORT`, advertising a second accessory over Avahi alongside a live
+ * service, or spawning ffmpeg. server.js calls this from main().
+ *
+ * @returns {void}
+ */
+function start() {
+  if (started) {
+    logger.warn('Accessory start requested twice; ignoring', {
+      event: 'accessory-start-repeated',
+      reason: 'already-started',
+    });
+    return;
+  }
+  started = true;
+
+  accessory.publish({
+    username: config.hapUsername,
+    pincode: config.hapPincode,
+    port: config.hapPort,
+    category: Categories.VIDEO_DOORBELL,
+    advertiser: hap.MDNSAdvertiser.AVAHI,
   });
-  qrcode.generate(accessory.setupURI(), { small: true });
-} else {
-  logger.info('Pairing QR suppressed on non-interactive stdout; reprint it with buzz-me-in --qr', {
-    event: 'accessory-qr-suppressed',
-    reason: 'stdout-not-tty',
+
+  logger.info('Accessory published', {
+    event: 'accessory-published',
   });
-}
+  // The setup QR encodes the pairing pincode, so only print it on an
+  // interactive terminal — never into journald/log files.
+  if (process.stdout.isTTY) {
+    logger.info('Accessory QR setup URI generated', {
+      event: 'accessory-qr-setup',
+    });
+    qrcode.generate(accessory.setupURI(), { small: true });
+  } else {
+    logger.info(
+      'Pairing QR suppressed on non-interactive stdout; reprint it with buzz-me-in --qr',
+      {
+        event: 'accessory-qr-suppressed',
+        reason: 'stdout-not-tty',
+      }
+    );
+  }
 
-// Kick off snapshot generation asynchronously (non-blocking)
-initSnapshot().then(() =>
-  logger.info('Snapshot initialized', {
-    event: 'snapshot-ready',
-  })
-);
+  // Kick off snapshot generation asynchronously (non-blocking)
+  initSnapshot().then(() =>
+    logger.info('Snapshot initialized', {
+      event: 'snapshot-ready',
+    })
+  );
+}
 
 // ---------------------------------------------------------------------------
 // Exports called by server.js
@@ -778,6 +809,9 @@ function setOnHapSessionStarted(handler) {
 function shutdown() {
   endHapSession();
   removeSdpDir();
+  // Nothing to tear down if start() never ran: unpublish() on an accessory
+  // that was never published has no HAP server or advertiser to stop.
+  if (!started) return;
   accessory.unpublish().catch((error) => {
     logger.error('Failed to unpublish HAP accessory during shutdown', {
       event: 'accessory-unpublish-failed',
@@ -788,6 +822,7 @@ function shutdown() {
 }
 
 module.exports = {
+  start,
   triggerDoorbell,
   setMulawPassthrough,
   clearMulawPassthrough,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buzz-me-in",
-  "version": "2.1.1",
+  "version": "2.2.0-beta.0",
   "description": "HomeKit-compatible apartment intercom via Twilio media streams",
   "main": "server.js",
   "bin": {
@@ -22,6 +22,7 @@
     "check": "node --check server.js homekit.js twilio-api.js src/core/*.js",
     "test": "DOTENV_CONFIG_PATH=/dev/null node --test",
     "typecheck": "tsc --noEmit",
+    "coverage": "DOTENV_CONFIG_PATH=/dev/null node --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-include='server.js' --test-coverage-include='homekit.js' --test-coverage-include='twilio-api.js' --require ./tests/helpers/coverage-preload.cjs --test-reporter=lcov --test-reporter-destination=lcov.info --test-reporter=spec --test-reporter-destination=stdout",
     "prepare": "husky || true"
   },
   "license": "MIT",

package/server.js

@@ -3,23 +3,29 @@
 'use strict';
 
 // CLI flags are handled before every other require, and moving this down breaks
-// them: requiring ./homekit calls accessory.publish() at module scope, which
-// would put a second accessory on the network alongside the running service,
-// and requiring ./src/core/config throws on any missing env var, which under
-// systemd lives in EnvironmentFile and so is absent from an interactive shell.
-// A read-only query must touch neither. tests/cli.test.cjs pins this ordering.
+// them: requiring ./src/core/config throws on any missing env var, which under
+// systemd lives in EnvironmentFile and so is absent from an interactive shell,
+// and requiring ./homekit pulls in that same config. A read-only query must
+// touch neither. tests/cli.test.cjs pins this ordering.
+//
+// The require.main guard keeps process.argv out of it when this file is loaded
+// as a library rather than run: a test or the coverage run would otherwise have
+// the test runner's own argv parsed as intercom flags. Everything below module
+// scope is likewise inert until main() runs.
 //
 // Writes are synchronous because process.exit() can truncate a pending async
 // write to a pipe.
-const cliFs = require('fs');
-const cliExit = require('./src/core/cli').run({
-  argv: process.argv.slice(2),
-  write: (text) => cliFs.writeSync(1, text),
-  writeErr: (text) => cliFs.writeSync(2, text),
-  isTTY: Boolean(process.stdout.isTTY),
-  cwd: process.cwd(),
-});
-if (cliExit !== null) process.exit(cliExit);
+if (require.main === module) {
+  const cliFs = require('fs');
+  const cliExit = require('./src/core/cli').run({
+    argv: process.argv.slice(2),
+    write: (text) => cliFs.writeSync(1, text),
+    writeErr: (text) => cliFs.writeSync(2, text),
+    isTTY: Boolean(process.stdout.isTTY),
+    cwd: process.cwd(),
+  });
+  if (cliExit !== null) process.exit(cliExit);
+}
 
 const http = require('http');
 const twilio = require('twilio');
@@ -32,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');
@@ -39,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();
@@ -256,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
@@ -369,12 +408,53 @@ function isAuthorizedForStatus(req) {
 // Start server
 // ---------------------------------------------------------------------------
 
-wsserver.listen(HTTP_SERVER_PORT, () => {
-  logger.info('Server listening', {
-    event: 'server-start',
-    port: HTTP_SERVER_PORT,
+/**
+ * Every side effect that reaches outside the process lives here: publishing the
+ * HomeKit accessory, binding the HTTP/WebSocket port, and installing the
+ * process-level signal and crash handlers. Module scope above only builds
+ * objects and registers in-process callbacks, so requiring this file from a
+ * test or the coverage run advertises nothing, binds nothing, and cannot
+ * install an uncaughtException handler that would swallow a test failure.
+ *
+ * homekit.start() comes first so the accessory is on the network before the
+ * port accepts a Twilio stream, which is the order the module-scope version
+ * produced and the order README's startup log example shows.
+ *
+ * @returns {void}
+ */
+function main() {
+  homekit.start();
+
+  wsserver.listen(HTTP_SERVER_PORT, () => {
+    logger.info('Server listening', {
+      event: 'server-start',
+      port: HTTP_SERVER_PORT,
+    });
   });
-});
+
+  process.on('SIGINT', () => beginShutdown('SIGINT'));
+  process.on('SIGTERM', () => beginShutdown('SIGTERM'));
+
+  // Exit on unexpected errors instead of continuing in an undefined state;
+  // systemd restarts the service.
+  process.on('uncaughtException', (err) => {
+    logger.error('Uncaught exception; exiting', {
+      event: 'uncaught-exception',
+      reason: 'uncaught-exception',
+      error: err,
+    });
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    logger.error('Unhandled promise rejection; exiting', {
+      event: 'unhandled-rejection',
+      reason: 'unhandled-rejection',
+      error: reason instanceof Error ? reason : new Error(String(reason)),
+    });
+    process.exit(1);
+  });
+}
 
 function beginShutdown(signal) {
   if (shuttingDown) return;
@@ -415,25 +495,15 @@ function beginShutdown(signal) {
   });
 }
 
-process.on('SIGINT', () => beginShutdown('SIGINT'));
-process.on('SIGTERM', () => beginShutdown('SIGTERM'));
-
-// Exit on unexpected errors instead of continuing in an undefined state;
-// systemd restarts the service.
-process.on('uncaughtException', (err) => {
-  logger.error('Uncaught exception; exiting', {
-    event: 'uncaught-exception',
-    reason: 'uncaught-exception',
-    error: err,
-  });
-  process.exit(1);
-});
-
-process.on('unhandledRejection', (reason) => {
-  logger.error('Unhandled promise rejection; exiting', {
-    event: 'unhandled-rejection',
-    reason: 'unhandled-rejection',
-    error: reason instanceof Error ? reason : new Error(String(reason)),
-  });
-  process.exit(1);
-});
+if (require.main === module) main();
+
+module.exports = {
+  main,
+  beginShutdown,
+  buildTwiml,
+  handleRequest,
+  isAuthorizedForStatus,
+  isValidTwilioRequest,
+  parseFormUrlEncoded,
+  readRequestBody,
+};

package/src/core/cli.js

@@ -10,8 +10,11 @@
 //
 // Nothing here starts a server, contacts HomeKit, or signals a running
 // instance. run() is called from server.js BEFORE any other require, because
-// requiring ./homekit publishes an accessory at module scope and requiring
-// ./src/core/config throws on a missing env var.
+// requiring ./src/core/config throws on a missing env var and ./homekit pulls
+// in that same config. Neither entry point acts on being required any more —
+// server.js starts from main() and homekit.js publishes from start() — so a
+// --qr run that reached them would no longer advertise a second accessory, but
+// it would still die on the missing env.
 
 const fs = require('fs');
 const path = require('path');

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,