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.5 KB
Raw Blame
/**
 * Private managed-root publication: 0700 root, no symlink ancestors, bounded
 * 0600 receipts, and transactional status/identity pair publication.
 */
import { constants } from 'node:fs'
import { randomUUID } from 'node:crypto'
import { chmod, link, lstat, mkdir, open, rename, rm, writeFile } from 'node:fs/promises'
import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
const MAX_PRIVATE_BYTES = 64 * 1024

/** Create/validate a private managed root: 0700, owned, no symlinked ancestors. */
export async function ensureManagedRoot(root) {
  const abs = resolve(root)
  if (!isAbsolute(abs)) throw new Error(`managed root must be absolute: ${root}`)
  const parts = abs.split(sep).filter(Boolean)
  let current = sep
  for (const part of parts) {
    current = join(current, part)
    let info
    try {
      info = await lstat(current)
    } catch (err) {
      if (err.code !== 'ENOENT') throw err
      await mkdir(current, { mode: 0o700 })
      info = await lstat(current)
    }
    if (info.isSymbolicLink()) throw new Error(`managed root has symlink ancestor: ${current}`)
    if (!info.isDirectory()) throw new Error(`managed root ancestor is not a directory: ${current}`)
    // Only the managed root itself must be user-owned; system ancestors need not be.
    if (current === abs && info.uid !== process.getuid()) {
      throw new Error(`managed root is not owned by this user: ${current}`)
    }
  }
  if (((await lstat(abs)).mode & 0o077) !== 0) await chmod(abs, 0o700)
  if (((await lstat(abs)).mode & 0o077) !== 0) throw new Error(`managed root permissions are not 0700: ${abs}`)
  return abs
}

function contained(absRoot, absFile) {
  if (absFile === absRoot || !absFile.startsWith(`${absRoot}${sep}`)) {
    throw new Error(`path escapes managed root (outside): ${absFile}`)
  }
}

async function assertPrivateAncestors(absRoot, absFile) {
  const dir = dirname(absFile)
  if (dir === absRoot) return
  contained(absRoot, dir)
  let current = absRoot
  for (const part of dir.slice(absRoot.length + 1).split(sep)) {
    current = join(current, part)
    const info = await lstat(current)
    if (info.isSymbolicLink()) throw new Error(`refusing symlink ancestor: ${current}`)
    if (!info.isDirectory()) throw new Error(`private ancestor is not a directory: ${current}`)
    if (info.uid !== process.getuid()) throw new Error(`private ancestor is not owned by this user: ${current}`)
  }
}

