herdr-remote-relay 0.3.12 → 0.3.13

package/src/auth-store.js

@@ -1,256 +0,0 @@
-'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();
-}
-
-function validHostId(value) {
-  return typeof value === 'string'
-    && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value);
-}
-
-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 (!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]) {
-      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) => 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;
-  }
-}
-
-module.exports = { AuthStore, hash, equalHash, nowIso };

package/src/metrics.js

@@ -1,241 +0,0 @@
-'use strict';
-
-const os = require('node:os');
-const { monitorEventLoopDelay } = require('node:perf_hooks');
-
-function finite(value, fallback = 0) {
-  return Number.isFinite(value) ? value : fallback;
-}
-
-function bytesPerSecond(current, previous, elapsedMs) {
-  if (!elapsedMs || elapsedMs <= 0) return 0;
-  return Math.max(0, (current - previous) * 1000 / elapsedMs);
-}
-
-/**
- * How many people are attached, rather than how many sockets are open.
- *
- * A phone and a laptop belonging to one person are two connections but one
- * paired device each, and one person opening three browser windows is three
- * connections and one device — so the distinct paired device is the closest
- * thing the relay has to a user. Connections that predate device pairing carry
- * no `deviceId`; they fall back to their own connection id so they still count
- * once instead of collapsing into a single anonymous user.
- */
-function countActiveUsers(clients = []) {
-  const identities = new Set();
-  for (const client of clients) {
-    if (!client) continue;
-    identities.add(
-      typeof client.deviceId === 'string' && client.deviceId
-        ? `device:${client.deviceId}`
-        : `client:${client.id}`
-    );
-  }
-  return identities.size;
-}
-
-class RelayMetrics {
-  constructor({ version = '0.1.0', protocolVersion = 1 } = {}) {
-    this.version = version;
-    this.protocolVersion = protocolVersion;
-    this.startedAt = Date.now();
-    this.bytesIn = 0;
-    this.bytesOut = 0;
-    this.framesIn = 0;
-    this.framesOut = 0;
-    this.cleanup = {
-      staleClientsPurged: 0,
-      closedPtysCleaned: 0,
-      deadConnectionsClosed: 0,
-      idleHostsTerminated: 0,
-      slowClientsDropped: 0,
-      lastCleanupAt: null,
-    };
-    this.lastSample = { at: this.startedAt, bytesIn: 0, bytesOut: 0, framesIn: 0, framesOut: 0 };
-    this.hostTraffic = new Map();
-    this.cpuSampleAt = process.hrtime.bigint();
-    this.cpuSample = process.cpuUsage();
-    this.eventLoop = monitorEventLoopDelay({ resolution: 20 });
-    this.eventLoop.enable();
-  }
-
-  hostCounter(hostId) {
-    if (typeof hostId !== 'string' || hostId.length === 0) return null;
-    let counter = this.hostTraffic.get(hostId);
-    if (!counter) {
-      counter = {
-        bytesIn: 0,
-        bytesOut: 0,
-        framesIn: 0,
-        framesOut: 0,
-        sampleAt: Date.now(),
-        sampleBytesIn: 0,
-        sampleBytesOut: 0,
-        sampleFramesIn: 0,
-        sampleFramesOut: 0,
-      };
-      this.hostTraffic.set(hostId, counter);
-    }
-    return counter;
-  }
-
-  recordIn(bytes, hostId = null) {
-    const amount = Math.max(0, Number(bytes) || 0);
-    this.bytesIn += amount;
-    this.framesIn += 1;
-    const counter = this.hostCounter(hostId);
-    if (counter) {
-      counter.bytesIn += amount;
-      counter.framesIn += 1;
-    }
-  }
-
-  recordOut(bytes, hostId = null) {
-    const amount = Math.max(0, Number(bytes) || 0);
-    this.bytesOut += amount;
-    this.framesOut += 1;
-    const counter = this.hostCounter(hostId);
-    if (counter) {
-      counter.bytesOut += amount;
-      counter.framesOut += 1;
-    }
-  }
-
-  forgetHost(hostId) {
-    if (typeof hostId === 'string') this.hostTraffic.delete(hostId);
-  }
-
-  hostThroughput(hostId, now = Date.now()) {
-    const counter = this.hostCounter(hostId);
-    if (!counter) return {
-      bytesIn: 0,
-      bytesOut: 0,
-      bytesInPerSec: 0,
-      bytesOutPerSec: 0,
-      framesIn: 0,
-      framesOut: 0,
-      framesInPerSec: 0,
-      framesOutPerSec: 0,
-    };
-    const elapsedMs = now - counter.sampleAt;
-    const throughput = {
-      bytesIn: counter.bytesIn,
-      bytesOut: counter.bytesOut,
-      bytesInPerSec: bytesPerSecond(counter.bytesIn, counter.sampleBytesIn, elapsedMs),
-      bytesOutPerSec: bytesPerSecond(counter.bytesOut, counter.sampleBytesOut, elapsedMs),
-      framesIn: counter.framesIn,
-      framesOut: counter.framesOut,
-      framesInPerSec: bytesPerSecond(counter.framesIn, counter.sampleFramesIn, elapsedMs),
-      framesOutPerSec: bytesPerSecond(counter.framesOut, counter.sampleFramesOut, elapsedMs),
-    };
-    counter.sampleAt = now;
-    counter.sampleBytesIn = counter.bytesIn;
-    counter.sampleBytesOut = counter.bytesOut;
-    counter.sampleFramesIn = counter.framesIn;
-    counter.sampleFramesOut = counter.framesOut;
-    return throughput;
-  }
-
-  recordCleanup(name, amount = 1) {
-    if (Object.prototype.hasOwnProperty.call(this.cleanup, name) && typeof this.cleanup[name] === 'number') {
-      this.cleanup[name] += amount;
-    }
-    this.cleanup.lastCleanupAt = new Date().toISOString();
-  }
-
-  cpuPercent() {
-    const now = process.hrtime.bigint();
-    const elapsedNs = Number(now - this.cpuSampleAt);
-    const usage = process.cpuUsage(this.cpuSample);
-    this.cpuSampleAt = now;
-    this.cpuSample = process.cpuUsage();
-    if (elapsedNs <= 0) return 0;
-    const percent = ((usage.user + usage.system) * 100000) / elapsedNs;
-    return Math.max(0, Math.round(percent * 100) / 100);
-  }
-
-  eventLoopDelay() {
-    const percentile = (value) => Math.round(finite(value / 1e6) * 100) / 100;
-    return {
-      p50Ms: percentile(this.eventLoop.percentile(50)),
-      p90Ms: percentile(this.eventLoop.percentile(90)),
-      p99Ms: percentile(this.eventLoop.percentile(99)),
-      maxMs: percentile(this.eventLoop.max),
-      meanMs: percentile(this.eventLoop.mean),
-    };
-  }
-
-  /**
-   * `activeUserCount` is passed in rather than derived from `clients`: the
-   * public `/api/status` rows deliberately omit `deviceId`, so only the caller
-   * still holding the full connection records can count devices correctly.
-   * Omitting it falls back to counting whatever the given rows identify.
-   */
-  snapshot({ clients = [], hosts = [], ptys = [], sample = true, scopeHostId = null, activeUserCount = null } = {}) {
-    const now = Date.now();
-    const elapsedMs = now - this.lastSample.at;
-    const throughput = {
-      bytesIn: this.bytesIn,
-      bytesOut: this.bytesOut,
-      bytesInPerSec: bytesPerSecond(this.bytesIn, this.lastSample.bytesIn, elapsedMs),
-      bytesOutPerSec: bytesPerSecond(this.bytesOut, this.lastSample.bytesOut, elapsedMs),
-      framesIn: this.framesIn,
-      framesOut: this.framesOut,
-      framesInPerSec: bytesPerSecond(this.framesIn, this.lastSample.framesIn, elapsedMs),
-      framesOutPerSec: bytesPerSecond(this.framesOut, this.lastSample.framesOut, elapsedMs),
-    };
-    if (sample) {
-      this.lastSample = { at: now, bytesIn: this.bytesIn, bytesOut: this.bytesOut, framesIn: this.framesIn, framesOut: this.framesOut };
-    }
-    const memory = process.memoryUsage();
-    const load = os.loadavg();
-    // Every attached window has full input, so there is no "active controller"
-    // to name: reporting the first of them as one had an operator reading a
-    // distinction that does not exist. The host is still worth naming, and any
-    // client knows which workstation it is on.
-    const anyClient = clients[0];
-    const scopedThroughput = scopeHostId ? this.hostThroughput(scopeHostId, now) : throughput;
-    return {
-      version: this.version,
-      protocolVersion: this.protocolVersion,
-      uptimeSeconds: Math.floor((now - this.startedAt) / 1000),
-      startTime: new Date(this.startedAt).toISOString(),
-      serverTime: new Date(now).toISOString(),
-      activeControllerId: null,
-      activeHostId: anyClient?.hostId || hosts[0]?.id || null,
-      clients,
-      hosts,
-      ptys,
-      clientCount: clients.length,
-      hostCount: hosts.length,
-      ptyCount: ptys.length,
-      activeUserCount: Number.isFinite(activeUserCount) ? activeUserCount : countActiveUsers(clients),
-      throughput: scopedThroughput,
-      cpu: {
-        load1m: finite(load[0]),
-        load5m: finite(load[1]),
-        load15m: finite(load[2]),
-        cpuPercent: this.cpuPercent(),
-        cores: os.cpus().length,
-      },
-      memory: {
-        rssBytes: memory.rss,
-        heapUsedBytes: memory.heapUsed,
-        heapTotalBytes: memory.heapTotal,
-        externalBytes: memory.external,
-        systemTotalBytes: os.totalmem(),
-        systemFreeBytes: os.freemem(),
-      },
-      eventLoopDelay: this.eventLoopDelay(),
-      cleanup: { ...this.cleanup },
-    };
-  }
-
-  close() {
-    this.eventLoop.disable();
-    this.hostTraffic.clear();
-  }
-}
-
-module.exports = { RelayMetrics, countActiveUsers };