cartethyia 2.5.3 → 2.5.6

package/src/console/remote-support/contracts.ts

@@ -0,0 +1,61 @@
+/**
+ * Remote-support tunnel contracts.
+ *
+ * A tunnel publishes the loopback gateway to a public or tailnet address. This
+ * module owns the vocabulary (which tool, which states, what a status reports)
+ * and is deliberately free of Elysia and Node imports so the dashboard can
+ * import the same shape without dragging a server runtime into the browser
+ * bundle.
+ */
+
+/** The two supported publishers. Both must already be installed. */
+export const REMOTE_SUPPORT_TOOLS = ["cloudflared", "tailscale"] as const;
+
+export type RemoteSupportTool = (typeof REMOTE_SUPPORT_TOOLS)[number];
+
+/**
+ * Why a tunnel cannot start. `not_installed` is the common one: this product
+ * never installs third-party binaries, so a missing `cloudflared` or
+ * `tailscale` is reported for the operator to install, never downloaded.
+ */
+export type RemoteSupportBlocker =
+  | "not_installed"
+  | "unsupported_platform"
+  | "launch_failed";
+
+export interface RemoteSupportStatus {
+  /** Which publisher is up, or `null` when neither is. */
+  readonly active: RemoteSupportTool | null;
+  /** The published base URL, present once the publisher reported one. */
+  readonly url: string | null;
+  /** Set when a start was refused, with the operator-facing reason. */
+  readonly blocker: RemoteSupportBlocker | null;
+  /** Operator-facing detail for `blocker`, e.g. the install hint. */
+  readonly message: string | null;
+  /** Local port the tunnel forwards to. */
+  readonly port: number;
+  /** Which publishers are installed on this host. Cached so the UI doesn't poll. */
+  readonly installed: Readonly<Record<RemoteSupportTool, boolean>>;
+}
+
+export interface RemoteSupportStartRequest {
+  readonly tool: RemoteSupportTool;
+  /** Defaults to the gateway's own port when omitted. */
+  readonly port?: number;
+}
+
+export interface RemoteSupportStartResponse extends RemoteSupportStatus {
+  readonly started: boolean;
+}
+
+/** Human-readable install guidance, keyed by tool. Never an installer. */
+export const REMOTE_SUPPORT_INSTALL_HINT: Readonly<Record<RemoteSupportTool, string>> = {
+  cloudflared:
+    "cloudflared is not installed. Install it yourself (winget install Cloudflare.cloudflared) and try again.",
+  tailscale:
+    "tailscale is not installed. Install it yourself (winget install Tailscale.Tailscale), run `tailscale up` once, then try again.",
+};
+
+export function isRemoteSupportTool(value: unknown): value is RemoteSupportTool {
+  return typeof value === "string" && (REMOTE_SUPPORT_TOOLS as readonly string[]).includes(value);
+}

package/src/console/remote-support/routes.ts

@@ -0,0 +1,65 @@
+/**
+ * Remote-support HTTP surface.
+ *
+ * Three routes over one external launcher script: read the current tunnel,
+ * start one, stop one. Every mutating route needs `dashboard:write` because it
+ * runs a process on the host running the gateway.
+ *
+ * The start response never contains a secret and never performs an install; it
+ * reports `not_installed` with guidance when the publisher is missing.
+ */
+import { Elysia, t } from "elysia";
+import type { ConsoleAccessResolver } from "../auth/access";
+import { consoleErrorHandler, requireTenantScope } from "../shared/errors";
+import { REMOTE_SUPPORT_TOOLS } from "./contracts";
+import type { RemoteSupportService } from "./service";
+
+export interface RemoteSupportRoutesConfig {
+  readonly accessResolver: ConsoleAccessResolver;
+  readonly service: RemoteSupportService;
+}
+
+const toolSchema = t.Union([
+  t.Literal(REMOTE_SUPPORT_TOOLS[0]),
+  t.Literal(REMOTE_SUPPORT_TOOLS[1]),
+]);
+
+const startBody = t.Object({
+  tool: toolSchema,
+  port: t.Optional(t.Number()),
+});
+
+const stopBody = t.Object({
+  tool: t.Optional(toolSchema),
+});
+
+/**
+ * The return type is inferred rather than annotated as `Elysia`: `.error()`
+ * widens the instance type with its handler's response envelope, so the
+ * annotated base type no longer matches the chained result.
+ */
+export function createRemoteSupportRoutes(config: RemoteSupportRoutesConfig) {
+  return new Elysia()
+    .error(consoleErrorHandler("Remote support failed"))
+    .get("/remote-support/status", async ({ request }) => {
+      requireTenantScope(config.accessResolver(request), "dashboard:read");
+      return await config.service.status();
+    })
+    .post(
+      "/remote-support/start",
+      { body: startBody },
+      async ({ request, body }) => {
+        requireTenantScope(config.accessResolver(request), "dashboard:write");
+        const status = await config.service.start(body.tool, body.port);
+        return { started: status.active !== null, ...status };
+      },
+    )
+    .post(
+      "/remote-support/stop",
+      { body: stopBody },
+      async ({ request, body }) => {
+        requireTenantScope(config.accessResolver(request), "dashboard:write");
+        return await config.service.stop(body.tool);
+      },
+    );
+}

