herdr-remote 0.2.33 → 0.2.35

package/node_modules/herdr-remote-relay/dist/protocol/terminal.js

@@ -0,0 +1,150 @@
+// The workstation's terminal palette and font, as a host reports them and a
+// browser receives them. Browser-safe: no Node APIs, so the web app imports it.
+/**
+ * The sixteen ANSI slots a host may report, in index order. A palette is
+ * all-or-nothing: half the host's colors mixed with half the browser's would
+ * look worse than either set on its own.
+ */
+export const ANSI_PALETTE_KEYS = [
+    'black',
+    'red',
+    'green',
+    'yellow',
+    'blue',
+    'magenta',
+    'cyan',
+    'white',
+    'brightBlack',
+    'brightRed',
+    'brightGreen',
+    'brightYellow',
+    'brightBlue',
+    'brightMagenta',
+    'brightCyan',
+    'brightWhite',
+];
+/** The faces a host may offer, in the order a browser registers them. */
+export const TERMINAL_FONT_STYLES = ['regular', 'bold', 'italic', 'boldItalic'];
+export const TERMINAL_FONT_FORMATS = ['truetype', 'opentype'];
+/** `cjk`: the face Hanzi fall back to; `all`: the family itself, too big to send whole. */
+export const TERMINAL_FONT_SUBSET_SCOPES = ['cjk', 'all'];
+/** One font file; a CJK face is larger than this and is left to the browser. */
+export const MAX_TERMINAL_FONT_BYTES = 16 * 1024 * 1024;
+/** Raw bytes per `host_font_chunk`; base64 keeps it far below any payload cap. */
+export const TERMINAL_FONT_CHUNK_BYTES = 256 * 1024;
+const HEX_COLOR = /^#[0-9a-f]{6}$/i;
+/**
+ * A family name ends up inside a CSS `font-family` list in the browser. Quotes,
+ * separators and escapes are what would let a name break out of its slot, and
+ * no real family needs them.
+ */
+const FONT_FAMILY_FORBIDDEN = /["'\\;,{}<>@\u0000-\u001f\u007f]/;
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isOneOf(list, value) {
+    return list.includes(value);
+}
+function hexColor(value) {
+    return typeof value === 'string' && HEX_COLOR.test(value) ? value.toLowerCase() : undefined;
+}
+/**
+ * Validates a terminal palette crossing the wire.
+ *
+ * The host reports what its own terminal answered to the OSC color queries,
+ * and the browser paints with it. Anything that is not a plain `#rrggbb`
+ * string is dropped here, so a compromised or buggy host cannot push arbitrary
+ * data into a browser's renderer options.
+ */
+export function sanitizeTerminalPalette(value) {
+    if (!isRecord(value))
+        return null;
+    const palette = {};
+    for (const key of ['background', 'foreground', 'cursor']) {
+        const color = hexColor(value[key]);
+        if (color)
+            palette[key] = color;
+    }
+    const ansi = value.ansi;
+    if (isRecord(ansi)) {
+        const collected = {};
+        for (const key of ANSI_PALETTE_KEYS) {
+            const color = hexColor(ansi[key]);
+            if (color)
+                collected[key] = color;
+        }
+        if (Object.keys(collected).length === ANSI_PALETTE_KEYS.length) {
+            palette.ansi = collected;
+        }
+    }
+    return Object.keys(palette).length > 0 ? palette : null;
+}
+function familyName(value) {
+    const family = typeof value === 'string' ? value.trim() : '';
+    if (!family || family.length > 128 || FONT_FAMILY_FORBIDDEN.test(family))
+        return null;
+    return family;
+}
+/**
+ * Validates the terminal font a host reports.
+ *
+ * The browser draws the session in the family the workstation's terminal
+ * uses, and may fetch the font files by their hash. Every field is optional
+ * except the family; anything malformed is dropped rather than repaired.
+ */
+export function sanitizeTerminalFont(value) {
+    if (!isRecord(value))
+        return null;
+    const family = familyName(value.family);
+    if (!family)
+        return null;
+    const size = Number(value.sizePx);
+    const sizePx = Number.isFinite(size) && size >= 4 && size <= 96 ? Math.round(size * 10) / 10 : null;
+    const source = typeof value.source === 'string' && /^[a-z0-9-]{1,32}$/.test(value.source)
+        ? value.source
+        : null;
+    const faces = [];
+    const seen = new Set();
+    for (const face of Array.isArray(value.faces) ? value.faces.slice(0, 16) : []) {
+        if (!isRecord(face))
+            continue;
+        const { style, format, bytes, sha256 } = face;
+        if (!isOneOf(TERMINAL_FONT_STYLES, style) || seen.has(style))
+            continue;
+        if (!isOneOf(TERMINAL_FONT_FORMATS, format))
+            continue;
+        if (typeof bytes !== 'number' || !Number.isInteger(bytes))
+            continue;
+        if (bytes <= 0 || bytes > MAX_TERMINAL_FONT_BYTES)
+            continue;
+        if (typeof sha256 !== 'string' || !SHA256_HEX.test(sha256))
+            continue;
+        seen.add(style);
+        faces.push({ style, format, bytes, sha256 });
+    }
+    // Large fonts (CJK above all) are offered a few characters at a time.
+    const subsets = [];
+    for (const entry of Array.isArray(value.subsets) ? value.subsets.slice(0, 16) : []) {
+        if (!isRecord(entry))
+            continue;
+        const name = familyName(entry.family);
+        const { scope, sha256 } = entry;
+        if (!name || entry.style !== 'regular')
+            continue;
+        if (!isOneOf(TERMINAL_FONT_SUBSET_SCOPES, scope))
+            continue;
+        if (typeof sha256 !== 'string' || !SHA256_HEX.test(sha256))
+            continue;
+        if (subsets.some((known) => known.scope === scope))
+            continue;
+        subsets.push({ family: name, style: 'regular', scope, sha256 });
+    }
+    return {
+        family,
+        ...(sizePx !== null && { sizePx }),
+        ...(source !== null && { source }),
+        faces,
+        subsets,
+    };
+}

package/node_modules/herdr-remote-relay/dist/relay-config.d.ts

@@ -0,0 +1,74 @@
+declare const PACKAGE_ROOT: string;
+export type RelayMode = 'local' | 'remote';
+/** A relay configuration after `validate`: every field present and in range. */
+export interface RelayConfig {
+    relay: {
+        mode: RelayMode;
+        host: string;
+        port: number;
+        publicUrl: string;
+        maxPayloadBytes: number;
+        maxClientsPerHost: number;
+        maxHosts: number;
+        maxPendingHandshakes: number;
+        maxBufferedBytesPerClient: number;
+        allowedOrigins: string[];
+        trustProxy: boolean;
+        hostReconnectGraceMs: number;
+        /** Development only: simulated round-trip latency. */
+        devLatencyMs?: number;
+    };
+    auth: {
+        pairingTtlMs: number;
+        deviceTtlMs: number;
+        maxDevices: number;
+        password: string | null;
+        adminToken: string | null;
+        stateFile: string | null;
+    };
+    cleanup: {
+        intervalMs: number;
+        heartbeatIntervalMs: number;
+        staleAfterMs: number;
+    };
+}
+/**
+ * A configuration while it is being assembled: file, environment and flags
+ * may each put a string, or anything else, where `validate` expects a number.
+ */
+type RelayConfigDraft = {
+    [Section in keyof RelayConfig]: Record<string, unknown>;
+};
+/** Flags given as `--name value` or `--name=value`, by name. */
+export type RelayOptions = Record<string, string>;
+declare function defaultStateDir(): string;
+declare const DEFAULTS: RelayConfig;
+/**
+ * Parse `--flag value` / `--flag=value` pairs plus the standalone flags the
+ * relay binary understands. Returns { options, help, version, errors }.
+ */
+declare function parseArgv(argv?: readonly string[]): {
+    options: RelayOptions;
+    help: boolean;
+    version: boolean;
+    errors: string[];
+};
+declare function validate(config: RelayConfigDraft): RelayConfig;
+/**
+ * Warnings a standalone operator should see at startup. These are advisory —
+ * the relay still starts, because a loopback-only development run legitimately
+ * needs neither TLS nor tokens.
+ */
+declare function configWarnings(config: RelayConfig): string[];
+declare function loadRelayConfig({ argv, env, }?: {
+    argv?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+}): {
+    config: RelayConfig;
+    help: boolean;
+    version: boolean;
+    errors: string[];
+    configFile: string | null;
+    warnings: string[];
+};
+export { PACKAGE_ROOT, DEFAULTS, loadRelayConfig, parseArgv, validate, configWarnings, defaultStateDir, };

package/node_modules/herdr-remote-relay/dist/relay-config.js

@@ -0,0 +1,316 @@
+// Standalone relay configuration.
+//
+// The relay is deliberately decoupled from the herdr-remote plugin: it never
+// reads the plugin's config directory and never imports plugin code. Settings
+// come from (lowest to highest precedence) built-in defaults, an optional JSON
+// config file, environment variables, then command line flags.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const PACKAGE_ROOT = path.resolve(import.meta.dirname, '..');
+function defaultStateDir() {
+    if (process.env.RELAY_STATE_DIR)
+        return process.env.RELAY_STATE_DIR;
+    const stateHome = process.env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
+    return path.join(stateHome, 'herdr-remote-relay');
+}
+const DEFAULTS = {
+    relay: {
+        // A relay package is remote/operator-facing by default. The workstation
+        // service sets this to local for the private relay it starts itself so the
+        // web client can distinguish its own status page from the operator console.
+        mode: 'remote',
+        // Bind to loopback by default: the common production shape is a TLS
+        // reverse proxy on the same machine. Containers and LAN deployments set
+        // RELAY_BIND=0.0.0.0 explicitly.
+        host: '127.0.0.1',
+        port: 8787,
+        publicUrl: 'http://127.0.0.1:8787',
+        // Sized for a pasted image, not for keystrokes. `ws` closes a connection
+        // that receives an oversized frame (1009) rather than dropping the frame,
+        // so this ceiling is what a client's own upload cap has to stay under.
+        maxPayloadBytes: 5 * 1024 * 1024,
+        maxClientsPerHost: 16,
+        maxHosts: 1024,
+        maxPendingHandshakes: 1024,
+        maxBufferedBytesPerClient: 4 * 1024 * 1024,
+        allowedOrigins: [],
+        trustProxy: false,
+        hostReconnectGraceMs: 30 * 1000,
+    },
+    auth: {
+        pairingTtlMs: 10 * 60 * 1000,
+        deviceTtlMs: 30 * 24 * 60 * 60 * 1000,
+        maxDevices: 32,
+        // Optional shared password. Unset means a public relay: anyone may connect
+        // a workstation, and each one is still reachable only through its own host
+        // token.
+        password: null,
+        // Optional operator credential for the standalone relay dashboard. This is
+        // deliberately separate from the join password and from device tokens:
+        // the former is shared with workstations, while the latter is scoped to a
+        // single workstation.
+        adminToken: null,
+        stateFile: null,
+    },
+    cleanup: {
+        intervalMs: 60 * 1000,
+        heartbeatIntervalMs: 30 * 1000,
+        staleAfterMs: 90 * 1000,
+    },
+};
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        const { code, message } = error;
+        if (code === 'ENOENT')
+            return null;
+        throw new Error(`cannot read relay config ${filePath}: ${message}`);
+    }
+}
+function parseBoolean(value, fallback) {
+    if (value === undefined || value === null || value === '')
+        return fallback;
+    if (value === true || value === false)
+        return value;
+    const normalized = String(value).trim().toLowerCase();
+    if (['true', '1', 'yes', 'on'].includes(normalized))
+        return true;
+    if (['false', '0', 'no', 'off'].includes(normalized))
+        return false;
+    return fallback;
+}
+function parseInteger(value, fallback, min, max) {
+    const numeric = Number(value);
+    if (!Number.isInteger(numeric) || numeric < min || numeric > max)
+        return fallback;
+    return numeric;
+}
+function parseOriginList(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => String(entry).trim()).filter(Boolean);
+    if (typeof value !== 'string')
+        return null;
+    return value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function mergeSection(target, source) {
+    if (!source || typeof source !== 'object')
+        return;
+    const values = source;
+    for (const key of Object.keys(target)) {
+        if (values[key] !== undefined)
+            target[key] = values[key];
+    }
+}
+/**
+ * Parse `--flag value` / `--flag=value` pairs plus the standalone flags the
+ * relay binary understands. Returns { options, help, version, errors }.
+ */
+function parseArgv(argv = []) {
+    const options = {};
+    const errors = [];
+    let help = false;
+    let version = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+            continue;
+        }
+        if (arg === '--version' || arg === '-v') {
+            version = true;
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            errors.push(`unexpected argument: ${arg}`);
+            continue;
+        }
+        const equals = arg.indexOf('=');
+        const name = equals === -1 ? arg.slice(2) : arg.slice(2, equals);
+        let value = equals === -1 ? undefined : arg.slice(equals + 1);
+        if (value === undefined) {
+            const next = argv[index + 1];
+            if (next === undefined || next.startsWith('--')) {
+                // Bare boolean flag.
+                value = 'true';
+            }
+            else {
+                value = next;
+                index += 1;
+            }
+        }
+        options[name] = value;
+    }
+    return { options, help, version, errors };
+}
+function applyFile(config, fileConfig) {
+    if (!fileConfig || typeof fileConfig !== 'object')
+        return;
+    const sections = fileConfig;
+    mergeSection(config.relay, sections.relay);
+    mergeSection(config.auth, sections.auth);
+    mergeSection(config.cleanup, sections.cleanup);
+}
+function applyEnvironment(config, env) {
+    if (env.RELAY_DEPLOYMENT_MODE === 'local' || env.RELAY_DEPLOYMENT_MODE === 'remote') {
+        config.relay.mode = env.RELAY_DEPLOYMENT_MODE;
+    }
+    if (env.RELAY_BIND)
+        config.relay.host = env.RELAY_BIND;
+    if (env.RELAY_PORT)
+        config.relay.port = env.RELAY_PORT;
+    if (env.RELAY_PUBLIC_URL)
+        config.relay.publicUrl = env.RELAY_PUBLIC_URL;
+    if (env.RELAY_MAX_PAYLOAD_BYTES)
+        config.relay.maxPayloadBytes = env.RELAY_MAX_PAYLOAD_BYTES;
+    if (env.RELAY_MAX_CLIENTS_PER_HOST)
+        config.relay.maxClientsPerHost = env.RELAY_MAX_CLIENTS_PER_HOST;
+    if (env.RELAY_MAX_HOSTS)
+        config.relay.maxHosts = env.RELAY_MAX_HOSTS;
+    if (env.RELAY_MAX_PENDING_HANDSHAKES)
+        config.relay.maxPendingHandshakes = env.RELAY_MAX_PENDING_HANDSHAKES;
+    if (env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT)
+        config.relay.maxBufferedBytesPerClient = env.RELAY_MAX_BUFFERED_BYTES_PER_CLIENT;
+    if (env.RELAY_HOST_RECONNECT_GRACE_MS)
+        config.relay.hostReconnectGraceMs = env.RELAY_HOST_RECONNECT_GRACE_MS;
+    if (env.RELAY_ALLOWED_ORIGINS !== undefined) {
+        const origins = parseOriginList(env.RELAY_ALLOWED_ORIGINS);
+        if (origins)
+            config.relay.allowedOrigins = origins;
+    }
+    if (env.RELAY_TRUST_PROXY !== undefined) {
+        config.relay.trustProxy = parseBoolean(env.RELAY_TRUST_PROXY, config.relay.trustProxy);
+    }
+    if (env.RELAY_PASSWORD)
+        config.auth.password = env.RELAY_PASSWORD;
+    if (env.RELAY_ADMIN_TOKEN)
+        config.auth.adminToken = env.RELAY_ADMIN_TOKEN;
+    if (env.RELAY_AUTH_STATE_FILE)
+        config.auth.stateFile = env.RELAY_AUTH_STATE_FILE;
+    if (env.RELAY_PAIRING_TTL_MS)
+        config.auth.pairingTtlMs = env.RELAY_PAIRING_TTL_MS;
+    if (env.RELAY_DEVICE_TTL_MS)
+        config.auth.deviceTtlMs = env.RELAY_DEVICE_TTL_MS;
+    if (env.RELAY_MAX_DEVICES)
+        config.auth.maxDevices = env.RELAY_MAX_DEVICES;
+}
+function applyOptions(config, options) {
+    if (options['deployment-mode'] === 'local' || options['deployment-mode'] === 'remote') {
+        config.relay.mode = options['deployment-mode'];
+    }
+    if (options.bind)
+        config.relay.host = options.bind;
+    if (options.port)
+        config.relay.port = options.port;
+    if (options['public-url'])
+        config.relay.publicUrl = options['public-url'];
+    if (options['allowed-origins'] !== undefined) {
+        const origins = parseOriginList(options['allowed-origins']);
+        if (origins)
+            config.relay.allowedOrigins = origins;
+    }
+    if (options['trust-proxy'] !== undefined) {
+        config.relay.trustProxy = parseBoolean(options['trust-proxy'], config.relay.trustProxy);
+    }
+    if (options.password)
+        config.auth.password = options.password;
+    if (options['admin-token'])
+        config.auth.adminToken = options['admin-token'];
+    if (options['state-file'])
+        config.auth.stateFile = options['state-file'];
+    if (options['max-clients'])
+        config.relay.maxClientsPerHost = options['max-clients'];
+    if (options['max-hosts'])
+        config.relay.maxHosts = options['max-hosts'];
+    if (options['max-pending-handshakes'])
+        config.relay.maxPendingHandshakes = options['max-pending-handshakes'];
+    if (options['max-buffered-bytes'])
+        config.relay.maxBufferedBytesPerClient = options['max-buffered-bytes'];
+    if (options['host-reconnect-grace-ms'])
+        config.relay.hostReconnectGraceMs = options['host-reconnect-grace-ms'];
+}
+function validate(config) {
+    if (config.relay.mode !== 'local' && config.relay.mode !== 'remote')
+        config.relay.mode = DEFAULTS.relay.mode;
+    config.relay.port = parseInteger(config.relay.port, DEFAULTS.relay.port, 0, 65535);
+    config.relay.maxPayloadBytes = parseInteger(config.relay.maxPayloadBytes, DEFAULTS.relay.maxPayloadBytes, 4096, 16 * 1024 * 1024);
+    config.relay.maxClientsPerHost = parseInteger(config.relay.maxClientsPerHost, DEFAULTS.relay.maxClientsPerHost, 1, 256);
+    config.relay.maxHosts = parseInteger(config.relay.maxHosts, DEFAULTS.relay.maxHosts, 1, 100000);
+    config.relay.maxPendingHandshakes = parseInteger(config.relay.maxPendingHandshakes, DEFAULTS.relay.maxPendingHandshakes, 16, 100000);
+    config.relay.maxBufferedBytesPerClient = parseInteger(config.relay.maxBufferedBytesPerClient, DEFAULTS.relay.maxBufferedBytesPerClient, 64 * 1024, 256 * 1024 * 1024);
+    config.relay.hostReconnectGraceMs = parseInteger(config.relay.hostReconnectGraceMs, DEFAULTS.relay.hostReconnectGraceMs, 1000, 24 * 60 * 60 * 1000);
+    config.auth.pairingTtlMs = parseInteger(config.auth.pairingTtlMs, DEFAULTS.auth.pairingTtlMs, 30 * 1000, 24 * 60 * 60 * 1000);
+    config.auth.deviceTtlMs = parseInteger(config.auth.deviceTtlMs, DEFAULTS.auth.deviceTtlMs, 60 * 1000, 365 * 24 * 60 * 60 * 1000);
+    config.auth.maxDevices = parseInteger(config.auth.maxDevices, DEFAULTS.auth.maxDevices, 1, 10000);
+    config.cleanup.intervalMs = parseInteger(config.cleanup.intervalMs, DEFAULTS.cleanup.intervalMs, 1000, 24 * 60 * 60 * 1000);
+    config.cleanup.heartbeatIntervalMs = parseInteger(config.cleanup.heartbeatIntervalMs, DEFAULTS.cleanup.heartbeatIntervalMs, 1000, 10 * 60 * 1000);
+    config.cleanup.staleAfterMs = parseInteger(config.cleanup.staleAfterMs, DEFAULTS.cleanup.staleAfterMs, config.cleanup.heartbeatIntervalMs * 2, 24 * 60 * 60 * 1000);
+    if (typeof config.relay.host !== 'string' || config.relay.host.length === 0) {
+        config.relay.host = DEFAULTS.relay.host;
+    }
+    if (typeof config.relay.publicUrl !== 'string' || config.relay.publicUrl.length === 0) {
+        config.relay.publicUrl = `http://${config.relay.host}:${config.relay.port}`;
+    }
+    config.relay.publicUrl = String(config.relay.publicUrl).replace(/\/+$/, '');
+    if (!Array.isArray(config.relay.allowedOrigins))
+        config.relay.allowedOrigins = [];
+    config.relay.trustProxy = parseBoolean(config.relay.trustProxy, false);
+    if (!config.auth.stateFile) {
+        config.auth.stateFile = path.join(defaultStateDir(), 'relay-auth.json');
+    }
+    // Every field `RelayConfig` promises has been normalised above.
+    return config;
+}
+/**
+ * Warnings a standalone operator should see at startup. These are advisory —
+ * the relay still starts, because a loopback-only development run legitimately
+ * needs neither TLS nor tokens.
+ */
+function configWarnings(config) {
+    const warnings = [];
+    const isLoopbackBind = ['127.0.0.1', 'localhost', '::1'].includes(config.relay.host);
+    let publicUrl;
+    try {
+        publicUrl = new URL(config.relay.publicUrl);
+    }
+    catch {
+        warnings.push(`publicUrl is not a valid URL: ${config.relay.publicUrl}`);
+    }
+    if (!config.auth.password) {
+        warnings.push('no password set (RELAY_PASSWORD): this is a public relay, anyone may connect a workstation to it');
+    }
+    if (config.relay.mode === 'remote' && !config.auth.adminToken) {
+        warnings.push('no admin token set (RELAY_ADMIN_TOKEN): the relay operator dashboard is unavailable');
+    }
+    if (!isLoopbackBind &&
+        publicUrl &&
+        publicUrl.protocol === 'http:' &&
+        !['127.0.0.1', 'localhost'].includes(publicUrl.hostname)) {
+        warnings.push(`publicUrl uses plain http on a non-loopback address (${config.relay.publicUrl}); terminate TLS in front of the relay`);
+    }
+    return warnings;
+}
+function loadRelayConfig({ argv = [], env = process.env, } = {}) {
+    const { options, help, version, errors } = parseArgv(argv);
+    const draft = clone(DEFAULTS);
+    const configFile = options.config || env.HERDR_RELAY_CONFIG || null;
+    if (configFile) {
+        const fileConfig = readJsonFile(path.resolve(configFile));
+        if (fileConfig === null)
+            throw new Error(`relay config not found: ${configFile}`);
+        applyFile(draft, fileConfig);
+    }
+    applyEnvironment(draft, env);
+    applyOptions(draft, options);
+    const config = validate(draft);
+    return { config, help, version, errors, configFile, warnings: configWarnings(config) };
+}
+export { PACKAGE_ROOT, DEFAULTS, loadRelayConfig, parseArgv, validate, configWarnings, defaultStateDir, };

