@moondeck/station 0.0.0-stage → 1.0.0

package/lib/tunnel-runtime.ts

@@ -0,0 +1,235 @@
+import { isIP } from "node:net";
+
+import { dockerCli, type DockerResult } from "./docker-exec";
+import { reprobeContainerRuntimeMachineIdentity } from "./container-runtime";
+
+type DockerRunner = (
+  args: string[],
+  options?: { timeoutMs?: number },
+) => Promise<DockerResult>;
+
+export type TunnelContainerProof =
+  | {
+      kind: "running";
+      containerId: string;
+      published: { host: string; port: number } | null;
+      containerIp: string | null;
+      network: string | null;
+      labels: Record<string, string>;
+    }
+  | { kind: "unavailable" }
+  | { kind: "daemon-unavailable"; detail: string };
+
+interface DockerContainerInspection {
+  Id?: unknown;
+  Name?: unknown;
+  Config?: { Labels?: Record<string, unknown> | null };
+  State?: { Running?: unknown };
+  NetworkSettings?: {
+    Ports?: Record<
+      string,
+      Array<{ HostIp?: unknown; HostPort?: unknown }> | null
+    >;
+    Networks?: Record<string, { IPAddress?: unknown }>;
+  };
+}
+
+const COMPOSE_PROJECT_LABEL = "com.docker.compose.project";
+const COMPOSE_SERVICE_LABEL = "com.docker.compose.service";
+const CONTAINER_ID = /^[a-f0-9]{64}$/;
+
+/**
+ * Prove that an exact container is running and resolve its current routes.
+ *
+ * Persisted host ports and cached container IPs are unsafe after an unnoticed
+ * daemon restart: Docker may remap the app, and an unrelated local process (or
+ * another container) can inherit the old address. Every tunnel open crosses
+ * this proof before bytes are forwarded.
+ */
+export async function inspectTunnelContainer(
+  container: string,
+  containerPort: number,
+  deps: { docker?: DockerRunner } = {},
+): Promise<TunnelContainerProof> {
+  const run = deps.docker ?? dockerCli;
+  const inspected = await run(
+    ["inspect", "--format", "{{json .}}", container],
+    { timeoutMs: 5_000 },
+  );
+  if (inspected.status !== 0) {
+    if (!deps.docker) {
+      return (await reprobeContainerRuntimeMachineIdentity()) === null
+        ? { kind: "daemon-unavailable", detail: "docker did not answer" }
+        : { kind: "unavailable" };
+    }
+    const daemon = await run(
+      ["info", "--format", "{{.ServerVersion}}"],
+      { timeoutMs: 5_000 },
+    );
+    if (daemon.status !== 0 || !daemon.stdout.trim()) {
+      return {
+        kind: "daemon-unavailable",
+        // This reaches cloud-visible command errors. Docker's own diagnostic
+        // can contain the pinned unix socket (and therefore a host username),
+        // so keep endpoint details in Docker's local logs rather than the wire.
+        detail: "docker did not answer",
+      };
+    }
+    return { kind: "unavailable" };
+  }
+
+  let value: DockerContainerInspection;
+  try {
+    value = JSON.parse(inspected.stdout.trim()) as DockerContainerInspection;
+  } catch {
+    return { kind: "unavailable" };
+  }
+  if (value.State?.Running !== true) return { kind: "unavailable" };
+
+  const containerId = exactContainerId(value.Id);
+  if (!containerId) return { kind: "unavailable" };
+  const address = firstContainerAddress(value);
+
+  return {
+    kind: "running",
+    containerId,
+    published: publishedAddress(value, containerPort),
+    containerIp: address?.ip ?? null,
+    network: address?.network ?? null,
+    labels: stringLabels(value.Config?.Labels),
+  };
+}
+
+/**
+ * Stronger proof for editor/preview routing into a task's app. Docker's exact
+ * name lookup is necessary but not sufficient: a recreated or foreign
+ * container can reuse it. Bind the route to Compose's project/service labels,
+ * the full container ID, and only the expected project default network.
+ */
+export async function inspectTaskAppTunnelContainer(
+  request: {
+    readonly container: string;
+    readonly composeProject: string;
+    readonly containerPort: number;
+  },
+  deps: { docker?: DockerRunner } = {},
+): Promise<TunnelContainerProof> {
+  const run = deps.docker ?? dockerCli;
+  const inspected = await run(
+    ["inspect", "--format", "{{json .}}", request.container],
+    { timeoutMs: 5_000 },
+  );
+  if (inspected.status !== 0) {
+    if (!deps.docker) {
+      return (await reprobeContainerRuntimeMachineIdentity()) === null
+        ? { kind: "daemon-unavailable", detail: "docker did not answer" }
+        : { kind: "unavailable" };
+    }
+    const daemon = await run(
+      ["info", "--format", "{{.ServerVersion}}"],
+      { timeoutMs: 5_000 },
+    );
+    if (daemon.status !== 0 || !daemon.stdout.trim()) {
+      return { kind: "daemon-unavailable", detail: "docker did not answer" };
+    }
+    return { kind: "unavailable" };
+  }
+
+  let value: DockerContainerInspection;
+  try {
+    value = JSON.parse(inspected.stdout.trim()) as DockerContainerInspection;
+  } catch {
+    return { kind: "unavailable" };
+  }
+  const labels = stringLabels(value.Config?.Labels);
+  const containerId = exactContainerId(value.Id);
+  const network = `${request.composeProject}_default`;
+  const ip = exactNetworkAddress(value, network);
+  if (
+    value.State?.Running !== true ||
+    value.Name !== `/${request.container}` ||
+    !containerId ||
+    labels[COMPOSE_PROJECT_LABEL] !== request.composeProject ||
+    labels[COMPOSE_SERVICE_LABEL] !== "app" ||
+    !ip
+  ) {
+    return { kind: "unavailable" };
+  }
+  return {
+    kind: "running",
+    containerId,
+    published: publishedAddress(value, request.containerPort),
+    containerIp: ip,
+    network,
+    labels,
+  };
+}
+
+function exactContainerId(value: unknown): string | null {
+  return typeof value === "string" && CONTAINER_ID.test(value) ? value : null;
+}
+
+function stringLabels(
+  labels: Record<string, unknown> | null | undefined,
+): Record<string, string> {
+  if (!labels) return {};
+  return Object.fromEntries(
+    Object.entries(labels).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+}
+
+function publishedAddress(
+  value: DockerContainerInspection,
+  containerPort: number,
+): { host: string; port: number } | null {
+  const bindings = value.NetworkSettings?.Ports?.[`${containerPort}/tcp`];
+  if (!Array.isArray(bindings)) return null;
+  const candidates = bindings.flatMap((binding) => {
+    const port = parsePort(binding.HostPort);
+    const host = loopbackForBinding(binding.HostIp);
+    return port && host ? [{ host, port }] : [];
+  });
+  return (
+    candidates.find((candidate) => candidate.host === "127.0.0.1") ??
+    candidates[0] ??
+    null
+  );
+}
+
+function loopbackForBinding(value: unknown): string | null {
+  if (value === "127.0.0.1" || value === "0.0.0.0" || value === "") {
+    return "127.0.0.1";
+  }
+  if (value === "::1" || value === "::") return "::1";
+  return null;
+}
+
+function parsePort(value: unknown): number | null {
+  if (typeof value !== "string" || !/^\d{1,5}$/.test(value)) return null;
+  const port = Number(value);
+  return Number.isInteger(port) && port >= 1 && port <= 65_535 ? port : null;
+}
+
+function firstContainerAddress(
+  value: DockerContainerInspection,
+): { network: string; ip: string } | null {
+  const networks = value.NetworkSettings?.Networks;
+  if (!networks || typeof networks !== "object") return null;
+  for (const [name, network] of Object.entries(networks)) {
+    const address = network?.IPAddress;
+    if (typeof address === "string" && isIP(address) !== 0) {
+      return { network: name, ip: address };
+    }
+  }
+  return null;
+}
+
+function exactNetworkAddress(
+  value: DockerContainerInspection,
+  network: string,
+): string | null {
+  const address = value.NetworkSettings?.Networks?.[network]?.IPAddress;
+  return typeof address === "string" && isIP(address) !== 0 ? address : null;
+}

package/lib/ulid.ts

@@ -0,0 +1,16 @@
+import { ulid } from "ulid";
+
+export function newId(): string {
+  return ulid().toLowerCase();
+}
+
+/**
+ * A ULID with its canonical UPPERCASE base32, unlike `newId()` above.
+ *
+ * Renamed from `monotonicUlid`, which it never was: the plain generator
+ * randomises the suffix, so two ids minted in the same millisecond do not
+ * sort in call order. Nothing in this package imports it — it is kept only to
+ * mirror `lib/ulid.ts`, and it is renamed here too so the false promise is
+ * not sitting in the copy someone reads next.
+ */
+export { ulid as rawUlid };

package/lib/user-bus-env.ts

@@ -0,0 +1,116 @@
+/**
+ * What `systemctl --user` needs to reach the user's service manager:
+ * XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS. A login shell has both. A
+ * stripped environment does not (an old-host command run with only the old
+ * defaults, a non-login shell, `su` without `-l`), and there systemctl fails
+ * with "Failed to connect to bus: No medium found" (the 2026-11-01 rehearsal,
+ * uninstall-legacy on Linux).
+ *
+ * Every value is checked before it is used, inherited or derived alike, so a
+ * borrowed environment can't point this user's systemctl at someone else's
+ * manager:
+ * - a runtime directory must be a real directory (not a link) owned by this
+ *   uid and not group- or world-writable;
+ * - a bus must be `unix:path=<absolute path>` naming a socket (not a link)
+ *   owned by this uid.
+ * An inherited value that fails is replaced by the one derived the way
+ * pam_systemd sets it (/run/user/<uid>, and its `bus`), or left unset.
+ *
+ * An inherited bus address in any other form (`unix:abstract=`, `tcp:`,
+ * `unix:tmpdir=`, a `;`-separated list) can't be checked this way and is
+ * dropped. The systemd user bus is always `unix:path=$XDG_RUNTIME_DIR/bus`, so
+ * nothing this runs needs another form.
+ *
+ * Every path, inherited or derived, must also be plain: letters, digits and
+ * `_ / . -` only, the bytes D-Bus never escapes. A D-Bus client percent-decodes
+ * an address and splits it at `;` and `,`, so `…/target%2fbus` would name a
+ * socket other than the one checked, and a runtime dir holding
+ * `;unix:path=…` would emit a second address. A path that isn't plain is
+ * dropped, never escaped, so what is checked is byte for byte what is used.
+ */
+
+import { lstatSync } from "node:fs";
+import path from "node:path";
+
+export interface UserBusEntry {
+  readonly uid: number;
+  readonly mode: number;
+  readonly kind: "directory" | "socket" | "other";
+}
+
+export interface UserBusProbe {
+  readonly uid: number;
+  /** lstat (never through a link), or null when absent or unreadable. */
+  stat(target: string): UserBusEntry | null;
+}
+
+export const systemUserBusProbe = (): UserBusProbe => ({
+  uid: process.getuid?.() ?? -1,
+  stat: (target) => {
+    try {
+      const entry = lstatSync(target);
+      return {
+        uid: entry.uid,
+        mode: entry.mode,
+        kind: entry.isDirectory() ? "directory" : entry.isSocket() ? "socket" : "other",
+      };
+    } catch {
+      return null;
+    }
+  },
+});
+
+/** An absolute path of bytes D-Bus never escapes, so it reads back as itself. */
+const plainPath = (target: string) => /^\/[A-Za-z0-9_/.-]*$/.test(target);
+
+function ownRuntimeDir(dir: string | undefined, probe: UserBusProbe): string | undefined {
+  if (!dir || !plainPath(dir) || probe.uid < 0) return undefined;
+  const entry = probe.stat(dir);
+  return entry?.kind === "directory" && entry.uid === probe.uid && (entry.mode & 0o022) === 0 ? dir : undefined;
+}
+
+function ownBusSocket(socket: string, probe: UserBusProbe): boolean {
+  if (!plainPath(socket) || probe.uid < 0) return false;
+  const entry = probe.stat(socket);
+  return entry?.kind === "socket" && entry.uid === probe.uid;
+}
+
+/** The socket of a `unix:path=<p>[,guid=<hex>]` address, or null for any other form. */
+function busSocketPath(address: string): string | null {
+  const match = /^unix:path=([^,;]+)(?:,guid=[0-9a-f]+)?$/.exec(address);
+  return match ? match[1]! : null;
+}
+
+export function userBusEnv(
+  inherited: NodeJS.ProcessEnv,
+  probe: UserBusProbe,
+): { XDG_RUNTIME_DIR?: string; DBUS_SESSION_BUS_ADDRESS?: string } {
+  const runtimeDir =
+    ownRuntimeDir(inherited.XDG_RUNTIME_DIR || undefined, probe) ??
+    ownRuntimeDir(probe.uid >= 0 ? `/run/user/${probe.uid}` : undefined, probe);
+  let bus: string | undefined;
+  const inheritedBus = inherited.DBUS_SESSION_BUS_ADDRESS;
+  const inheritedSocket = inheritedBus ? busSocketPath(inheritedBus) : null;
+  if (inheritedBus && inheritedSocket && ownBusSocket(inheritedSocket, probe)) {
+    bus = inheritedBus;
+  } else if (runtimeDir && ownBusSocket(path.join(runtimeDir, "bus"), probe)) {
+    bus = `unix:path=${path.join(runtimeDir, "bus")}`;
+  }
+  return {
+    ...(runtimeDir ? { XDG_RUNTIME_DIR: runtimeDir } : {}),
+    ...(bus ? { DBUS_SESSION_BUS_ADDRESS: bus } : {}),
+  };
+}
+
+/**
+ * `inherited` (its defined values) with the user-bus variables replaced by the
+ * checked ones: an inherited value that fails the checks is removed, never
+ * passed on.
+ */
+export function withUserBusEnv(inherited: NodeJS.ProcessEnv, probe: UserBusProbe): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [name, value] of Object.entries(inherited)) {
+    if (value !== undefined && name !== "XDG_RUNTIME_DIR" && name !== "DBUS_SESSION_BUS_ADDRESS") env[name] = value;
+  }
+  return { ...env, ...userBusEnv(inherited, probe) };
+}