herdr-remote-relay 0.3.24 → 0.3.26

package/README.md

@@ -11,10 +11,12 @@ Brokers WebSocket connections between browsers and workstation host connectors.
 ## Installation
 
 ```bash
-npm install -g herdr-remote-relay
+npm install -g https://github.com/dibin666/herdr-remote/releases/latest/download/herdr-remote-relay.tgz
 herdr-remote-relay --public-url https://herdr.example.com --password <password>
 ```
 
+From npm instead: `npm install -g herdr-remote-relay` (it can lag a new release by a while).
+
 Requirements: Node.js 22+, TLS reverse proxy (nginx, Caddy, Cloudflare Tunnel).
 
 ## Docker

package/README.zh-CN.md

@@ -11,10 +11,12 @@
 ## 安装
 
 ```bash
-npm install -g herdr-remote-relay
+npm install -g https://github.com/dibin666/herdr-remote/releases/latest/download/herdr-remote-relay.tgz
 herdr-remote-relay --public-url https://herdr.example.com --password <密码>
 ```
 
+也可从 npm 安装：`npm install -g herdr-remote-relay`（新版本上线后 npm 可能要过一段时间才同步）。
+
 前置要求：Node.js 22+、TLS 反向代理（nginx、Caddy、Cloudflare Tunnel 等）。
 
 ## Docker 运行

package/dist/protocol/herdr-keys.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validates the Herdr prefix keys crossing the wire, or read from a config
+ * file, into one canonical list: lowercase, no whitespace, no duplicates, at
+ * most `MAX_HERDR_PREFIX_KEYS` short entries. Herdr ignores entries it cannot
+ * read and so does this. `undefined` when nothing usable is left, so a host
+ * that says nothing and one that says garbage look the same.
+ */
+export declare function sanitizeHerdrPrefixKeys(value: unknown): string[] | undefined;

package/dist/protocol/herdr-keys.js

@@ -0,0 +1,34 @@
+// The keys that put the workstation's Herdr into prefix mode, as a host reads
+// them from Herdr's config and a browser receives them. Browser-safe: no Node
+// APIs, so the web app imports it.
+/** Herdr accepts any number of prefix keys; a window has no use for more than this. */
+const MAX_HERDR_PREFIX_KEYS = 8;
+/** Longest real combo is `ctrl+shift+double_quote`; this leaves room for spelling variants. */
+const MAX_HERDR_PREFIX_KEY_LENGTH = 32;
+/**
+ * What the browser can act on: a key combo is printable ASCII (modifiers and
+ * key names joined by `+`). Whitespace is removed before this is tested.
+ */
+const PREFIX_KEY = /^[\x21-\x7e]+$/;
+/**
+ * Validates the Herdr prefix keys crossing the wire, or read from a config
+ * file, into one canonical list: lowercase, no whitespace, no duplicates, at
+ * most `MAX_HERDR_PREFIX_KEYS` short entries. Herdr ignores entries it cannot
+ * read and so does this. `undefined` when nothing usable is left, so a host
+ * that says nothing and one that says garbage look the same.
+ */
+export function sanitizeHerdrPrefixKeys(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const keys = new Set();
+    for (const entry of value) {
+        if (keys.size >= MAX_HERDR_PREFIX_KEYS)
+            break;
+        if (typeof entry !== 'string')
+            continue;
+        const key = entry.replace(/\s+/g, '').toLowerCase();
+        if (key.length <= MAX_HERDR_PREFIX_KEY_LENGTH && PREFIX_KEY.test(key))
+            keys.add(key);
+    }
+    return keys.size > 0 ? [...keys] : undefined;
+}

package/dist/protocol/index.d.ts

@@ -1,5 +1,7 @@
 export * from './frames.js';
 export * from './terminal.js';
+export * from './herdr-keys.js';
 export * from './messages.js';
 export * from './paste.js';
+export * from './release.js';
 export type * from './http.js';

package/dist/protocol/index.js

@@ -3,5 +3,7 @@
 // packages build against; nothing here may be copied into the CLI or the web.
 export * from './frames.js';
 export * from './terminal.js';
+export * from './herdr-keys.js';
 export * from './messages.js';
 export * from './paste.js';
+export * from './release.js';

package/dist/protocol/messages.d.ts

