@monotykamary/localterm-server 0.0.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aiden Bai
+
+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/dist/constants.d.ts

@@ -0,0 +1,44 @@
+export declare const DEFAULT_PORT = 3417;
+export declare const DEFAULT_HOST = "0.0.0.0";
+export declare const DEFAULT_COLS = 120;
+export declare const DEFAULT_ROWS = 32;
+export declare const DEFAULT_SHELL_FALLBACK = "/bin/sh";
+export declare const TERM_TYPE = "xterm-256color";
+export declare const COLORTERM_VALUE = "truecolor";
+export declare const TITLE_POLL_INTERVAL_MS = 500;
+export declare const CWD_RESOLVE_TIMEOUT_MS = 250;
+export declare const CWD_RESOLVE_BACKOFF_MS = 30000;
+export declare const CWD_RESOLVE_COOLDOWN_MS = 5000;
+export declare const TITLE_MAX_PATH_SEGMENTS = 3;
+export declare const TITLE_TRUNCATION_PREFIX = "\u2026";
+/**
+ * Strip terminal-emulator identity env vars inherited from the daemon's parent.
+ * If we leak e.g. TERM_PROGRAM=ghostty, modern Ink-based TUIs (Cursor Agent,
+ * Claude Code) will probe for that terminal's protocol (kitty keyboard,
+ * XTQVERSION, XTGETTCAP, OSC 1337, etc.) and — when xterm.js doesn't answer —
+ * fall back to a degraded inline-plain rendering instead of the full boxed
+ * TUI. Removing these lets the TUI treat us as a generic xterm-256color and
+ * render normally.
+ */
+export declare const PTY_ENV_DENYLIST: string[];
+export declare const MAX_INPUT_BYTES: number;
+export declare const MAX_OUTPUT_BYTES: number;
+export declare const MAX_FOREGROUND_LENGTH = 256;
+export declare const MAX_TITLE_LENGTH: number;
+export declare const MAX_COLS = 1000;
+export declare const MAX_ROWS = 1000;
+export declare const MAX_CONCURRENT_SESSIONS = 64;
+export declare const WS_OUTBOUND_PAUSE_HIGH_WATER_BYTES: number;
+export declare const WS_OUTBOUND_RESUME_LOW_WATER_BYTES: number;
+export declare const WS_OUTBOUND_DRAIN_POLL_MS = 50;
+export declare const WS_BACKPRESSURE_THRESHOLD_BYTES: number;
+export declare const WS_HEARTBEAT_INTERVAL_MS = 20000;
+export declare const WS_HEARTBEAT_TIMEOUT_MS = 60000;
+export declare const SERVER_STOP_GRACE_MS = 1500;
+export declare const LOOPBACK_HOSTS: Set<string>;
+export declare const HTTP_STATUS_NOT_FOUND = 404;
+export declare const WS_READY_STATE_OPEN = 1;
+export declare const WS_CLOSE_POLICY_VIOLATION = 1008;
+export declare const WS_CLOSE_BACKPRESSURE = 4429;
+export declare const WS_CLOSE_CAPACITY_REACHED = 4503;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,OAAO,CAAC;AACjC,eAAO,MAAM,YAAY,YAAY,CAAC;AACtC,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC,eAAO,MAAM,YAAY,KAAK,CAAC;AAC/B,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAEhD,eAAO,MAAM,SAAS,mBAAmB,CAAC;AAC1C,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAC7C,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAC7C,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,uBAAuB,WAAM,CAAC;AAE3C;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,UAe5B,CAAC;AAEF,eAAO,MAAM,eAAe,QAAY,CAAC;AACzC,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAChD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,gBAAgB,QAAW,CAAC;AACzC,eAAO,MAAM,QAAQ,OAAO,CAAC;AAC7B,eAAO,MAAM,QAAQ,OAAO,CAAC;AAC7B,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAO1C,eAAO,MAAM,kCAAkC,QAAkB,CAAC;AAClE,eAAO,MAAM,kCAAkC,QAAkB,CAAC;AAClE,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,eAAO,MAAM,+BAA+B,QAAmB,CAAC;AAOhE,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAK9C,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C,eAAO,MAAM,cAAc,aAMzB,CAAC;AAEH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,eAAO,MAAM,yBAAyB,OAAO,CAAC"}

package/dist/constants.js

