buzz-me-in 2.0.0 → 2.1.0-beta.0

package/README.md

@@ -202,6 +202,51 @@ 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`)
 
+#### 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:
+
+```bash
+buzz-me-in --check   # persist directory, accessory file, and paired client count
+buzz-me-in --qr      # the setup QR, for Add Accessory → More options
+```
+
+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.
+
+Putting those together, from the machine you are sitting at:
+
+```bash
+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:
+
+```bash
+$ buzz-me-in --check
+persistDir    : /home/<user>/intercom/persist
+accessoryInfo : AccessoryInfo.XXXXXXXXXXXX.json
+category      : 18 (video doorbell)
+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.
+
 ### 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.
@@ -422,10 +467,11 @@ curl https://intercom.yourdomain.com/readyz
 
 ```text
 .
-├── server.js               # HTTP routes + WebSocket server; graceful shutdown
+├── server.js               # CLI flag dispatch; HTTP routes + WebSocket server; graceful shutdown
 ├── homekit.js              # HAP-NodeJS camera+doorbell accessory; ffmpeg pipelines
 ├── twilio-api.js           # Twilio REST API helpers (hangup)
 ├── src/core/
+│   ├── cli.js              # --qr/--check/--help/--version, dispatched before any other require
 │   ├── config.js           # validated env/config loading
 │   ├── log.js              # structured JSON-lines logger
 │   ├── media-stream.js     # Twilio media stream protocol (start/media/stop)

package/homekit.js