package/node_modules/herdr-remote-relay/dist/relay-server.d.ts

@@ -0,0 +1,64 @@
+import http from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer } from 'ws';
+import { AuthStore } from './auth-store.js';
+import { RelayMetrics } from './metrics.js';
+import { PROTOCOL_VERSION } from './protocol/index.js';
+import { type RelayConfig } from './relay-config.js';
+import type { AttemptWindow, RelayClient, RelayContext, RelayHost, RelaySocket, SendQueue } from './server/types.js';
+import { VERSION } from './server/version.js';
+/** A configuration with any field left out; the defaults fill the rest. */
+export type RelayConfigInput = {
+    [Section in keyof RelayConfig]?: Partial<RelayConfig[Section]>;
+};
+/** Overrides for embedding the relay, mostly in tests. */
+export interface RelayServerOptions {
+    stateFile?: string;
+    password?: string | null;
+    adminToken?: string | null;
+    trustProxy?: boolean;
+    /** Simulated round-trip latency; each direction is delayed by half. */
+    devLatencyMs?: number | string;
+    metrics?: RelayMetrics;
+    auth?: AuthStore;
+}
+export type RelayAddress = {
+    host: string;
+    port: number;
+} | {
+    path: string;
+};
+declare class RelayServer implements RelayContext {
+    config: RelayConfig;
+    relayMode: 'local' | 'remote';
+    hosts: Map<string, RelayHost>;
+    clients: Map<string, RelayClient>;
+    streams: Map<string, string>;
+    pairAttempts: Map<string, AttemptWindow>;
+    clientHandshakeAttempts: Map<string, AttemptWindow>;
+    hostHandshakeAttempts: Map<string, AttemptWindow>;
+    /** Sockets that are upgraded but have not finished their hello. */
+    pendingHandshakes: Set<RelaySocket>;
+    startedAt: number;
+    metrics: RelayMetrics;
+    stateFile: string;
+    password: string | null;
+    adminToken: string | null;
+    trustProxy: boolean;
+    devLatencyMs: number;
+    devDelayMs: number;
+    sendQueues: WeakMap<RelaySocket, SendQueue>;
+    activeDelayTimers: Set<NodeJS.Timeout>;
+    auth: AuthStore;
+    server: http.Server;
+    wss: WebSocketServer;
+    heartbeatTimer: NodeJS.Timeout | null;
+    cleanupTimer: NodeJS.Timeout | null;
+    constructor(config?: RelayConfigInput, options?: RelayServerOptions);
+    listen(port?: number, host?: string): Promise<RelayAddress>;
+    address(): RelayAddress | null;
+    close(): Promise<void>;
+    handleUpgrade(req: http.IncomingMessage, socket: Duplex, head: Buffer): void;
+    finishHandshake(ws: RelaySocket): void;
+}
+export { RelayServer, PROTOCOL_VERSION, VERSION };