async function readPrivateRaw(filePath, { root, maxBytes = MAX_PRIVATE_BYTES } = {}) {
  const absRoot = await ensureManagedRoot(root)
  const absFile = resolve(filePath)
  contained(absRoot, absFile)
  await assertPrivateAncestors(absRoot, absFile)
  // One descriptor both inspects and reads: the bytes returned are the bytes the
  // stat described, so nothing can be swapped in between. O_NOFOLLOW makes a
  // symlinked receipt fail at open time instead of being followed.
  let handle
  try {
    handle = await open(absFile, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
  } catch (err) {
    if (err.code === 'ENOENT') return null
    if (err.code === 'ELOOP') throw new Error(`private file is not a regular file: ${absFile}`)
    throw err
  }
  try {
    const info = await handle.stat()
    const problem = !info.isFile() ? 'is not a regular file'
      : (info.mode & 0o077) !== 0 ? 'permissions are not 0600'
      : info.uid !== process.getuid() ? 'is not owned by this user'
      : info.size > maxBytes ? `exceeds ${maxBytes} bytes` : null
    if (problem) throw new Error(`private file ${problem}: ${absFile}`)
    return { absFile, raw: await handle.readFile('utf8') }
  } finally {
    await handle.close().catch(() => {})
  }
}

export async function readPrivateJson(filePath, options = {}) {
  const file = await readPrivateRaw(filePath, options)
  if (!file) throw new Error(`private file is missing: ${resolve(filePath)}`)
  return JSON.parse(file.raw)
}

/** Atomic 0600 write inside a verified managed root; no temp file survives failure. */
export async function writePrivateFile(filePath, data, { root } = {}) {
  const absRoot = await ensureManagedRoot(root)
  const absFile = resolve(filePath)
  contained(absRoot, absFile)
  await ensureManagedRoot(dirname(absFile))
  const existing = await lstat(absFile).catch((err) => { if (err.code !== 'ENOENT') throw err; return null })
  if (existing && (existing.isSymbolicLink() || !existing.isFile())) {
    throw new Error(`refusing non-regular or symlink private file: ${absFile}`)
  }
  const raw = typeof data === 'string' ? data : JSON.stringify(data, null, 2)
  const tmp = `${absFile}.tmp-${process.pid}-${randomUUID()}`
  try {
    await writeFile(tmp, raw, { mode: 0o600, flag: 'wx' })
    await rename(tmp, absFile)
  } catch (err) {
    await rm(tmp, { force: true }).catch(() => {})
    throw err
  }
  return absFile
}

/**
 * Publish a receipt pair as one transaction. Both files are staged before any
 * rename; a later failure restores only entries whose bytes still equal ours.
 */
export async function publishPrivatePair({ root, entries, renameImpl = rename } = {}) {
  const absRoot = await ensureManagedRoot(root)
  if (!Array.isArray(entries) || entries.length === 0) throw new Error('receipt entries are required')
  const prepared = []
  const seen = new Set()
  try {
    for (const entry of entries) {
      const absFile = resolve(entry.path)
      contained(absRoot, absFile)
      if (seen.has(absFile)) throw new Error(`duplicate receipt path: ${absFile}`)
      seen.add(absFile)
      await ensureManagedRoot(dirname(absFile))
      const previous = await readPrivateRaw(absFile, { root: absRoot })
      const raw = typeof entry.data === 'string' ? entry.data : JSON.stringify(entry.data, null, 2)
      const tmp = `${absFile}.tmp-${process.pid}-${randomUUID()}`
      await writeFile(tmp, raw, { mode: 0o600, flag: 'wx' })
      prepared.push({ absFile, raw, previous: previous?.raw ?? null, tmp, renamed: false })
    }
    for (const item of prepared) {
      await renameImpl(item.tmp, item.absFile)
      item.renamed = true
    }
    return { files: prepared.map((item) => item.absFile) }
  } catch (err) {
    for (const item of [...prepared].reverse()) {
      if (item.tmp) await rm(item.tmp, { force: true }).catch(() => {})
      if (!item.renamed) continue
      const current = await readPrivateRaw(item.absFile, { root: absRoot }).catch(() => null)
      if (!current || current.raw !== item.raw) continue
      try {
        if (item.previous === null) {
          await rm(item.absFile, { force: true })
        } else {
          await writePrivateFile(item.absFile, item.previous, { root: absRoot })
        }
      } catch {}
    }
    throw err
  } finally {
    await Promise.all(prepared.map((item) => rm(item.tmp, { force: true }).catch(() => {})))
  }
}

async function restoreQuarantine(quarantine, absFile) {
  try {
    await link(quarantine, absFile)
    await rm(quarantine, { force: true })
    return
  } catch (err) {
    if (err.code === 'EEXIST') {
      // Another runtime recreated the path while we inspected it: keep theirs.
      await rm(quarantine, { force: true })
      return
    }
  }
  const existing = await lstat(absFile).catch(() => null)
  if (existing) throw new Error(`cannot restore quarantined receipt without clobbering: ${absFile}`)
  await rename(quarantine, absFile)
}

/**
 * Remove only receipts that still parse and match this runtime's predicate.
 * Each candidate is renamed aside, inspected, then deleted or restored.
 */
export async function clearPrivatePairIfMatch({ root, matches = [] } = {}) {
  const absRoot = await ensureManagedRoot(root)
  const cleared = []
  const preserved = []
  for (const match of matches) {
    const absFile = resolve(match.path)
    contained(absRoot, absFile)
    const quarantine = `${absFile}.quarantine-${process.pid}-${randomUUID()}`
    try {
      await rename(absFile, quarantine)
    } catch (err) {
      if (err.code === 'ENOENT') continue
      throw err
    }
    let matchesOwn = false
    try {
      const current = await readPrivateRaw(quarantine, { root: absRoot })
      if (current) {
        let parsed
        try { parsed = JSON.parse(current.raw) } catch { parsed = undefined }
        matchesOwn = Boolean(parsed && match.predicate(parsed))
      }
    } catch (err) {
      await restoreQuarantine(quarantine, absFile).catch(() => {})
      throw err
    }
    if (matchesOwn) {
      await rm(quarantine, { force: true })
      cleared.push(absFile)
    } else {
      await restoreQuarantine(quarantine, absFile)
      preserved.push(absFile)
    }
  }
  return { cleared, preserved }
}