package/src/console/remote-support/service.ts

@@ -0,0 +1,207 @@
+/**
+ * Remote-support tunnel service.
+ *
+ * The tunnel is launched by an external script rather than by spawning
+ * `cloudflared`/`tailscale` directly, for one reason that matters: the script
+ * hands the publisher to the OS session, so the tunnel is not a child of this
+ * gateway. A gateway restart, a hot reload, or a Ctrl-C in the owning terminal
+ * therefore cannot kill an operator's live remote-support session.
+ *
+ * This service never installs anything. A missing binary is reported as a
+ * blocker with install guidance; downloading a third-party agent on the
+ * operator's behalf is out of scope.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../../config/package-paths";
+import {
+  REMOTE_SUPPORT_INSTALL_HINT,
+  type RemoteSupportBlocker,
+  type RemoteSupportStatus,
+  type RemoteSupportTool,
+} from "./contracts";
+
+/** How long the launcher may take to report a URL before we stop waiting. */
+const LAUNCH_TIMEOUT_MS = 40_000;
+
+/** Cached install detection so we don't spawn `where` on every status poll. */
+const installedCache = new Map<RemoteSupportTool, boolean>();
+
+export interface RemoteSupportServiceConfig {
+  /** Defaults to the gateway's configured port. */
+  readonly port: number;
+  /** Overridable for tests; defaults to the package root. */
+  readonly scriptDir?: string;
+}
+
+interface CommandResult {
+  readonly status: number;
+  readonly stdout: string;
+}
+
+function scriptPath(config: RemoteSupportServiceConfig, name: string): string {
+  const dir = config.scriptDir ?? join(PACKAGE_ROOT, "scripts");
+  return join(dir, name);
+}
+
+function runScript(
+  config: RemoteSupportServiceConfig,
+  args: readonly string[],
+): Promise<CommandResult> {
+  const { promise, resolve, reject } = Promise.withResolvers<CommandResult>();
+  const isWindows = process.platform === "win32";
+  // Windows cannot spawn a `.cmd` directly — `spawn` rejects it with EINVAL
+  // because a batch file is not an executable image. It has to be handed to
+  // `cmd.exe /c`, which is also what lets the batch call `exit /b 3` and have
+  // that code reach us as the child's status.
+  const command = isWindows ? "cmd.exe" : "powershell";
+  const fileName = isWindows ? "remote-support.cmd" : "remote-support.ps1";
+  const file = scriptPath(config, fileName);
+  const spawnArgs = isWindows
+    ? ["/d", "/s", "/c", file, ...args]
+    : ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", file, ...args];
+  const child = spawn(command, spawnArgs, {
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  let stdout = "";
+  let stderr = "";
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (chunk: string) => {
+    stdout += chunk;
+  });
+  child.stderr.on("data", (chunk: string) => {
+    stderr += chunk;
+  });
+  const timer = setTimeout(() => child.kill(), LAUNCH_TIMEOUT_MS);
+  child.on("error", reject);
+  child.on("close", (status) => {
+    clearTimeout(timer);
+    resolve({ status: status ?? 1, stdout: `${stdout}${stderr}`.trim() });
+  });
+  return promise;
+}
+
+/**
+ * `where`/`which` lookup, mirroring what the script does itself so the route
+ * can answer `not_installed` with a clear message instead of a generic failure.
+ */
+function toolAvailable(tool: RemoteSupportTool): Promise<boolean> {
+  const cached = installedCache.get(tool);
+  if (cached !== undefined) return Promise.resolve(cached);
+  const { promise, resolve } = Promise.withResolvers<boolean>();
+  const command = process.platform === "win32" ? "where" : "which";
+  const child = spawn(command, [tool], { stdio: "ignore", windowsHide: true });
+  child.on("error", () => {
+    installedCache.set(tool, false);
+    resolve(false);
+  });
+  child.on("close", (status) => {
+    const ok = status === 0;
+    installedCache.set(tool, ok);
+    resolve(ok);
+  });
+  return promise;
+}
+
+export interface RemoteSupportService {
+  status(): Promise<RemoteSupportStatus>;
+  start(tool: RemoteSupportTool, port?: number): Promise<RemoteSupportStatus>;
+  stop(tool?: RemoteSupportTool): Promise<RemoteSupportStatus>;
+}
+
+export function createRemoteSupportService(config: RemoteSupportServiceConfig): RemoteSupportService {
+  const port = config.port;
+
+  /**
+   * Install state for both publishers, cached per process.
+   *
+   * Every status carries it so the card can show "not installed" without the
+   * browser probing on its own — but the probe is `where`/`which`, which is a
+   * process spawn, so it is memoised here rather than run on each poll.
+   */
+  async function detectInstalled(): Promise<Readonly<Record<RemoteSupportTool, boolean>>> {
+    return {
+      cloudflared: await toolAvailable("cloudflared"),
+      tailscale: await toolAvailable("tailscale"),
+    } as const;
+  }
+
+  async function readStatus(blocker: RemoteSupportBlocker | null = null, message: string | null = null): Promise<RemoteSupportStatus> {
+    const result = await runScript(config, ["status"]);
+    const text = result.stdout;
+    const active: RemoteSupportTool | null = text.includes("cloudflared running")
+      ? "cloudflared"
+      : text.includes("tailscale running")
+        ? "tailscale"
+        : null;
+    let url: string | null = null;
+    if (active !== null) {
+      const urlResult = await runScript(config, ["url"]);
+      const candidate = urlResult.stdout.trim().split(/\s+/).find((line) => line.startsWith("https://"));
+      url = candidate ?? null;
+    }
+    const installed = await detectInstalled();
+    return { active, url, blocker, message, port, installed };
+  }
+
+  return {
+    async status() {
+      return await readStatus();
+    },
+
+    async start(tool, requestedPort) {
+      if (process.platform !== "win32") {
+        return {
+          active: null,
+          url: null,
+          blocker: "unsupported_platform",
+          message: "Remote support is currently scripted for Windows hosts only.",
+          port,
+          installed: { cloudflared: false, tailscale: false },
+        };
+      }
+      const launcher = scriptPath(config, "remote-support.cmd");
+      if (!existsSync(launcher)) {
+        return {
+          active: null,
+          url: null,
+          blocker: "launch_failed",
+          message: `Launcher not found: ${launcher}`,
+          port,
+          installed: await detectInstalled(),
+        };
+      }
+      if (!(await toolAvailable(tool))) {
+        return {
+          active: null,
+          url: null,
+          blocker: "not_installed",
+          message: REMOTE_SUPPORT_INSTALL_HINT[tool],
+          port,
+          installed: await detectInstalled(),
+        };
+      }
+      const target = requestedPort ?? port;
+      const result = await runScript(config, ["start", tool, String(target)]);
+      if (result.status !== 0 && !result.stdout.includes("started")) {
+        return {
+          active: null,
+          url: null,
+          blocker: "launch_failed",
+          message: result.stdout || `Failed to start ${tool}.`,
+          port,
+          installed: await detectInstalled(),
+        };
+      }
+      return await readStatus();
+    },
+
+    async stop(tool) {
+      await runScript(config, tool === undefined ? ["stop"] : ["stop", tool]);
+      return await readStatus();
+    },
+  };
+}

package/src/console/response-compression.ts

@@ -18,9 +18,6 @@
  * only". A path test can, and it lives inside `gzipResponse` — the one place
  * that runs on every request.
  *
- * Consequence: `/v1/models` was previously compressed as a side effect of
- * that `hoc` propagation. It deliberately is not now.
- *
  * ## Why this is scoped to the console, not the proxy
  *
  * `/v1/*` is deliberately excluded, for two independent reasons:

package/src/console/routing/pools/import-parse.ts

@@ -0,0 +1,206 @@
+// Parsing a proxy list pasted from a file.
+//
+// Every provider hands out its proxy list in a different shape, and the shape
+// is not something an operator should have to convert by hand before this
+// gateway will accept it. Three forms cover what actually arrives:
+//
+//   - a JSON array of pool objects (the shape `POST /network/pools` takes);
+//   - one bare URI per line — `http://user:pass@1.2.3.4:8080`;
+//   - one `host:port:user:password` row per line, which is what resellers send.
+//
+// A line that parses to nothing is reported rather than silently dropped: a
+// list of 200 where 40 were skipped looks like a successful import and leaves
+// the operator short 40 nodes with no reason.
+//
+// Secrets are handled as little as possible — they are parsed into a
+// credential and handed straight to the store, never logged.
+
+import { POOL_KINDS, POOL_STATUSES } from "./contracts";
+
+/** One row that parsed, ready to become a pool. */
+export interface ParsedProxyRow {
+  readonly kind: (typeof POOL_KINDS)[number];
+  readonly endpoint: string;
+  readonly credential: string | null;
+  readonly label: string | null;
+}
+
+/** One row that did not parse, with the reason. */
+export interface SkippedProxyRow {
+  readonly line: number;
+  readonly reason: string;
+}
+
+export interface ParsedProxyFile {
+  readonly rows: readonly ParsedProxyRow[];
+  readonly skipped: readonly SkippedProxyRow[];
+}
+
+/** Schemes this gateway can dispatch through, mapped to a pool kind. */
+const SCHEME_KINDS: Readonly<Record<string, (typeof POOL_KINDS)[number]>> = {
+  http: "http",
+  https: "http",
+  socks5: "socks5",
+  socks5h: "socks5",
+  socks4: "socks5",
+};
+
+/** Kept as a name rather than a literal, because two callers compare against it. */
+const DEFAULT_KIND: (typeof POOL_KINDS)[number] = "http";
+
+function isPoolKind(value: unknown): value is (typeof POOL_KINDS)[number] {
+  return typeof value === "string" && (POOL_KINDS as readonly string[]).includes(value);
+}
+
+function isPoolStatus(value: unknown): value is (typeof POOL_STATUSES)[number] {
+  return typeof value === "string" && (POOL_STATUSES as readonly string[]).includes(value);
+}
+
+/**
+ * The endpoint scheme, lowercased, or `null` when the line carries none.
+ *
+ * A line without a scheme is still valid — `host:port` is the most common
+ * reseller form — so "no scheme" means "assume http", not "unparseable".
+ */
+function schemeOf(text: string): string | null {
+  const match = /^([a-z][a-z0-9+.-]*):\/\//i.exec(text.trim());
+  const scheme = match?.[1];
+  return scheme ? scheme.toLowerCase() : null;
+}
+
+/** Splits `host:port:user:password`, where the password may itself contain `:`. */
+function splitColonRow(text: string): {
+  readonly host: string;
+  readonly port: string;
+  readonly user: string | null;
+  readonly password: string | null;
+} | null {
+  // The password is last and may contain colons, so it is everything after the
+  // third separator rather than a fourth field.
+  const parts: readonly string[] = text.trim().split(":");
+  if (parts.length < 2) return null;
+  const host = (parts[0] ?? "").trim();
+  const port = (parts[1] ?? "").trim();
+  if (!host || !port || !/^\d+$/.test(port)) return null;
+  const user = parts.length > 2 ? (parts[2] ?? "").trim() : "";
+  const password = parts.length > 3 ? parts.slice(3).join(":").trim() : "";
+  return {
+    host,
+    port,
+    user: user !== "" ? user : null,
+    password: password !== "" ? password : null,
+  };
+}
+
+/** One bare-URI line, e.g. `http://user:pass@1.2.3.4:8080`. */
+function parseUriLine(text: string): ParsedProxyRow | null {
+  const scheme = schemeOf(text);
+  if (scheme === null) return null;
+  const kind = SCHEME_KINDS[scheme] ?? DEFAULT_KIND;
+  const withoutScheme = text.trim().slice(scheme.length + 3);
+  const at = withoutScheme.lastIndexOf("@");
+  const authority = at >= 0 ? withoutScheme.slice(at + 1) : withoutScheme;
+  const userinfo = at >= 0 ? withoutScheme.slice(0, at) : null;
+  if (!authority) return null;
+  const credential = userinfo
+    ? decodeURIComponent(userinfo)
+    : null;
+  const hasPort = /:\d+$/.test(authority);
+  const endpoint = hasPort ? authority : `${authority}`;
+  if (!endpoint) return null;
+  return { kind, endpoint: `${scheme}://${endpoint}`, credential, label: null };
+}
+
+/** One `host:port[:user[:password]]` line. */
+function parseColonLine(text: string): ParsedProxyRow | null {
+  const row = splitColonRow(text);
+  if (!row) return null;
+  const credential =
+    row.user !== null ? (row.password !== null ? `${row.user}:${row.password}` : row.user) : null;
+  // The store requires a full URL, and a reseller row carries no scheme.
+  // `http://` is the safe reading: it is the default for a bare row, and an
+  // operator who means socks writes the scheme.
+  return {
+    kind: DEFAULT_KIND,
+    endpoint: `http://${row.host}:${row.port}`,
+    credential,
+    label: null,
+  };
+}
+
+/**
+ * Parses one line.
+ *
+ * Blank lines and `#` comments are skipped without being reported: they are
+ * structure, not failed rows, and listing them as skipped would bury the rows
+ * that actually failed.
+ */
+function parseLine(text: string): ParsedProxyRow | null {
+  const trimmed = text.trim();
+  if (trimmed === "" || trimmed.startsWith("#")) return null;
+  return parseUriLine(trimmed) ?? parseColonLine(trimmed);
+}
+
+/** Parses a JSON array of pool objects. */
+function parseJsonArray(value: unknown): ParsedProxyFile | null {
+  if (!Array.isArray(value)) return null;
+  const rows: ParsedProxyRow[] = [];
+  const skipped: SkippedProxyRow[] = [];
+  value.forEach((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      skipped.push({ line: index + 1, reason: "not an object" });
+      return;
+    }
+    const record = entry as Record<string, unknown>;
+    const endpoint = typeof record["endpoint"] === "string" ? record["endpoint"].trim() : "";
+    if (!endpoint) {
+      skipped.push({ line: index + 1, reason: "no endpoint" });
+      return;
+    }
+    rows.push({
+      kind: isPoolKind(record["kind"]) ? record["kind"] : DEFAULT_KIND,
+      endpoint,
+      credential: typeof record["credential"] === "string" ? record["credential"] : null,
+      label: typeof record["label"] === "string" ? record["label"] : null,
+    });
+  });
+  return { rows, skipped };
+}
+
+/**
+ * Parses a pasted proxy list.
+ *
+ * JSON is tried first, because a whole file that happens to be valid JSON is
+ * unambiguous; anything else is treated as line-oriented text.
+ */
+export function parseProxyFile(content: string): ParsedProxyFile {
+  const trimmed = content.trim();
+  if (trimmed === "") return { rows: [], skipped: [] };
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed) as unknown;
+      if (Array.isArray(parsed)) {
+        const result = parseJsonArray(parsed);
+        if (result) return result;
+      }
+      // A single object is one pool, which is a legitimate one-line file.
+      const single = parseJsonArray([parsed]);
+      if (single && single.rows.length > 0) return single;
+    } catch {
+      // Falls through to the line parser: a file that is *nearly* JSON is more
+      // likely a text list than a corrupt one.
+    }
+  }
+  const rows: ParsedProxyRow[] = [];
+  const skipped: SkippedProxyRow[] = [];;
+  trimmed.split(/\r?\n/).forEach((line, index) => {
+    const parsed = parseLine(line);
+    if (parsed) rows.push(parsed);
+    else if (line.trim() !== "" && !line.trim().startsWith("#")) {
+      skipped.push({ line: index + 1, reason: "not a proxy URI or host:port row" });
+    }
+  });
+  return { rows, skipped };
+}
+
+export { isPoolKind, isPoolStatus };