herdr-remote 0.2.18 → 0.2.20

package/dist/keepalive/systemd.js

@@ -0,0 +1,108 @@
+// systemd --user: a unit that runs `herdr-remote run` and restarts it.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ensureDir } from 'herdr-remote-relay/state';
+import { cliEntryPoint, serviceEnvironment } from './environment.js';
+const SYSTEMD_UNIT_NAME = 'herdr-remote.service';
+function systemdUnitPath() {
+    const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    return path.join(configHome, 'systemd', 'user', SYSTEMD_UNIT_NAME);
+}
+/**
+ * One `KEY=value` per directive. An unquoted systemd value ends at the first
+ * space, and `%` starts a specifier, so a `PATH` with either in it would be
+ * silently truncated or rewritten.
+ */
+export function systemdEnvironmentLine(key, value) {
+    const text = String(value)
+        .replace(/[\r\n]+/g, ' ')
+        .replace(/%/g, '%%');
+    if (/^[\w@+=:,./-]*$/.test(text))
+        return `Environment=${key}=${text}`;
+    return `Environment="${key}=${text.replace(/([\\"])/g, '\\$1')}"`;
+}
+export function renderSystemdUnit({ nodePath = process.execPath, entryPoint = cliEntryPoint(), environment = {}, } = {}) {
+    const environmentLines = Object.entries(environment)
+        .map(([key, value]) => systemdEnvironmentLine(key, value))
+        .join('\n');
+    return `[Unit]
+Description=Herdr Remote (relay and host connector)
+Documentation=https://github.com/dibin666/herdr-remote
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=${nodePath} ${entryPoint} run
+Restart=always
+RestartSec=3
+# Give the relay and host connector time to close sessions cleanly.
+TimeoutStopSec=15
+${environmentLines}
+
+[Install]
+WantedBy=default.target
+`;
+}
+function systemctl(args) {
+    return spawnSync('systemctl', ['--user', ...args], { encoding: 'utf8', stdio: 'pipe' });
+}
+/** Run a systemctl command that must succeed, throwing its stderr when it does not. */
+function systemctlOrThrow(args, failure) {
+    const result = systemctl(args);
+    if (result.status !== 0) {
+        throw new Error(`${failure}: ${String(result.stderr || '').trim()}`);
+    }
+}
+export const systemd = {
+    name: 'systemd',
+    status() {
+        const installed = fs.existsSync(systemdUnitPath());
+        if (!installed)
+            return { manager: 'systemd', installed: false, active: false, enabled: false };
+        const active = systemctl(['is-active', SYSTEMD_UNIT_NAME]);
+        const enabled = systemctl(['is-enabled', SYSTEMD_UNIT_NAME]);
+        const lingering = spawnSync('loginctl', ['show-user', os.userInfo().username, '--property=Linger'], { encoding: 'utf8' });
+        return {
+            manager: 'systemd',
+            installed: true,
+            active: String(active.stdout || '').trim() === 'active',
+            enabled: String(enabled.stdout || '')
+                .trim()
+                .startsWith('enabled'),
+            linger: String(lingering.stdout || '').includes('Linger=yes'),
+            unitPath: systemdUnitPath(),
+            state: String(active.stdout || active.stderr || '').trim(),
+        };
+    },
+    install() {
+        const unitPath = systemdUnitPath();
+        ensureDir(path.dirname(unitPath));
+        fs.writeFileSync(unitPath, renderSystemdUnit({ environment: serviceEnvironment() }), {
+            mode: 0o644,
+        });
+        systemctlOrThrow(['daemon-reload'], 'systemctl --user daemon-reload failed');
+        systemctlOrThrow(['enable', '--now', SYSTEMD_UNIT_NAME], 'systemctl --user enable --now failed');
+        return { ok: true, unitPath, hint: `loginctl enable-linger ${os.userInfo().username}` };
+    },
+    uninstall() {
+        const unitPath = systemdUnitPath();
+        systemctl(['disable', '--now', SYSTEMD_UNIT_NAME]);
+        fs.rmSync(unitPath, { force: true });
+        systemctl(['daemon-reload']);
+        return { ok: true, unitPath };
+    },
+    restart() {
+        const result = systemctl(['restart', SYSTEMD_UNIT_NAME]);
+        if (result.status !== 0)
+            throw new Error(String(result.stderr || '').trim() || 'systemctl restart failed');
+        return { ok: true };
+    },
+    stop() {
+        systemctl(['stop', SYSTEMD_UNIT_NAME]);
+    },
+    logsHint() {
+        return `journalctl --user -u ${SYSTEMD_UNIT_NAME} -f`;
+    },
+};

