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.

8.2 KB
Raw Blame
// SERVER-ONLY. Host filesystem ops behind /api/v1/fs/*. Reads follow READ
// roots (browse), mutations follow WRITE roots (see paths.ts). Returns the
// os-rr shapes directly so route handlers are thin.
import { promises as fs, constants as fsConstants, type ReadStream } from "fs";
import type { FileHandle } from "node:fs/promises";
import path from "node:path";
import { openReadableHandle, pinDirectory, readBoundedBytes } from "./fs-descriptors";
import { copyPinned, removePinned } from "./fs-recursive";
import { randomUUID } from "node:crypto";
import type { FsUsage } from "@/lib/os-api/types";
import { HostError } from "./host-error";
import {
  assertNoAppSecretDescendants,
  assertNoCredentialDescendants,
  assertNoSensitiveDescendants,
  assertNotRoot,
  resolveReadable,
  safeMkdirPath,
  safeWritePath,
} from "./paths";

export { listDir, searchFs } from "./fs-enumeration";

export async function readFile(requested: string): Promise<string> {
  const p = await resolveReadable(requested);
  let handle;
  try {
    handle = await openReadableHandle(p);
    const stat = await handle.stat();
    if (!stat.isFile()) throw new HostError(stat.isDirectory() ? "Is a directory" : "Not a regular file");
    if (stat.size > 5_000_000) throw new HostError("File too large to read (max 5 MiB)");
    return (await readBoundedBytes(handle, 5_000_000)).toString("utf8");
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ELOOP") throw new HostError("Refusing symlink file");
    throw error;
  } finally {
    await handle?.close().catch(() => undefined);
  }
}

export async function writeFile(requested: string, content: string): Promise<void> {
  const p = await safeWritePath(requested, false);
  await assertNotRoot(p);
  const parent = await pinDirectory(path.dirname(p), true);
  let handle, tmp: string | undefined;
  try {
    tmp = await parent.child(`${path.basename(p)}.tmp-${randomUUID()}`);
    handle = await fs.open(tmp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW, 0o600);
    await handle.writeFile(content ?? ""); await handle.close();
    await fs.rename(tmp, await parent.child(path.basename(p)));
  } finally { await handle?.close().catch(() => undefined); if (tmp) await fs.unlink(tmp).catch(() => undefined); await parent.handle.close(); }
}

export async function makeDir(requested: string): Promise<void> {
  const p = await safeMkdirPath(requested);
  const dir = await pinDirectory(p, true, true);
  await dir.handle.close();
}

export async function remove(requested: string): Promise<void> {
  const p = await safeWritePath(requested, true);
  await assertNotRoot(p);
  await assertNoCredentialDescendants(p);
  const parent = await pinDirectory(path.dirname(p), true);
  try { await removePinned(await parent.child(path.basename(p))); }
  finally { await parent.handle.close(); }
}

export async function move(from: string, to: string): Promise<void> {
  const src = await safeWritePath(from, true);
  await assertNotRoot(src);
  assertNoSensitiveDescendants(src); // fixed sensitive locations under a parent
  assertNoAppSecretDescendants(src); // the cockpit's own .env* under a parent
  await assertNoCredentialDescendants(src); // loose id_* / *.pem anywhere below
  const dest = await safeWritePath(to, false);
  const sourceParent = await pinDirectory(path.dirname(src), true);
  let destParent;
  try {
    destParent = await pinDirectory(path.dirname(dest), true);
    const source = await sourceParent.child(path.basename(src)), target = await destParent.child(path.basename(dest));
    try { await fs.rename(source, target); }
    catch (error) {
      if ((error as NodeJS.ErrnoException).code !== "EXDEV") throw error;
      await copyPinned(source, target);
      await removePinned(await sourceParent.child(path.basename(src)));
    }
  } finally { await sourceParent.handle.close(); await destParent?.handle.close(); }
}

