Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

10.2 KB
Raw Blame
// SERVER-ONLY. Builds a zip of selected entries via the host `zip` binary
// (Info-ZIP 3.0, already on the box) — no archive dependency. zip writes to a
// SEEKABLE temp file, then we stream that file to the HTTP response and delete it.
// We can't pipe zip's stdout straight to the response: Info-ZIP aborts when a
// stored/symlink entry has to go to a NON-seekable pipe ("zip -0 not supported for
// I/O on pipes"), which with `-y` (below) breaks any tree containing a symlink
// (e.g. pnpm node_modules) → a truncated, unextractable archive. A temp file is
// seekable, so the central directory is written correctly. Each name is a plain
// basename inside `base`; `base` and every child are realpath'd + bounds-checked
// inside the READ roots (and credential-blocked) before zip runs. Names are
// `./`-prefixed so a file literally named "-x" can't be read as a flag — we can't
// use `--` because it also disables the TRAILING `-x` exclude options (host-verified).
// `exclude` (heavy dirs like node_modules/.git) → `-x name/* */name/*`; Info-ZIP `*`
// spans `/`, so the second drops that dir at any depth below the root and the first
// covers the root itself, where there is nothing before the slash to match. Excludes
// only NARROW the archive (never widen access), so they're low-risk, but each is
// still a safe basename.
import { spawn } from "child_process";
import { constants, promises as fsp } from "fs";
import os from "os";
import path from "path";
import type { Readable } from "stream";
import { HostError } from "./host-error";
import { snapshotArchive } from "./fs-archive-snapshot";
import { appDir, isCredentialPath, looseCredentialExcludes, resolveReadable, sensitiveExcludes } from "./paths";

const ZIP_MAX_INPUT_BYTES = 512 * 1024 * 1024;
const ZIP_MAX_OUTPUT_BYTES = 600 * 1024 * 1024;
const ZIP_MAX_FILES = 50_000;
const ZIP_SCAN_TIMEOUT_MS = 5_000;
const ZIP_PROCESS_TIMEOUT_MS = 60_000;
const zipGate = (globalThis as typeof globalThis & { __msoZipActive?: boolean });

async function assertArchiveBudget(realBase: string, names: string[], exclude: string[]): Promise<void> {
  const excluded = new Set(exclude);
  const deadline = Date.now() + ZIP_SCAN_TIMEOUT_MS;
  let files = 0, bytes = 0;
  const stack = names.map((name) => path.join(realBase, name));
  while (stack.length) {
    if (Date.now() > deadline) throw new HostError("Archive preflight exceeded its time limit");
    const current = stack.pop()!;
    if (excluded.has(path.basename(current)) || isCredentialPath(current)) continue;
    let stat: import("node:fs").Stats;
    try { stat = await fsp.lstat(current); } catch { continue; }
    if (stat.isSymbolicLink()) {
      files += 1; bytes += stat.size;
    } else if (stat.isDirectory()) {
      let children: string[];
      try { children = await fsp.readdir(current); } catch { continue; }
      for (const child of children) stack.push(path.join(current, child));
    } else if (stat.isFile()) {
      files += 1; bytes += stat.size;
    }
    if (files > ZIP_MAX_FILES) throw new HostError("Archive selection exceeds the 50000 file limit");
    if (bytes > ZIP_MAX_INPUT_BYTES) throw new HostError("Archive selection exceeds the 512 MiB input limit");
  }
  const statfs = await fsp.statfs(os.tmpdir());
  const free = Number(statfs.bavail) * Number(statfs.bsize);
  if (!Number.isFinite(free) || free < bytes * 2 + 64 * 1024 * 1024) {
    throw new HostError("Insufficient temporary disk space for archive generation");
  }
}

// A selectable item is a single basename in the listed dir — never a path. Reject
// separators/traversal/NUL so a name can't escape `base` (defense-in-depth; the
// per-child resolveReadable below also realpaths + bounds-checks each one).
export function assertSafeName(name: string): void {
  if (!name || name === "." || name === ".." || /[/\\\0]/.test(name))
    throw new HostError("Invalid item name");
}

// Forced excludes that guard the app's OWN secrets no matter what the user picks:
// when APP_DIR is nested inside the archived base, `zip -r` would recurse into it
// past the per-name credential gate, so strip its `.env*` (OS_SESSION_SECRET).
// Returns [] when base is APP_DIR itself or unrelated to it.
export function appSecretExcludes(realBase: string): string[] {
  const rel = path.relative(realBase, appDir());
  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return [];
  return [`${rel}/.env`, `${rel}/.env.*`];
}

