buzz-me-in 2.2.4 → 3.0.1

package/README.md

@@ -11,13 +11,17 @@
 
 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.
+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
 
 - [Architecture guide](docs/architecture.md)
 - [Testing guide](docs/testing.md)
-- [Contributor guide](AGENTS.md) — git workflow, module format, logging conventions
+- [Contributor guide](AGENTS.md) — git workflow, module format, logging
+  conventions
 
 ## How it works
 
@@ -58,11 +62,13 @@ RPi: server.js (HTTP + WebSocket on one port)
                     sent over the active Twilio WebSocket
 ```
 
-**Single process, single port.** HTTP (TwiML) and WebSocket (media stream) share port 8080. Cloudflare Tunnel exposes one stable public URL for both.
+**Single process, single port.** HTTP (TwiML) and WebSocket (media stream) share
+port 8080. Cloudflare Tunnel exposes one stable public URL for both.
 
 ### HTTP endpoints
 
-All endpoints are reachable from the public internet through the tunnel; each enforces its own auth:
+All endpoints are reachable from the public internet through the tunnel; each
+enforces its own auth:
 
 | Endpoint    | Method    | Auth                                                                                   | Purpose                                |
 | ----------- | --------- | -------------------------------------------------------------------------------------- | -------------------------------------- |
@@ -73,38 +79,53 @@ All endpoints are reachable from the public internet through the tunnel; each en
 | `/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}`.
+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}`.
 
 ## Architecture notes
 
-- **CallSid** arrives in the WebSocket `start` event (`data.start.callSid`), not in HTTP headers. It is stored in the call session manager and retrieved via `state.getActiveCall()` for mid-call operations (currently hangup).
-- **Call hold** uses a bidirectional `<Connect><Stream>` in TwiML. The server sends ringback and unlock DTMF as mu-law media over the active WebSocket so the stream stays attached to the call.
-- **Video** is a synthetic black H.264 stream generated by ffmpeg (`lavfi color` source). HomeKit requires a video track; there is no real camera.
-- **Audio codec** is Opus (two-way). AAC-ELD is supported by some older HomeKit devices but requires compiling ffmpeg with `--enable-libfdk-aac --enable-nonfree`.
+- **CallSid** arrives in the WebSocket `start` event (`data.start.callSid`), not
+  in HTTP headers. It is stored in the call session manager and retrieved via
+  `state.getActiveCall()` for mid-call operations (currently hangup).
+- **Call hold** uses a bidirectional `<Connect><Stream>` in TwiML. The server
+  sends ringback and unlock DTMF as mu-law media over the active WebSocket so
+  the stream stays attached to the call.
+- **Video** is a synthetic black H.264 stream generated by ffmpeg (`lavfi color`
+  source). HomeKit requires a video track; there is no real camera.
+- **Audio codec** is Opus (two-way). AAC-ELD is supported by some older HomeKit
+  devices but requires compiling ffmpeg with
+  `--enable-libfdk-aac --enable-nonfree`.
 
----
+______________________________________________________________________
 
 ## Requirements
 
 ### Raspberry Pi
 
 - Raspberry Pi 4 (2 GB RAM recommended) running Raspberry Pi OS (64-bit)
-- Node.js >= 20
-  - Runtime is tested on Node 20+.
-  - Repo tooling/CI currently runs on Node 20, 22, and 24.
+- Node.js >= 22
+  - Runtime is tested on every Node line currently in LTS.
+  - CI runs on every Node line currently in LTS.
 - 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.