@@ -0,0 +1,80 @@
+export const DEFAULT_PORT = 3417;
+export const DEFAULT_HOST = "0.0.0.0";
+export const DEFAULT_COLS = 120;
+export const DEFAULT_ROWS = 32;
+export const DEFAULT_SHELL_FALLBACK = "/bin/sh";
+export const TERM_TYPE = "xterm-256color";
+export const COLORTERM_VALUE = "truecolor";
+export const TITLE_POLL_INTERVAL_MS = 500;
+export const CWD_RESOLVE_TIMEOUT_MS = 250;
+export const CWD_RESOLVE_BACKOFF_MS = 30_000;
+export const CWD_RESOLVE_COOLDOWN_MS = 5_000;
+export const TITLE_MAX_PATH_SEGMENTS = 3;
+export const TITLE_TRUNCATION_PREFIX = "…";
+/**
+ * Strip terminal-emulator identity env vars inherited from the daemon's parent.
+ * If we leak e.g. TERM_PROGRAM=ghostty, modern Ink-based TUIs (Cursor Agent,
+ * Claude Code) will probe for that terminal's protocol (kitty keyboard,
+ * XTQVERSION, XTGETTCAP, OSC 1337, etc.) and — when xterm.js doesn't answer —
+ * fall back to a degraded inline-plain rendering instead of the full boxed
+ * TUI. Removing these lets the TUI treat us as a generic xterm-256color and
+ * render normally.
+ */
+export const PTY_ENV_DENYLIST = [
+    "LOCALTERM_DAEMON_CHILD",
+    "TERM_PROGRAM",
+    "TERM_PROGRAM_VERSION",
+    "TERM_SESSION_ID",
+    "ITERM_SESSION_ID",
+    "ITERM_PROFILE",
+    "KITTY_WINDOW_ID",
+    "KITTY_PID",
+    "WT_SESSION",
+    "WT_PROFILE_ID",
+    "GHOSTTY_RESOURCES_DIR",
+    "GHOSTTY_BIN_DIR",
+    "VSCODE_INJECTION",
+    "VSCODE_GIT_IPC_HANDLE",
+];
+export const MAX_INPUT_BYTES = 64 * 1024;
+export const MAX_OUTPUT_BYTES = 1 * 1024 * 1024;
+export const MAX_FOREGROUND_LENGTH = 256;
+export const MAX_TITLE_LENGTH = 4 * 1024;
+export const MAX_COLS = 1000;
+export const MAX_ROWS = 1000;
+export const MAX_CONCURRENT_SESSIONS = 64;
+// High/low water marks gate the PTY -> WS pipe instead of killing the socket.
+// Crossing the high water mark pauses the PTY so the OS pipe absorbs further
+// child output until the WS drains below the low water mark, at which point
+// we resume. Anything past WS_BACKPRESSURE_THRESHOLD_BYTES is treated as a
+// runaway: the WS *did* drain below low water at some point, the receiver is
+// genuinely stuck, and we'd rather drop the connection than balloon memory.
+export const WS_OUTBOUND_PAUSE_HIGH_WATER_BYTES = 4 * 1024 * 1024;
+export const WS_OUTBOUND_RESUME_LOW_WATER_BYTES = 1 * 1024 * 1024;
+export const WS_OUTBOUND_DRAIN_POLL_MS = 50;
+export const WS_BACKPRESSURE_THRESHOLD_BYTES = 64 * 1024 * 1024;
+// Heartbeat: send a WS ping every N ms; if no pong arrives within the timeout
+// we tear down the socket. Without this, half-open connections (laptop sleep,
+// VPN dropout, kernel‑side TCP keepalives at 2h+) wedge the session — the
+// server keeps a dead PTY tied to a phantom client and the browser eventually
+// trips its own write error and shows "Shell ended" with no idea why.
+export const WS_HEARTBEAT_INTERVAL_MS = 20_000;
+export const WS_HEARTBEAT_TIMEOUT_MS = 60_000;
+// Hard ceiling for server.stop() — clients get terminated, then the http
+// server is given this long to actually close before we resolve anyway. Keeps
+// the daemon's SIGTERM path bounded so the CLI's force-exit fallback never
+// fires for normal shutdowns.
+export const SERVER_STOP_GRACE_MS = 1_500;
+export const LOOPBACK_HOSTS = new Set([
+    "127.0.0.1",
+    "localhost",
+    "::1",
+    "[::1]",
+    "0:0:0:0:0:0:0:1",
+]);
+export const HTTP_STATUS_NOT_FOUND = 404;
+export const WS_READY_STATE_OPEN = 1;
+export const WS_CLOSE_POLICY_VIOLATION = 1008;
+export const WS_CLOSE_BACKPRESSURE = 4429;
+export const WS_CLOSE_CAPACITY_REACHED = 4503;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AACjC,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC;AACtC,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAChC,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAC/B,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAEhD,MAAM,CAAC,MAAM,SAAS,GAAG,gBAAgB,CAAC;AAC1C,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAC1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAC7C,MAAM,CAAC,MAAM,uBAAuB,GAAG,KAAK,CAAC;AAC7C,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,wBAAwB;IACxB,cAAc;IACd,sBAAsB;IACtB,iBAAiB;IACjB,kBAAkB;IAClB,eAAe;IACf,iBAAiB;IACjB,WAAW;IACX,YAAY;IACZ,eAAe;IACf,uBAAuB;IACvB,iBAAiB;IACjB,kBAAkB;IAClB,uBAAuB;CACxB,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,GAAG,IAAI,CAAC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAChD,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAG,IAAI,CAAC;AACzC,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,CAAC;AAC7B,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,CAAC;AAC7B,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAC1C,8EAA8E;AAC9E,6EAA6E;AAC7E,4EAA4E;AAC5E,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAC5E,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAClE,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAClE,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAC5C,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEhE,8EAA8E;AAC9E,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAC9E,sEAAsE;AACtE,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAC/C,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAC9C,yEAAyE;AACzE,8EAA8E;AAC9E,2EAA2E;AAC3E,8BAA8B;AAC9B,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAE1C,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IACpC,WAAW;IACX,WAAW;IACX,KAAK;IACL,OAAO;IACP,iBAAiB;CAClB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC;AAC9C,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC"}

