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.

6.8 KB
Raw Blame
import "server-only";
import { constants, promises as fs } from "node:fs";
import type { FileHandle } from "node:fs/promises";
import path from "node:path";

/**
 * Bounded, symlink-proof filesystem reads for the MSO-owned Orca unit proof.
 *
 * Both the unit file and the trusted `managed-service.json` receipt are opened
 * through a pinned directory fd with `O_NOFOLLOW`, capped from `fstat` before a
 * single byte is read (the read loop stops at cap+1, so a growing file cannot
 * allocate or return unbounded data), and re-`stat`ed to reject an in-flight
 * replacement. The receipt is 0600 inside the 0700 managed root.
 */

export const ORCA_UNIT_MARKER = "# mso-managed-app: orca";
const UNIT_MAX_BYTES = 32 * 1024;
const CONFIG_MAX_BYTES = 64 * 1024;
const SERVICE_CONFIG = "managed-service.json";
const CONTROL = /[\0\r\n]/;
const LOOPBACK_HOSTS = new Set(["localhost", "::1", "[::1]", "0.0.0.0", "[::]", "::"]);

export type TrustedOrcaConfig = {
  hostNode: string;
  cliScript: string;
  managedRoot: string;
  port: number;
  advertisedEndpoint: string;
};

export type TrustedConfigRead =
  | { state: "ok"; config: TrustedOrcaConfig }
  | { state: "missing" }
  | { state: "stale" }
  | { state: "invalid" };

export function ownerUidMatches(uid: number): boolean {
  return typeof process.getuid !== "function" || uid === process.getuid();
}

/** Read at most `maxBytes`; a file that reaches cap+1 is refused. */
async function readBounded(handle: FileHandle, maxBytes: number): Promise<Buffer | null> {
  const chunks: Buffer[] = [];
  let total = 0;
  for (;;) {
    const remaining = maxBytes + 1 - total;
    if (remaining <= 0) return null;
    const chunk = Buffer.alloc(Math.min(remaining, 16 * 1024));
    const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
    if (bytesRead === 0) break;
    total += bytesRead;
    if (total > maxBytes) return null;
    chunks.push(chunk.subarray(0, bytesRead));
  }
  return Buffer.concat(chunks, total);
}

async function readOwnedFile(dir: string, filename: string, maxBytes: number, privateMode: boolean): Promise<string | null> {
  let canonicalDir: string;
  try {
    canonicalDir = await fs.realpath(dir);
  } catch {
    return null;
  }
  if (canonicalDir !== path.resolve(dir)) return null;
  let directory;
  try {
    directory = await fs.open(canonicalDir, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
  } catch {
    return null;
  }
  try {
    const dirStat = await directory.stat();
    if (!dirStat.isDirectory() || !ownerUidMatches(dirStat.uid) || (dirStat.mode & 0o022) !== 0) return null;
    let handle;
    try {
      handle = await fs.open(`/proc/self/fd/${directory.fd}/${filename}`, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
    } catch {
      return null;
    }
    try {
      const before = await handle.stat();
      const modeReject = privateMode ? (before.mode & 0o077) !== 0 : (before.mode & 0o022) !== 0;
      if (!before.isFile() || !ownerUidMatches(before.uid) || modeReject || before.size > maxBytes) return null;
      const buffer = await readBounded(handle, maxBytes);
      if (buffer === null) return null;
      const after = await handle.stat();
      if (after.size !== buffer.length || after.ino !== before.ino || after.mtimeMs !== before.mtimeMs || after.mode !== before.mode) return null;
      return buffer.toString("utf-8");
    } finally {
      await handle.close();
    }
  } finally {
    await directory.close();
  }
}

export async function readOrcaUnitText(unitPath: string): Promise<string | null> {
  return readOwnedFile(path.dirname(unitPath), path.basename(unitPath), UNIT_MAX_BYTES, false);
}

function isAdvertisedEndpoint(value: unknown): value is string {
  if (typeof value !== "string" || value.length === 0) return false;
  let url: URL;
  try {
    url = new URL(value);
  } catch {
    return false;
  }
  if (url.protocol !== "wss:" || url.username || url.password || url.search || url.hash) return false;
  return !LOOPBACK_HOSTS.has(url.hostname) && !/^127\./.test(url.hostname);
}

/** A recorded launcher node is trusted only if it is a real, non-replaceable
 *  executable. Sticky world-writable directories (e.g. `/tmp`) may host a file
 *  this user already owns; a non-sticky writable ancestor may not. */
async function isTrustedHostNode(node: unknown): Promise<boolean> {
  if (typeof node !== "string" || !path.isAbsolute(node) || CONTROL.test(node)) return false;
  let info;
  try {
    info = await fs.lstat(node);
  } catch {
    return false;
  }
  if (!info.isFile() || info.isSymbolicLink() || (info.mode & 0o111) === 0 || (info.mode & 0o022) !== 0) return false;
  if (info.uid !== 0 && !ownerUidMatches(info.uid)) return false;
  let dir = path.dirname(node);
  for (;;) {
    let dirInfo;
    try {
      dirInfo = await fs.lstat(dir);
    } catch {
      return false;
    }
    if (!dirInfo.isDirectory() || dirInfo.isSymbolicLink()) return false;
    if ((dirInfo.mode & 0o002) !== 0 && (dirInfo.mode & 0o1000) === 0) return false;
    const parent = path.dirname(dir);
    if (parent === dir) return true;
    dir = parent;
  }
}

/**
 * The trusted installation configuration written by the installer. `hostNode`
 * and `cliScript` are the exact launcher the unit was rendered with; there is
 * deliberately no `release.nodeBinary` fallback (that is the pinned child
 * runtime). A config from an older MSO release without these fields is
 * `stale`, so the consumer can demand a reinstall instead of silently adopting
 * a unit it cannot reproduce.
 */
export async function readTrustedConfig(root: string): Promise<TrustedConfigRead> {
  const text = await readOwnedFile(root, SERVICE_CONFIG, CONFIG_MAX_BYTES, true);
  if (text === null) return { state: "missing" };
  let raw: unknown;
  try {
    raw = JSON.parse(text);
  } catch {
    return { state: "invalid" };
  }
  if (!raw || typeof raw !== "object") return { state: "invalid" };
  const config = raw as Record<string, unknown>;
  if (config.schemaVersion !== 1 || config.applicationId !== "orca" || config.unitIdentity !== ORCA_UNIT_MARKER) {
    return { state: "invalid" };
  }
  if (config.managedRoot !== root) return { state: "invalid" };
  if (typeof config.hostNode !== "string" || typeof config.cliScript !== "string") return { state: "stale" };
  if (!path.isAbsolute(config.cliScript) || CONTROL.test(config.cliScript)) return { state: "invalid" };
  const port = config.port;
  if (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) return { state: "invalid" };
  if (!isAdvertisedEndpoint(config.advertisedEndpoint)) return { state: "invalid" };
  if (!(await isTrustedHostNode(config.hostNode))) return { state: "invalid" };
  return {
    state: "ok",
    config: {
      hostNode: config.hostNode,
      cliScript: config.cliScript,
      managedRoot: root,
      port,
      advertisedEndpoint: config.advertisedEndpoint
    }
  };
}