+  - 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
 
 - [Twilio account](https://console.twilio.com) with a Voice-enabled phone number
-- [Cloudflare account](https://dash.cloudflare.com) (free) with a domain, or use Cloudflare's free `*.cfargotunnel.com` subdomain
+- [Cloudflare account](https://dash.cloudflare.com) (free) with a domain, or use
+  Cloudflare's free `*.cfargotunnel.com` subdomain
 
----
+______________________________________________________________________
 
 ## Setup
 
-Throughout this guide `pi@raspberrypi.local`, the `pi` user and `~/intercom` are the Raspberry Pi OS defaults, used as examples. Any host, user or directory works, as long as `WorkingDirectory`, `EnvironmentFile` and `User` in `intercom.service` are edited to match.
+Throughout this guide `pi@raspberrypi.local`, the `pi` user and `~/intercom` are
+the Raspberry Pi OS defaults, used as examples. Any host, user or directory
+works, as long as `WorkingDirectory`, `EnvironmentFile` and `User` in
+`intercom.service` are edited to match.
 
 ### 1. Install
 
@@ -113,11 +134,14 @@ sudo npm install -g buzz-me-in
 command -v buzz-me-in   # sanity check; the bin lands under `npm prefix -g`
 ```
 
-Contributors work from a clone of the repository instead, with `npm install`. See `AGENTS.md` for the workflow and quality gates.
+Contributors work from a clone of the repository instead, with `npm install`.
+See `AGENTS.md` for the workflow and quality gates.
 
 ### 2. Environment variables
 
-The server reads `.env` from its working directory and writes HomeKit pairing state into `persist/` there, so that state stays separate from the global install npm manages:
+The server reads `.env` from its working directory and writes HomeKit pairing
+state into `persist/` there, so that state stays separate from the global
+install npm manages:
 
 ```bash
 mkdir -p ~/intercom && cd ~/intercom
@@ -125,11 +149,15 @@ cp "$(npm root -g)/buzz-me-in/.env.example" .env
 chmod 600 .env
 ```
 
-Edit `.env` with your credentials. Each variable is explained inline in `.env.example`. The `chmod 600` keeps the Twilio auth token and other secrets readable only by your user.
+Edit `.env` with your credentials. Each variable is explained inline in
+`.env.example`. The `chmod 600` keeps the Twilio auth token and other secrets
+readable only by your user.
 
 ### 3. Cloudflare Tunnel
 
-Install `cloudflared` on the RPi via the official Cloudflare apt repository (preferred over a manual binary download — gives you automatic updates via `apt upgrade`):
+Install `cloudflared` on the RPi via the official Cloudflare apt repository
+(preferred over a manual binary download — gives you automatic updates via
+`apt upgrade`):
 
 ```bash
 sudo mkdir -p --mode=0755 /usr/share/keyrings
@@ -140,7 +168,10 @@ echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudf
 sudo apt-get update && sudo apt-get install cloudflared
 ```
 
-Authenticate (do this once per machine). Run on the RPi — it will print a URL; open that URL in any browser on any device, log into your Cloudflare account, and select your domain. The RPi polls for the auth and writes `~/.cloudflared/cert.pem` automatically:
+Authenticate (do this once per machine). Run on the RPi — it will print a URL;
+open that URL in any browser on any device, log into your Cloudflare account,
+and select your domain. The RPi polls for the auth and writes
+`~/.cloudflared/cert.pem` automatically:
 
 ```bash
 cloudflared tunnel login
@@ -153,13 +184,17 @@ cloudflared tunnel create intercom
 cloudflared tunnel route dns intercom intercom.yourdomain.com
 ```
 
-`tunnel create` writes a credentials JSON to `~/.cloudflared/<tunnel-id>.json`. The UUID is in the create output, the credentials filename, and `cloudflared tunnel info intercom`. Keep these credentials private alongside `cert.pem`:
+`tunnel create` writes a credentials JSON to `~/.cloudflared/<tunnel-id>.json`.
+The UUID is in the create output, the credentials filename, and
+`cloudflared tunnel info intercom`. Keep these credentials private alongside
+`cert.pem`:
 
 ```bash
 chmod 600 ~/.cloudflared/cert.pem ~/.cloudflared/*.json
 ```
 
-Create `~/.cloudflared/config.yml` (adjust `/home/pi` if you run as a different user):
+Create `~/.cloudflared/config.yml` (adjust `/home/pi` if you run as a different
+user):
 
 ```yaml
 tunnel: <tunnel-id-from-create-output>
@@ -181,7 +216,8 @@ curl https://intercom.yourdomain.com/healthz
 
 ### 4. Configure Twilio
 
-In the [Twilio Console](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming):
+In the
+[Twilio Console](https://console.twilio.com/us1/develop/phone-numbers/manage/incoming):
 
 1. Click your phone number.
 2. Under **Voice Configuration → A call comes in**, set:
@@ -192,10 +228,21 @@ 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 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`.
+- `/twiml` enforces `X-Twilio-Signature` verification with your
+  `TWILIO_AUTH_TOKEN`.
+- 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
 
@@ -206,18 +253,22 @@ cd ~/intercom
 buzz-me-in
 ```
 
-Open the **Home app** on your iPhone → **+** → **Add Accessory** → **More options** → you should see **Apartment Intercom**. Enter the pincode from your `.env` file (e.g. `XXX-XX-XXX`).
+Open the **Home app** on your iPhone → **+** → **Add Accessory** → **More
+options** → you should see **Apartment Intercom**. Enter the pincode from your
+`.env` file (e.g. `XXX-XX-XXX`).
 
 After pairing you will see:
 
 - A **doorbell** tile (rings when the intercom calls)
-- A **lock** tile (tap to unlock — plays the DTMF unlock sequence, default `w9w`, configurable via `TWILIO_UNLOCK_DIGITS`)
+- A **lock** tile (tap to unlock — plays the DTMF unlock sequence, default
+  `w9w`, configurable via `TWILIO_UNLOCK_DIGITS`)
 
 #### Re-pairing later, or checking the pairing
 
-Once the server runs under systemd its stdout is not a terminal, so it never prints the setup QR.
-Two flags read the pairing state directly instead. Neither starts the server, contacts HomeKit or
-signals the running service, so both are safe against a live deployment:
+Once the server runs under systemd its stdout is not a terminal, so it never
+prints the setup QR. Two flags read the pairing state directly instead. Neither
+starts the server, contacts HomeKit or signals the running service, so both are
+safe against a live deployment:
 
 ```bash
 buzz-me-in --check   # persist directory, accessory file, and paired client count
@@ -226,16 +277,17 @@ buzz-me-in --qr      # the setup QR, for Home app → Add Accessory
 
 Three things to know before the QR works over SSH:
 
-- **`ssh -t` is required.** `ssh host "command"` allocates no pty, so stdout is not a TTY and the
-  command refuses by design: the URI encodes the setup code and must never reach a pipe or a log.
-  An interactive `ssh host` session already has a pty.
-- **Run it from the working directory**, the one holding `.env` and `persist/`. Pairing state is
-  read relative to the current directory, so elsewhere it reports finding nothing while the service
-  is perfectly healthy.
-- **Use a dark terminal background.** The QR is drawn with block characters that take the terminal's
-  foreground colour for the _light_ modules, so it scans on a dark background and comes out inverted
-  on a light one. If your phone will not lock onto it, switch profile before assuming anything is
-  broken.
+- **`ssh -t` is required.** `ssh host "command"` allocates no pty, so stdout is
+  not a TTY and the command refuses by design: the URI encodes the setup code
+  and must never reach a pipe or a log. An interactive `ssh host` session
+  already has a pty.
+- **Run it from the working directory**, the one holding `.env` and `persist/`.
+  Pairing state is read relative to the current directory, so elsewhere it
+  reports finding nothing while the service is perfectly healthy.
+- **Use a dark terminal background.** The QR is drawn with block characters that
+  take the terminal's foreground colour for the _light_ modules, so it scans on
+  a dark background and comes out inverted on a light one. If your phone will
+  not lock onto it, switch profile before assuming anything is broken.
 
 Putting those together, from the machine you are sitting at:
 
@@ -243,7 +295,8 @@ Putting those together, from the machine you are sitting at:
 ssh -t <pi-host> 'cd <working-directory> && buzz-me-in --qr'
 ```
 
-`--check` has no such constraints, prints no secret, and is safe to pipe or paste:
+`--check` has no such constraints, prints no secret, and is safe to pipe or
+paste:
 
 ```bash
 $ buzz-me-in --check
@@ -254,19 +307,25 @@ setupID       : present
 pairedClients : 4
 ```
 
-`pairedClients: 0` on an accessory you believe is paired means the pairing is gone, not that the
-network is broken. See [docs/testing.md](docs/testing.md) and `tests/homekit-shutdown.test.cjs` for
-the failure that used to cause exactly that.
+`pairedClients: 0` on an accessory you believe is paired means the pairing is
+gone, not that the network is broken. See [docs/testing.md](docs/testing.md) and
+`tests/homekit-shutdown.test.cjs` for the failure that used to cause exactly
+that.
 
 ### 6. Install systemd units (production)
 
-Install the tunnel as a service using cloudflared's built-in installer. It copies the config to `/etc/cloudflared/config.yml`, writes its own systemd unit, and enables and starts it in one step. The explicit `--config` matters: under `sudo`, cloudflared searches root's config locations and would not find files in your home directory.
+Install the tunnel as a service using cloudflared's built-in installer. It
+copies the config to `/etc/cloudflared/config.yml`, writes its own systemd unit,
+and enables and starts it in one step. The explicit `--config` matters: under
+`sudo`, cloudflared searches root's config locations and would not find files in
+your home directory.
 
 ```bash
 sudo cloudflared --config ~/.cloudflared/config.yml service install
 ```
 
-Future tunnel config edits go in `/etc/cloudflared/config.yml`, followed by `sudo systemctl restart cloudflared`.
+Future tunnel config edits go in `/etc/cloudflared/config.yml`, followed by
+`sudo systemctl restart cloudflared`.
 
 Install the intercom server unit, which ships inside the npm package:
 
@@ -288,18 +347,23 @@ sudo systemctl status intercom
 
 ### Deploying updates
 
-After the initial setup, ship a new release by installing it from npm and restarting:
+After the initial setup, ship a new release by installing it from npm and
+restarting:
 
 ```bash
 sudo npm install -g buzz-me-in@latest
 sudo systemctl restart intercom
 ```
 
-Nothing triggers this automatically. Upgrading is a manual step or a cron job you add yourself.
+Nothing triggers this automatically. Upgrading is a manual step or a cron job
+you add yourself.
 
 ### Upgrading from a git checkout
 
-Releases before 2.0.0 ran `node server.js` out of a working tree on the Pi. To move an existing deployment onto the published package, keep the working directory exactly as it is (`.env` and `persist/` do not move, so the HomeKit pairing survives), install the package globally, and replace the unit file:
+Releases before 2.0.0 ran `node server.js` out of a working tree on the Pi. To
+move an existing deployment onto the published package, keep the working
+directory exactly as it is (`.env` and `persist/` do not move, so the HomeKit
+pairing survives), install the package globally, and replace the unit file:
 
 ```bash
 sudo systemctl stop intercom
@@ -312,17 +376,21 @@ sudo systemctl daemon-reload
 sudo systemctl start intercom
 ```
 
-Confirm the Home app still shows the accessory **without re-pairing** before deleting the old code from the working directory. Leave `.env` and `persist/` in place.
+Confirm the Home app still shows the accessory **without re-pairing** before
+deleting the old code from the working directory. Leave `.env` and `persist/` in
+place.
 
----
+______________________________________________________________________
 
 ## End-to-end test sequence
 
-Work through these stages in order. Each has a clear pass/fail check before wiring the next.
+Work through these stages in order. Each has a clear pass/fail check before
+wiring the next.
 
 ### Stage 1 — Server starts cleanly
 
-Run from the working directory holding `.env`, so config and pairing state resolve:
+Run from the working directory holding `.env`, so config and pairing state
+resolve:
 
 ```bash
 cd ~/intercom
@@ -331,9 +399,10 @@ curl http://localhost:8080/healthz
 curl http://localhost:8080/readyz
 ```
 
-**Pass:** `/healthz` and `/readyz` both return `{"ok":true}` with no errors in the log.
+**Pass:** `/healthz` and `/readyz` both return `{"ok":true}` with no errors in
+the log.
 
----
+______________________________________________________________________
 
 ### Stage 2 — Tunnel is reachable
 
@@ -345,15 +414,17 @@ curl https://intercom.yourdomain.com/readyz
 
 **Pass:** both endpoints return `{"ok":true}` from the public internet.
 
----
+______________________________________________________________________
 
 ### Stage 3 — HomeKit pairing
 
 Open Home app → Add Accessory → enter pincode.
 
-**Pass:** A doorbell tile and a lock tile appear in the Home app. Tapping the lock tile while no call is active should log `Unlock requested but no active call` and snap back to Secured.
+**Pass:** A doorbell tile and a lock tile appear in the Home app. Tapping the
+lock tile while no call is active should log
+`Unlock requested but no active call` and snap back to Secured.
 
----
+______________________________________________________________________
 
 ### Stage 4 — Inbound Twilio call
 
@@ -373,9 +444,11 @@ curl -H "Authorization: Bearer $STATUS_API_TOKEN" https://intercom.yourdomain.co
 # → {"active":true,"callSid":"CA..."}
 ```
 
-If the doorbell notification does not appear, check that the RPi and iPhone are on the same LAN (HAP uses mDNS) and that port `HAP_PORT` (default 47129) is not blocked.
+If the doorbell notification does not appear, check that the RPi and iPhone are
+on the same LAN (HAP uses mDNS) and that port `HAP_PORT` (default 47129) is not
+blocked.
 
----
+______________________________________________________________________
 
 ### Stage 5 — Live view opens (inbound audio + video)
 
@@ -387,15 +460,20 @@ Tap the doorbell notification → open the live camera view.
 {"ts":"...","level":"info","message":"Bound mulaw stream to active HomeKit session","component":"homekit","event":"mulaw-stream-bound","sessionId":"..."}
 ```
 
-**Pass (iPhone):** A black video tile appears. You should hear audio from the intercom caller through the iPhone speaker.
+**Pass (iPhone):** A black video tile appears. You should hear audio from the
+intercom caller through the iPhone speaker.
 
 **Troubleshooting:**
 
-- `ffin-stderr` log events show libx264 errors → check `ffmpeg -codecs | grep 264`.
-- Video shows "stream unavailable" → try removing the `?rtcpport=…` query parameters from the SRTP URLs in `homekit.js` (some HomeKit implementations use RTCP-mux on the same port).
-- Audio missing → check `ffmpeg -codecs | grep opus`. If `libopus` is absent, `sudo apt install ffmpeg` again or compile with `--enable-libopus`.
+- `ffin-stderr` log events show libx264 errors → check
+  `ffmpeg -codecs | grep 264`.
+- Video shows "stream unavailable" → try removing the `?rtcpport=…` query
+  parameters from the SRTP URLs in `homekit.js` (some HomeKit implementations
+  use RTCP-mux on the same port).
+- Audio missing → check `ffmpeg -codecs | grep opus`. If `libopus` is absent,
+  `sudo apt install ffmpeg` again or compile with `--enable-libopus`.
 
----
+______________________________________________________________________
 
 ### Stage 6 — Two-way audio (outbound)
 
@@ -403,16 +481,21 @@ Speak into the iPhone microphone while the live view is open.
 
 **Pass:** Your voice comes out of the intercom speaker (the caller hears you).
 
-**Troubleshooting (no outbound audio):**
-The SDP file used by ffmpeg is generated dynamically using the Opus payload type negotiated by HAP-NodeJS in the START request, so a PT mismatch should not occur. If audio is still missing, capture the return UDP traffic to verify:
+**Troubleshooting (no outbound audio):** The SDP file used by ffmpeg is
+generated dynamically using the Opus payload type negotiated by HAP-NodeJS in
+the START request, so a PT mismatch should not occur. If audio is still missing,
+capture the return UDP traffic to verify:
 
 ```bash
 sudo tcpdump -i any -n "udp port <returnAudioPort>" -c 10 -X
 ```
 
-Byte 1 of each RTP packet (bitwise AND with `0x7F`) is the payload type. If it does not match the PT in the generated SDP at `/tmp/intercom_return_<sessionID>.sdp`, the HAP-NodeJS negotiation and actual RTP stream are out of sync — check for a HAP-NodeJS version incompatibility.
+Byte 1 of each RTP packet (bitwise AND with `0x7F`) is the payload type. If it
+does not match the PT in the generated SDP at
+`/tmp/intercom_return_<sessionID>.sdp`, the HAP-NodeJS negotiation and actual
+RTP stream are out of sync — check for a HAP-NodeJS version incompatibility.
 
----
+______________________________________________________________________
 
 ### Stage 7 — Unlock
 
@@ -428,9 +511,15 @@ Tap the lock tile in the Home app → set to Unlocked.
 
 The lock tile resets to Secured automatically after 3 seconds.
 
-Two routes reach the lock tile, and they behave differently. The grid button at the bottom right of the camera view brings the lock up _beside_ the running stream, which is the smoother of the two. Backing out to the room view instead closes the camera view and tears the stream down; the lock tile is still there under **Other**, and it works because the call is held open for `HOMEKIT_HANGUP_GRACE_MS` after the view closes. Tapping unlock restarts that window, so the digits are never cut off mid-sequence.
+Two routes reach the lock tile, and they behave differently. The grid button at
+the bottom right of the camera view brings the lock up _beside_ the running
+stream, which is the smoother of the two. Backing out to the room view instead
+closes the camera view and tears the stream down; the lock tile is still there
+under **Other**, and it works because the call is held open for
+`HOMEKIT_HANGUP_GRACE_MS` after the view closes. Tapping unlock restarts that
+window, so the digits are never cut off mid-sequence.
 
----
+______________________________________________________________________
 
 ### Stage 8 — Caller hangs up
 
@@ -445,7 +534,7 @@ Have the intercom caller hang up (or wait for them to go away).
 
 **Pass (iPhone):** The live view dismisses automatically.
 
----
+______________________________________________________________________
 
 ### Stage 9 — HomeKit hangs up
 
@@ -459,11 +548,16 @@ Open the live view, then dismiss it on the iPhone (tap the X / end button).
 {"ts":"...","level":"info","message":"Hanging up call","component":"twilio-api","event":"hangup","callSid":"CA..."}
 ```
 
-The call is not hung up the instant the view closes. It is held open for `HOMEKIT_HANGUP_GRACE_MS` (default 8000) so the lock tile still has a call to send DTMF to, then hung up. Reopening the view inside that window logs `hangup-cancelled` instead and the call continues; if the caller hangs up first, the pending hangup logs `hangup-skipped` and does nothing.
+The call is not hung up the instant the view closes. It is held open for
+`HOMEKIT_HANGUP_GRACE_MS` (default 8000) so the lock tile still has a call to
+send DTMF to, then hung up. Reopening the view inside that window logs
+`hangup-cancelled` instead and the call continues; if the caller hangs up first,
+the pending hangup logs `hangup-skipped` and does nothing.
 
-**Pass (Twilio):** The call shows as completed in the [Twilio Console call log](https://console.twilio.com/us1/monitor/logs/calls).
+**Pass (Twilio):** The call shows as completed in the
+[Twilio Console call log](https://console.twilio.com/us1/monitor/logs/calls).
 
----
+______________________________________________________________________
 
 ### Stage 10 — Production reboot test
 
@@ -475,9 +569,10 @@ curl https://intercom.yourdomain.com/healthz
 curl https://intercom.yourdomain.com/readyz
 ```
 
-**Pass:** Both services are `active (running)`. `/healthz` and `/readyz` respond with `ok: true`. Make a test call to confirm end-to-end flow survives a reboot.
+**Pass:** Both services are `active (running)`. `/healthz` and `/readyz` respond
+with `ok: true`. Make a test call to confirm end-to-end flow survives a reboot.
 
----
+______________________________________________________________________
 
 ## File structure
 
@@ -505,9 +600,16 @@ curl https://intercom.yourdomain.com/readyz
 └── package.json
 ```
 
-The npm package ships only what the server needs at runtime: `server.js`, `homekit.js`, `twilio-api.js`, `src/`, `intercom.service`, `.env.example`, plus `README.md`, `LICENSE` and `package.json`. Everything else above, including `tests/`, `docs/`, `.github/` and `.claude/`, is repo-only. `package.json`'s `files` array is the allowlist; `npm pack --dry-run` prints exactly what would be published.
+The npm package ships only what the server needs at runtime: `server.js`,
+`homekit.js`, `twilio-api.js`, `src/`, `intercom.service`, `.env.example`, plus
+`README.md`, `LICENSE` and `package.json`. Everything else above, including
+`tests/`, `docs/`, `.github/` and `.claude/`, is repo-only. `package.json`'s
+`files` array is the allowlist; `npm pack --dry-run` prints exactly what would
+be published.
 
-Runtime state lives in the working directory rather than the install: `.env` and `persist/` (HomeKit pairing, containing long-term keys) are read and written relative to `WorkingDirectory`, so a global npm install never touches them.
+Runtime state lives in the working directory rather than the install: `.env` and
+`persist/` (HomeKit pairing, containing long-term keys) are read and written
+relative to `WorkingDirectory`, so a global npm install never touches them.
 
 ## Environment variables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buzz-me-in",
-  "version": "2.2.4",
+  "version": "3.0.1",
   "description": "HomeKit-compatible apartment intercom via Twilio media streams",
   "keywords": [
     "homekit",
@@ -50,7 +50,7 @@
     "url": "https://github.com/atdr/buzz-me-in/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dependencies": {
     "dotenv": "^18.0.1",
@@ -78,7 +78,7 @@
       "eslint --fix",
       "prettier --write"
     ],
-    "*.{md,yml,yaml,json}": [
+    "*.{yml,yaml,json}": [
       "prettier --write"
     ]
   }

package/src/core/stream-auth.js

@@ -10,14 +10,14 @@ const STREAM_TOKEN_VERSION = 1;
 const STREAM_PATH = '/media';
 const pendingStreamNonces = new Map();
 
+// Node's native base64url is unpadded RFC 4648 §5, the same format the old
+// replace() chain produced, so tokens issued before this change still verify.
 function toBase64Url(buffer) {
-  return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+  return buffer.toString('base64url');
 }
 
 function fromBase64Url(value) {
-  const normalized = value.replace(/-/g, '+').replace(/_/g, '/');
-  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
-  return Buffer.from(padded, 'base64');
+  return Buffer.from(value, 'base64url');
 }
 
 function pruneExpiredNonces() {