package/dist/keepalive/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/process.js

@@ -0,0 +1,12 @@
+/** Whether `pid` names a running process, including one owned by another user. */
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}

package/dist/lifecycle.js

@@ -0,0 +1,59 @@
+// Start/stop/restart that respect the keep-alive manager.
+//
+// When systemd or launchd supervises the services, killing the processes just
+// makes the manager start them again — and starting them by hand produces a
+// second, unmanaged copy fighting for the port. Every entry point goes through
+// here so the managed and unmanaged paths behave the same from the outside.
+import { loadConfig } from './config.js';
+import * as keepalive from './keepalive/index.js';
+import { restartServices, startServices, statusServices, stopServices } from './service.js';
+function managerInUse(config) {
+    const status = keepalive.status(config);
+    return status.installed || status.active ? status : null;
+}
+function startAll(config = loadConfig()) {
+    const managed = managerInUse(config);
+    if (managed) {
+        // Start means "make it run", not "restart it". Herdr runs this through the
+        // plugin's startup hook every time a Herdr server starts, and a restart
+        // there dropped every browser attached to the workstation — including the
+        // one that had just asked for that Herdr to be started.
+        if (!managed.active)
+            keepalive.restart(config);
+        return {
+            ok: true,
+            managed: true,
+            manager: managed.manager,
+            alreadyRunning: Boolean(managed.active),
+        };
+    }
+    return { ...startServices(), managed: false };
+}
+function stopAll(config = loadConfig()) {
+    const result = keepalive.stopManaged(config);
+    if (result.managed) {
+        // The manager stops the supervisor, which stops its children; clear the
+        // recorded pids so status does not report ghosts.
+        stopServices();
+        return { ok: true, managed: true, manager: result.manager };
+    }
+    return { ...stopServices(), managed: false };
+}
+function restartAll(config = loadConfig()) {
+    const managed = managerInUse(config);
+    if (managed) {
+        keepalive.restart(config);
+        return { ok: true, managed: true, manager: managed.manager };
+    }
+    return { ...restartServices(), managed: false };
+}
+/** Service status plus the keep-alive picture, which is what the TUI shows. */
+async function fullStatus(config = loadConfig()) {
+    const [services, keepaliveStatus] = [await statusServices(), keepalive.status(config)];
+    return {
+        ...services,
+        keepalive: keepaliveStatus,
+        logsHint: keepalive.logsHint(config),
+    };
+}
+export { startAll, stopAll, restartAll, fullStatus, managerInUse };

package/dist/net-interfaces.js

