herdr-remote-relay 0.3.12 → 0.3.13

package/bin/herdr-remote-relay.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-'use strict';
 
 // Standalone entry point for the Herdr Remote relay.
 //
@@ -7,10 +6,10 @@
 // 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');
+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
 
@@ -73,11 +72,12 @@ async function main(argv = process.argv.slice(2)) {
   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})`
-        : '';
+    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;
@@ -86,8 +86,12 @@ async function main(argv = process.argv.slice(2)) {
   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(
+    `  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()) {
@@ -106,11 +110,7 @@ async function main(argv = process.argv.slice(2)) {
   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 };
+main().catch((error) => {
+  process.stderr.write(`herdr-remote-relay: ${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/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/dist/auth-store.js

@@ -0,0 +1,276 @@
+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);
+}
+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 = 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;
+    }
+}
+export { AuthStore };

package/dist/metrics.d.ts

@@ -0,0 +1,76 @@
+import type { AdminStatusResponse, CleanupCounters, ConnectedClientInfo, EventLoopDelayMetrics, HostInfo, PtyInfo, ThroughputMetrics } from './protocol/http.js';
+/** Cleanup counters that `recordCleanup` may increment. */
+type CleanupCounterName = Exclude<keyof CleanupCounters, 'lastCleanupAt'>;
+interface HostTrafficCounter {
+    bytesIn: number;
+    bytesOut: number;
+    framesIn: number;
+    framesOut: number;
+    sampleAt: number;
+    sampleBytesIn: number;
+    sampleBytesOut: number;
+    sampleFramesIn: number;
+    sampleFramesOut: number;
+}
+/** A connection as `countActiveUsers` sees it. */
+interface ClientIdentity {
+    id: string;
+    deviceId?: string | null;
+}
+interface SnapshotOptions {
+    clients?: ConnectedClientInfo[];
+    hosts?: HostInfo[];
+    ptys?: PtyInfo[];
+    sample?: boolean;
+    scopeHostId?: string | null;
+    activeUserCount?: number | null;
+}
+/**
+ * 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.
+ */
+declare function countActiveUsers(clients?: readonly (ClientIdentity | null | undefined)[]): number;
+declare class RelayMetrics {
+    readonly version: string;
+    readonly protocolVersion: number;
+    readonly startedAt: number;
+    bytesIn: number;
+    bytesOut: number;
+    framesIn: number;
+    framesOut: number;
+    cleanup: Required<Omit<CleanupCounters, 'lastCleanupAt'>> & {
+        lastCleanupAt: string | null;
+    };
+    private lastSample;
+    private readonly hostTraffic;
+    private cpuSampleAt;
+    private cpuSample;
+    private readonly eventLoop;
+    constructor({ version, protocolVersion }?: {
+        version?: string | undefined;
+        protocolVersion?: number | undefined;
+    });
+    hostCounter(hostId: string | null | undefined): HostTrafficCounter | null;
+    recordIn(bytes: number, hostId?: string | null): void;
+    recordOut(bytes: number, hostId?: string | null): void;
+    forgetHost(hostId: string | null | undefined): void;
+    hostThroughput(hostId: string | null | undefined, now?: number): ThroughputMetrics;
+    recordCleanup(name: CleanupCounterName, amount?: number): void;
+    cpuPercent(): number;
+    eventLoopDelay(): EventLoopDelayMetrics;
+    /**
+     * `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, scopeHostId, activeUserCount, }?: SnapshotOptions): AdminStatusResponse;
+    close(): void;
+}
+export { RelayMetrics, countActiveUsers };