buzz-me-in 2.2.0-beta.4 → 2.2.0

package/.env.example

@@ -66,6 +66,18 @@ SHUTDOWN_GRACE_MS=10000
 # unlock bothers you.
 HOMEKIT_HANGUP_GRACE_MS=8000
 
+# Optional labels for numbers you expect to call in, so the journal says who
+# rang rather than only a number. The intercom panel is normally the only
+# caller; anything else is a wrong number or a dialler that found the number.
+# Comma-separated <E.164>=<label> pairs. Labels may contain spaces, up to 64
+# characters, and each number may appear once.
+# Purely descriptive: an unlabelled caller is logged as "unknown" and still
+# rings the doorbell. Nothing is ever rejected on the strength of this, because
+# the building's dialler could change without warning and a silently blocked
+# visitor is much worse than a labelled unknown one.
+# Leave unset to omit the caller field entirely.
+#KNOWN_CALLERS=+15551234567=Intercom,+15557654321=Building management
+
 # Logging
 # LOG_LEVEL controls minimum emitted level: debug | info | warn | error
 # Default is info when unset/invalid.

package/README.md

@@ -1,10 +1,14 @@
 # buzz-me-in
 
-Apartment intercom to Apple HomeKit, bridged over Twilio.
-
+[![npm](https://img.shields.io/npm/v/buzz-me-in.svg?style=flat-square)](https://www.npmjs.com/package/buzz-me-in)
+[![npm@beta](https://img.shields.io/npm/v/buzz-me-in/beta.svg?style=flat-square&label=npm%40beta)](https://www.npmjs.com/package/buzz-me-in/v/beta)
+[![npm](https://img.shields.io/npm/dt/buzz-me-in.svg?style=flat-square)](https://www.npmjs.com/package/buzz-me-in)
+[![GitHub last commit](https://img.shields.io/github/last-commit/atdr/buzz-me-in.svg?style=flat-square)](https://github.com/atdr/buzz-me-in)
 [![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)
 
+Apartment intercom to Apple HomeKit, bridged over Twilio.
+
 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

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "buzz-me-in",
-  "version": "2.2.0-beta.4",
+  "version": "2.2.0",
   "description": "HomeKit-compatible apartment intercom via Twilio media streams",
+  "keywords": [
+    "homekit",
+    "intercom",
+    "twilio",
+    "doorbell",
+    "smart-home",
+    "raspberry-pi",
+    "hap-nodejs",
+    "ffmpeg",
+    "nodejs"
+  ],
   "main": "server.js",
   "bin": {
     "buzz-me-in": "./server.js"
@@ -42,7 +53,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "dotenv": "^17.4.2",
+    "dotenv": "^18.0.1",
     "hap-nodejs": "^0.14.2",
     "qrcode-terminal": "^0.12.0",
     "twilio": "^6.1.0",

package/server.js

@@ -165,6 +165,33 @@ function buildTwiml(callSid) {
 </Response>`;
 }
 
+/**
+ * A repeated form field parses to an array, so take the first value. A sender
+ * can repeat From freely; the signature covers the whole body, not its shape.
+ *
+ * @param {string | string[] | undefined} value
+ * @returns {string | undefined}
+ */
+function firstFormValue(value) {
+  if (Array.isArray(value)) return value.length ? value[0] : undefined;
+  return value;
+}
+
+/**
+ * Label for a calling number, from KNOWN_CALLERS. Returns 'unknown' for a
+ * number we have no label for, and null when nothing was configured, so the
+ * field is absent rather than misleadingly saying 'unknown' on every call.
+ *
+ * @param {string | string[] | undefined} from
+ * @returns {string | null}
+ */
+function describeCaller(from) {
+  if (config.knownCallers.size === 0) return null;
+  const number = firstFormValue(from);
+  if (!number) return 'unknown';
+  return config.knownCallers.get(number.trim()) || 'unknown';
+}
+
 async function handleTwimlRequest(req, res) {
   twimlLogger.info('Incoming TwiML request', {
     event: 'twiml-request',
@@ -200,9 +227,18 @@ async function handleTwimlRequest(req, res) {
   const formData = parseFormUrlEncoded(rawBody);
   const callSid = normalizeCallSid(formData.CallSid);
   const body = buildTwiml(callSid);
+  // Who rang. Logged here rather than on twiml-request, which fires before the
+  // body is read and before the signature is checked: an unverified From is
+  // whatever the sender typed. forwardedFrom is logged as Twilio reports it,
+  // but carriers fill it inconsistently: on EE it is simply the dialled number
+  // on every call, so it cannot tell a diverted call from a direct one.
+  const caller = describeCaller(formData.From);
   twimlLogger.info('TwiML response generated', {
     event: 'twiml-response',
     callSid: callSid || undefined,
+    from: firstFormValue(formData.From) || undefined,
+    forwardedFrom: firstFormValue(formData.ForwardedFrom) || undefined,
+    caller: caller || undefined,
   });
   res.writeHead(200, {
     'Content-Type': 'text/xml',
@@ -506,6 +542,7 @@ module.exports = {
   main,
   beginShutdown,
   buildTwiml,
+  describeCaller,
   handleRequest,
   isAuthorizedForStatus,
   isValidTwilioRequest,

package/src/core/config.js

@@ -96,6 +96,50 @@ if (!MEDIA_SIGNATURE_MODES.includes(twilioMediaSignatureMode)) {
   fail(`TWILIO_MEDIA_SIGNATURE_MODE must be one of: ${MEDIA_SIGNATURE_MODES.join(', ')}`);
 }
 
+// Optional labels for numbers we expect to see calling in, so the journal says
+// who rang rather than only a number. The intercom panel is the only caller
+// that should normally appear; anything else is a wrong number or a dialler
+// finding an open PSTN number, and being able to tell them apart at a glance is
+// the point. Purely descriptive: nothing is rejected on the strength of it, and
+// an unknown caller still rings the doorbell, because the building's dialler
+// could change without warning and a silently blocked visitor is far worse
+// than a labelled unknown one.
+//
+// Format: comma-separated E.164=Label pairs, e.g.
+//   KNOWN_CALLERS=+15551234567=Intercom,+15557654321=Building management
+const E164 = /^\+[1-9]\d{1,14}$/;
+
+function parseKnownCallers(name) {
+  const raw = optional(name);
+  const callers = new Map();
+  if (!raw) return callers;
+
+  for (const entry of raw.split(',')) {
+    const trimmed = entry.trim();
+    if (!trimmed) continue;
+    const separator = trimmed.indexOf('=');
+    if (separator === -1) {
+      fail(`${name} entries must be <E.164>=<label>, got "${trimmed}"`);
+    }
+    const number = trimmed.slice(0, separator).trim();
+    const label = trimmed.slice(separator + 1).trim();
+    if (!E164.test(number)) {
+      fail(`${name} entry "${trimmed}" does not start with an E.164 number`);
+    }
+    if (!label) {
+      fail(`${name} entry "${trimmed}" has an empty label`);
+    }
+    if (label.length > 64) {
+      fail(`${name} label for ${number} is longer than 64 characters`);
+    }
+    if (callers.has(number)) {
+      fail(`${name} lists ${number} more than once`);
+    }
+    callers.set(number, label);
+  }
+  return callers;
+}
+
 const twilioWebhookBaseUrl = sanitizeBaseUrl(
   optional('TWILIO_WEBHOOK_BASE_URL') || `https://${tunnelHostname}`
 );
@@ -139,6 +183,7 @@ module.exports = {
   twilioMediaPayloadMaxBytes: parsePositiveInt('TWILIO_MEDIA_PAYLOAD_MAX_BYTES', '512'),
   shutdownGraceMs: parsePositiveInt('SHUTDOWN_GRACE_MS', '10000'),
   homekitHangupGraceMs: parsePositiveInt('HOMEKIT_HANGUP_GRACE_MS', '8000'),
+  knownCallers: parseKnownCallers('KNOWN_CALLERS'),
   streamAuthSecret,
   streamAuthTtlSec: 90,
   statusApiToken,