herdr-remote 0.2.32 → 0.2.34

package/node_modules/herdr-remote-relay/bin/herdr-remote-relay.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+// Standalone entry point for the Herdr Remote relay.
+//
+// This binary has no knowledge of the herdr-remote plugin: it can be installed
+// and run on its own host (`npm i -g herdr-remote-relay`) with nothing but
+// environment variables for configuration.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadRelayConfig, PACKAGE_ROOT } from '../dist/relay-config.js';
+import { RelayServer, VERSION, PROTOCOL_VERSION } from '../dist/relay-server.js';
+
+const USAGE = `herdr-remote-relay ${VERSION} — standalone relay for Herdr Remote
+
+Usage: herdr-remote-relay [options]
+
+Options:
+  --password <password>      Workstation password (RELAY_PASSWORD, empty for public)
+  --admin-token <token>      Admin dashboard token (RELAY_ADMIN_TOKEN)
+  --deployment-mode <mode>   Deployment mode: local or remote (default remote)
+  --public-url <url>         Public URL for browsers (RELAY_PUBLIC_URL)
+  --bind <address>           Listen address (default 127.0.0.1, RELAY_BIND)
+  --port <number>            Listen port (default 8787, RELAY_PORT)
+  --trust-proxy              Trust X-Forwarded-For headers (RELAY_TRUST_PROXY)
+  --state-file <file>        Auth state file path (RELAY_AUTH_STATE_FILE)
+  --allowed-origins <list>   Allowed browser origins, comma-separated
+  --max-clients <number>     Max clients per workstation (default 16)
+  --max-hosts <number>       Max workstations on this relay (default 1024)
+  --max-pending-handshakes <n> Max unauthenticated WebSockets (default 1024)
+  --max-buffered-bytes <n>   Max queued bytes per browser (default 4194304)
+  --host-reconnect-grace-ms <n> Grace period for host handoff (default 30000)
+  --config <file>            JSON config file (HERDR_RELAY_CONFIG)
+  -h, --help                 Show help
+  -v, --version              Show version
+
+Guide: docs/self-hosted-relay.md
+`;
+
+function webUiBuilt() {
+  return fs.existsSync(path.join(PACKAGE_ROOT, 'web', 'dist', 'index.html'));
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let loaded;
+  try {
+    loaded = loadRelayConfig({ argv });
+  } catch (error) {
+    process.stderr.write(`herdr-remote-relay: ${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const { config, help, version, errors, warnings, configFile } = loaded;
+
+  if (help) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (version) {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+  if (errors.length > 0) {
+    for (const message of errors) process.stderr.write(`herdr-remote-relay: ${message}\n`);
+    process.stderr.write(USAGE);
+    process.exitCode = 2;
+    return;
+  }
+
+  const server = new RelayServer(config);
+  let address;
+  try {
+    address = await server.listen(config.relay.port, config.relay.host);
+  } catch (error) {
+    const hint =
+      error.code === 'EADDRINUSE'
+        ? ` (port ${config.relay.port} is already in use)`
+        : error.code === 'EACCES'
+          ? ` (no permission to bind port ${config.relay.port})`
+          : '';
+    process.stderr.write(`herdr-remote-relay: failed to listen${hint}: ${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write(`herdr-remote-relay ${VERSION} (protocol ${PROTOCOL_VERSION})\n`);
+  process.stdout.write(`  listening   http://${config.relay.host}:${address.port}\n`);
+  process.stdout.write(`  public url  ${config.relay.publicUrl}\n`);
+  process.stdout.write(
+    `  password    ${config.auth.password ? 'set' : 'not set (public relay)'}\n`,
+  );
+  process.stdout.write(
+    `  admin       ${config.auth.adminToken ? 'set (/admin)' : 'not configured'}\n`,
+  );
+  process.stdout.write(`  state file  ${server.stateFile}\n`);
+  if (configFile) process.stdout.write(`  config file ${configFile}\n`);
+  if (!webUiBuilt()) {
+    process.stdout.write('  web ui      NOT BUILT (run "npm run build" in this package)\n');
+  }
+  for (const warning of warnings) process.stdout.write(`  warning: ${warning}\n`);
+
+  let closing = false;
+  const stop = (signal) => {
+    if (closing) return;
+    closing = true;
+    process.stdout.write(`herdr-remote-relay: ${signal} received, shutting down\n`);
+    server.close().finally(() => process.exit(0));
+  };
+  process.on('SIGINT', () => stop('SIGINT'));
+  process.on('SIGTERM', () => stop('SIGTERM'));
+}
+
+main().catch((error) => {
+  process.stderr.write(`herdr-remote-relay: ${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/node_modules/herdr-remote-relay/config.example.json

@@ -0,0 +1,18 @@
+{
+  "relay": {
+    "mode": "remote",
+    "host": "127.0.0.1",
+    "port": 8787,
+    "publicUrl": "https://herdr.example.com",
+    "trustProxy": true,
+    "maxHosts": 1024,
+    "maxPendingHandshakes": 1024,
+    "maxBufferedBytesPerClient": 4194304,
+    "hostReconnectGraceMs": 30000
+  },
+  "auth": {
+    "password": "change-me",
+    "adminToken": "replace-with-a-long-random-operator-token",
+    "stateFile": "/var/lib/herdr-remote-relay/relay-auth.json"
+  }
+}

package/node_modules/herdr-remote-relay/deploy/cloudflared/config.yml.example

@@ -0,0 +1,9 @@
+# Copy this file to ~/.cloudflared/config.yml after creating a named tunnel.
+# The relay itself remains bound to 127.0.0.1.
+tunnel: YOUR_TUNNEL_UUID
+credentials-file: /home/YOUR_USER/.cloudflared/YOUR_TUNNEL_UUID.json
+
+ingress:
+  - hostname: herdr.example.com
+    service: http://127.0.0.1:8787
+  - service: http_status:404

package/node_modules/herdr-remote-relay/deploy/docker/compose.yaml

@@ -0,0 +1,23 @@
+# Put your own reverse proxy (nginx, Caddy, Traefik, Cloudflare Tunnel…) in
+# front of port 8787 and terminate TLS there.
+
+services:
+  relay:
+    image: node:22-alpine
+    command: npx -y herdr-remote-relay
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:8787:8787"
+    environment:
+      RELAY_BIND: 0.0.0.0
+      RELAY_PORT: "8787"
+      RELAY_PUBLIC_URL: https://herdr.example.com
+      # Leave empty for a public relay.
+      RELAY_PASSWORD: change-me
+      RELAY_TRUST_PROXY: "1"
+      RELAY_AUTH_STATE_FILE: /data/relay-auth.json
+    volumes:
+      - relay-state:/data
+
+volumes:
+  relay-state:

package/node_modules/herdr-remote-relay/deploy/nginx/herdr-remote-relay.conf.example

@@ -0,0 +1,49 @@
+# nginx site for a self-hosted relay. Obtain the certificate first, e.g. with
+#   sudo certbot --nginx -d herdr.example.com
+
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name herdr.example.com;
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+    http2 on;
+    server_name herdr.example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/herdr.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/herdr.example.com/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:8787;
+        proxy_http_version 1.1;
+
+        # Required for /ws/host and /ws/client. Without these the browser falls
+        # back to nothing: the terminal never opens.
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+
+        proxy_set_header Host $host;
+        # The relay checks the Origin header against the request Host, and rate
+        # limits pairing per client address.
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # A terminal can sit idle for a long time between keystrokes; the
+        # default 60s would drop the session.
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+
+        # Terminal output must arrive as it is produced.
+        proxy_buffering off;
+    }
+}

package/node_modules/herdr-remote-relay/deploy/systemd/herdr-remote-relay.service

@@ -0,0 +1,41 @@
+# System-wide unit for a self-hosted relay.
+#
+#   sudo cp herdr-remote-relay.service /etc/systemd/system/
+#   sudo useradd --system --home /var/lib/herdr-remote-relay --create-home herdr-relay
+#   sudo install -m 600 -o herdr-relay -g herdr-relay relay.env /etc/herdr-remote-relay.env
+#   sudo systemctl enable --now herdr-remote-relay
+
+[Unit]
+Description=Herdr Remote relay
+Documentation=https://github.com/herdr/herdr-remote
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=herdr-relay
+Group=herdr-relay
+# Tokens live here, not on the command line, where `ps` would expose them.
+EnvironmentFile=/etc/herdr-remote-relay.env
+ExecStart=/usr/bin/npx herdr-remote-relay
+Restart=always
+RestartSec=3
+StateDirectory=herdr-remote-relay
+WorkingDirectory=/var/lib/herdr-remote-relay
+
+# The relay reads no user files and runs no subprocesses; it only needs its own
+# state directory and a socket.
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictAddressFamilies=AF_INET AF_INET6
+RestrictNamespaces=true
+LockPersonality=true
+MemoryDenyWriteExecute=false
+
+[Install]
+WantedBy=multi-user.target

package/node_modules/herdr-remote-relay/deploy/systemd/relay.env.example

@@ -0,0 +1,25 @@
+# Copy to /etc/herdr-remote-relay.env with mode 0600.
+
+RELAY_PUBLIC_URL=https://herdr.example.com
+# Standalone/self-hosted relay; the workstation-managed relay sets this to local.
+RELAY_DEPLOYMENT_MODE=remote
+RELAY_BIND=127.0.0.1
+RELAY_PORT=8787
+RELAY_MAX_HOSTS=1024
+RELAY_MAX_PENDING_HANDSHAKES=1024
+RELAY_MAX_CLIENTS_PER_HOST=16
+RELAY_MAX_BUFFERED_BYTES_PER_CLIENT=4194304
+RELAY_HOST_RECONNECT_GRACE_MS=30000
+
+# Password a workstation must present. Leave empty for a public relay.
+RELAY_PASSWORD=change-me
+
+# Credential for the relay operator dashboard at /admin. Keep this separate
+# from RELAY_PASSWORD; it is sent only in X-Relay-Admin-Token.
+RELAY_ADMIN_TOKEN=replace-with-a-long-random-operator-token
+
+# Set when a reverse proxy sits in front, so pairing rate limits key on the
+# real client address instead of the proxy's.
+RELAY_TRUST_PROXY=1
+
+RELAY_AUTH_STATE_FILE=/var/lib/herdr-remote-relay/relay-auth.json

package/node_modules/herdr-remote-relay/dist/auth-store.d.ts

@@ -0,0 +1,114 @@
+import type { PairedDeviceInfo } from './protocol/http.js';
+interface HostRecord {
+    tokenHash: string;
+    createdAt: string;
+    lastSeenAt: string;
+}
+export interface DeviceRecord {
+    deviceId: string;
+    hostId: string;
+    tokenHash: string;
+    createdAt: string;
+    lastSeenAt: string;
+    expiresAt: number;
+    userAgent?: string;
+    lastIp?: string;
+}
+interface AuthState {
+    version: 1;
+    hosts: Record<string, HostRecord>;
+    devices: Record<string, DeviceRecord>;
+}
+interface AuthStoreOptions {
+    stateFile?: string;
+    pairingTtlMs?: number;
+    deviceTtlMs?: number;
+    maxDevices?: number;
+    password?: string | null;
+}
+type RegisterHostResult = {
+    ok: true;
+    hostId: string;
+    firstSeen: boolean;
+} | {
+    ok: false;
+    code: 'invalid_host_credentials' | 'relay_password_required' | 'host_auth_failed';
+    message: string;
+};
+interface PairingStart {
+    code: string;
+    hostId: string;
+    publicUrl: string;
+    expiresAt: number;
+    expiresAtIso: string;
+}
+interface PairingResult {
+    deviceId: string;
+    hostId: string;
+    token: string;
+    expiresAt: number;
+    expiresAtIso: string;
+    publicUrl: string;
+}
+interface RevokedDevice {
+    deviceId: string;
+    hostId: string;
+    userAgent: string | null;
+    lastIp: string | null;
+}
+declare class AuthStore {
+    readonly stateFile: string;
+    readonly pairingTtlMs: number;
+    readonly deviceTtlMs: number;
+    readonly maxDevices: number;
+    readonly password: string | null;
+    private readonly pairings;
+    private readonly lastDeviceSaveAt;
+    state: AuthState;
+    constructor({ stateFile, pairingTtlMs, deviceTtlMs, maxDevices, password, }?: AuthStoreOptions);
+    save(): void;
+    /** Does this request carry the relay password, if one is required at all? */
+    checkPassword(supplied: unknown): boolean;
+    /**
+     * Enrol a workstation, or re-authenticate one that is already enrolled.
+     *
+     * The password (when the relay has one) decides who may *join*. The host
+     * token decides who may act *as a given workstation*: it is generated on the
+     * workstation and only its hash is ever stored here, so even on a public
+     * relay nobody else can impersonate an enrolled host or pair a device to it.
+     */
+    registerHost(hostId: unknown, token: unknown, password?: unknown, now?: number): RegisterHostResult;
+    /** Verify a host token without enrolling anything. */
+    authenticateHost(hostId: unknown, token: unknown): boolean;
+    hostCount(): number;
+    startPairing(hostId: unknown, publicUrl: string, now?: number): PairingStart;
+    completePairing(code: unknown, now?: number): PairingResult | null;
+    /**
+     * Record how a device presented itself, so an operator revoking a device can
+     * tell which phone or laptop they are about to cut off. Only the coarse
+     * user agent string and the address are kept — never terminal content.
+     */
+    noteDeviceSeen(deviceId: string, { userAgent, ip }?: {
+        userAgent?: string | null;
+        ip?: string | null;
+    }, now?: number): DeviceRecord | null;
+    /**
+     * Devices an operator may act on, newest first. Token hashes are never
+     * included: the dashboard has no use for them and they must not leave the
+     * process.
+     */
+    listDevices(now?: number): PairedDeviceInfo[];
+    /**
+     * Permanently invalidate a paired device. The stored hash is dropped, so the
+     * token it was derived from can never authenticate again. Returns the removed
+     * record so the caller can also close whatever sockets it still holds.
+     */
+    revokeDevice(deviceId: unknown): RevokedDevice | null;
+    authenticateDevice(token: unknown, now?: number): DeviceRecord | null;
+    cleanup(now?: number): {
+        removedDevices: number;
+        removedPairings: number;
+    };
+    deviceCount(): number;
+}
+export { AuthStore };

package/node_modules/herdr-remote-relay/dist/auth-store.js

@@ -0,0 +1,289 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { randomToken, readJson, writeJsonAtomic, ensureDir } from './state.js';
+function hash(value) {
+    return crypto.createHash('sha256').update(String(value), 'utf8').digest('hex');
+}
+function equalHash(left, right) {
+    if (typeof left !== 'string' || typeof right !== 'string')
+        return false;
+    const a = Buffer.from(left, 'hex');
+    const b = Buffer.from(right, 'hex');
+    return a.length === b.length && a.length > 0 && crypto.timingSafeEqual(a, b);
+}
+function nowIso(now = Date.now()) {
+    return new Date(now).toISOString();
+}
+function validHostId(value) {
+    return typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value);
+}
+/**
+ * What a person reads off one screen and types on another: six characters,
+ * without 0/O or 1/I/L to confuse. Cutting base64 and dropping its `-` and `_`
+ * made one code in seven shorter than six, and some too short to pair at all.
+ */
+const PAIR_CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+const PAIR_CODE_LENGTH = 6;
+function newPairCode() {
+    let code = '';
+    for (let i = 0; i < PAIR_CODE_LENGTH; i += 1)
+        code += PAIR_CODE_ALPHABET[crypto.randomInt(PAIR_CODE_ALPHABET.length)];
+    return code;
+}
+class AuthStore {
+    stateFile;
+    pairingTtlMs;
+    deviceTtlMs;
+    maxDevices;
+    password;
+    pairings = new Map();
+    lastDeviceSaveAt = new Map();
+    state;
+    constructor({ stateFile, pairingTtlMs = 10 * 60 * 1000, deviceTtlMs = 30 * 24 * 60 * 60 * 1000, maxDevices = 32, password = null, } = {}) {
+        if (!stateFile)
+            throw new TypeError('stateFile is required');
+        this.stateFile = stateFile;
+        this.pairingTtlMs = pairingTtlMs;
+        this.deviceTtlMs = deviceTtlMs;
+        this.maxDevices = maxDevices;
+        // Optional shared password. When unset the relay is public: anyone may
+        // enrol a workstation. That is safe because a workstation is only ever
+        // reachable through its own host token, which the relay never hands out.
+        this.password = password || null;
+        this.state = readJson(stateFile, { version: 1, hosts: {}, devices: {} });
+        this.state.version = 1;
+        this.state.hosts =
+            this.state.hosts && typeof this.state.hosts === 'object' ? this.state.hosts : {};
+        this.state.devices =
+            this.state.devices && typeof this.state.devices === 'object' ? this.state.devices : {};
+        ensureDir(path.dirname(stateFile));
+    }
+    save() {
+        writeJsonAtomic(this.stateFile, this.state);
+    }
+    /** Does this request carry the relay password, if one is required at all? */
+    checkPassword(supplied) {
+        if (!this.password)
+            return true;
+        return typeof supplied === 'string' && equalHash(hash(supplied), hash(this.password));
+    }
+    /**
+     * Enrol a workstation, or re-authenticate one that is already enrolled.
+     *
+     * The password (when the relay has one) decides who may *join*. The host
+     * token decides who may act *as a given workstation*: it is generated on the
+     * workstation and only its hash is ever stored here, so even on a public
+     * relay nobody else can impersonate an enrolled host or pair a device to it.
+     */
+    registerHost(hostId, token, password = null, now = Date.now()) {
+        if (!validHostId(hostId) ||
+            typeof token !== 'string' ||
+            token.length < 16 ||
+            token.length > 4096) {
+            return {
+                ok: false,
+                code: 'invalid_host_credentials',
+                message: 'hostId and token are required',
+            };
+        }
+        if (!this.checkPassword(password)) {
+            return {
+                ok: false,
+                code: 'relay_password_required',
+                message: 'the relay password is missing or wrong',
+            };
+        }
+        const existing = this.state.hosts[hostId];
+        if (existing) {
+            if (!equalHash(existing.tokenHash, hash(token))) {
+                return { ok: false, code: 'host_auth_failed', message: 'host token is invalid' };
+            }
+            existing.lastSeenAt = nowIso(now);
+            this.save();
+            return { ok: true, hostId, firstSeen: false };
+        }
+        this.state.hosts[hostId] = {
+            tokenHash: hash(token),
+            createdAt: nowIso(now),
+            lastSeenAt: nowIso(now),
+        };
+        this.save();
+        return { ok: true, hostId, firstSeen: true };
+    }
+    /** Verify a host token without enrolling anything. */
+    authenticateHost(hostId, token) {
+        if (!validHostId(hostId) ||
+            typeof token !== 'string' ||
+            token.length < 16 ||
+            token.length > 4096)
+            return false;
+        const existing = this.state.hosts[hostId];
+        return Boolean(existing) && equalHash(existing.tokenHash, hash(token));
+    }
+    hostCount() {
+        return Object.keys(this.state.hosts).length;
+    }
+    startPairing(hostId, publicUrl, now = Date.now()) {
+        if (!validHostId(hostId) || !this.state.hosts[hostId]) {
+            throw Object.assign(new Error('host is not connected or enrolled'), {
+                code: 'host_not_found',
+            });
+        }
+        this.cleanup(now);
+        let code;
+        do {
+            code = newPairCode();
+        } while ([...this.pairings.values()].some((pairing) => equalHash(pairing.codeHash, hash(code))));
+        const expiresAt = now + this.pairingTtlMs;
+        this.pairings.set(code, {
+            codeHash: hash(code),
+            hostId,
+            expiresAt,
+            publicUrl,
+        });
+        return { code, hostId, publicUrl, expiresAt, expiresAtIso: nowIso(expiresAt) };
+    }
+    completePairing(code, now = Date.now()) {
+        if (typeof code !== 'string' || code.length < 4 || code.length > 32)
+            return null;
+        this.cleanup(now);
+        const normalized = code.trim().toUpperCase();
+        const pairing = this.pairings.get(normalized);
+        if (!pairing || pairing.expiresAt <= now || !equalHash(pairing.codeHash, hash(normalized)))
+            return null;
+        this.pairings.delete(normalized);
+        const devices = Object.values(this.state.devices);
+        if (devices.length >= this.maxDevices) {
+            devices.sort((a, b) => (a.lastSeenAt || '').localeCompare(b.lastSeenAt || ''));
+            delete this.state.devices[devices[0].deviceId];
+        }
+        const deviceId = `device-${randomToken(9)}`;
+        const token = randomToken(32);
+        const expiresAt = now + this.deviceTtlMs;
+        this.state.devices[deviceId] = {
+            deviceId,
+            hostId: pairing.hostId,
+            tokenHash: hash(token),
+            createdAt: nowIso(now),
+            lastSeenAt: nowIso(now),
+            expiresAt,
+        };
+        this.save();
+        return {
+            deviceId,
+            hostId: pairing.hostId,
+            token,
+            expiresAt,
+            expiresAtIso: nowIso(expiresAt),
+            publicUrl: pairing.publicUrl,
+        };
+    }
+    /**
+     * Record how a device presented itself, so an operator revoking a device can
+     * tell which phone or laptop they are about to cut off. Only the coarse
+     * user agent string and the address are kept — never terminal content.
+     */
+    noteDeviceSeen(deviceId, { userAgent, ip } = {}, now = Date.now()) {
+        const device = this.state.devices[deviceId];
+        if (!device)
+            return null;
+        let changed = false;
+        if (userAgent && device.userAgent !== userAgent) {
+            device.userAgent = String(userAgent).slice(0, 256);
+            changed = true;
+        }
+        if (ip && device.lastIp !== ip) {
+            device.lastIp = String(ip).slice(0, 64);
+            changed = true;
+        }
+        device.lastSeenAt = nowIso(now);
+        if (changed)
+            this.save();
+        return { ...device };
+    }
+    /**
+     * Devices an operator may act on, newest first. Token hashes are never
+     * included: the dashboard has no use for them and they must not leave the
+     * process.
+     */
+    listDevices(now = Date.now()) {
+        return Object.values(this.state.devices)
+            .filter((device) => device && device.expiresAt > now)
+            .map((device) => ({
+            deviceId: device.deviceId,
+            hostId: device.hostId,
+            createdAt: device.createdAt,
+            lastSeenAt: device.lastSeenAt,
+            expiresAt: device.expiresAt,
+            expiresAtIso: nowIso(device.expiresAt),
+            userAgent: device.userAgent || null,
+            lastIp: device.lastIp || null,
+        }))
+            .sort((a, b) => String(b.lastSeenAt || '').localeCompare(String(a.lastSeenAt || '')));
+    }
+    /**
+     * Permanently invalidate a paired device. The stored hash is dropped, so the
+     * token it was derived from can never authenticate again. Returns the removed
+     * record so the caller can also close whatever sockets it still holds.
+     */
+    revokeDevice(deviceId) {
+        if (typeof deviceId !== 'string' || !deviceId)
+            return null;
+        const device = this.state.devices[deviceId];
+        if (!device)
+            return null;
+        delete this.state.devices[deviceId];
+        this.lastDeviceSaveAt.delete(deviceId);
+        this.save();
+        return {
+            deviceId: device.deviceId,
+            hostId: device.hostId,
+            userAgent: device.userAgent || null,
+            lastIp: device.lastIp || null,
+        };
+    }
+    authenticateDevice(token, now = Date.now()) {
+        if (typeof token !== 'string' || token.length < 16)
+            return null;
+        const tokenHash = hash(token);
+        for (const device of Object.values(this.state.devices)) {
+            if (device.expiresAt <= now)
+                continue;
+            if (!equalHash(device.tokenHash, tokenHash))
+                continue;
+            device.lastSeenAt = nowIso(now);
+            device.expiresAt = now + this.deviceTtlMs;
+            const lastSaveAt = this.lastDeviceSaveAt.get(device.deviceId) || 0;
+            if (now - lastSaveAt >= 60 * 1000) {
+                this.lastDeviceSaveAt.set(device.deviceId, now);
+                this.save();
+            }
+            return { ...device };
+        }
+        return null;
+    }
+    cleanup(now = Date.now()) {
+        let removedDevices = 0;
+        for (const [deviceId, device] of Object.entries(this.state.devices)) {
+            if (!device || device.expiresAt <= now) {
+                delete this.state.devices[deviceId];
+                this.lastDeviceSaveAt.delete(deviceId);
+                removedDevices += 1;
+            }
+        }
+        let removedPairings = 0;
+        for (const [code, pairing] of this.pairings.entries()) {
+            if (pairing.expiresAt <= now) {
+                this.pairings.delete(code);
+                removedPairings += 1;
+            }
+        }
+        if (removedDevices)
+            this.save();
+        return { removedDevices, removedPairings };
+    }
+    deviceCount() {
+        return Object.keys(this.state.devices).length;
+    }
+}
+export { AuthStore };