@@ -766,14 +766,22 @@ function setOnHapSessionStarted(handler) {
 /**
  * Graceful shutdown: tear down streaming sessions and unpublish the
  * accessory so the mDNS advertisement does not linger after exit.
+ *
+ * MUST be unpublish(), never destroy(). Both tear down the HAP server and the
+ * mDNS advertiser, but destroy() additionally calls
+ * Accessory.cleanupAccessoryData(), which deletes AccessoryInfo,
+ * IdentifierCache and ControllerStorage from persist/ — i.e. it erases every
+ * HomeKit pairing. destroy() means "this accessory is gone for good"; a
+ * restart is not that. Using it here silently unpaired the accessory on every
+ * clean stop, restart and reboot.
  */
 function shutdown() {
   endHapSession();
   removeSdpDir();
-  accessory.destroy().catch((error) => {
-    logger.error('Failed to destroy HAP accessory during shutdown', {
-      event: 'accessory-destroy-failed',
-      reason: 'destroy-threw',
+  accessory.unpublish().catch((error) => {
+    logger.error('Failed to unpublish HAP accessory during shutdown', {
+      event: 'accessory-unpublish-failed',
+      reason: 'unpublish-threw',
       error,
     });
   });

package/package.json

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

package/server.js

@@ -2,6 +2,25 @@
 // based on https://github.com/twilio/media-streams/blob/master/node/basic/README.md
 '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.
+//
+// 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);
+
 const http = require('http');
 const twilio = require('twilio');
 const WebSocketServer = require('websocket').server;

package/src/core/cli.js

@@ -0,0 +1,256 @@
+'use strict';
+
+// Read-only CLI queries against the pairing state in persist/.
+//
+// These exist because the server only prints the HomeKit setup QR when stdout
+// is a TTY (homekit.js), which under systemd is never. Recovering a lost
+// pairing therefore had no supported path. They also expose pairedClients,
+// which is the one number that reveals an accessory has been silently
+// unpaired (see tests/homekit-shutdown.test.cjs for how that used to happen).
+//
+// 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.
+
+const fs = require('fs');
+const path = require('path');
+
+const PERSIST_DIR_NAME = 'persist';
+const ACCESSORY_INFO_PREFIX = 'AccessoryInfo.';
+
+const USAGE = `buzz-me-in - HomeKit-compatible apartment intercom via Twilio media streams
+
+Usage:
+  buzz-me-in             Start the server
+  buzz-me-in --qr        Print the HomeKit setup QR for the accessory (terminal only)
+  buzz-me-in --check     Report pairing state: persist directory, accessory, paired clients
+  buzz-me-in --help      Show this message
+  buzz-me-in --version   Print the version
+
+--qr and --check read ${PERSIST_DIR_NAME}/ under the current working directory. They do
+not start the server, contact HomeKit, or signal a running instance, so they
+are safe to run against a live deployment.
+
+--qr requires a terminal: the URI it encodes contains the setup code, so it is
+refused on a pipe or a non-interactive SSH command. Use 'ssh -t'.
+`;
+
+/**
+ * Absolute path of the directory HAP-NodeJS persists pairing state into.
+ *
+ * HAP-NodeJS never calls HAPStorage.setCustomStoragePath, so HAPStorage calls
+ * node-persist's initSync() with no argument. That skips setOptions(), which is
+ * the only place a relative dir is made absolute, so the option stays the
+ * literal string 'persist' from node-persist's defaults and every fs call
+ * resolves it against process.cwd(). Hence <cwd>/persist, which under systemd
+ * is <WorkingDirectory>/persist. tests/cli.test.cjs pins that default so a
+ * node-persist upgrade cannot move it silently.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+function resolvePersistDir(cwd) {
+  return path.resolve(cwd, PERSIST_DIR_NAME);
+}
+
+/**
+ * @typedef {object} AccessoryInfoFile
+ * @property {string} file Basename of the AccessoryInfo JSON.
+ * @property {string[]} allFiles Every AccessoryInfo JSON found, sorted.
+ * @property {any} info Parsed contents.
+ */
+
+/**
+ * Locate and parse the persisted AccessoryInfo.
+ *
+ * @param {string} persistDir
+ * @returns {AccessoryInfoFile}
+ * @throws {Error & { code: string }} with code 'PERSIST_MISSING' or 'NO_ACCESSORY_INFO'.
+ */
+function readAccessoryInfo(persistDir) {
+  /** @param {string} code @param {string} message */
+  const fail = (code, message) => {
+    const error = /** @type {Error & { code: string }} */ (new Error(message));
+    error.code = code;
+    throw error;
+  };
+
+  let entries;
+  try {
+    entries = fs.readdirSync(persistDir);
+  } catch {
+    fail('PERSIST_MISSING', `No pairing directory at ${persistDir}`);
+    throw new Error('unreachable');
+  }
+
+  const allFiles = entries.filter((name) => name.startsWith(ACCESSORY_INFO_PREFIX)).sort();
+  if (allFiles.length === 0) {
+    fail('NO_ACCESSORY_INFO', `No ${ACCESSORY_INFO_PREFIX}*.json in ${persistDir}`);
+  }
+
+  return {
+    file: allFiles[0],
+    allFiles,
+    info: JSON.parse(fs.readFileSync(path.join(persistDir, allFiles[0]), 'utf8')),
+  };
+}
+
+/**
+ * Build the X-HM:// setup URI for a persisted accessory.
+ *
+ * This delegates to HAP-NodeJS rather than reimplementing the encoding. The
+ * upstream zero-padding loop re-reads the string's length as it grows
+ * (`for (i = 0; i <= 9 - encodedPayload.length; i++)`), so it converges on nine
+ * characters from a seven-character payload but eight from a five-character
+ * one. Any local reimplementation therefore agrees only for some categories,
+ * and a QR that differs by one character scans to nothing.
+ *
+ * Accessory.prototype.setupURI reads only `_accessoryInfo.pincode`,
+ * `_accessoryInfo.category` and `_setupID`, so a plain object stands in for a
+ * published accessory: no HAP server, no mDNS advertiser, no storage. That is
+ * a private API, pinned by tests/cli.test.cjs so a rename fails there rather
+ * than producing an unscannable code here.
+ *
+ * @param {{ pincode: string, category: number, setupID: string }} info
+ * @returns {string}
+ */
+function computeSetupUri(info) {
+  const { Accessory } = require('hap-nodejs');
+  /** @type {any} */
+  const publishedAccessoryStub = {
+    _accessoryInfo: { pincode: info.pincode, category: info.category },
+    _setupID: info.setupID,
+  };
+  return Accessory.prototype.setupURI.call(publishedAccessoryStub);
+}
+
+/**
+ * @param {any} info
+ * @returns {number}
+ */
+function countPairedClients(info) {
+  return Object.keys(info?.pairedClients || {}).length;
+}
+
+/** @returns {string} */
+function readVersion() {
+  const packageJson = path.join(__dirname, '..', '..', 'package.json');
+  return JSON.parse(fs.readFileSync(packageJson, 'utf8')).version;
+}
+
+/**
+ * @param {Error & { code?: string }} error
+ * @returns {string}
+ */
+function explainLookupFailure(error) {
+  if (error.code !== 'PERSIST_MISSING' && error.code !== 'NO_ACCESSORY_INFO') throw error;
+  return (
+    `${error.message}\n` +
+    `\nPairing state lives in ./${PERSIST_DIR_NAME} under the server's working directory, so run\n` +
+    `this from there. On a systemd host:\n` +
+    `\n  cd "$(systemctl show intercom -p WorkingDirectory --value)" && buzz-me-in\n`
+  );
+}
+
+/**
+ * Handle a CLI invocation.
+ *
+ * @param {object} options
+ * @param {string[]} options.argv Arguments after the executable and script.
+ * @param {(text: string) => void} options.write stdout sink.
+ * @param {(text: string) => void} options.writeErr stderr sink.
+ * @param {boolean} options.isTTY Whether stdout is an interactive terminal.
+ * @param {string} options.cwd Directory to resolve persist/ against.
+ * @returns {number | null} An exit code, or null meaning "start the server".
+ */
+function run({ argv, write, writeErr, isTTY, cwd }) {
+  if (argv.length === 0) return null;
+
+  const flag = argv[0];
+
+  if (flag === '--help' || flag === '-h') {
+    write(USAGE);
+    return 0;
+  }
+
+  if (flag === '--version' || flag === '-v') {
+    write(`${readVersion()}\n`);
+    return 0;
+  }
+
+  if (flag !== '--qr' && flag !== '--check') {
+    writeErr(`Unknown option: ${flag}\n\n${USAGE}`);
+    return 2;
+  }
+
+  // Checked before reading anything, so a piped --qr cannot be told whether an
+  // accessory exists either.
+  if (flag === '--qr' && !isTTY) {
+    writeErr(
+      'Refusing to print the pairing QR to a non-TTY: it encodes the setup code.\n' +
+        "Run it from a terminal, e.g.  ssh -t <host> 'cd <working-directory> && buzz-me-in --qr'\n"
+    );
+    return 1;
+  }
+
+  const persistDir = resolvePersistDir(cwd);
+
+  let accessory;
+  try {
+    accessory = readAccessoryInfo(persistDir);
+  } catch (error) {
+    writeErr(explainLookupFailure(/** @type {Error & { code?: string }} */ (error)));
+    return 1;
+  }
+
+  const { file, allFiles, info } = accessory;
+  const pairedClients = countPairedClients(info);
+
+  if (flag === '--check') {
+    write(
+      `persistDir    : ${persistDir}\n` +
+        `accessoryInfo : ${allFiles.join(', ')}\n` +
+        `category      : ${info.category}${info.category === 18 ? ' (video doorbell)' : ''}\n` +
+        `setupID       : ${info.setupID ? 'present' : 'MISSING'}\n` +
+        `pairedClients : ${pairedClients}\n`
+    );
+    return 0;
+  }
+
+  // Two accessories means two pincodes, and printing the wrong one sends the
+  // user round a pairing loop with no indication why. HAP_USERNAME in .env
+  // decides which is live, and this command deliberately does not read .env.
+  if (allFiles.length > 1) {
+    writeErr(
+      `Found ${allFiles.length} accessories in ${persistDir}:\n` +
+        allFiles.map((name) => `  ${name}\n`).join('') +
+        '\nRefusing to guess which one is live. HAP_USERNAME in .env decides;\n' +
+        'move the stale files aside and run --qr again.\n'
+    );
+    return 1;
+  }
+
+  if (!info.setupID || !info.pincode) {
+    writeErr(`${file} has no setupID or pincode; it cannot produce a setup QR.\n`);
+    return 1;
+  }
+
+  const uri = computeSetupUri(info);
+  const qrcode = require('qrcode-terminal');
+
+  write('\n  Home app -> Add Accessory -> More options -> scan this:\n\n');
+  qrcode.generate(uri, { small: true }, (/** @type {string} */ rendered) => write(rendered));
+  write(`\n  Paired clients right now: ${pairedClients}\n\n`);
+  return 0;
+}
+
+module.exports = {
+  PERSIST_DIR_NAME,
+  USAGE,
+  computeSetupUri,
+  countPairedClients,
+  readAccessoryInfo,
+  resolvePersistDir,
+  run,
+};