herdr-remote-relay 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dibin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# herdr-remote-relay
+
+Standalone relay server for [Herdr Remote](https://www.npmjs.com/package/herdr-remote):
+it serves the mobile web terminal and brokers browser ↔ workstation sessions.
+
+Its only runtime dependency is `ws`, so the machine running it needs no
+compiler, no Herdr and no plugin. It never runs a shell and never touches your
+Herdr socket — only the host connector on your own workstation does that.
+
+**You usually do not need to install this yourself.** `herdr-remote` starts a
+relay locally unless you point it at one you host. Install this package only
+when you want to reach your workstation from outside your own network.
+
+```bash
+npm install -g herdr-remote-relay
+herdr-remote-relay --public-url https://herdr.example.com \
+  --password your-password --admin-token your-long-random-admin-token \
+  --trust-proxy
+```
+
+Requirements: Node.js 22+, a domain name, and TLS. Terminate TLS in a reverse
+proxy in front of the relay — nginx, Caddy, Traefik and Cloudflare Tunnel all
+work. Example configs for nginx, Cloudflare Tunnel, systemd and Docker Compose
+ship in `deploy/` inside this package.
+
+## Docker
+
+```bash
+docker run -d --name herdr-relay --restart unless-stopped \
+  -p 127.0.0.1:8787:8787 \
+  -v herdr-relay:/data \
+  -e RELAY_BIND=0.0.0.0 \
+  -e RELAY_PUBLIC_URL=https://herdr.example.com \
+  -e RELAY_PASSWORD=your-password \
+  -e RELAY_ADMIN_TOKEN=your-long-random-admin-token \
+  -e RELAY_TRUST_PROXY=1 \
+  -e RELAY_AUTH_STATE_FILE=/data/relay-auth.json \
+  node:22-alpine npx -y herdr-remote-relay
+```
+
+## Options
+
+Every setting has a flag, an environment variable and a JSON config file key
+(`--config`, or `HERDR_RELAY_CONFIG`). Precedence runs defaults → file →
+environment → flags.
+
+| Variable | Default | |
+|---|---|---|
+| `RELAY_PUBLIC_URL` | `http://127.0.0.1:8787` | URL browsers open |
+| `RELAY_PASSWORD` | *(none)* | Password a workstation must present. **Empty = public relay** |
+| `RELAY_ADMIN_TOKEN` | *(none)* | Operator token for the relay dashboard at `/admin` |
+| `RELAY_BIND` | `127.0.0.1` | Listen address (`0.0.0.0` in Docker) |
+| `RELAY_PORT` | `8787` | Listen port |
+| `RELAY_TRUST_PROXY` | `0` | Set to `1` behind a reverse proxy |
+| `RELAY_AUTH_STATE_FILE` | `~/.local/state/herdr-remote-relay/relay-auth.json` | Device records |
+| `RELAY_ALLOWED_ORIGINS` | *(same-origin)* | Extra browser origins, comma separated |
+| `RELAY_MAX_CLIENTS_PER_HOST` | `16` | Browsers per workstation |
+| `RELAY_DEPLOYMENT_MODE` | `remote` | `local` is reserved for the workstation-managed relay |
+
+Whatever proxy you put in front must forward WebSocket upgrades and must not
+time out idle connections — a terminal is idle between keystrokes.
+
+## Public relays
+
+Leaving `RELAY_PASSWORD` empty makes the relay public: anyone may connect a
+workstation to it. That is safe to share, because each workstation is reachable
+only through its own host token — generated on that machine, never handed out
+by the relay. Nobody else can pair a device to your terminal.
+
+What a public relay does give away is bandwidth and the fact that your
+workstation is online. Set a password if that matters.
+
+## Connect a workstation
+
+On the workstation, run `herdr-remote`, open the **Relay** tab and set the
+access mode to **Self-hosted relay**, the relay URL to
+`wss://herdr.example.com`, and the relay password to the same `RELAY_PASSWORD`.
+Then check:
+
+```bash
+curl https://herdr.example.com/healthz    # hosts should be 1
+```
+
+| Symptom | Cause |
+|---|---|
+| `hosts: 0` | Workstation not connected — check `herdr-remote status` |
+| `relay_password_required` | Password differs between the two sides |
+| Page loads, terminal never opens | Proxy is not forwarding `Upgrade` headers |
+| Drops after ~60s idle | Proxy read timeout too short |
+
+## Security
+
+- Tokens are stored as SHA-256 hashes, never in clear text. Terminal content is
+  never written to disk.
+- Pairing codes are single-use, expire in ten minutes, and are rate limited.
+- The `/admin` operator credential is separate from the workstation join
+  password and from paired device tokens.
+- Losing the state file just means re-pairing your devices.
+
+## License
+
+MIT

package/bin/herdr-remote-relay.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+'use strict';
+
+// 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.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadRelayConfig, PACKAGE_ROOT } = require('../src/relay-config');
+const { RelayServer, VERSION, PROTOCOL_VERSION } = require('../src/relay-server');
+
+const USAGE = `herdr-remote-relay ${VERSION} — standalone relay for Herdr Remote
+
+Usage: herdr-remote-relay [options]
+
+Options:
+  --password <password>      Password a workstation must present (RELAY_PASSWORD).
+                             Leave unset for a public relay.
+  --admin-token <token>      Operator token for the relay dashboard (RELAY_ADMIN_TOKEN).
+  --deployment-mode <mode>   WebUI deployment mode: local or remote (default remote).
+  --public-url <url>         Public URL browsers use (RELAY_PUBLIC_URL)
+  --bind <address>           Listen address (default 127.0.0.1, RELAY_BIND)
+  --port <number>            Listen port (default 8787, RELAY_PORT)
+  --trust-proxy              Read X-Forwarded-For for rate limiting (RELAY_TRUST_PROXY)
+  --state-file <file>        Where device/host records are stored (RELAY_AUTH_STATE_FILE)
+  --allowed-origins <list>   Extra comma-separated browser origins (RELAY_ALLOWED_ORIGINS)
+  --max-clients <number>     Max browsers per workstation (RELAY_MAX_CLIENTS_PER_HOST)
+  --config <file>            JSON config file (also HERDR_RELAY_CONFIG)
+  -h, --help                 Show this help
+  -v, --version              Show the version
+
+See 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'));
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`herdr-remote-relay: ${error.stack || error.message}\n`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { main, USAGE };

package/config.example.json

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

package/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/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/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/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/deploy/systemd/relay.env.example

@@ -0,0 +1,20 @@
+# 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
+
+# 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/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "herdr-remote-relay",
+  "version": "0.2.0",
+  "description": "Standalone relay server for Herdr Remote: serves the mobile web terminal and brokers browser <-> workstation sessions",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dibin666/herdr-remote.git",
+    "directory": "packages/relay"
+  },
+  "homepage": "https://github.com/dibin666/herdr-remote#readme",
+  "bugs": {
+    "url": "https://github.com/dibin666/herdr-remote/issues"
+  },
+  "keywords": [
+    "herdr",
+    "relay",
+    "terminal",
+    "websocket",
+    "remote"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "herdr-remote-relay": "./bin/herdr-remote-relay.js"
+  },
+  "main": "./src/relay-server.js",
+  "exports": {
+    ".": "./src/relay-server.js",
+    "./protocol": "./src/stream-frame.js",
+    "./config": "./src/relay-config.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "web/dist",
+    "deploy",
+    "config.example.json"
+  ],
+  "scripts": {
+    "build": "npm --prefix web run build",
+    "start": "node bin/herdr-remote-relay.js",
+    "test": "node --test tests/*.test.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  }
+}

package/src/auth-store.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { randomToken, readJson, writeJsonAtomic, ensureDir } = require('./state');
+
+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();
+}
+
+class AuthStore {
+  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.pairings = new Map();
+    this.lastDeviceSaveAt = new Map();
+    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(require('node: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 (typeof hostId !== 'string' || hostId.length < 1 || hostId.length > 128 || typeof token !== 'string' || token.length < 16) {
+      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 (typeof hostId !== 'string' || typeof token !== 'string' || token.length < 16) 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 (!this.state.hosts[hostId]) {
+      const error = new Error('host is not connected or enrolled');
+      error.code = 'host_not_found';
+      throw error;
+    }
+    this.cleanup(now);
+    let code;
+    do {
+      code = randomToken(4).toUpperCase().replace(/[-_]/g, '').slice(0, 6);
+    } while ([...this.pairings.values()].some((pairing) => 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 || 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 };
+  }
+
+  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;
+  }
+}
+
+module.exports = { AuthStore, hash, equalHash, nowIso };