@@ -94,6 +94,11 @@ export interface ServerReadyMessage {
     clientCount?: number;
     /** The workstation's herdr-remote release; null when it is too old to say. */
     hostVersion?: string | null;
+    /**
+     * The keys that put the workstation's Herdr into prefix mode, lowercase,
+     * like `ctrl+b`. Left out when the host is too old to say.
+     */
+    herdrPrefixKeys?: string[];
 }
 export interface ServerPairedMessage {
     type: 'paired';
@@ -133,6 +138,8 @@ export interface ServerSessionRestartedMessage {
     terminalFont?: HostTerminalFont | null;
     /** As in `ready`: the host may have come back on another release. */
     hostVersion?: string | null;
+    /** As in `ready`: the host may have come back with another Herdr config. */
+    herdrPrefixKeys?: string[];
 }
 export interface ServerExitMessage {
     type: 'exit';
@@ -239,6 +246,11 @@ export interface HostHelloMessage {
     version?: string;
     terminalPalette?: HostTerminalPalette | null;
     terminalFont?: HostTerminalFont | null;
+    /**
+     * The keys `keys.prefix` in the workstation's Herdr config names, as the
+     * host read them. The relay sanitizes them; older connectors leave them out.
+     */
+    herdrPrefixKeys?: string[];
     capabilities?: string[];
 }
 /** One PTY the host is running, as the relay's status page lists it. */

package/dist/protocol/release.d.ts

@@ -0,0 +1,8 @@
+/** Also the name an update check reports as its source. */
+export declare const GITHUB_RELEASES_URL = "https://github.com/dibin666/herdr-remote/releases";
+/** `{ schema, version, tag, relayVersion, tarball }`, attached to every release. */
+export declare const LATEST_RELEASE_MANIFEST_URL = "https://github.com/dibin666/herdr-remote/releases/latest/download/latest.json";
+/** The newest self-contained CLI tarball, for a workstation that cannot say which it needs. */
+export declare const LATEST_CLI_TARBALL_URL = "https://github.com/dibin666/herdr-remote/releases/latest/download/herdr-remote.tgz";
+/** One CLI release's self-contained tarball; it bundles the relay it was released with. */
+export declare function cliTarballUrl(version: string): string;

package/dist/protocol/release.js

@@ -0,0 +1,17 @@
+// Where herdr-remote is released. The CLI updates from here and the browser
+// shows the same addresses in its manual steps, so there is one definition.
+//
+// GitHub Releases is the primary channel: a release is downloadable the moment
+// it is created, whereas npm can take many minutes after `npm publish` before
+// a new version installs. npm carries the same tarballs as a fallback.
+const RELEASE_REPOSITORY = 'dibin666/herdr-remote';
+/** Also the name an update check reports as its source. */
+export const GITHUB_RELEASES_URL = `https://github.com/${RELEASE_REPOSITORY}/releases`;
+/** `{ schema, version, tag, relayVersion, tarball }`, attached to every release. */
+export const LATEST_RELEASE_MANIFEST_URL = `${GITHUB_RELEASES_URL}/latest/download/latest.json`;
+/** The newest self-contained CLI tarball, for a workstation that cannot say which it needs. */
+export const LATEST_CLI_TARBALL_URL = `${GITHUB_RELEASES_URL}/latest/download/herdr-remote.tgz`;
+/** One CLI release's self-contained tarball; it bundles the relay it was released with. */
+export function cliTarballUrl(version) {
+    return `${GITHUB_RELEASES_URL}/download/herdr-remote-v${version}/herdr-remote-${version}.tgz`;
+}

package/dist/server/client-channel.js

@@ -148,6 +148,7 @@ export function handleClientConnection(relay, ws, req) {
                 terminalFont: host.terminalFont || null,
                 clientCount: host.clients.size,
                 hostVersion: host.version,
+                ...(host.herdrPrefixKeys ? { herdrPrefixKeys: host.herdrPrefixKeys } : {}),
             });
             if (host.agentStatus)
                 jsonSend(ws, host.agentStatus);

package/dist/server/host-channel.js

@@ -1,7 +1,7 @@
 // The host side of the relay: a workstation's WebSocket, from its hello and
 // the hand-off from an older connection to every message it sends after.
 import os from 'node:os';
-import { CAPABILITY, PROTOCOL_VERSION, sanitizeTerminalFont, sanitizeTerminalPalette, unpackStreamFrame, } from '../protocol/index.js';
+import { CAPABILITY, PROTOCOL_VERSION, sanitizeHerdrPrefixKeys, sanitizeTerminalFont, sanitizeTerminalPalette, unpackStreamFrame, } from '../protocol/index.js';
 import { forwardFontChunk, forwardFontSubset, settleFontChunk, settleFontSubset, } from './font-proxy.js';
 import { broadcastAgentStatus, broadcastTerminalFont, broadcastUpdateStatus, releaseVersion, } from './host-broadcasts.js';
 import { allowHostHandshake } from './requests.js';
@@ -10,6 +10,7 @@ import { closeSocket, isOpen, jsonSend, parseJson, randomId, rejectHandshake } f
 import { broadcastToClients, notifyHostClientCount, sendClientBinary } from './transport.js';
 function createHostRecord(message, ws, pending, clients = new Set()) {
     const capabilities = Array.isArray(message.capabilities) ? message.capabilities : [];
+    const herdrPrefixKeys = sanitizeHerdrPrefixKeys(message.herdrPrefixKeys);
     return {
         id: message.hostId,
         ws,
@@ -23,6 +24,7 @@ function createHostRecord(message, ws, pending, clients = new Set()) {
         terminalPalette: sanitizeTerminalPalette(message.terminalPalette),
         /** Family, size and fetchable files of the workstation's terminal font. */
         terminalFont: sanitizeTerminalFont(message.terminalFont),
+        ...(herdrPrefixKeys ? { herdrPrefixKeys } : {}),
         /** The latest workstation snapshot is replayed when a browser joins late. */
         agentStatus: null,
         /** Whether the workstation's herdr-remote is behind; replayed the same way. */

package/dist/server/sessions.js

@@ -72,6 +72,7 @@ export function startSession(relay, host, client, { restarted = false } = {}) {
             terminalPalette: host.terminalPalette || null,
             terminalFont: host.terminalFont || null,
             hostVersion: host.version,
+            ...(host.herdrPrefixKeys ? { herdrPrefixKeys: host.herdrPrefixKeys } : {}),
         });
     }
 }

package/dist/server/types.d.ts

@@ -31,6 +31,8 @@ export interface RelayHost {
     connectedAtMs: number;
     terminalPalette: HostTerminalPalette | null;
     terminalFont: HostTerminalFont | null;
+    /** Sanitized `keys.prefix` of the host's Herdr; absent when the host did not say. */
+    herdrPrefixKeys?: string[];
     /** The latest agent summary, replayed to a window that joins late. */
     agentStatus: ServerAgentStatusMessage | null;
     /** Whether the workstation's herdr-remote is behind; replayed the same way. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-remote-relay",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "description": "Standalone relay server and web terminal for Herdr Remote",
   "license": "MIT",
   "type": "module",