export async function zipStream(
  base: string,
  names: string[],
  exclude: string[] = [],
): Promise<Readable> {
  if (!names.length) throw new HostError("No items to archive");
  const real = await resolveReadable(base);
  for (const n of names) {
    assertSafeName(n);
    await resolveReadable(path.join(real, n)); // realpath + read-root + credential gate
  }
  for (const n of exclude) assertSafeName(n);
  if (zipGate.__msoZipActive) throw new HostError("Another archive is already being generated");
  zipGate.__msoZipActive = true;
  let tmpDir = "";
  let snapshot = "";
  try {
    await assertArchiveBudget(real, names, exclude);
    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), "os-zip-"));
    snapshot = path.join(tmpDir, "snapshot");
    await fsp.mkdir(snapshot, {mode: 0o700});
    await snapshotArchive(real, names, exclude, snapshot);
  } catch (error) {
    if (tmpDir) await fsp.rm(tmpDir, {recursive: true, force: true});
    zipGate.__msoZipActive = false;
    throw error;
  }
  const out = path.join(tmpDir, "archive.zip");
  // `-y` = store symlinks AS links, never follow. Without it `zip -r` archives a
  // link's TARGET content, escaping the realpath/credential bounds checked above
  // (a link to ~/.ssh/id_rsa inside a zipped dir would otherwise leak).
  const args = ["-r", "-y", "-q", out, ...names.map((n) => `./${n}`)];
  const patterns: string[] = [];
  for (const name of exclude) {
    // already validated before preflight; keep the comment here because patterns
    // remain intentionally derived only from basenames, never raw client globs.
    // BOTH forms are needed. Info-ZIP `*` spans `/`, so `*/name/*` drops the dir at
    // any depth BELOW the archive root — but it cannot match at the root itself,
    // where the entry is `name/…` with nothing before the slash. Selecting
    // node_modules directly (or any sibling set containing it) with "skip
    // node_modules" ticked therefore archived it in full. Host-verified both ways.
    patterns.push(`${name}/*`, `*/${name}/*`);
  }
  patterns.push(...appSecretExcludes(real)); // forced credential guard, see above
  patterns.push(...sensitiveExcludes(real)); // same, for ~/ credential dirs nested under `base`
  patterns.push(...looseCredentialExcludes()); // basename-anywhere private keys / *.pem
  if (patterns.length) args.push("-x", ...patterns);

  // All stdio ignored — zip writes to the temp FILE, not a pipe, so there's no
  // stream to drain (and nothing can deadlock on an unread stderr). Wait for it to
  // finish before streaming, so the archive is complete + the central dir is sound.
  //
  // 18 = "could not open a specified file to read". Info-ZIP still writes a COMPLETE,
  // valid archive of everything else and only skips what it could not read, so this is
  // a partial success, not a failure — and on a real VPS home dir (root-owned files,
  // sockets, other users' dirs) it fires constantly. Rejecting it deletes the tmpdir and
  // hands the user nothing over one unreadable file. Verified on this host:
  // `zip -r -y -q out.zip ./good.txt ./nope.txt` with nope.txt chmod 000 → exit 18,
  // archive contains good.txt.
  const PARTIAL_OK = 18;
  // 12 = "Nothing to do" — every selected entry was excluded, and NO file is written
  // (verified), so streaming would ENOENT. It is the one code that needs its own words.
  const NOTHING_TO_DO = 12;
  try {
    await new Promise<void>((resolve, reject) => {
      const child = spawn("zip", args, { cwd: snapshot, stdio: "ignore" });
      let timedOut = false;
      const timer = setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, ZIP_PROCESS_TIMEOUT_MS);
      child.on("error", (error) => { clearTimeout(timer); reject(error); }); // missing binary / spawn fail
      child.on("close", (code) => {
        clearTimeout(timer);
        if (timedOut) return reject(new HostError("Archive generation exceeded the 60 second limit"));
        if (code === 0 || code === PARTIAL_OK) return resolve();
        if (code === NOTHING_TO_DO)
          return reject(new HostError("Nothing to archive: everything selected was excluded"));
        reject(new HostError(`zip exited ${code}`));
      });
    });
  } catch (e) {
    await fsp.rm(tmpDir, { recursive: true, force: true });
    zipGate.__msoZipActive = false;
    throw e;
  }
  // Open first with O_NOFOLLOW, then inspect that exact descriptor. A path-level
  // stat followed by open is a TOCTOU race and was correctly flagged by CodeQL.
  // The private mkdtemp directory already narrows the attack surface, but the
  // descriptor check makes the invariant explicit and race-free.
  let handle: Awaited<ReturnType<typeof fsp.open>> | undefined;
  try {
    handle = await fsp.open(/* turbopackIgnore: true */ out, constants.O_RDONLY | constants.O_NOFOLLOW);
    const outStat = await handle.stat();
    if (!outStat.isFile() || outStat.size > ZIP_MAX_OUTPUT_BYTES) {
      throw new HostError("Generated archive exceeds the 600 MiB output limit");
    }

    // ponytail: staged on disk, not streamed as zip runs — correctness over the
    // buffer-free ideal, since a piped zip won't extract. Opened, then unlinked
    // BEFORE the stream is handed back: the open fd keeps bytes readable while the
    // directory entry is already gone, so abandoned responses cannot strand /tmp.
    await fsp.rm(tmpDir, { recursive: true, force: true });
    const stream = handle.createReadStream({ autoClose: true });
    const timer = setTimeout(() => stream.destroy(), ZIP_PROCESS_TIMEOUT_MS).unref();
    stream.once("close", () => { clearTimeout(timer); zipGate.__msoZipActive = false; });
    handle = undefined; // stream now owns the descriptor
    return stream;
  } catch (error) {
    await handle?.close().catch(() => undefined);
    await fsp.rm(tmpDir, { recursive: true, force: true });
    zipGate.__msoZipActive = false;
    if (error instanceof HostError) throw error;
    throw new HostError("Generated archive is unavailable");
  }
}