export async function copy(from: string, to: string): Promise<void> {
  const src = await safeWritePath(from, true);
  assertNoSensitiveDescendants(src); // fixed sensitive locations under a parent
  // The app's own .env* are intentionally filtered below; every other credential
  // descendant (including arbitrary nested id_* / *.pem) makes the copy fail closed.
  await assertNoCredentialDescendants(src, { ignoreAppSecrets: true });
  const dest = await safeWritePath(to, false);
  // Skip the cockpit's own .env* rather than refuse the copy — on the default
  // roots APP_DIR sits under ~/projects, so refusing would block copying it.
  if (dest === src || dest.startsWith(src + path.sep)) throw new HostError("Cannot copy a directory into itself");
  const sourceParent = await pinDirectory(path.dirname(src), true);
  let destParent;
  try {
    destParent = await pinDirectory(path.dirname(dest), true);
    await copyPinned(await sourceParent.child(path.basename(src)), await destParent.child(path.basename(dest)));
  } finally { await sourceParent.handle.close(); await destParent?.handle.close(); }
}

export async function usage(requested: string): Promise<FsUsage> {
  const p = await resolveReadable(requested || "~");
  const s = await fs.statfs(p);
  const total = s.blocks * s.bsize;
  const free = s.bfree * s.bsize;
  return { used: total - free, total };
}

// --- raw byte serving (images / video / audio / pdf preview) ---

// PASSIVE MEDIA TYPES ONLY. Everything absent from this table is served as
// application/octet-stream, which browsers download instead of executing — and that
// is doing real work: `text/html` here would turn any host file into an ACTIVE
// document on the cockpit's own origin, with the session cookie attached (the exact
// hazard the SVG sandbox header below exists for). The Preview app reads text and
// HTML with fetch() and renders it in a sandboxed frame precisely so this table
// never has to grow an executable type. Do not add html/xhtml/xml here.
const MIME: Record<string, string> = {
  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", jfif: "image/jpeg",
  gif: "image/gif", webp: "image/webp", svg: "image/svg+xml", avif: "image/avif",
  bmp: "image/bmp", ico: "image/x-icon", tif: "image/tiff", tiff: "image/tiff",
  heic: "image/heic", heif: "image/heif",
  mp4: "video/mp4", m4v: "video/x-m4v", webm: "video/webm", mov: "video/quicktime",
  mkv: "video/x-matroska", avi: "video/x-msvideo", ogv: "video/ogg",
  mpg: "video/mpeg", mpeg: "video/mpeg", "3gp": "video/3gpp", wmv: "video/x-ms-wmv",
  mp3: "audio/mpeg", wav: "audio/wav", m4a: "audio/mp4", flac: "audio/flac",
  aiff: "audio/aiff", aif: "audio/aiff", ogg: "audio/ogg", oga: "audio/ogg",
  opus: "audio/opus", aac: "audio/aac", wma: "audio/x-ms-wma",
  pdf: "application/pdf", json: "application/json", zip: "application/zip",
};

export function mimeFor(p: string): string {
  return MIME[p.split(".").pop()?.toLowerCase() ?? ""] ?? "application/octet-stream";
}

// Resolve + stat a readable file (within READ roots) for byte streaming.
export async function statReadable(
  requested: string,
): Promise<{ path: string; size: number; mime: string; handle: FileHandle }> {
  const p = await resolveReadable(requested);
  const handle = await openReadableHandle(p);
  try {
    const st = await handle.stat();
    if (!st.isFile()) throw new HostError(st.isDirectory() ? "Is a directory" : "Not a regular file");
    return { path: p, size: st.size, mime: mimeFor(p), handle };
  } catch (error) { await handle.close(); throw error; }
}

export type FsReadableMeta = {
  kind: "file" | "dir" | "symlink";
  sizeBytes: number;
  mtimeMs: number;
  ctimeMs: number;
  mode: number;
};

// Resolve + stat a readable path (within READ roots) for bounded metadata.
export async function statReadableMeta(requested: string): Promise<FsReadableMeta> {
  const p = await resolveReadable(requested);
  const st = await fs.stat(p);
  const kind: FsReadableMeta["kind"] = st.isDirectory() ? "dir" : st.isSymbolicLink() ? "symlink" : "file";
  return {
    kind,
    sizeBytes: st.size,
    mtimeMs: st.mtimeMs,
    ctimeMs: st.ctimeMs,
    mode: st.mode,
  };
}

// Transfer the verified handle to the stream, optionally for a byte range.
export function fileStream(handle: FileHandle, start?: number, end?: number): ReadStream {
  return handle.createReadStream({ autoClose: true, ...(start !== undefined ? { start, end } : {}) });
}