@@ -0,0 +1,73 @@
+import os from 'node:os';
+// Interface names that are almost always virtual bridges rather than something
+// a phone can reach. They are still listed, just ranked last.
+const VIRTUAL_NAME_PATTERN = /^(docker|br-|virbr|veth|vmnet|vboxnet|lxcbr|cni|flannel|kube)/i;
+const TAILSCALE_NAME_PATTERN = /^(tailscale|ts)\d*$/i;
+/**
+ * Is this address inside Tailscale's 100.64.0.0/10 CGNAT range? Interface names
+ * differ per platform (tailscale0 on Linux, utunN on macOS), so the address
+ * range is the portable signal.
+ */
+function isTailscaleAddress(address) {
+    const octets = String(address).split('.');
+    if (octets.length !== 4)
+        return false;
+    const first = Number(octets[0]);
+    const second = Number(octets[1]);
+    if (!Number.isInteger(first) || !Number.isInteger(second))
+        return false;
+    return first === 100 && second >= 64 && second <= 127;
+}
+function classify(name, info) {
+    if (info.internal)
+        return 'loopback';
+    if (TAILSCALE_NAME_PATTERN.test(name) || isTailscaleAddress(info.address))
+        return 'tailscale';
+    if (VIRTUAL_NAME_PATTERN.test(name))
+        return 'virtual';
+    return 'lan';
+}
+const KIND_ORDER = { tailscale: 0, lan: 1, virtual: 2, loopback: 3 };
+/**
+ * Addresses this machine can be reached at, best candidate first.
+ *
+ * Tailscale addresses come first because a device on the tailnet reaches them
+ * from anywhere, which is exactly the "works away from home without running a
+ * relay" case; plain LAN addresses follow, then virtual bridges, then loopback.
+ */
+function listReachableAddresses({ includeLoopback = true, includeIpv6 = false, } = {}) {
+    const interfaces = os.networkInterfaces();
+    const results = [];
+    for (const [name, entries] of Object.entries(interfaces)) {
+        for (const info of entries || []) {
+            // Older Node releases reported the family as a number.
+            const rawFamily = info.family;
+            const family = typeof rawFamily === 'string' ? rawFamily : `IPv${rawFamily}`;
+            if (family !== 'IPv4' && !(includeIpv6 && family === 'IPv6'))
+                continue;
+            const kind = classify(name, info);
+            if (kind === 'loopback' && !includeLoopback)
+                continue;
+            results.push({
+                name,
+                address: info.address,
+                family,
+                kind,
+                internal: Boolean(info.internal),
+            });
+        }
+    }
+    results.sort((a, b) => {
+        const byKind = KIND_ORDER[a.kind] - KIND_ORDER[b.kind];
+        if (byKind !== 0)
+            return byKind;
+        return a.address.localeCompare(b.address);
+    });
+    return results;
+}
+/** Best guess for the address to advertise when binding to every interface. */
+function preferredLanAddress() {
+    const candidates = listReachableAddresses({ includeLoopback: false });
+    return candidates.length > 0 ? candidates[0].address : null;
+}
+export { isTailscaleAddress, listReachableAddresses, preferredLanAddress };

package/dist/pasted-files.js