package/dist/default-shell.d.ts

@@ -0,0 +1,2 @@
+export declare const getDefaultShell: () => string;
+//# sourceMappingURL=default-shell.d.ts.map

package/dist/default-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-shell.d.ts","sourceRoot":"","sources":["../src/default-shell.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,eAAe,QAAO,MAyBlC,CAAC"}

package/dist/default-shell.js

@@ -0,0 +1,44 @@
+import { accessSync, constants as fsConstants } from "node:fs";
+import os from "node:os";
+import { DEFAULT_SHELL_FALLBACK } from "./constants.js";
+const isExecutable = (binaryPath) => {
+    try {
+        accessSync(binaryPath, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const getDefaultShell = () => {
+    if (process.platform === "win32") {
+        return process.env.COMSPEC ?? "cmd.exe";
+    }
+    // Priority order (matches VS Code, Hyper, and Warp):
+    //   1. LOCALTERM_SHELL — explicit user override
+    //   2. os.userInfo().shell — the user's persistent login shell from passwd / DSCL
+    //   3. process.env.SHELL — only as a fallback; this leaks the parent process's
+    //      shell (often zsh from launchd / a Cursor terminal) and is wrong when the
+    //      user has changed their default with `chsh`
+    //   4. DEFAULT_SHELL_FALLBACK
+    const candidates = [];
+    if (process.env.LOCALTERM_SHELL)
+        candidates.push(process.env.LOCALTERM_SHELL);
+    try {
+        const userInfo = os.userInfo();
+        if (userInfo.shell)
+            candidates.push(userInfo.shell);
+    }
+    catch {
+        /* os.userInfo throws on systems without /etc/passwd entry for the uid */
+    }
+    if (process.env.SHELL)
+        candidates.push(process.env.SHELL);
+    candidates.push(DEFAULT_SHELL_FALLBACK);
+    for (const candidate of candidates) {
+        if (isExecutable(candidate))
+            return candidate;
+    }
+    return DEFAULT_SHELL_FALLBACK;
+};
+//# sourceMappingURL=default-shell.js.map

package/dist/default-shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-shell.js","sourceRoot":"","sources":["../src/default-shell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,IAAI,WAAW,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,MAAM,YAAY,GAAG,CAAC,UAAkB,EAAW,EAAE;IACnD,IAAI,CAAC;QACH,UAAU,CAAC,UAAU,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,GAAW,EAAE;IAC1C,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC;IAC1C,CAAC;IACD,qDAAqD;IACrD,gDAAgD;IAChD,kFAAkF;IAClF,+EAA+E;IAC/E,gFAAgF;IAChF,kDAAkD;IAClD,8BAA8B;IAC9B,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe;QAAE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC9E,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;QAC/B,IAAI,QAAQ,CAAC,KAAK;YAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK;QAAE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1D,UAAU,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACxC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,YAAY,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAChD,CAAC;IACD,OAAO,sBAAsB,CAAC;AAChC,CAAC,CAAC"}

package/dist/ensure-spawn-helper-executable.d.ts

@@ -0,0 +1,2 @@
+export declare const ensureSpawnHelperExecutable: () => void;
+//# sourceMappingURL=ensure-spawn-helper-executable.d.ts.map

package/dist/ensure-spawn-helper-executable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-spawn-helper-executable.d.ts","sourceRoot":"","sources":["../src/ensure-spawn-helper-executable.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,2BAA2B,QAAO,IAkB9C,CAAC"}

package/dist/ensure-spawn-helper-executable.js

@@ -0,0 +1,34 @@
+import { chmodSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+const requireCjs = createRequire(import.meta.url);
+const SPAWN_HELPER_MODE = 0o755;
+let alreadyEnsured = false;
+const candidateSpawnHelperPaths = (nodePtyDir) => [
+    path.join(nodePtyDir, "build", "Release", "spawn-helper"),
+    path.join(nodePtyDir, "prebuilds", `${process.platform}-${process.arch}`, "spawn-helper"),
+];
+export const ensureSpawnHelperExecutable = () => {
+    if (alreadyEnsured)
+        return;
+    alreadyEnsured = true;
+    let nodePtyDir;
+    try {
+        const ptyEntry = requireCjs.resolve("node-pty");
+        nodePtyDir = path.dirname(path.dirname(ptyEntry));
+    }
+    catch {
+        return;
+    }
+    for (const candidate of candidateSpawnHelperPaths(nodePtyDir)) {
+        if (!existsSync(candidate))
+            continue;
+        try {
+            chmodSync(candidate, SPAWN_HELPER_MODE);
+        }
+        catch {
+            /* helper already executable, or filesystem refused chmod (e.g. read-only mount) */
+        }
+    }
+};
+//# sourceMappingURL=ensure-spawn-helper-executable.js.map

package/dist/ensure-spawn-helper-executable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-spawn-helper-executable.js","sourceRoot":"","sources":["../src/ensure-spawn-helper-executable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC,IAAI,cAAc,GAAG,KAAK,CAAC;AAE3B,MAAM,yBAAyB,GAAG,CAAC,UAAkB,EAAY,EAAE,CAAC;IAClE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,CAAC;IACzD,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,EAAE,cAAc,CAAC;CAC1F,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAS,EAAE;IACpD,IAAI,cAAc;QAAE,OAAO;IAC3B,cAAc,GAAG,IAAI,CAAC;IACtB,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QAChD,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,KAAK,MAAM,SAAS,IAAI,yBAAyB,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,SAAS;QACrC,IAAI,CAAC;YACH,SAAS,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,mFAAmF;QACrF,CAAC;IACH,CAAC;AACH,CAAC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,64 @@
+import { WS_BACKPRESSURE_THRESHOLD_BYTES, WS_CLOSE_BACKPRESSURE, WS_CLOSE_CAPACITY_REACHED, WS_CLOSE_POLICY_VIOLATION } from "./constants.js";
+interface NonLoopbackHostError {
+    kind: "non-loopback-host";
+    code: "E_LT_SERVER_NON_LOOPBACK_HOST";
+    host: string;
+}
+interface ListenFailedError {
+    kind: "listen-failed";
+    code: "E_LT_SERVER_LISTEN_FAILED";
+    host: string;
+    port: number;
+    cause: Error;
+}
+interface LoopbackDeniedError {
+    kind: "loopback-denied";
+    code: "E_LT_SERVER_LOOPBACK_DENIED";
+    reason: "host" | "origin";
+    observed: string | null;
+    wsCloseCode: typeof WS_CLOSE_POLICY_VIOLATION;
+}
+interface BackpressureError {
+    kind: "backpressure";
+    code: "E_LT_SERVER_BACKPRESSURE";
+    bufferedBytes: number;
+    thresholdBytes: typeof WS_BACKPRESSURE_THRESHOLD_BYTES;
+    wsCloseCode: typeof WS_CLOSE_BACKPRESSURE;
+}
+interface SessionCapacityError {
+    kind: "session-capacity";
+    code: "E_LT_SERVER_SESSION_CAPACITY";
+    limit: number;
+    wsCloseCode: typeof WS_CLOSE_CAPACITY_REACHED;
+}
+interface FrameRejectedError {
+    kind: "frame-rejected";
+    code: "E_LT_SERVER_FRAME_REJECTED";
+    direction: "inbound" | "outbound";
+    reason: string;
+}
+interface PathTraversalError {
+    kind: "path-traversal";
+    code: "E_LT_SERVER_PATH_TRAVERSAL";
+    requested: string;
+}
+export type ServerError = NonLoopbackHostError | ListenFailedError | LoopbackDeniedError | BackpressureError | SessionCapacityError | FrameRejectedError | PathTraversalError;
+export type ServerErrorCode = ServerError["code"];
+export type ServerErrorKind = ServerError["kind"];
+export declare const serverError: {
+    nonLoopbackHost: (host: string) => NonLoopbackHostError;
+    listenFailed: (host: string, port: number, cause: Error) => ListenFailedError;
+    loopbackDenied: (reason: "host" | "origin", observed: string | null) => LoopbackDeniedError;
+    backpressure: (bufferedBytes: number) => BackpressureError;
+    sessionCapacity: (limit: number) => SessionCapacityError;
+    frameRejected: (direction: "inbound" | "outbound", reason: string) => FrameRejectedError;
+    pathTraversal: (requested: string) => PathTraversalError;
+};
+export declare const formatServerError: (error: ServerError) => string;
+export declare class ServerErrorException extends Error {
+    readonly error: ServerError;
+    constructor(error: ServerError);
+}
+export declare const isServerErrorException: (value: unknown) => value is ServerErrorException;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,qBAAqB,EACrB,yBAAyB,EACzB,yBAAyB,EAC1B,MAAM,gBAAgB,CAAC;AAExB,UAAU,oBAAoB;IAC5B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,+BAA+B,CAAC;IACtC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,iBAAiB;IACzB,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE,2BAA2B,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,6BAA6B,CAAC;IACpC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,OAAO,yBAAyB,CAAC;CAC/C;AAED,UAAU,iBAAiB;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,0BAA0B,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,+BAA+B,CAAC;IACvD,WAAW,EAAE,OAAO,qBAAqB,CAAC;CAC3C;AAED,UAAU,oBAAoB;IAC5B,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,8BAA8B,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,yBAAyB,CAAC;CAC/C;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,4BAA4B,CAAC;IACnC,SAAS,EAAE,SAAS,GAAG,UAAU,CAAC;IAClC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,4BAA4B,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,WAAW,GACnB,oBAAoB,GACpB,iBAAiB,GACjB,mBAAmB,GACnB,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAClD,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;AAElD,eAAO,MAAM,WAAW;4BACE,MAAM,KAAG,oBAAoB;yBAKhC,MAAM,QAAQ,MAAM,SAAS,KAAK,KAAG,iBAAiB;6BAOlD,MAAM,GAAG,QAAQ,YAAY,MAAM,GAAG,IAAI,KAAG,mBAAmB;kCAO3D,MAAM,KAAG,iBAAiB;6BAO/B,MAAM,KAAG,oBAAoB;+BAM3B,SAAS,GAAG,UAAU,UAAU,MAAM,KAAG,kBAAkB;+BAM3D,MAAM,KAAG,kBAAkB;CAKvD,CAAC;AAMF,eAAO,MAAM,iBAAiB,GAAI,OAAO,WAAW,KAAG,MAsBtD,CAAC;AAEF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;gBAChB,KAAK,EAAE,WAAW;CAO/B;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,oBAC1B,CAAC"}

package/dist/errors.js

@@ -0,0 +1,84 @@
+import { WS_BACKPRESSURE_THRESHOLD_BYTES, WS_CLOSE_BACKPRESSURE, WS_CLOSE_CAPACITY_REACHED, WS_CLOSE_POLICY_VIOLATION, } from "./constants.js";
+export const serverError = {
+    nonLoopbackHost: (host) => ({
+        kind: "non-loopback-host",
+        code: "E_LT_SERVER_NON_LOOPBACK_HOST",
+        host,
+    }),
+    listenFailed: (host, port, cause) => ({
+        kind: "listen-failed",
+        code: "E_LT_SERVER_LISTEN_FAILED",
+        host,
+        port,
+        cause,
+    }),
+    loopbackDenied: (reason, observed) => ({
+        kind: "loopback-denied",
+        code: "E_LT_SERVER_LOOPBACK_DENIED",
+        reason,
+        observed,
+        wsCloseCode: WS_CLOSE_POLICY_VIOLATION,
+    }),
+    backpressure: (bufferedBytes) => ({
+        kind: "backpressure",
+        code: "E_LT_SERVER_BACKPRESSURE",
+        bufferedBytes,
+        thresholdBytes: WS_BACKPRESSURE_THRESHOLD_BYTES,
+        wsCloseCode: WS_CLOSE_BACKPRESSURE,
+    }),
+    sessionCapacity: (limit) => ({
+        kind: "session-capacity",
+        code: "E_LT_SERVER_SESSION_CAPACITY",
+        limit,
+        wsCloseCode: WS_CLOSE_CAPACITY_REACHED,
+    }),
+    frameRejected: (direction, reason) => ({
+        kind: "frame-rejected",
+        code: "E_LT_SERVER_FRAME_REJECTED",
+        direction,
+        reason,
+    }),
+    pathTraversal: (requested) => ({
+        kind: "path-traversal",
+        code: "E_LT_SERVER_PATH_TRAVERSAL",
+        requested,
+    }),
+};
+const exhaustivenessGuard = (impossible) => {
+    throw new Error(`unhandled ServerError variant: ${JSON.stringify(impossible)}`);
+};
+export const formatServerError = (error) => {
+    switch (error.kind) {
+        case "non-loopback-host":
+            return `refusing to bind non-loopback host '${error.host}': pass 127.0.0.1 or localhost`;
+        case "listen-failed":
+            return `failed to listen on ${error.host}:${error.port}: ${error.cause.message}`;
+        case "loopback-denied": {
+            const where = error.reason === "host" ? "Host header" : "Origin header";
+            const seen = error.observed ? ` (saw '${error.observed}')` : "";
+            return `forbidden: non-loopback ${where}${seen}`;
+        }
+        case "backpressure":
+            return `closing socket: outbound buffered ${error.bufferedBytes}B exceeds ${error.thresholdBytes}B threshold`;
+        case "session-capacity":
+            return `refusing new session: at capacity (${error.limit} concurrent sessions)`;
+        case "frame-rejected":
+            return `dropping malformed ${error.direction} frame: ${error.reason}`;
+        case "path-traversal":
+            return `refusing path-traversal request: '${error.requested}'`;
+        default:
+            return exhaustivenessGuard(error);
+    }
+};
+export class ServerErrorException extends Error {
+    error;
+    constructor(error) {
+        super(formatServerError(error), {
+            cause: "cause" in error ? error.cause : undefined,
+        });
+        this.name = "ServerErrorException";
+        this.error = error;
+    }
+}
+export const isServerErrorException = (value) => value instanceof ServerErrorException;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { SessionRegistry } from "./session-registry.js";
+export interface ServerOptions {
+    port?: number;
+    host?: string;
+    staticRoot?: string | null;
+}
+export interface RunningServer {
+    port: number;
+    host: string;
+    registry: SessionRegistry;
+    stop: () => Promise<void>;
+}
+export declare const createServer: (options?: ServerOptions) => Promise<RunningServer>;
+export type { Session } from "./session.js";
+export type { SessionRegistry } from "./session-registry.js";
+export type * from "./types.js";
+export { DEFAULT_HOST, DEFAULT_PORT, WS_CLOSE_BACKPRESSURE } from "./constants.js";
+export { isLoopbackHost } from "./security.js";
+export { healthSchema } from "./schemas.js";
+export { ServerErrorException, formatServerError, isServerErrorException, serverError, } from "./errors.js";
+export type { ServerError, ServerErrorCode, ServerErrorKind } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAIxD,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAuDD,eAAO,MAAM,YAAY,GAAU,UAAS,aAAkB,KAAG,OAAO,CAAC,aAAa,CAiUrF,CAAC;AAEF,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,mBAAmB,YAAY,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}