@@ -0,0 +1,115 @@
+/**
+ * Secure file storage and validation for pasted clipboard images.
+ *
+ * Security requirements:
+ * 1. Pinned directory: writes strictly to path.join(stateDir(), 'pasted') (directory mode 0o700).
+ * 2. Unpredictable filename: generated via crypto.randomUUID(), never using client-provided strings.
+ * 3. Whitelisted extension: derived exclusively from verified MIME type.
+ * 4. Host-side size check: re-validated to enforce <= 3 MB independently of relay checks.
+ * 5. Magic bytes sniffing: inspects raw binary headers (PNG, JPEG, GIF, WebP) to prevent file-type spoofing.
+ * 6. File mode: files are created with mode 0o600.
+ * 7. Automatic pruning: caps at 20 files and 50 MB (oldest deleted first), removes >24h stale files at startup.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { stateDir } from './paths.js';
+import { ensureDir } from 'herdr-remote-relay/state';
+import { PASTE_MAX_BYTES, PASTE_IMAGE_EXTENSIONS, isPasteImageMime, hasImageSignature, } from 'herdr-remote-relay/protocol';
+const MAX_SAVED_FILES = 20;
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024; // 50 MB
+const MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
+function getPastedDir() {
+    const dir = path.join(stateDir(), 'pasted');
+    ensureDir(dir);
+    return dir;
+}
+/**
+ * Prunes the pasted directory:
+ * - Removes files older than maxAgeMs (default 24 hours).
+ * - Caps total file count (default 20) and total disk footprint (default 50 MB),
+ *   deleting oldest files first.
+ */
+function cleanPastedDir({ dir = getPastedDir(), maxFiles = MAX_SAVED_FILES, maxBytes = MAX_TOTAL_BYTES, maxAgeMs = MAX_AGE_MS, now = Date.now(), } = {}) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const fileInfos = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const fullPath = path.join(dir, entry.name);
+        try {
+            const stat = fs.statSync(fullPath);
+            if (now - stat.mtimeMs > maxAgeMs) {
+                try {
+                    fs.unlinkSync(fullPath);
+                }
+                catch {
+                    // Removed by another process meanwhile, or not ours to remove: skip it.
+                }
+                continue;
+            }
+            fileInfos.push({ path: fullPath, size: stat.size, mtimeMs: stat.mtimeMs });
+        }
+        catch {
+            // The file vanished between listing and stat; nothing to account for.
+        }
+    }
+    // Sort oldest first
+    fileInfos.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    let totalSize = fileInfos.reduce((sum, f) => sum + f.size, 0);
+    while (fileInfos.length > maxFiles || totalSize > maxBytes) {
+        const oldest = fileInfos.shift();
+        if (!oldest)
+            break;
+        try {
+            fs.unlinkSync(oldest.path);
+            totalSize -= oldest.size;
+        }
+        catch {
+            // Pruning is best effort; the next save prunes again.
+        }
+    }
+}
+/**
+ * Validates base64 data, checks payload limits, sniffs magic bytes against declared MIME,
+ * writes to state storage with mode 0o600, and returns the absolute local path.
+ */
+function savePastedFile({ mime, dataBase64, dir = getPastedDir(), }) {
+    if (!isPasteImageMime(mime)) {
+        throw new Error(`unsupported MIME type: ${mime}`);
+    }
+    if (typeof dataBase64 !== 'string') {
+        throw new Error('missing or invalid dataBase64 payload');
+    }
+    const buf = Buffer.from(dataBase64, 'base64');
+    if (buf.length > PASTE_MAX_BYTES) {
+        throw new Error(`file size (${buf.length} bytes) exceeds maximum limit of 3 MB`);
+    }
+    if (buf.length === 0) {
+        throw new Error('file payload is empty');
+    }
+    if (!hasImageSignature(mime, buf)) {
+        throw new Error(`file magic bytes do not match declared MIME type ${mime}`);
+    }
+    // Prune before writing new file
+    cleanPastedDir({ dir });
+    const fileName = `${crypto.randomUUID()}${PASTE_IMAGE_EXTENSIONS[mime]}`;
+    const filePath = path.join(dir, fileName);
+    fs.writeFileSync(filePath, buf, { mode: 0o600, flag: 'wx' });
+    try {
+        fs.chmodSync(filePath, 0o600);
+    }
+    catch {
+        // The file was created 0600 already; chmod only guards against a lax umask.
+    }
+    // Prune again after writing to strictly observe count/size ceiling
+    cleanPastedDir({ dir });
+    return filePath;
+}
+export { cleanPastedDir, savePastedFile };

package/dist/paths.js

@@ -0,0 +1,62 @@
+// Where herdr-remote keeps its files: the package itself, the configuration
+// directory and the state directory.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Locate the package directory by walking up to our own package.json.
+ *
+ * This module runs from src/ under the tests and from dist/ once built.
+ * Everything that matters — the plugin manifest, the host connector entry
+ * point, the systemd unit's ExecStart — is resolved from this value, so it has
+ * to be independent of where the code happens to be loaded from.
+ */
+function findPackageRoot(start) {
+    let directory = start;
+    for (let depth = 0; depth < 8; depth += 1) {
+        const candidate = path.join(directory, 'package.json');
+        try {
+            if (JSON.parse(fs.readFileSync(candidate, 'utf8')).name === 'herdr-remote')
+                return directory;
+        }
+        catch {
+            // Keep climbing: a missing or unrelated package.json is expected.
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return path.resolve(start, '..');
+}
+const PACKAGE_ROOT = findPackageRoot(import.meta.dirname);
+/**
+ * The canonical configuration directory.
+ *
+ * Deliberately NOT $HERDR_PLUGIN_CONFIG_DIR: Herdr sets that variable only when
+ * it launches the plugin itself, so honouring it would give "herdr-remote" run
+ * from a shell and the same tool run from a Herdr pane two different config
+ * files. One path, one config; `migrateLegacyConfig()` imports the old one.
+ */
+function configDir() {
+    return process.env.HERDR_REMOTE_CONFIG_DIR || path.join(os.homedir(), '.config', 'herdr-remote');
+}
+function stateDir() {
+    return (process.env.HERDR_REMOTE_STATE_DIR || path.join(os.homedir(), '.local', 'state', 'herdr-remote'));
+}
+function configPath() {
+    return path.join(configDir(), 'config.json');
+}
+function runtimeStatePath() {
+    return path.join(stateDir(), 'runtime.json');
+}
+/** Where a service (relay, host, supervisor) writes its output. */
+function logPath(name) {
+    return path.join(stateDir(), `${name}.log`);
+}
+function legacyConfigPath() {
+    return process.env.HERDR_PLUGIN_CONFIG_DIR
+        ? path.join(process.env.HERDR_PLUGIN_CONFIG_DIR, 'config.json')
+        : null;
+}
+export { PACKAGE_ROOT, configDir, stateDir, configPath, runtimeStatePath, logPath, legacyConfigPath, };

package/dist/pty-session.js

@@ -0,0 +1,96 @@
+import os from 'node:os';
+import pty from 'node-pty';
+class PtySession {
+    static DEFAULT_COLS = 100;
+    static DEFAULT_ROWS = 30;
+    static MIN_DIMENSION = 2;
+    static MAX_DIMENSION = 500;
+    command;
+    args;
+    cwd;
+    socketPath;
+    terminal;
+    startedAt;
+    constructor({ command, args = [], cwd = os.homedir(), socketPath } = {}) {
+        if (typeof command !== 'string' || command.length === 0)
+            throw new TypeError('command must be a non-empty string');
+        if (!Array.isArray(args) || !args.every((arg) => typeof arg === 'string'))
+            throw new TypeError('args must be strings');
+        this.command = command;
+        this.args = args;
+        this.cwd = cwd;
+        this.socketPath = socketPath;
+        this.terminal = null;
+        this.startedAt = null;
+    }
+    static childEnv(socketPath) {
+        const env = { ...process.env };
+        for (const key of Object.keys(env)) {
+            if (key.startsWith('HERDR_'))
+                delete env[key];
+        }
+        if (socketPath)
+            env.HERDR_SOCKET_PATH = socketPath;
+        env.TERM = 'xterm-256color';
+        env.COLORTERM = 'truecolor';
+        return env;
+    }
+    static clampDimension(value, fallback) {
+        const numeric = Number(value);
+        if (!Number.isInteger(numeric))
+            return fallback;
+        return Math.min(PtySession.MAX_DIMENSION, Math.max(PtySession.MIN_DIMENSION, numeric));
+    }
+    start({ cols, rows, onData, onExit }) {
+        if (this.terminal)
+            throw new Error('PTY session already started');
+        this.terminal = pty.spawn(this.command, this.args, {
+            name: 'xterm-256color',
+            cols: PtySession.clampDimension(cols, PtySession.DEFAULT_COLS),
+            rows: PtySession.clampDimension(rows, PtySession.DEFAULT_ROWS),
+            cwd: this.cwd,
+            env: PtySession.childEnv(this.socketPath),
+        });
+        this.startedAt = new Date().toISOString();
+        const terminal = this.terminal;
+        if (onData)
+            terminal.onData(onData);
+        if (onExit) {
+            terminal.onExit((event) => {
+                this.terminal = null;
+                onExit(event);
+            });
+        }
+        return this;
+    }
+    write(data) {
+        if (!this.terminal)
+            return;
+        this.terminal.write(Buffer.isBuffer(data) ? data.toString('utf8') : String(data));
+    }
+    resize(cols, rows) {
+        if (!this.terminal)
+            return;
+        this.terminal.resize(PtySession.clampDimension(cols, PtySession.DEFAULT_COLS), PtySession.clampDimension(rows, PtySession.DEFAULT_ROWS));
+    }
+    info() {
+        return {
+            pid: this.terminal?.pid || null,
+            command: this.command,
+            cols: this.terminal?.cols || null,
+            rows: this.terminal?.rows || null,
+            cwd: this.cwd,
+            createdAt: this.startedAt,
+        };
+    }
+    kill() {
+        try {
+            this.terminal?.kill();
+        }
+        catch {
+            // The process has already exited.
+        }
+        this.terminal = null;
+    }
+}
+export { PtySession };

package/dist/relay-client.js

@@ -0,0 +1,106 @@
+// Talking to a relay's HTTP API from this workstation: health, status, pairing.
+import http from 'node:http';
+import https from 'node:https';
+import { resolveAdminOrigin } from './relay-urls.js';
+import { ensureRuntime } from './runtime.js';
+/**
+ * Minimal JSON client. Picks http or https from the URL: a self-hosted relay is
+ * reached over https, while the local relay is plain http on loopback.
+ */
+export function requestJson(urlString, options = {}) {
+    return new Promise((resolve, reject) => {
+        let url;
+        try {
+            url = new URL(urlString);
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        const transport = url.protocol === 'https:' ? https : http;
+        const request = transport.request(url, {
+            method: options.method || 'GET',
+            headers: options.headers || {},
+            timeout: options.timeout || 1500,
+        }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => chunks.push(chunk));
+            response.on('end', () => {
+                const text = Buffer.concat(chunks).toString('utf8');
+                let body;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = { raw: text };
+                }
+                const status = response.statusCode || 0;
+                if (status >= 400) {
+                    const error = new Error(typeof body.message === 'string' ? body.message : `HTTP ${status}`);
+                    error.statusCode = status;
+                    error.body = body;
+                    reject(error);
+                }
+                else
+                    resolve(body);
+            });
+        });
+        request.on('timeout', () => request.destroy(new Error('request timed out')));
+        request.on('error', reject);
+        if (options.body)
+            request.write(options.body);
+        request.end();
+    });
+}
+export function healthUrl(config) {
+    return `${resolveAdminOrigin(config)}/healthz`;
+}
+/** This workstation's own credentials, which scope a relay's answers to it. */
+export function hostHeaders() {
+    const state = ensureRuntime();
+    return { 'X-Herdr-Host-Id': state.hostId, 'X-Herdr-Host-Token': state.hostToken };
+}
+export async function waitForRelay(config, { attempts = 20, delayMs = 100 } = {}) {
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            return await requestJson(healthUrl(config), { timeout: 800 });
+        }
+        catch (error) {
+            lastError = error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    throw lastError || new Error('relay did not become ready');
+}
+export async function waitForHost(config, { attempts = 30, delayMs = 100 } = {}) {
+    const headers = hostHeaders();
+    const hostId = headers['X-Herdr-Host-Id'];
+    const statusEndpoint = `${resolveAdminOrigin(config)}/api/status`;
+    let lastStatus = null;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            lastStatus = await requestJson(statusEndpoint, {
+                timeout: 800,
+                headers,
+            });
+            if (lastStatus.hosts?.some((host) => host.id === hostId))
+                return lastStatus;
+        }
+        catch (error) {
+            lastStatus = { ok: false, message: error.message };
+        }
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    const error = new Error(lastStatus?.message || 'the Herdr host connector did not register with the relay');
+    error.health = lastStatus;
+    throw error;
+}
+export function extractPairingCode(response) {
+    const answer = response;
+    const code = answer?.code || answer?.pairCode;
+    if (typeof code !== 'string' || code.length === 0) {
+        throw new Error('the relay response did not contain a valid pairing code');
+    }
+    return code;
+}